Skip to content

Consolidate PRs #1 + #2; ship AI SDK provider; drop streamAgent/generateAgent#3

Merged
aidenybai merged 26 commits intomainfrom
consolidate-prs
Apr 26, 2026
Merged

Consolidate PRs #1 + #2; ship AI SDK provider; drop streamAgent/generateAgent#3
aidenybai merged 26 commits intomainfrom
consolidate-prs

Conversation

@aidenybai
Copy link
Copy Markdown
Member

Summary

Single PR that consolidates the two open Cursor agent PRs (#1 ACP overhaul + #2 reliability hardening) into a coherent tree, then turns use-local-agent into a real Vercel AI SDK provider on top.

Closes #1 and #2 (their commits are preserved in this branch's history; this PR is the merged-and-resolved superset).

What's in this PR

1. Consolidation of PR #1 + PR #2

Both PRs touched the same core files (connect.ts, local-agent.ts, errors.ts, constants.ts, mock-agent.ts, run-command.ts). Conflicts were resolved by favoring the stricter / more correct fix in each case:

2. Real AI SDK provider (LanguageModelV3)

use-local-agent now plugs directly into streamText / generateText from the ai package — no parallel one-shot helper API needed:

import { streamText } from "ai";
import { localAgent } from "use-local-agent";

const { textStream } = streamText({
  model: localAgent("claude"),
  prompt: "Refactor src/auth.ts",
});

New module src/ai-sdk/:

  • convert-prompt.tsLanguageModelV3Prompt → ACP ContentBlock[]. System messages flatten into systemPrompt; image/audio file parts become ACP image/audio blocks; unsupported file mediaTypes / assistant tool-call replays / tool-result messages emit unsupported warnings.
  • local-agent-language-model.ts — implements LanguageModelV3:
    • doGenerate returns ordered reasoning + text + tool-call content with mapped finish reason and usage.
    • doStream emits stream-start (with warnings), response-metadata (carrying ACP sessionId), grouped text-start/-delta/-end and reasoning-start/-delta/-end, tool-call, tool-result, finish, and error parts. Opt-in raw passthrough via includeRawChunks.
    • Takes a connect factory so it's testable through the existing connectMockAgent harness without spawning a subprocess.
  • provider.tscreateLocalAgentProvider() returns a callable ProviderV3 (call-form + .languageModel()) plus .fromAdapter() for custom ACP-speaking subprocesses; default localAgent instance. embeddingModel / imageModel throw NoSuchModelError. Default permission: "auto-allow" so streamText Just Works.

Mappings:

  • ACP text-delta → V3 text-delta (start/end framed by message id)
  • ACP thinking-delta → V3 reasoning-delta
  • ACP tool-call → V3 tool-call with providerExecuted: true
  • ACP tool-call-update (completed/failed) → V3 tool-result (with isError on failure)
  • ACP stop reason → { unified, raw } (end_turnstop, max_tokens/max_turn_requestslength, refusalcontent-filter, cancelledother)
  • Unsupported V3 call options (temperature, topP/topK, seed, stopSequences, responseFormat:json, tools, etc.) → stream-start warnings.

3. Removed streamAgent / generateAgent

Now redundant with streamText / generateText from ai. Deleted src/stream.ts and all related exports.

LocalAgent (sessions, multi-turn, permission gating, slash commands, terminal handlers, session resume) stays as the stateful escape hatch for use cases that don't fit a single AI SDK call.

4. README rewrite

Both root and package READMEs rewritten in the react-grab style, leading with streamText({ model: localAgent('claude') }) and moving LocalAgent to an "Advanced" section. Tagline: "An API for accessing any locally-installed coding agent."

Public API

Added

  • localAgent(modelId, settings?) — default provider (call form + .languageModel() + .fromAdapter())
  • createLocalAgentProvider(defaults?) — provider factory
  • LocalAgentLanguageModel (class), LocalAgentLanguageModelConfig, LocalAgentProvider, LocalAgentProviderSettings
  • convertPromptToContentBlocks (utility)
  • AgentStdinClosedError (_tag: "StdinClosed")
  • pendingUpdateBufferLimit, disposeGraceMs, onTrace, envFilter, stderrFatalPatterns, traceContext, onAuthRequired, terminal options on LocalAgentConnectOptions
  • loadSessionStreaming, additionalDirectories on session inputs, commandsFor / modeStateFor / configOptionsFor getters, streamAllSessions
  • New peer deps: @ai-sdk/provider@^3.0.8, @ai-sdk/provider-utils@^4.0.23
  • Subpath export: use-local-agent/ai-sdk

Removed

  • streamAgent, generateAgent, OneShotAgentStream, StreamAgentOptions, GenerateAgentResult

Quality gates

Stats

46 files changed, 3638 insertions(+), 314 deletions(-)

cursoragent and others added 17 commits April 26, 2026 02:35
- Picks up reliability fixes from 0.17→0.20:
  - PR #103/#111: clean transport-failure handling, propagate ndjson errors
  - PR #119: parse final NDJSON message without trailing newline
  - PR #122: no spurious unhandledRejection on transport failures
  - PR #127: TS private keyword for cross-copy compatibility
  - PR #130: response/notification ordering fix
- Renames stabilized methods (PR #132):
  - unstable_resumeSession → resumeSession
  - unstable_closeSession → closeSession
- Updates LocalAgent, mock-agent harness, echo-agent fixture
- Adds resume-close.test.ts regression tests

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
- connect.ts:
  - Wait for spawn or error event before constructing connection
    (avoids races with later spawn errors leaking unhandled rejections).
  - Add disposeGraceMs option (default unchanged at 2000ms).
  - Add onTrace hook for inspecting in/out JSON-RPC messages and stderr.
  - Add envFilter hook for env scrubbing.
- local-agent.ts:
  - Race connection.initialize() against subprocess close so a process
    that exits before responding fails fast as AgentConnectionClosedError
    (instead of waiting initializeTimeoutMs).
  - Gate stderr-pattern fatal detection (auth/usage) until after init
    succeeds, eliminating false positives during boot/login banners.
  - Allow callers to override stderrFatalPatterns.
- utils/run-command.ts: Escalate to SIGKILL after a grace when SIGTERM
  is ignored on timeout.
- New tests:
  - tests/spawn-failures.test.ts: ENOENT, fast subprocess exit
  - tests/stderr-fatal-detection.test.ts: pre/post-init stderr gating

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
- Inactivity watchdog: pause while a permission request is pending in
  stream mode (prevents killing sessions waiting on the user). Permission
  events also bump lastActivityAt.
- Per-session buffered update cap (MAX_BUFFERED_UPDATES_PER_SESSION = 1024)
  drops oldest first to prevent unbounded memory growth.
- Add loadSessionStreaming() returning { sessionId, replay, completion }
  so callers can iterate replay updates emitted during session/load BEFORE
  the first prompt. Existing loadSession() preserved for back-compat.
- Slash commands:
  - Track latest available_commands_update per session.
  - Add LocalAgent.commandsFor(sessionId) / modeStateFor() / configOptionsFor() getters.
  - PromptInput now accepts { command: { name, input? } } and validates
    against advertised commands when known.
- Error message preservation: stringifyCause now includes Error.cause
  message in wrapped errors when distinct.
- Late tool_call_update notifications received after session/cancel are
  forwarded through the iterator (already worked in practice; explicit
  test coverage added).
- Mode tracking: current_mode_update mutates the cached modeState.
- New tests:
  - tests/late-updates.test.ts
  - tests/watchdog-permission.test.ts
  - tests/buffer-cap.test.ts
  - tests/load-session-replay.test.ts
  - tests/slash-commands.test.ts

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
- Optional terminal/* support: when caller provides options.terminal
  handlers, advertise terminal capability and forward all five client
  terminal methods (create/output/release/wait_for_exit/kill).
- additionalDirectories on createSession / loadSession /
  loadSessionStreaming / resumeSession with capability gating
  (sessionCapabilities.additionalDirectories) and absolute-path validation.
- listSessions(input?: { cwd?, cursor? }) with pagination plumbing.
  Adds streamAllSessions helper that auto-paginates.
- _meta trace context propagation via opt-in traceContext: () => Record.
  Only the W3C-reserved keys traceparent / tracestate / baggage are
  forwarded; other keys filtered out.
- onAuthRequired hook: when newSession returns auth_required (-32000)
  and a hook is configured, prompt for an auth method, call authenticate,
  then retry once. Returning undefined from the hook preserves the
  original AgentUnauthenticatedError.
- Convenience getters: commandsFor / modeStateFor / configOptionsFor.
- Mode tracking: current_mode_update mutates cached modeState.
- Tests:
  - tests/terminal.test.ts
  - tests/additional-directories.test.ts
  - tests/list-sessions-pagination.test.ts
  - tests/trace-context.test.ts
  - tests/auth-retry.test.ts

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
- claude: ANTHROPIC_API_KEY env fallback bypasses 'claude auth status'
  parsing when the env is set; checkAuthenticated honors it.
- copilot: GITHUB_TOKEN env fallback bypasses 'gh auth token' lookup;
  helpful error message updated.
- gemini: GEMINI_API_KEY / GOOGLE_API_KEY env fallback before reading
  ~/.gemini/google_accounts.json; updated error message.

(envFilter hook from Phase 2 already exposed for env scrubbing.)

- New: tests/adapter-env-fallbacks.test.ts covering gemini env auth.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
…aul (Phase 6)

- Bump apps/playground SDK pin to ^0.20.0 for consistency
- Document new options (terminal, additionalDirectories, listSessions
  pagination, traceContext, onAuthRequired, onTrace, disposeGraceMs,
  envFilter) in README
- Document slash command helper and reliability features
- Add .changeset entry summarizing the multi-phase upgrade
- New tests:
  - tests/sdk-upgrade.test.ts (covers ordering through wrapper)

End state: 70 unit tests green; 8/8 e2e Playwright tests against the
real echo-agent subprocess green.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
…ants

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
- Add testing/mock-agent.ts helpers:
  - withSpawnFailure(id?): builds an AgentAdapter that always points at
    a missing binary (used by spawn-failures.test.ts)
  - withSdkOutOfOrderRace(chunks): builds a prompt handler that emits
    multiple notifications back-to-back, exercising the SDK's response/
    notification ordering guarantee.
- tests/spawn-failures.test.ts now uses withSpawnFailure for clarity.
- tests/wire-fuzz.test.ts: bounded property-based test that feeds 200
  randomized session updates per turn (seeded RNG) plus an interleaved
  cancellation variant to verify the wrapper does not crash and produces
  well-shaped AgentEvent values terminating in 'finish'.

Total: 72 unit tests across 24 files.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
…irectories

Closes the documentation gap from the plan's file change matrix:
- Documents the echo-agent fixture commands used by the e2e tests.
- Shows fileSystem and terminal handler wiring patterns for callers.
- Documents additionalDirectories session-input field and absolute-path
  requirement.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
…ffer, validation timer leak, pending-update cap, abort short-circuit, perm settle gate, EPIPE handlers, stdout-noise filter, run-command caps

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>
Resolves overlap between the SDK upgrade / spec coverage overhaul and the
reliability bug-fix pass into a single tree.

Conflicts resolved (favoring stricter / more correct behavior):
- run-command.ts: keep PR #2's isProcessAlive check + PR #1's configurable grace
- connect.ts: combine waitForSpawnOrError, no-op stream error listeners,
  and isProcessAlive-based dispose with disposeGraceMs option
- local-agent.ts:
  - merge option fields (pendingUpdateBufferLimit + traceContext +
    onAuthRequired + onTrace + envFilter + disposeGraceMs +
    stderrFatalPatterns)
  - keep PR #2's raceInitialize helper (subprocess-close vs init vs timeout)
    while preserving PR #1's defensive AgentConnectionClosedError fallback
  - validate prompt blocks (with slash-command processing) before draining
    buffered updates / pendingConfigOptions
  - use PR #2's bufferSessionUpdate with droppedPendingUpdateCount and the
    configurable PENDING_UPDATE_BUFFER_LIMIT_PER_SESSION cap
- constants.ts: keep PENDING_UPDATE_BUFFER_LIMIT_PER_SESSION; drop the
  duplicate MAX_BUFFERED_UPDATES_PER_SESSION
- buffer-cap.test.ts: realign to the PENDING_UPDATE_BUFFER_LIMIT_PER_SESSION
  constant
- changesets: collapse acp-reliability-overhaul + reliability-hardening into
  a single comprehensive entry

Verified: pnpm typecheck, pnpm lint (0/0), pnpm test (86/86 unit tests
across 25 files), and the playground node project (8/8 e2e tests against
the real echo-agent subprocess) all pass.
…ent/generateAgent

Implements the LanguageModelV3 spec (`@ai-sdk/provider` v3.0.x) so
`use-local-agent` plugs directly into `streamText` / `generateText` from
the `ai` package, eliminating the parallel one-shot helper API:

  import { streamText } from "ai";
  import { localAgent } from "use-local-agent";

  const { textStream } = streamText({
    model: localAgent("claude"),
    prompt: "Refactor src/auth.ts",
  });

New module `src/ai-sdk/`:
- `convert-prompt.ts` maps a `LanguageModelV3Prompt` (system/user/
  assistant/tool messages) to ACP `ContentBlock[]`. System messages
  flatten into `systemPrompt`; image/audio file parts become ACP image/
  audio blocks; unsupported file mediaTypes, assistant tool-call replays,
  and tool-result messages emit `unsupported` warnings.
- `local-agent-language-model.ts` implements `LanguageModelV3`:
  - `doGenerate` returns ordered `reasoning` + `text` + `tool-call`
    content with mapped `LanguageModelV3FinishReason` and usage.
  - `doStream` emits `stream-start` (with warnings), `response-metadata`
    (carrying ACP `sessionId`), grouped `text-start/-delta/-end` and
    `reasoning-start/-delta/-end`, `tool-call`, `tool-result`, `finish`,
    and `error` parts. Opt-in raw passthrough via `includeRawChunks`.
  - Takes a `connect` factory so it's testable through the existing
    `connectMockAgent` harness without spawning a subprocess.
- `provider.ts` exports `createLocalAgentProvider()` (a callable
  `ProviderV3` with a `.languageModel()` method, plus `.fromAdapter()`
  for custom ACP-speaking subprocesses) and a default `localAgent`
  instance. `embeddingModel` / `imageModel` throw `NoSuchModelError`.
  Default `permission: "auto-allow"` so `streamText` Just Works.

Mappings:
- ACP `text-delta` → V3 `text-delta` (start/end framed by message id)
- ACP `thinking-delta` → V3 `reasoning-delta`
- ACP `tool-call` → V3 `tool-call` with `providerExecuted: true`
- ACP `tool-call-update` (completed/failed) → V3 `tool-result`
  (with `isError` on failure)
- ACP stop reason → `{ unified, raw }`
- Unsupported V3 call options (temperature, topP/topK, seed, stopSequences,
  responseFormat:json, tools, etc.) → `stream-start` warnings.

Removed:
- `src/stream.ts` (`streamAgent`, `generateAgent`, `OneShotAgentStream`,
  `StreamAgentOptions`, `GenerateAgentResult`) — fully redundant with
  `streamText` / `generateText` from `ai`.

Wiring:
- New deps: `@ai-sdk/provider@^3.0.8`, `@ai-sdk/provider-utils@^4.0.23`.
- Subpath export `use-local-agent/ai-sdk` and a top-level re-export.
- `vite.config.ts` adds `src/ai-sdk/index.ts` as a build entry.
- README leads with `streamText({ model: localAgent('claude') })`; the
  `LocalAgent` API moves to an "Advanced" section for stateful multi-turn,
  permission gating, slash commands, and session resume.

Tests:
- New `tests/ai-sdk-provider.test.ts` covers prompt conversion, provider
  shape, `NoSuchModelError`, `doGenerate` (reasoning+text+tool-call
  ordering, finish-reason mapping), `doStream` part ordering, and
  unsupported-option warnings.

Quality gates: `pnpm typecheck` clean, `pnpm lint` 0/0 on 72 files, and
all 96 tests across 26 files pass.

Also drops the leftover `.changeset/acp-reliability-overhaul.md` per
prior cleanup.
…treamObject/generateObject

Adds `ai@^6.0.168` as a regular dependency and re-exports its top-level
helpers from `use-local-agent`'s main entry, so callers get the
end-to-end story from a single install:

  import { streamText, localAgent } from "use-local-agent";

  streamText({
    model: localAgent("claude", { cwd: "/path/to/project" }),
    prompt: "...",
  });

Bringing your own `ai` still works — importing from `"ai"` directly is
unchanged and resolves to the same versions transitively.

README updated to:
- show the new single-import pattern as the headline usage,
- demonstrate inline per-call settings on the model factory
  (`localAgent("codex", { cwd, permission, inactivityTimeoutMs, onTrace })`),
- call out that users can still import from `"ai"` if they prefer.
Moves `ai` from `dependencies` to `peerDependencies` (required, not
optional) and drops the top-level re-exports of `streamText`,
`generateText`, `streamObject`, `generateObject`. Callers install `ai`
themselves and import it directly:

  npm install use-local-agent ai

  import { streamText } from "ai";
  import { localAgent } from "use-local-agent";

Same behavior as `@ai-sdk/openai`, `@ai-sdk/anthropic`, etc. — keeps the
provider package small and avoids dragging in `ai` for callers that
might not use it transitively. README updated to use separate imports
throughout.
…mText

Adds an AI-SDK-shaped path for multi-turn ACP sessions so callers don't
have to drop down to the LocalAgent API for follow-up turns:

  import { streamText } from "ai";
  import { createLocalAgentSession } from "use-local-agent";

  await using session = await createLocalAgentSession("codex");

  await streamText({ model: session.model, prompt: "list TODOs" });
  await streamText({ model: session.model, prompt: "now fix the highest one" });

  await streamText({
    model: session.model,
    prompt: "agent client protocol",
    providerOptions: { useLocalAgent: { command: "web" } },
  });

Implementation:

- LocalAgentLanguageModel: replace the single-purpose `connect` factory
  with a more general `acquire` factory that returns
  { agent, sessionId, historyAlreadyApplied, release }. One-shot mode
  (default `localAgent("...")`) creates a fresh agent + session and
  closes both on release. Session-bound mode (createLocalAgentSession)
  reuses an existing agent + session and makes release a no-op.
- convertPromptToContentBlocks: new `lastUserOnly` option used by
  session-bound models to skip prior conversation history (the ACP
  session already holds it). Emits a `compatibility` warning describing
  how many messages were skipped, plus an `unsupported` warning if the
  prompt has no trailing user message at all.
- providerOptions.useLocalAgent.command: forwards a slash command to the
  underlying ACP session (object form `{ name, input? }` or bare string).
- createLocalAgentSession opens one LocalAgent + one session, exposes
  `.model` (LanguageModelV3 bound to the session), `.agent` and
  `.sessionId` for ACP-specific surfaces, and implements
  `Symbol.asyncDispose` so `await using` cleans up the subprocess.

3 new tests cover: trailing-user-only behavior with a compatibility
warning, slash command via `{ name, input }`, and the bare-string
command shorthand. Existing 96 tests updated to the new acquire shape.

Total: 99 tests across 26 files passing; pnpm typecheck and lint clean.

README: replaces the LocalAgent-based stateful example with a session +
streamText example; LocalAgent escape hatch still mentioned for
permission prompts / terminal handlers / session resume.
…vider

High severity:
- LocalAgentLanguageModel: emit a `system-message-on-bound-session`
  warning when a session-bound model sees a per-turn system message.
  Previously the system prompt was silently dropped because the
  underlying ACP session was already opened.
- createLocalAgentSession: drop the no-op `typeof === "string" ? x : x`
  ternary; the parameter is already correctly typed.

Medium severity:
- provider.ts: extract a shared `buildOneShotAcquire` so
  `buildLanguageModel` and `buildFromAdapter` no longer duplicate the
  same 14-line acquire factory body (DRY).
- LocalAgentProvider: tighten `modelId` parameter from
  `SupportedAgentId | string` to just `SupportedAgentId`; arbitrary
  strings now go through `fromAdapter(...)` so typos like
  `localAgent("clauder")` fail at compile time instead of runtime.
- Add tests covering:
  - system-message-on-bound-session warning
  - no-trailing-user-message warning + zero-block prompt to ACP
  - abort during doStream calls release exactly once
- toJsonValue -> toJsonResult: returns NonNullable<JSONValue> (matches
  LanguageModelV3ToolResult.result) by JSON-roundtripping with a
  String(value) fallback. Drops the over-permissive
  NonNullable<unknown> contract.

Low severity / style:
- Hoist provider name / providerOptions key to `constants.ts` as
  `AI_SDK_PROVIDER_NAME` and `AI_SDK_PROVIDER_OPTIONS_KEY`.
- Rename `historyAlreadyApplied` -> `isSessionBound` everywhere
  (config, AcquiredSession, tests).
- LocalAgentSessionOptions now `extends LocalAgentConnectOptions`
  directly instead of going through the type alias.
- Inline `.filter((p) => p.type === ...)` + `.map(...)` -> single `.map`
  / `.flatMap` to drop two `as { ... }` casts in convert-prompt.
- Trim JSDoc that restated field / function names per AGENTS.md
  "default to NO comments". Comments on `release()` (idempotency
  semantic) and the public `localAgent` / `createLocalAgentSession`
  examples are kept.

Verified: pnpm typecheck clean, pnpm lint 0/0 on 72 files, pnpm test
102 passing across 26 files.
Renames the package and aligns the AI SDK provider surface with the
Vercel AI SDK community convention (factory drops the `Provider` suffix:
`createLocalAgentProvider` -> `createSpawnAgent`).

Public API surface:
- `localAgent` -> `spawnAgent`
- `createLocalAgentProvider` -> `createSpawnAgent`
- `createLocalAgentSession` -> `createSpawnAgentSession`
- `LocalAgent` (runtime class) -> `SpawnAgent`
- `LocalAgent{Provider,LanguageModel,Session,ConnectOptions,ClientInfo,Error,...}`
  -> `SpawnAgent*`
- `providerOptions: { useLocalAgent: { command } }`
  -> `providerOptions: { spawnAgent: { command } }`
- `model.provider` is now `"spawn-agent"`

Constants in src/constants.ts updated: `PACKAGE_NAME`, `PACKAGE_TITLE`,
`AI_SDK_PROVIDER_NAME`, `AI_SDK_PROVIDER_OPTIONS_KEY`.

Files renamed via `git mv` to preserve history:
- packages/use-local-agent/ -> packages/spawn-agent/
- src/local-agent.ts -> src/spawn-agent.ts
- src/ai-sdk/local-agent-language-model.ts -> spawn-agent-language-model.ts
- masterdocs/.../integration-notes-for-use-local-agent.md
  -> integration-notes-for-spawn-agent.md

Includes review-pass cleanup: local `spawnAgent` variables renamed to
`agent` to avoid shadowing the public default export, error re-exports
re-sorted alphabetically, and a major-version changeset documenting the
migration.
`@agentclientprotocol/claude-agent-acp` and `@zed-industries/codex-acp`
now ship as regular dependencies of `spawn-agent` instead of optional
peer dependencies. Users no longer need to install them separately to
drive Claude Code or Codex.

`ai` remains a peer dependency.

Updates README install instructions accordingly.
@aidenybai aidenybai merged commit acb5de7 into main Apr 26, 2026
2 checks passed
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.

2 participants