@agentproto/adapter-mastra-agent 0.4.2 → 0.5.0

package/dist/index.d.ts

@@ -1,77 +1,20 @@
 import { AgentCliHandle, AgentCliRuntime } from '@agentproto/driver-agent-cli';
 export { AgentCliHandle, AgentCliRuntime } from '@agentproto/driver-agent-cli';
 import { MastraToolLike } from '@agentproto/mastra';
-import { Agent, AgentSideConnection, InitializeRequest, InitializeResponse, AuthenticateRequest, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, CancelNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SessionUpdate, ToolKind } from '@agentclientprotocol/sdk';
+import { BuiltinToolId, AgentController, PermissionRules, AgentControllerEvent } from '@mastra/core/agent-controller';
+import { Agent, AgentSideConnection, InitializeRequest, InitializeResponse, AuthenticateRequest, NewSessionRequest, NewSessionResponse, LoadSessionRequest, LoadSessionResponse, PromptRequest, PromptResponse, CancelNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SessionUpdate, ToolKind } from '@agentclientprotocol/sdk';
+import { LanguageModelV3 } from '@ai-sdk/provider';
 import { ModelRef, MemoryConfig } from '@agentproto/agent';
 import { createTool } from '@mastra/core/tools';
+import { LibSQLStore } from '@mastra/libsql';
 import { Memory } from '@mastra/memory';
 
 /**
- * WP2 — the agent side of AIP-44 ACP, backed by a live Mastra agent.
- *
- * Implements the `@agentclientprotocol/sdk` `Agent` interface: handles the
- * session lifecycle and, on `session/prompt`, drives a Mastra agent's
- * `stream()` — relaying each text delta as an `agent_message_chunk`
- * `session/update`, exactly as an IDE/host expects from codex or claude-code.
- *
- * No Mastra-specific protocol knowledge leaks past this file; everything above
- * is the standard ACP wire, so the daemon spawns this like any other arm.
- */
-
-/** A built Mastra agent — only the surface we need (its `stream`). Typed
- *  structurally so we don't couple to a specific @mastra/core version.
- *
- *  We read `fullStream` (the typed chunk union: text deltas AND tool-call /
- *  tool-result events) so tool activity surfaces as ACP `tool_call` updates,
- *  not only the final prose. `textStream` is kept as an optional fallback for
- *  a stripped agent that exposes only text. */
-interface MastraLike {
-    stream(input: string, options?: {
-        abortSignal?: AbortSignal;
-        /** Memory threading — `thread` scopes recall to one ACP session. */
-        memory?: {
-            thread?: string;
-            resource?: string;
-        };
-        /** Max agentic loop steps (tool-call → execute → continue). Default 1 = no loop. */
-        maxSteps?: number;
-    }): Promise<{
-        fullStream?: ReadableStream<unknown>;
-        textStream?: ReadableStream<string>;
-        text?: Promise<string>;
-    }>;
-}
-/** Lazily builds the Mastra agent (so model/key errors surface on the first
- *  prompt with a clear message, not at process spawn). */
-type AgentFactory = () => Promise<MastraLike>;
-/** Pull the user's text out of an ACP prompt (its `text` content blocks). */
-declare function promptText(params: PromptRequest): string;
-declare class MastraAcpAgent implements Agent {
-    #private;
-    constructor(conn: AgentSideConnection, buildAgent: AgentFactory, resource?: string);
-    initialize(_params: InitializeRequest): Promise<InitializeResponse>;
-    authenticate(_params: AuthenticateRequest): Promise<Record<string, never>>;
-    newSession(_params: NewSessionRequest): Promise<NewSessionResponse>;
-    prompt(params: PromptRequest): Promise<PromptResponse>;
-    cancel(params: CancelNotification): Promise<void>;
-    /**
-     * The host applies the `model` (and other operator options) as a `--model`
-     * spawn arg via the manifest `bin_args_template`, then ALSO calls this ACP
-     * config hook (the daemon's default "config" apply path). The model is
-     * already in effect, so this is a no-op that just reports our (empty) set of
-     * runtime-configurable options. Without it the spawn fails with
-     * "Method not found: session/set_config_option".
-     */
-    setSessionConfigOption(_params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
-    /** No agent-specific modes; accept and ignore so a host that sets one
-     *  doesn't error. */
-    setSessionMode(_params: SetSessionModeRequest): Promise<Record<string, never>>;
-}
-
-/**
- * Builds a runnable Mastra agent from an AIP-42 AGENT.md — either a caller's
- * file or a zero-config built-in default — wiring the model, the markdown body
- * as instructions, the SQLite memory, and the workspace toolset.
+ * Builds a runnable Mastra `AgentController` from an AIP-42 AGENT.md — either
+ * a caller's file or a zero-config built-in default — wiring the model, the
+ * markdown body as instructions, the SQLite memory/storage, and the workspace
+ * toolset, then wrapping the built `Agent` as the controller's shared backing
+ * agent. The ACP host drives controller sessions, not the raw agent stream.
  */
 
 /** Cheap OpenRouter coder by default — this is the budget first-party arm,
@@ -94,16 +37,203 @@ interface AgentSourceOptions {
      * wants to grant tools the built-in toolset doesn't cover. No CLI flag.
      */
     extraTools?: Record<string, MastraToolLike>;
+    /**
+     * `false` runs WP-1 parity: a single mode, no tool approvals, yolo
+     * execution — exactly the old raw-stream behavior. Anything else (or
+     * omitted) runs the plan/build/review modes with real tool approvals
+     * (WP-3 default). The `AGENTPROTO_MASTRA_NO_MODES` env var is the
+     * spawn-time equivalent of passing `false` here, for hosts that can't pass
+     * this option directly (e.g. the CLI, which owns no `--no-modes` flag yet
+     * — see this WP's report).
+     */
+    modes?: false | "default";
 }
 /** The built-in AGENT.md used when no file is supplied. */
 declare function defaultAgentManifest(model: string): string;
