Skip to content

feat: add AdaL as a supported harness agent - #171

Draft
Ricardoran wants to merge 1 commit into
firecrawl:mainfrom
Ricardoran:add-adal-agent
Draft

feat: add AdaL as a supported harness agent#171
Ricardoran wants to merge 1 commit into
firecrawl:mainfrom
Ricardoran:add-adal-agent

Conversation

@Ricardoran

@Ricardoran Ricardoran commented Jul 28, 2026

Copy link
Copy Markdown

Summary

Adds AdaL as a supported harness in the native agent detection registry, with a non-destructive collision guard that never overwrites user-owned skill directories or files.

Changes

File Change
src/commands/skills-native.ts Add adal entry to AGENTS array + non-destructive collision guard in symlink phase
README.md Add adal to harness table + section separating native bootstrap from AdaL marketplace install + collision safety docs
src/__tests__/adal-agent.test.ts 13 focused test assertions (AdaL + cross-harness Codex)

How it works

  • firecrawl init --agent adal installs Firecrawl CLI skills to ~/.adal/skills/ as relative symlinks from a canonical ~/.agents/skills/ directory.
  • firecrawl init --all auto-detects AdaL by checking for ~/.adal/ existence.
  • No Firecrawl API key is required for skill installation.

Collision safety (non-destructive by default)

The symlink-creation phase now handles existing paths as follows:

Existing path type Behavior
Correct symlink (already points to canonical) Skip (no-op)
Stale/incorrect symlink Replace safely
User-owned directory Skip — never delete (emit warning)
User-owned file Skip — never delete (emit warning)
Nothing exists Create symlink

This ensures init --agent adal (including non-interactive mode) never destroys user-authored content at ~/.adal/skills/<skill-name>.

The guard is generic — it protects all harnesses equally (not AdaL-specific). Cross-harness behavior is proven by dedicated Codex collision tests.

AdaL's skill discovery

AdaL's SkillsLoader scans ~/.adal/skills/ for directories containing SKILL.md files with YAML frontmatter (name + description). All Firecrawl CLI skills satisfy this format.

AdaL also has a separate marketplace-based install path (/plugin marketplace add firecrawl/cli) that places skills in ~/.adal/plugin-cache/. The README documents both paths so users can choose — they use different install locations and precedence rules.

Test results

✓ assertion 3+5: adal agent is registered with correct detectDir and globalSkillsDir
✓ assertion 7: auto-detection recognizes existing .adal directory
✓ assertion 8+9: isolated install succeeds and places artifacts in .adal/skills
✓ assertion 10: every installed skill has valid SKILL.md with name+description
✓ assertion 11: preserves pre-existing user-owned skill files with non-conflicting names
✓ assertion 12: idempotent reinstall produces stable result
✓ assertion 13: collision — same-named user directory is preserved, NOT overwritten
✓ assertion 13b: collision — same-named user file is preserved, NOT overwritten
✓ assertion 13c: stale symlinks ARE safely replaced
✓ assertion 14: unwritable destination causes error, no corrupt partial state
✓ assertion 15: paths resolve under isolated HOME, not real HOME
✓ [codex] preserves same-named user-owned directory for codex harness
✓ [codex] preserves same-named user-owned file for codex harness

Test Files  23 passed | 1 skipped (24)
     Tests  403 passed | 1 skipped (404)

All existing tests pass with zero regressions.

Scope of collision guard

The non-destructive guard is applied generically in the installSkillsNative symlink phase (not AdaL-specific). It protects all harnesses equally — any agent with an existing user-owned skill at a same-named path will have it preserved. This is proven by the cross-harness Codex collision tests.

Licensing note

This PR adds only a registry entry pointing to AdaL's existing ~/.adal/skills/ directory convention. No Firecrawl content is redistributed by AdaL.

Adds AdaL to the native agent detection registry so that
`firecrawl init --agent adal` and `firecrawl init --all` install
skills into ~/.adal/skills/.

- Registry entry: name='adal', detectDir='.adal', globalSkillsDir='.adal/skills'
- Non-destructive collision guard: existing user-owned directories and
  files at skill link paths are NEVER overwritten (only stale symlinks
  are replaced). Skipped collisions emit a warning.
- Guard is generic (protects all harnesses equally), tested against both
  adal and codex harnesses.
- README: harness table entry + section distinguishing native bootstrap
  from AdaL marketplace install + collision safety documentation
- Tests: 13 focused assertions covering detection, isolation, SKILL.md
  validity, collision preservation (dir + file for adal AND codex),
  stale symlink replacement, idempotence, and error handling

Co-Authored-By: AdaL <adal@sylph.ai>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant