feat(cli): agent threads in the Alexandria beta

[nickscamara]

Summary

Brings the new agent threads API (spark-2, firecrawl SDK 4.40.0) to the CLI as part of the Alexandria beta. Options are documented in --help like the rest of the beta surface after #230; the alexandria npm dist-tag is the gate. Version bumps to 1.23.4-alexandria-beta.7 so merging publishes under that tag.

What's added

• firecrawl agent "<prompt>" --thread <threadId> continues an existing thread. --mode extract|chat and --effort low|medium|high are forwarded; spark-2 is accepted for --model and listed as the default.
• Start output now includes threadId / threadTurn. Status output (--json and human-readable) includes threadId, threadTurn, mode, message, and suggestions when present, so chat turns are readable.
• firecrawl agent thread <threadId> [--include-data] [--json] [--pretty] lists a thread's runs via GET /v2/agent/threads/:id.
• API errors (thread_busy 409, thread_not_found 404) are relayed with the server message and exit 1.
• New beta skill beta-skills/firecrawl-agent documents using agent as a web-data subagent and keeping threads for follow-ups; setup alexandria installs it alongside the Alexandria skill. The Alexandria skill itself is unchanged.

Notes

• The thread subcommand shares option names with agent, and commander lets the parent consume known options anywhere in argv, so the subcommand reads optsWithGlobals(). It also runs the same auth gate the preAction hook applies to agent (subcommand names are not matched by AUTH_REQUIRED_COMMANDS).
• The beta e2e mock server now tolerates body-less GET requests.

Testing

• pnpm test: 470 passed (7 new cases in alexandria-beta.test.ts covering continuation, plain-start body shape, malformed --thread, chat status output, thread_busy, thread listing with/without --include-data, and thread_not_found; the help test also asserts the new options and subcommand are documented).
• pnpm run type-check, pnpm run format:check clean.

[cubic-dev-ai]

1 issue found across 6 files

Confidence score: 3/5

• src/index.ts can prompt users to log in even when they provide agent thread <id> --api-key <key>, preventing the supplied key from reaching the handler and blocking API-key-only usage; skip the auth prompt when options.apiKey is present while retaining the custom-URL check.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/index.ts">

<violation number="1" location="src/index.ts:1721">
P2: When users provide only `agent thread <id> --api-key <key>`, this gate prompts for login before the handler can apply that key. Skip the auth prompt when `options.apiKey` is present, while retaining the custom-URL check.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When users provide only agent thread <id> --api-key <key>, this gate prompts for login before the handler can apply that key. Skip the auth prompt when options.apiKey is present, while retaining the custom-URL check.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/index.ts, line 1721:

<comment>When users provide only `agent thread <id> --api-key <key>`, this gate prompts for login before the handler can apply that key. Skip the auth prompt when `options.apiKey` is present, while retaining the custom-URL check.</comment>

<file context>
@@ -1671,6 +1695,45 @@ function createAgentCommand(): Command {
+        const options = command.optsWithGlobals();
+        // Subcommands are not matched by AUTH_REQUIRED_COMMANDS; gate here.
+        const { isCustomApiUrl } = await import('./utils/config');
+        if (!isCustomApiUrl(options.apiUrl)) {
+          await ensureAuthenticated();
+        }
</file context>