+/** Every AgentController built-in tool id — WP-1 parity mode disables them ALL
+ *  so the controller adds nothing the raw-stream agent didn't have. Modes-on
+ *  (the default, WP-3/WP-5) re-enables `submit_plan` and `subagent` — see
+ *  `makeAgentFactory`. */
+declare const DISABLED_BUILTIN_TOOL_IDS: readonly BuiltinToolId[];
+/** Session state the controller carries for us (see `initialState` below). */
+interface AdapterControllerState {
+    /** WP-1 parity mode only: skips tool approvals entirely. Unset when modes are on. */
+    yolo?: boolean;
+    /** Modes-on default: seeded from {@link DEFAULT_PERMISSION_RULES}, read by `session.permissions`. */
+    permissionRules?: PermissionRules;
+}
 /**
  * A lazy factory: parses the AGENT.md, builds the Mastra agent with the model
  * resolver, SQLite memory, the markdown body as instructions, and the
- * workspace toolset (matched by tool id), then returns it as the structural
- * `MastraLike` the ACP host needs.
+ * workspace toolset (matched by tool id), then wraps it in an
+ * `AgentController` the ACP host creates sessions on.
  */
-declare function makeAgentFactory(opts?: AgentSourceOptions): () => Promise<MastraLike>;
+declare function makeAgentFactory(opts?: AgentSourceOptions): () => Promise<{
+    controller: AgentController<AdapterControllerState>;
+}>;
+
+/**
+ * WP2 — the agent side of AIP-44 ACP, backed by a Mastra `AgentController`.
+ *
+ * Implements the `@agentclientprotocol/sdk` `Agent` interface: handles the
+ * session lifecycle and, on `session/prompt`, drives a controller `Session`'s
+ * `sendMessage()` — relaying its subscription events as ACP `session/update`s
+ * (text deltas as `agent_message_chunk`, tool activity as `tool_call` /
+ * `tool_call_update`), exactly as an IDE/host expects from codex or
+ * claude-code.
+ *
+ * Beyond the prompt loop, this file bridges the rest of the session surface:
+ *   - `session/load` — reconnect to the Mastra thread keyed by the ACP session
+ *     id and replay its text history as user/agent message chunks
+ *   - `tool_approval_required` / `tool_suspended` — parked controller runs
+ *     surface as `session/request_permission` round-trips
+ *   - `session/set_config_option` (model) and `session/set_mode` — applied via
+ *     `session.model.switch` / `session.mode.switch`, with `model_changed` /
+ *     `mode_changed` relayed back as config/mode session updates
+ *   - image / audio / embedded-resource prompt blocks — passed to
+ *     `sendMessage` as file attachments
+ *
+ * No Mastra-specific protocol knowledge leaks past this file; everything above
+ * is the standard ACP wire, so the daemon spawns this like any other arm.
+ */
+
+/** A prompt attachment in the shape `Session.sendMessage` accepts: text
+ *  attachments carry raw text, binary ones base64 (Mastra inlines `text/*` /
+ *  JSON as fenced code and forwards the rest as model file parts). */
+interface PromptFile {
+    data: string;
+    mediaType: string;
+    filename?: string;
+}
+/** The slice of a thread message that history replay reads (text parts). */
+interface ThreadMessageLike {
+    role: string;
+    content?: {
+        parts?: unknown[];
+    };
+}
+/** The slice of a controller `Session` this host drives. Typed structurally so
+ *  tests can script one and we don't couple to a specific @mastra/core
+ *  version's `Session` generics. */
+interface ControllerSessionLike {
+    subscribe(listener: (event: AgentControllerEvent) => void | Promise<void>): () => void;
+    sendMessage(input: {
+        content: string;
+        files?: PromptFile[];
+    }): Promise<void>;
+    /** Abort the active run and send in one step — the interrupt semantics a
+     *  mid-turn prompt maps to. */
+    steer(input: {
+        content: string;
+    }): Promise<void>;
+    abort(): void;
+    respondToToolApproval(input: {
+        decision: "approve" | "decline" | "always_allow_category";
+        toolCallId?: string;
+        declineContext?: {
+            reason?: string;
+            message?: string;
+        };
+    }): void;
+    respondToToolSuspension(input: {
+        resumeData: unknown;
+        toolCallId?: string;
+    }): Promise<void>;
+    model: {
+        /** The currently-selected model id ('' when none selected yet). */
+        get(): string;
+        switch(input: {
+            modelId: string;
+        }): Promise<void>;
+    };
+    mode: {
+        switch(input: {
+            modeId: string;
+        }): Promise<void>;
+    };
+    thread: {
+        listMessages(input: {
+            threadId: string;
+            limit?: number;
+        }): Promise<ThreadMessageLike[]>;
+    };
+}
+/** The slice of an `AgentController` this host drives (structural, as above).
+ *  `createSession` keys on (resourceId, scope) — one ACP session maps to one
+ *  controller session via a unique scope, with the thread pinned to the ACP
+ *  session id so memory recall is scoped exactly as before. */
+interface ControllerLike {
+    init(): Promise<void>;
+    createSession(opts: {
+        resourceId?: string;
+        scope?: string;
+        threadId?: string;
+    }): Promise<ControllerSessionLike>;
+}
+/** Lazily builds the controller (so model/key/AGENT.md errors surface on the
+ *  first prompt with a clear message, not at process spawn or session/new). */
+type ControllerFactory = () => Promise<{
+    controller: ControllerLike;
+}>;
+/** The model catalog reported through the `model` session config option.
+ *  Mirrors `models.allowed` in the manifest (index.ts) — keep in sync. Any
+ *  Mastra-routable id is still accepted as a value; this is just what the
+ *  client's selector lists. */
+declare const DEFAULT_MODEL_CATALOG: ReadonlyArray<{
+    id: string;
+    name?: string;
+}>;
+/** Pull the user's text out of an ACP prompt (its `text` content blocks). */
+declare function promptText(params: PromptRequest): string;
+/**
+ * Split an ACP prompt into the user's text (its `text` blocks, exactly as
+ * {@link promptText} always did) and file attachments: `image`/`audio` blocks
+ * (base64 + mime type) and embedded `resource` blocks (text or blob contents).
+ * `resource_link` blocks carry no contents to attach — hosts inline referenced
+ * context as `resource` blocks when `embeddedContext` is on — so they are
+ * skipped, as before.
+ */
+declare function promptContent(params: PromptRequest): {
+    text: string;
+    files: PromptFile[];
+};
+declare class MastraAcpAgent implements Agent {
+    #private;
+    constructor(conn: AgentSideConnection, buildController: ControllerFactory, resource?: string, models?: ReadonlyArray<{
+        id: string;
+        name?: string;
+    }>);
+    initialize(_params: InitializeRequest): Promise<InitializeResponse>;
+    authenticate(_params: AuthenticateRequest): Promise<Record<string, never>>;
+    newSession(_params: NewSessionRequest): Promise<NewSessionResponse>;
+    /**
+     * Resume an existing session: reconnect the controller session (scope +
+     * thread keyed by the ACP session id — `createSession` resumes an existing
+     * Mastra thread with full history) and replay the conversation to the
+     * client, as the `session/load` contract requires, via `user_message_chunk`
+     * / `agent_message_chunk` updates.
+     *
+     * Unlike `prompt`, this NEEDS the controller now (replay reads the thread),
+     * so build errors surface as this request's JSON-RPC error rather than a
+     * first-prompt error chunk.
+     */
+    loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse>;
+    prompt(params: PromptRequest): Promise<PromptResponse>;
+    cancel(params: CancelNotification): Promise<void>;
+    /**
+     * The host applies the operator's `model` as a `--model` spawn arg via the
+     * manifest `bin_args_template`, then ALSO calls this ACP config hook (the
+     * daemon's default "config" apply path). Runtime switches go through
+     * `session.model.switch`; a choice made before the controller session
+     * exists is remembered and applied on creation, preserving the invariant
+     * that controller build errors surface on the first prompt.
+     */
+    setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
+    /** Switch the controller session's mode (the catalog itself is controller
+     *  config — WP-3). Mode-change confirmations reach the client via the
+     *  session-lifetime `mode_changed` → `current_mode_update` relay. */
+    setSessionMode(params: SetSessionModeRequest): Promise<Record<string, never>>;
+}
 
 /**
  * WP1 — AIP-42 `model:` ref -> a model Mastra's `Agent` can run.
@@ -114,7 +244,12 @@ declare function makeAgentFactory(opts?: AgentSourceOptions): () => Promise<Mast
  * the provider's key from the environment. So the resolver is a thin,
  * *validated* pass-through: extract the ref string, sanity-check the shape,
  * surface a friendly error when the obvious provider key is missing, and hand
- * the string to Mastra. No bespoke provider wiring, no extra ai-sdk deps.
+ * the string to Mastra.
+ *
+ * Exception: Anthropic OAuth Access Tokens (OATs, `sk-ant-oat*`) need
+ * `Authorization: Bearer`, not `x-api-key`. Mastra's router always sends
+ * `x-api-key`, so OATs bypass the string path — the resolver builds the
+ * ai-sdk model directly via `createAnthropic({ authToken })`.
  */
 
 /** Pull the model id string out of an AIP-42 `ModelRef` (string | { ref }). */
@@ -123,10 +258,15 @@ declare function modelRefToString(ref: ModelRef): string;
 declare function providerOf(modelId: string): string;
 /**
  * Resolve an AIP-42 model ref to the value Mastra's `Agent` constructor takes.
- * Returns the `provider/model` string — Mastra routes it. `env` defaults to
- * `process.env`; injectable for tests.
+ *
+ * For most providers this returns the `provider/model` string and Mastra's
+ * internal router does the rest. For Anthropic OAuth Access Tokens (OATs) it
+ * returns a pre-built ai-sdk `LanguageModel` with `authToken` so the token
+ * is sent as `Authorization: Bearer` instead of `x-api-key`.
+ *
+ * `env` defaults to `process.env`; injectable for tests.
  */
-declare function resolveMastraModel(ref: ModelRef, env?: Record<string, string | undefined>): string;
+declare function resolveMastraModel(ref: ModelRef, env?: Record<string, string | undefined>): string | LanguageModelV3;
 
 /**
  * Workspace toolset — gives the Mastra agent the ability to inspect, edit, and
@@ -137,6 +277,38 @@ declare function resolveMastraModel(ref: ModelRef, env?: Record<string, string |
  * execution runs with `cwd` and a timeout, and is gated by `allowExec` (the CLI
  * sets it from `AGENTPROTO_MASTRA_NO_EXEC`). The agent only ever touches the
  * directory the daemon spawned it in.
+ *
+ * ## Tool id vocabulary
+ *
+ * Two tool-id vocabularies exist in this codebase for the same operations:
+ * this adapter's own coding-agent style (`list_dir`, `read_file`, `write_file`,
+ * `run_command`, ...) and the daemon's MCP-filesystem-compatible style
+ * (`directory_list`, `file_read`, `file_write`, `file_info`, `command_execute`,
+ * matching `packages/runtime/src/fs-tools.ts` / `command-tools.ts`). Apps'
+ * AGENT.md `tools:` lists have shipped with either vocabulary (see
+ * `packages/apps/src/media-viewer/agents/cataloger.ts` mixing `list_dir` +
+ * `file_info`), so both id sets resolve here — the daemon-style ids are
+ * aliases over the same implementations, plus `file_info` and `command_execute`
+ * which have no adapter-style equivalent.
+ *
+ * ## Fail-fast for unresolved tool refs
+ *
+ * `resolveTool` in `default-agent.ts` no longer silently drops an AGENT.md
+ * tool ref that doesn't match anything here — see `makeUnwiredToolStub`. A
+ * declared-but-unwired tool stays visible to the model and fails fast and
+ * clearly instead of the model either never seeing it (silent drop) or
+ * hallucinating a call the SDK can't resolve, which used to surface as an
+ * opaque `NoSuchToolError` this adapter's ACP layer then dropped on the
+ * floor (see `tool-call-map.ts`'s `tool-error` handling), leaving the turn
+ * looking hung with zero recorded tool calls.
+ *
+ * ## Execution guard
+ *
+ * Every tool's `execute` is wrapped with a hard timeout (`execTimeoutMs`,
+ * default 120s) so a stalled fs op or an unresponsive allowlist check can't
+ * block a turn indefinitely — past the deadline the call rejects with a
+ * clear timeout error (surfaced to the model as a normal tool failure) in
+ * place of an unbounded hang.
  */
 
 interface WorkspaceToolsOptions {
@@ -144,7 +316,7 @@ interface WorkspaceToolsOptions {
     cwd: string;
     /** When false, `run_command` (and the other exec-gated tools) are omitted. Default true. */
     allowExec?: boolean;
-    /** Per-command timeout (ms). Default 120_000. */
+    /** Per-tool execution timeout (ms), enforced on every tool by `withTimeoutGuard`. Default 120_000. */
     execTimeoutMs?: number;
     /**
      * Extra tools merged over the built-ins, keyed by id — lets an embedding
@@ -161,6 +333,214 @@ declare function resolveInCwd(cwd: string, p: string): string;
  */
 declare function makeWorkspaceTools(opts: WorkspaceToolsOptions): Record<string, ReturnType<typeof createTool>>;
 
+/**
+ * Zero-dependency HTTP client for the agentproto daemon.
+ *
+ * The adapter is spawned as an ACP child with `AGENTPROTO_SESSION_ID` /
+ * `AGENTPROTO_PARENT_SESSION_ID` in its env, but no daemon URL/token — unlike
+ * the CLI (`packages/cli/src/commands/_daemon-helpers.ts`, read as reference),
+ * this package cannot import `@agentproto/runtime` or `@agentproto/cli`
+ * (would pull the whole daemon runtime into an agent process). So this is a
+ * deliberately smaller reimplementation of that discovery order:
+ *
+ *   1. `AGENTPROTO_DAEMON_URL` env (+ optional `AGENTPROTO_DAEMON_TOKEN`)
+ *   2. `<cwd>/.agentproto/runtime.json`
+ *   3. `~/.agentproto/runtime.json`
+ *   4. central registry `~/.agentproto/daemons/*.json`, newest-mtime-first
+ *
+ * Unlike the CLI helper, this skips the `workspaces.json` walk (needs
+ * `@agentproto/runtime`'s config loader) and the declared-port preference
+ * in the central registry (needs `loadConfig()`). Good enough for an agent
+ * process discovering the daemon that spawned it or one on the same host.
+ *
+ * A runtime.json / registry entry whose `pid` is dead (`process.kill(pid, 0)`
+ * throwing anything but `EPERM`) is never trusted — same footgun the CLI
+ * helper guards against (a crashed daemon's stale token 401ing a fresh one
+ * on the same port).
+ */
+interface DaemonEndpoint {
+    url: string;
+    token?: string;
+    /** Path of the runtime.json / registry file the endpoint came from.
+     *  Undefined when the endpoint came from env vars. */
+    sourcePath?: string;
+}
+/** Thrown when no daemon endpoint can be discovered. */
+declare class DaemonNotFoundError extends Error {
+    constructor(message?: string);
+}
+/** Thrown on a non-2xx daemon HTTP response. */
+declare class DaemonHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+interface DiscoverDaemonOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Override `homedir()` for BOTH `~/.agentproto/runtime.json` and the
+     *  central registry dir (unless `registryDir` also overrides the latter
+     *  separately) — test hook, so discovery never has to touch a real
+     *  developer machine's `~/.agentproto`. */
+    homeDir?: string;
+    /** Override the central registry directory — test hook. Wins over `homeDir`. */
+    registryDir?: string;
+    /** Override the liveness check for a runtime.json / registry entry's
+     *  `pid` — test hook. Defaults to a real `process.kill(pid, 0)` probe. */
+    isPidAlive?: (pid: number) => boolean;
+}
+/**
+ * Resolve the first live daemon endpoint, in the order documented above.
+ * Returns undefined when nothing live is found.
+ */
+declare function discoverDaemonEndpoint(opts?: DiscoverDaemonOptions): Promise<DaemonEndpoint | undefined>;
+interface StartAgentInput {
+    adapter: string;
+    cwd?: string;
+    model?: string;
+    prompt?: string;
+    label?: string;
+}
+interface PromptAgentOptions {
+    /** Cancel the in-flight turn and deliver this prompt instead. Default false. */
+    interrupt?: boolean;
+    /** `false` returns as soon as the prompt is queued/validated, without
+     *  waiting for the turn to drain. Default true (blocking). */
+    wait?: boolean;
+}
+interface ListSessionsOptions {
+    includeArchived?: boolean;
+    kind?: string;
+}
+interface ReadOutputOptions {
+    format?: "markdown" | "json";
+}
+interface PollEventsOptions {
+    /** Cursor from a prior call's `nextSeq`. Omit to start from the beginning. */
+    since?: number;
+    /** Client-side filter on each record's `kind` field. Omit → all kinds. */
+    types?: string[];
+    limit?: number;
+}
+interface PollEventsResult {
+    sessionId: string;
+    events: Array<Record<string, unknown>>;
+    nextSeq: number;
+    complete: boolean;
+}
+interface DaemonClientOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable fetch — test hook. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Pre-resolved endpoint — skips discovery, mainly a test hook. */
+    endpoint?: DaemonEndpoint;
+    /** Test hooks forwarded to {@link discoverDaemonEndpoint}. */
+    homeDir?: string;
+    registryDir?: string;
+    isPidAlive?: (pid: number) => boolean;
+}
+/**
+ * Thin HTTP client over the daemon's REST surface (`packages/runtime/src/http-server.ts`,
+ * read-only reference — this package never imports it). Discovers the daemon
+ * endpoint lazily on first call and caches it; a connection failure triggers
+ * one re-discovery attempt (covers a daemon restart on the same well-known
+ * runtime.json / registry path but a new port/token).
+ */
+declare class DaemonClient {
+    private readonly cwd;
+    private readonly env;
+    private readonly fetchImpl;
+    private readonly homeDir;
+    private readonly registryDir;
+    private readonly isPidAlive;
+    private cachedEndpoint;
+    constructor(opts?: DaemonClientOptions);
+    private resolveEndpoint;
+    private request;
+    /**
+     * Spawn a child session — `POST /sessions/agent`. `parentSessionId` is
+     * derived from `AGENTPROTO_SESSION_ID` (set by the daemon on every
+     * ACP-spawned adapter) when present, so session lineage is recorded
+     * without the caller having to thread it through.
+     */
+    startAgent(input: StartAgentInput): Promise<Record<string, unknown>>;
+    /** Send a follow-up turn to a live session — `POST /sessions/:id/prompt`. */
+    promptAgent(sessionId: string, text: string, opts?: PromptAgentOptions): Promise<Record<string, unknown>>;
+    /** List sessions — `GET /sessions`. */
+    listSessions(opts?: ListSessionsOptions): Promise<{
+        sessions: Array<Record<string, unknown>>;
+    }>;
+    /**
+     * Read a session's transcript — `GET /sessions/:id/export`. Chosen over
+     * `/sessions/:id/conversation` (needs a provider-native store registered
+     * for the adapter; not every adapter has one) and `/sessions/:id/preview`
+     * (a raw ring-buffer snapshot, not a rendered transcript): `/export`
+     * works for ANY agent-cli session, falling back to the daemon's own
+     * `events.jsonl` capture when no provider-native reader is registered
+     * (`source: "auto"`, see `transcript-export.ts`) — the one built for
+     * programmatic reads of "what did this session say".
+     */
+    readOutput(sessionId: string, opts?: ReadOutputOptions): Promise<Record<string, unknown>>;
+    /**
+     * Cursor-based poll of a session's structured event log —
+     * `GET /sessions/:id/events`. NOT the same event source as the MCP
+     * `session_events_poll` tool: that tool reads the daemon's in-memory,
+     * cross-session `EventRing` (turn-end/awaiting-input/exited/... lifecycle
+     * events, `packages/runtime/src/orchestration-tools.ts:528`), which has no
+     * plain-HTTP equivalent — it's only reachable over the MCP JSON-RPC
+     * transport, which this zero-dependency client doesn't speak. This route
+     * is the per-SESSION structured `events.jsonl` transcript instead
+     * (`packages/runtime/src/transcript-writer.ts`): cursor-based via
+     * `since`/`nextSeq` same as the MCP tool, and its records DO carry many of
+     * the same `kind`s (`turn-end`, `error`, `permission-resolved`, ...) — but
+     * it has no `exited` / `session:spawned` records (those are registry
+     * state changes, not transcript writes) and no cross-session fan-in
+     * (`sessionIds` filter). `types` is therefore filtered client-side here
+     * against each record's `kind`, not sent as a query param.
+     *
+     * WP-6 (`AgentprotoSignalProvider`, polling every 5s): this is a
+     * non-blocking snapshot read, so it's a direct fit for a poll loop. If
+     * WP-6 needs the actual cross-session lifecycle events (`exited`,
+     * `session:spawned`, multi-session fan-in), it either needs its own
+     * light MCP JSON-RPC client to call `session_events_poll` directly, or
+     * per-session `GET /sessions/:id/wait?since=&event=` (a blocking
+     * long-poll over the SAME EventRing `session_events_poll` reads, but
+     * scoped to one session and one event name at a time — no `types` array).
+     */
+    pollEvents(sessionId: string, opts?: PollEventsOptions): Promise<PollEventsResult>;
+}
+
+/**
+ * Daemon sub-agent-spawning tools — the Mastra-tool front for
+ * {@link DaemonClient}. Lets the agent spawn/prompt/read/list sibling
+ * sessions through the agentproto daemon (any adapter: claude-code, hermes,
+ * another mastra-agent, ...), mirroring `workspace-tools.ts`'s style
+ * (`createTool`, zod schemas, a bounded `tail` on large text output, a
+ * per-call timeout guard).
+ *
+ * Every tool fails fast with a clear message when no daemon is discoverable
+ * ({@link DaemonNotFoundError}'s message) instead of hanging — `DaemonClient`
+ * throws that before any network call is attempted.
+ */
+
+interface DaemonToolsOptions {
+    /** Reuse a pre-built client (mainly a test hook) — one is built otherwise. */
+    client?: DaemonClient;
+    /** Forwarded to `new DaemonClient(...)` when no `client` is supplied. */
+    clientOptions?: DaemonClientOptions;
+    /** Per-tool execution timeout (ms). Default 30_000 — network calls, not
+     *  local fs/exec, so a shorter default than workspace-tools' 120_000. */
+    execTimeoutMs?: number;
+}
+/**
+ * Build the daemon sub-agent-spawning toolset: `agent_start`, `agent_prompt`,
+ * `agent_output`, `session_list`. Tool ids match `tool-categories.ts`'s
+ * `CATEGORY_BY_TOOL` entries exactly (all category `mcp`, default policy
+ * `ask`).
+ */
+declare function makeDaemonTools(opts?: DaemonToolsOptions): Record<string, ReturnType<typeof createTool>>;
+
 /**
  * SQLite-backed memory for the agent, via Mastra's LibSQL store.
  *
@@ -176,6 +556,13 @@ type MastraMemoryLike = Memory;
 /** Resolve the SQLite file path, creating the parent dir. `AGENTPROTO_MASTRA_MEMORY_DB`
  *  wins; otherwise `~/.agentproto/mastra-agent/memory.db`. */
 declare function resolveMemoryDbPath(env?: Record<string, string | undefined>): string;
+/**
+ * Build the LibSQL store backing the agent's memory. Exposed separately so the
+ * `AgentController` can share the SAME store instance as its `storage` (thread
+ * rows, per-thread settings) — two stores on one SQLite file would race each
+ * other on writes.
+ */
+declare function buildSqliteStore(env?: Record<string, string | undefined>): LibSQLStore;
 /**
  * Build a Mastra `Memory` from an AIP-42 `memory:` config. Returns `undefined`
  * when memory is disabled (`scope: "none"`) so `buildMastraAgent` attaches none.
@@ -184,58 +571,61 @@ declare function resolveMemoryDbPath(env?: Record<string, string | undefined>):
  *   replay into context). Defaults to 20.
  * - Semantic recall is left off (it needs an embedder + vector index) — this is
  *   conversation-history memory, the SQLite ask.
+ * - `store` lets the caller share one LibSQL store between this memory and the
+ *   AgentController's storage; omitted, a fresh store is built.
  */
-declare function buildSqliteMemory(config?: MemoryConfig, env?: Record<string, string | undefined>): MastraMemoryLike | undefined;
+declare function buildSqliteMemory(config?: MemoryConfig, env?: Record<string, string | undefined>, store?: LibSQLStore): MastraMemoryLike | undefined;
 
 /**
- * Pure mapping from Mastra `fullStream` chunks to AIP-44 ACP `session/update`
- * payloads. Kept dependency-light (no SDK import beyond types) and side-effect
- * free so it is straightforward to unit-test; the ACP host (acp-host.ts) owns
- * the wire/IO and just forwards whatever this returns.
+ * Pure mapping from Mastra `AgentController` session events to AIP-44 ACP
+ * `session/update` payloads. Kept dependency-light (type-only imports) and
+ * IO-free so it is straightforward to unit-test; the ACP host (acp-host.ts)
+ * owns the wire and just forwards whatever this returns.
+ *
+ * A controller session (`session.subscribe`) emits `AgentControllerEvent`s.
+ * We surface three kinds:
+ *   - `message_update` → ACP `agent_message_chunk` (assistant prose, as a delta)
+ *   - `tool_start`     → ACP `tool_call`        (a tool started, status in_progress)
+ *   - `tool_end`       → ACP `tool_call_update` (that tool finished: completed/failed)
+ * Everything else (message_start/end, tool_input_*, usage, display state,
+ * agent_start/end, error, …) has no ACP surface here — `error` and `agent_end`
+ * are read by the host to pick the turn's stop reason, not mapped to updates.
  *
- * Mastra emits a typed chunk union on `agent.stream(...).fullStream`. We care
- * about three kinds:
- *   - `text-delta`  → ACP `agent_message_chunk` (assistant prose)
- *   - `tool-call`   → ACP `tool_call`        (a tool started, status in_progress)
- *   - `tool-result` → ACP `tool_call_update` (that tool finished/failed)
- * Everything else (reasoning, step boundaries, finish, …) is not surfaced.
+ * `message_update` carries the FULL message accumulated so far (Mastra's run
+ * engine re-emits the whole `MastraDBMessage` on every text delta), while ACP
+ * `agent_message_chunk` is a delta wire. The mapper is therefore a stateful
+ * factory: it remembers how much of each message's text it has already
+ * relayed and emits only the new suffix. Create one mapper per prompt turn.
+ *
+ * `tool_end` covers BOTH a successful tool result and a failed one (a tool's
+ * own `execute` throwing, or the SDK failing to resolve the call) — the old
+ * raw-stream `tool-result`/`tool-error` split collapses into `isError`.
+ * Dropping failures used to leave the matching `tool_call` stuck
+ * "in_progress" forever on the ACP wire, so failed calls map to a `failed`
+ * update carrying the error text.
  */
 
-/** The narrow slice of a Mastra fullStream chunk we read. Typed structurally
- *  so we don't couple to a specific @mastra/core version.
- *  Mastra 1.45 wraps all chunk data in a `payload` field. */
-type MastraStreamChunk = {
-    type: "text-delta";
-    payload?: {
-        text?: string;
-    };
-} | {
-    type: "tool-call";
-    payload?: {
-        toolCallId?: string;
-        toolName?: string;
-        args?: unknown;
-    };
-} | {
-    type: "tool-result";
-    payload?: {
-        toolCallId?: string;
-        result?: unknown;
-        isError?: boolean;
-    };
-};
 /** Map a workspace tool id to the ACP {@link ToolKind} that drives client
  *  icon/UI treatment. Unknown ids fall back to "other". */
 declare function toolKindFor(toolName: string): ToolKind;
 /** A short, human-readable title for a tool call, e.g. `run_command: ls -la`
  *  or `read_file: src/index.ts`. Falls back to the bare tool name. */
 declare function toolCallTitle(toolName: string, args: unknown): string;
+/** Concatenate a message's plain-text parts (assistant prose; reasoning and
+ *  tool-invocation parts are not ACP message text). Also used by the host's
+ *  `session/load` replay to render prior thread messages. */
+declare function messageText(message: {
+    content?: {
+        parts?: unknown[];
+    };
+}): string;
 /**
- * Translate one Mastra chunk into an ACP `session/update` payload, or `null`
- * when the chunk has no ACP surface (or is missing the ids we need). The ACP
- * host wraps the result with the `sessionId`.
+ * Create a stateful event mapper for one prompt turn: translates each
+ * controller event into an ACP `session/update` payload, or `null` when the
+ * event has no ACP surface (or carries no new text). The ACP host wraps each
+ * result with the `sessionId`.
  */
-declare function chunkToSessionUpdate(chunk: MastraStreamChunk): SessionUpdate | null;
+declare function createEventMapper(): (event: AgentControllerEvent) => SessionUpdate | null;
 
 /**
  * Boots the ACP server over stdio — the standard wiring for a spawned ACP
@@ -243,7 +633,7 @@ declare function chunkToSessionUpdate(chunk: MastraStreamChunk): SessionUpdate |
  * JSON-RPC to stdout and reads from stdin.
  */
 
-declare function runAcpOverStdio(buildAgent: AgentFactory): AgentSideConnection;
+declare function runAcpOverStdio(buildController: ControllerFactory): AgentSideConnection;
 
 /**
  * @agentproto/adapter-mastra-agent — the first-party agentproto agent.
@@ -260,4 +650,4 @@ declare function runAcpOverStdio(buildAgent: AgentFactory): AgentSideConnection;
 declare const mastraAgent: AgentCliHandle;
 declare function mastraAgentRuntime(): AgentCliRuntime;
 
-export { DEFAULT_MODEL, DEFAULT_TOOL_IDS, MastraAcpAgent, type MastraLike, type MastraStreamChunk, buildSqliteMemory, chunkToSessionUpdate, defaultAgentManifest, makeAgentFactory, makeWorkspaceTools, mastraAgent, mastraAgentRuntime, modelRefToString, promptText, providerOf, resolveInCwd, resolveMastraModel, resolveMemoryDbPath, runAcpOverStdio, toolCallTitle, toolKindFor };
+export { type ControllerFactory, type ControllerLike, type ControllerSessionLike, DEFAULT_MODEL, DEFAULT_MODEL_CATALOG, DEFAULT_TOOL_IDS, DISABLED_BUILTIN_TOOL_IDS, DaemonClient, type DaemonClientOptions, type DaemonEndpoint, DaemonHttpError, DaemonNotFoundError, type DaemonToolsOptions, MastraAcpAgent, type PromptFile, type ThreadMessageLike, buildSqliteMemory, buildSqliteStore, createEventMapper, defaultAgentManifest, discoverDaemonEndpoint, makeAgentFactory, makeDaemonTools, makeWorkspaceTools, mastraAgent, mastraAgentRuntime, messageText, modelRefToString, promptContent, promptText, providerOf, resolveInCwd, resolveMastraModel, resolveMemoryDbPath, runAcpOverStdio, toolCallTitle, toolKindFor };