@superatomai/sdk-node 0.0.52-dsp → 0.0.53-dsp

package/dist/index.d.ts

@@ -4472,6 +4472,616 @@ interface DashboardAgentCollectionConfig {
 }
 declare function registerDashboardAgentCollection(sdk: SuperatomSDK, config?: DashboardAgentCollectionConfig): void;
 
+/**
+ * Coding-agent driver contract — one shape over every harness (codex today;
+ * claude-code / opencode / pi next). Callers depend on this file only, never on
+ * a harness SDK, so swapping the agent behind a task is a config change.
+ *
+ * Deliberately narrower than the harness SDKs it wraps: the three things a
+ * production run needs and that harness abstractions usually omit — real abort,
+ * real token accounting, and structured tool args — are part of the contract,
+ * not per-driver extras.
+ */
+type AgentEventKind = 'turn' | 'message' | 'reasoning' | 'command' | 'tool' | 'file' | 'todo' | 'error';
+interface AgentEvent {
+    kind: AgentEventKind;
+    /** Stable across started→updated→completed, so a UI updates one block in place. */
+    id?: string;
+    text?: string;
+    command?: string;
+    output?: string;
+    /** Tool calls carry real parsed args — never SQL scraped back out of a shell string. */
+    tool?: {
+        server?: string;
+        name: string;
+        args?: unknown;
+    };
+    status?: 'in_progress' | 'completed' | 'failed';
+    done?: boolean;
+}
+interface AgentUsage {
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Tool + command invocations. With tokens, separates "silently did nothing" from a real run. */
+    toolCalls: number;
+    /** Only when the harness reports it — codex reports tokens but not cost. */
+    costUSD?: number;
+}
+interface AgentRunHandlers {
+    /** Formatted live stream: assistant text deltas plus one-line tool/command markers. */
+    onOutput?: (chunk: string) => void;
+    onEvent?: (event: AgentEvent) => void;
+    /** Assistant prose only — safe to show a non-technical user as progress. */
+    onNarration?: (text: string) => void;
+    onUsage?: (usage: AgentUsage) => void;
+    /**
+     * Polled once the turn is live. When it returns true the run ends immediately —
+     * for tasks whose deliverable is a file, the moment it exists there is nothing
+     * left to wait for.
+     */
+    doneWhen?: () => boolean | Promise<boolean>;
+}
+type AgentRunStatus = 'completed' | 'early' | 'aborted' | 'error';
+interface AgentRunResult {
+    status: AgentRunStatus;
+    /** The final assistant message. */
+    answer: string;
+    ms: number;
+    usage: AgentUsage;
+    /**
+     * Set when status is 'error'. Covers stream-reported failures too, which arrive
+     * as events rather than thrown exceptions — a swallowed provider error is the
+     * failure mode that otherwise looks like a successful empty run.
+     */
+    error?: string;
+    sessionId?: string;
+}
+interface McpServerSpec {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+interface CodingAgentSessionOptions {
+    /** Working directory the agent operates in. Scope it to a runtime dir, not a source checkout. */
+    cwd: string;
+    model?: string;
+    /** Resume a prior conversation — the value a previous run returned as sessionId. */
+    resumeId?: string;
+    /** Tools, as MCP servers. Keyed by server name, which shows up on every tool event. */
+    mcpServers?: Record<string, McpServerSpec>;
+    /**
+     * Extra env for the agent process. By default only a small allowlist is passed
+     * through (see ENV_ALLOWLIST) so an agent with shell access can't read the
+     * backend's own secrets out of its environment.
+     */
+    env?: Record<string, string>;
+    /** Opt out of env scrubbing. Only for local debugging. */
+    inheritEnv?: boolean;
+}
+interface CodingAgentSession {
+    readonly harness: string;
+    /** Structured event log vs. a raw terminal stream — the UI picks its renderer from this. */
+    readonly kind: 'events' | 'pty';
+    run(prompt: string, handlers?: AgentRunHandlers, signal?: AbortSignal): Promise<AgentRunResult>;
+    /** Rolling structured events, for replay when a client reconnects mid-run. */
+    events(): AgentEvent[];
+    /** Rolling formatted text, same purpose as events() for text-oriented views. */
+    buffer(): string;
+    busy(): boolean;
+    /** Persist this and pass it back as resumeId to continue the conversation. */
+    sessionId(): string | undefined;
+    /** Abandon the conversation; the next run starts fresh. */
+    reset(): void;
+    dispose(): void;
+}
+
+/**
+ * Harness registry. Kept separate from index.ts so collection.ts can reach the
+ * factory without importing the module's own barrel (a cycle tsup would have to
+ * resolve at bundle time).
+ */
+type Harness = 'codex';
+declare function createCodingAgentSession(harness: Harness, opts: CodingAgentSessionOptions): CodingAgentSession;
+
+/**
+ * Codex driver — OpenAI Codex via @openai/codex-sdk.
+ *
+ * FORMAT CONTRACT: written against @openai/codex-sdk 0.149.1. Harness event
+ * shapes drift; if the event log goes blank after an SDK bump, check normEvent
+ * against the package's dist/index.d.ts first.
+ *
+ * Three things this leans on that the SDK gives natively, so we don't reinvent
+ * them: TurnOptions.signal (real cancellation), TurnCompletedEvent.usage (token
+ * accounting), and mcp_tool_call items (tool args arrive parsed, not scraped
+ * out of a shell command string).
+ *
+ * The package is an optionalDependency: every deployment gets it, but an
+ * install that cannot fetch the ~309MB platform binary skips it rather than
+ * failing. It is therefore loaded dynamically and its types mirrored
+ * structurally below, so a VM without it still builds, starts, and runs
+ * everything else — only the coding agent reports itself unavailable.
+ */
+type CodexSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+type CodexReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra';
+interface CodexSessionOptions extends CodingAgentSessionOptions {
+    reasoningEffort?: CodexReasoningEffort;
+    /**
+     * Filesystem reach. Default 'workspace-write' — the agent writes its
+     * deliverable into cwd and nothing else. 'danger-full-access' hands a
+     * shell-capable agent the whole box; don't use it on a client VM.
+     */
+    sandboxMode?: CodexSandboxMode;
+    /** Network for commands the agent runs. Off by default; MCP tools don't need it. */
+    networkAccessEnabled?: boolean;
+    apiKey?: string;
+    baseUrl?: string;
+    /** Raw `--config` overrides merged into the codex config. */
+    extraConfig?: Record<string, unknown>;
+    approvalPolicy?: 'never' | 'on-request' | 'on-failure' | 'untrusted';
+}
+declare function createCodexSession(opts: CodexSessionOptions): CodingAgentSession;
+
+/**
+ * What makes an agent fire.
+ *
+ * Declared ON the definition, deliberately. If triggers lived at the call sites
+ * instead — a counter in the conversation handler, a hook in the kb-nodes
+ * collection — then adding an agent would mean editing unrelated files across
+ * the backend, and no one file would tell you when an agent actually runs.
+ * Here, an agent's folder plus its definition is the whole story.
+ *
+ * The deployment's only job is to announce that something happened:
+ *
+ *   emitAgentEvent('conversation.answered', { threadId })
+ *   emitAgentEvent('kb-node.changed', { id, op: 'update' })
+ *
+ * Which agents care, and how many events it takes, is the agents' business.
+ */
+type AgentTrigger = 
+/** Only runCodingAgent(). The default. */
+{
+    type: 'manual';
+}
+/** Every N milliseconds while the process is up. */
+ | {
+    type: 'interval';
+    everyMs: number;
+}
+/**
+ * On a named event. `debounceMs` collapses a burst into one run — editing
+ * five knowledge nodes in a row is one reason to rebuild, not five.
+ */
+ | {
+    type: 'event';
+    on: string | string[];
+    debounceMs?: number;
+}
+/**
+ * Every Nth occurrence of an event. The count is PERSISTED, so "after 10
+ * questions" survives a restart instead of silently starting over.
+ */
+ | {
+    type: 'count';
+    on: string;
+    every: number;
+};
+interface TriggerFireInfo {
+    agentId: string;
+    /** What set it off, for the log line. */
+    reason: string;
+    payload?: unknown;
+}
+/** Notified after every triggered run — for recording history or alerting. */
+type RunListener = (record: AgentRunRecord, info: TriggerFireInfo) => void;
+declare function onAgentRun(fn: RunListener): () => void;
+/**
+ * Tell the agents something happened. Safe to call from anywhere, including a
+ * request path — it never throws and never blocks: matching runs are started,
+ * not awaited.
+ */
+declare function emitAgentEvent(event: string, payload?: unknown): void;
+/**
+ * Start interval triggers. Call once at startup, after registerCodingAgents.
+ * Event and count triggers need nothing started — they wake on emitAgentEvent.
+ */
+declare function startAgentTriggers(): void;
+declare function stopAgentTriggers(): void;
+/** What fires each agent — for a startup log or an admin screen. */
+declare function describeTriggers(): Array<{
+    agentId: string;
+    triggers: string[];
+}>;
+
+/**
+ * What a coding agent IS.
+ *
+ * An agent is a job description, not code that does the job: instructions, the
+ * inputs it should be handed, the tools it may reach, the deliverable it must
+ * produce, and what we do with that deliverable. The agent itself decides HOW —
+ * it can read the inputs, write and run scripts over them, check its own work,
+ * and iterate. That is the whole reason for using a coding agent rather than a
+ * single LLM call: the job's data never has to fit in a context window.
+ *
+ * Adding an agent is a folder with a system.md, one file implementing this
+ * interface, and one line in the registry. Nothing else changes.
+ */
+/** The disposable directory one run happens in. */
+interface Workspace {
+    /** Absolute path the agent runs in. Everything below is relative to it. */
+    dir: string;
+    /** Unique per run — also the folder name, so runs never collide. */
+    runId: string;
+    /** Write a file into the workspace, creating parent directories. */
+    write(relPath: string, contents: string): Promise<void>;
+    /** Write JSON (pretty-printed — the agent reads these by eye as often as by script). */
+    writeJson(relPath: string, value: unknown): Promise<void>;
+    /** Write one JSON object per line. The right shape for anything the agent will stream or grep. */
+    writeJsonl(relPath: string, rows: unknown[]): Promise<void>;
+    /** Read a file the agent produced. Returns null when it isn't there. */
+    read(relPath: string): Promise<string | null>;
+    /** Absolute path for a workspace-relative path — for telling the agent where to write. */
+    pathTo(relPath: string): string;
+}
+/** Minimal validator shape, so this file needn't depend on a schema library. */
+interface OutputValidator<T> {
+    /** Throw with a useful message, or return the parsed value. Zod's `.parse` satisfies this. */
+    parse(value: unknown): T;
+}
+interface OutputContract<T> {
+    /**
+     * Workspace-relative path the agent must write, e.g. 'out/concepts.json'.
+     * Nothing else counts as the deliverable: the run ends the moment this
+     * appears, and a run that finishes without it is a failure, not a partial
+     * success.
+     */
+    file: string;
+    /** Validated before anything is persisted, so a malformed run fails loudly and applies nothing. */
+    schema: OutputValidator<T>;
+}
+/** What apply() reports back — surfaced in the run record and to the caller. */
+interface ApplySummary {
+    /** One line a human can read in a log or the UI. */
+    summary: string;
+    /** Whatever counts for this agent: {created, updated, skipped}, etc. */
+    counts?: Record<string, number>;
+    /** Anything the caller may want to inspect or show. */
+    details?: unknown;
+}
+interface AgentRunContext {
+    projectId?: string;
+    userId?: string;
+    /**
+     * This run's id — also the workspace directory name. Passed so apply() can
+     * stamp whatever it persists with the run that produced it, which is the
+     * only link from a stored result back to the inputs and scripts behind it.
+     */
+    runId?: string;
+    /** The run's workspace, for an apply() that needs a file the agent left. */
+    workspaceDir?: string;
+    /** Cancels the run; forwarded to the driver's real abort. */
+    signal?: AbortSignal;
+    /** Live progress. Populated for chat mode; a task run may also stream to a log. */
+    onOutput?: (chunk: string) => void;
+    onEvent?: (event: AgentEvent) => void;
+    onUsage?: (usage: AgentUsage) => void;
+}
+/**
+ * How much an agent carries between runs.
+ *
+ * Codex manages its own context: it tracks the window and compacts when it
+ * crosses `auto_compact_token_limit`, emitting a ContextCompacted event. That
+ * happens with no involvement from us, so a persistent session survives
+ * indefinitely on its own. (The mechanism is in the engine but not the
+ * TypeScript SDK — Thread exposes only id/run/runStreamed — which is why there
+ * is nothing here to call.)
+ *
+ * What compaction cannot do is make the session authoritative. It summarises to
+ * make room, so detail is lost by design; and ~/.codex/sessions is a directory
+ * on one machine, not the database. So durable facts belong in `memory/` files
+ * and in the tables the agent writes through apply(), with the session free to
+ * compact itself as it likes. Memory on disk, context managed by codex.
+ */
+interface SessionPolicy {
+    /**
+     * 'per-run'    a fresh harness session each time (default).
+     * 'persistent' resume the same session across runs, so the agent keeps its
+     *              working context. Always paired with durable files — never rely
+     *              on it alone.
+     */
+    scope?: 'per-run' | 'persistent';
+    /**
+     * 'per-run'    a throwaway directory per run (default); pruned by keepRuns.
+     * 'persistent' one directory the agent owns across runs. `memory/` survives
+     *              untouched; `input/` is cleared each run so a stale input can
+     *              never be mistaken for this run's.
+     */
+    workspace?: 'per-run' | 'persistent';
+    /**
+     * Safety valve, not the compaction mechanism — codex already compacts on its
+     * own. Starts a fresh session after this many runs while keeping the
+     * workspace, for when you want a hard ceiling on how much summarised history
+     * an agent drags along, or a clean slate on a cadence. Omit by default.
+     */
+    resetAfterTurns?: number;
+}
+interface CodingAgentDefinition<TInput = unknown, TOutput = unknown> {
+    /** Stable id: the folder name under .prompts/coding-agents, and the key callers use. */
+    id: string;
+    /** Human-readable, for the UI and logs. */
+    title: string;
+    /** One line: what this agent is for. */
+    description?: string;
+    /**
+     * 'task' — headless. Runs from a cron, an event, or a command; produces the
+     *   deliverable and applies it. Nobody is watching.
+     * 'chat' — a person is typing. Streams, keeps its session across turns, and
+     *   is not required to produce a deliverable at all.
+     */
+    mode: 'task' | 'chat';
+    /**
+     * Directory holding this agent's system.md. Defaults to
+     * `<promptRoot>/<id>`. The runner copies system.md into the workspace as
+     * AGENTS.md, which is the filename the harness actually reads from its
+     * working directory — that indirection is what lets the instructions stay
+     * version-controlled while the workspace stays disposable.
+     */
+    promptDir?: string;
+    /** Override the deployment default for this agent alone. */
+    harness?: Harness;
+    model?: string;
+    /**
+     * Let this agent's shell reach the network. Off by default.
+     *
+     * Needed by any agent given bridge shims (writeBridgeShims), which reach the
+     * backend over localhost HTTP. Note the sandbox has no host allowlist, so
+     * this grants the whole internet, not just the bridge — scope it to agents
+     * that genuinely need it.
+     */
+    networkAccessEnabled?: boolean;
+    /**
+     * Filesystem reach. Defaults to the driver's 'workspace-write'.
+     * 'danger-full-access' removes the sandbox entirely — it is the only mode in
+     * which codex permits MCP tool calls headlessly, which is exactly why the
+     * shims exist instead.
+     */
+    sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    /**
+     * Tools this agent may reach, as MCP servers. Deliberately per-agent: an
+     * agent that reads the knowledge base has no business holding a database
+     * connection. Omit for an agent that only needs the files it is given.
+     */
+    tools?: Record<string, McpServerSpec>;
+    /**
+     * Put the job's inputs in the workspace as FILES, not prompt text. A coding
+     * agent can grep, aggregate and script over a file; it cannot do any of that
+     * with text pasted into its prompt, and a large input would not fit there
+     * anyway.
+     */
+    prepare?(ws: Workspace, input: TInput, ctx: AgentRunContext): Promise<void>;
+    /**
+     * The short framing sent as the turn's prompt. Keep it short — the standing
+     * instructions belong in system.md and the data belongs in files. Defaults
+     * to a generic instruction naming the output path.
+     */
+    buildPrompt?(ws: Workspace, input: TInput, ctx: AgentRunContext): string | Promise<string>;
+    /** Required for 'task' mode; meaningless for 'chat'. */
+    output?: OutputContract<TOutput>;
+    /**
+     * Persist the validated deliverable — through existing services, never raw
+     * SQL from inside the agent. Keeping the write on this side is what makes a
+     * run auditable and replayable: the artifact on disk is the same input
+     * apply() would get again tomorrow.
+     */
+    apply?(result: TOutput, input: TInput, ctx: AgentRunContext): Promise<ApplySummary>;
+    /**
+     * What makes this agent run. Declared here so an agent's folder plus this
+     * file is the complete story of when it fires. See triggers.ts.
+     */
+    trigger?: AgentTrigger | AgentTrigger[];
+    /**
+     * WHO this agent's accumulated state belongs to. Distinct from `mode`, which
+     * is only how a run was triggered — the two were conflated before, so a
+     * project agent someone chatted with silently got a private per-thread
+     * workspace and lost its memory.
+     *
+     *   'project'  ONE workspace and session for the whole deployment, whoever
+     *              invokes it. A concept builder is project-wide: everything it
+     *              learns should accumulate in one place, and a chat turn joins
+     *              that same workspace rather than forking a copy. Concurrent
+     *              runs serialise.
+     *   'user'     one per user, shared across that user's threads.
+     *   'thread'   one per conversation — an ordinary chat assistant.
+     *
+     * Default: 'thread' for mode 'chat', 'project' for mode 'task'.
+     */
+    scope?: 'project' | 'user' | 'thread';
+    /**
+     * Kill the turn the moment the deliverable file appears, instead of letting
+     * the agent finish.
+     *
+     * Off by default, and the reason is measured: an agent typically writes its
+     * output and then keeps going — verifying, re-reading, summarising — so
+     * stopping at the write cuts the turn well before codex emits
+     * turn.completed, which is the only event carrying token usage. Early stop
+     * therefore costs you all cost tracking, and skips the agent's own
+     * self-check. Turn it on for a long-tailed agent where the file really is
+     * the last thing that matters.
+     */
+    stopOnDeliverable?: boolean;
+    /** What this agent carries between runs. Default: nothing (fresh session and workspace). */
+    session?: SessionPolicy;
+    /** Hard cap for one run. Default 15 minutes. */
+    timeoutMs?: number;
+}
+/** What a completed run reports. */
+interface AgentRunRecord<TOutput = unknown> {
+    agentId: string;
+    runId: string;
+    /** The run's directory — instructions, inputs, scripts and output all still there. */
+    workspaceDir: string;
+    /**
+     * 'early'   the deliverable landed and we stopped the turn — a success, kept
+     *           distinct from 'completed' so a masked early exit is visible.
+     * 'skipped' another run of this agent held the lock; nothing was done.
+     */
+    status: 'completed' | 'early' | 'aborted' | 'error' | 'skipped';
+    /** The agent's closing message. */
+    answer: string;
+    ms: number;
+    usage: AgentUsage;
+    /** Present when the agent produced and validated its deliverable. */
+    output?: TOutput;
+    /** Present when apply() ran. */
+    applied?: ApplySummary;
+    error?: string;
+    /** Harness session id, for resuming a chat. */
+    sessionId?: string;
+}
+
+/**
+ * The agent registry — one place that knows which agents this deployment has.
+ *
+ * Deliberately a plain module-level map rather than something on the SDK: a
+ * cron job, a CLI command and the websocket handler all need to reach the same
+ * agents, and only one of those has an SDK instance in hand.
+ */
+interface CodingAgentsConfig {
+    /**
+     * Where per-agent instruction folders live. Each agent reads
+     * `<promptRoot>/<agent.id>/system.md`.
+     * Default: `<cwd>/.prompts/coding-agents`, matching the .prompts convention
+     * the rest of the deployment already uses.
+     */
+    promptRoot?: string;
+    /**
+     * Root for run workspaces: `<runtimeDir>/<agentId>/<runId>/`. Regenerated
+     * per run and safe to gitignore — deliberately not inside promptRoot, which
+     * is version-controlled.
+     * Default: `<cwd>/.coding-agent-runtime`.
+     */
+    runtimeDir?: string;
+    /** Fallback harness for agents that don't name one. */
+    harness?: Harness;
+    /** Fallback model. */
+    model?: string;
+    /** Tools every agent gets, merged under each agent's own (the agent's win on a name clash). */
+    sharedTools?: Record<string, McpServerSpec>;
+    /** Keep this many run directories per agent; older ones are pruned. 0 keeps everything. */
+    keepRuns?: number;
+}
+/**
+ * Register this deployment's agents. Call once at startup.
+ *
+ * Re-registering an id replaces it — that keeps hot-reload working in dev and
+ * makes a double registration a no-op rather than a silent duplicate.
+ */
+declare function registerCodingAgents(definitions: CodingAgentDefinition<any, any>[], options?: CodingAgentsConfig): void;
+declare function getCodingAgent(id: string): CodingAgentDefinition<any, any> | undefined;
+declare function listCodingAgents(): Array<{
+    id: string;
+    title: string;
+    description?: string;
+    mode: 'task' | 'chat';
+}>;
+declare function getCodingAgentsConfig(): Required<Pick<CodingAgentsConfig, "harness" | "promptRoot" | "runtimeDir" | "keepRuns">> & CodingAgentsConfig;
+
+interface RunAgentOptions<TInput> extends AgentRunContext {
+    input?: TInput;
+    /** Scopes a 'thread' agent. Ignored by a project-scoped one. */
+    threadId?: string;
+    /**
+     * Escape hatch that pins the workspace directory outright. Almost never
+     * right — it defeats the agent's own scope, which is how a project agent
+     * ends up with a private copy per caller. Left for tests and one-offs.
+     */
+    workspaceDir?: string;
+    /** Resume the harness session — chat continuity across turns and restarts. */
+    resumeId?: string;
+    /** Overrides the definition's prompt entirely. Chat mode: this is the user's message. */
+    prompt?: string;
+}
+/**
+ * Run one agent, end to end.
+ *
+ * Never throws for an agent-side failure — a bad run comes back as a record
+ * with status 'error', because callers are usually crons and message handlers
+ * that must keep going. Genuinely programmer errors (unknown agent id) do throw.
+ */
+declare function runCodingAgent<TInput = unknown, TOutput = unknown>(agentId: string, options?: RunAgentOptions<TInput>): Promise<AgentRunRecord<TOutput>>;
+
+/**
+ * Write `./sources` and `./query` into an agent's workspace: read-only data
+ * access as plain executables it runs with bash.
+ *
+ * Why not MCP: codex gates MCP tool calls on the sandbox. Under any sandboxed
+ * mode they need approval, and a headless run must set approvalPolicy 'never',
+ * which denies rather than grants — measured, not assumed. Only
+ * danger-full-access permits them, and that removes the filesystem sandbox
+ * entirely. Bash commands under workspace-write need no approval, so a shim
+ * buys the same capability while the agent stays confined to its workspace.
+ *
+ * An MCP server for this was written and then removed: the same approval gate
+ * applies to the Agents chat tab, which is equally headless from codex's point
+ * of view, so it was unreachable everywhere. `mcpServers` stays plumbed through
+ * the driver for third-party servers; see git history for the removed one.
+ *
+ * The cost is structured tool events: calls arrive as `bash → ./query ...`
+ * rather than typed items with parsed arguments. That matters for a chat UI
+ * with a human watching; for a headless task agent it does not.
+ *
+ * Requires networkAccessEnabled on the session — the shim reaches the bridge
+ * over HTTP, and that is the whole point of it.
+ */
+declare function writeBridgeShims(ws: Workspace, opts: {
+    bridgeUrl: string;
+    sources: Array<{
+        id: string;
+        name?: string;
+        description?: string;
+    }>;
+    maxRows?: number;
+}): void;
+
+/**
+ * Read-only SQL guard for any path that hands an agent a database.
+ *
+ * Defence in depth, NOT a boundary. The agent has a shell and can reach the
+ * bridge directly, so anything enforced only here is advisory — it stops
+ * mistakes, not determination. The real boundary is a database user without
+ * write permission; this exists so a confused agent gets a clear correction
+ * instead of a silent partial write.
+ */
+/** Throws with a message written for the agent to act on. */
+declare function assertReadOnlySql(sql: string): void;
+
+/**
+ * The 'coding-agent'.'run' collection — a chat turn against a coding agent.
+ *
+ * Generic on purpose: nothing here knows about dashboards, reports, or any
+ * particular deliverable. It owns what every harness-backed chat needs — one
+ * session per thread, a per-thread workspace, a run lock, and forwarding the
+ * driver's callbacks to the transport. Task-specific flows (prompt assembly, a
+ * draft-file contract, persistence) build on top of this rather than inside it.
+ */
+interface CodingAgentCollectionConfig {
+    /**
+     * Root for per-thread agent workspaces. Each thread gets its own directory
+     * underneath, so one chat can't read or clobber another's files, and none of
+     * them sit inside the backend's own source tree.
+     * Default: `<process.cwd()>/.coding-agent-runtime`.
+     */
+    runtimeDir?: string;
+    /** Default harness when the request doesn't name one. */
+    harness?: Harness;
+    model?: string;
+    /** Tools, as MCP servers, handed to every session. */
+    mcpServers?: Record<string, McpServerSpec>;
+}
+declare function registerCodingAgentCollection(sdk: SuperatomSDK, config?: CodingAgentCollectionConfig): void;
+
 /**
  * ScriptMatcher — LLM-Based Script Matching + Parameter Extraction
  *
@@ -4783,4 +5393,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, type AgentConfig, type AgentResponse, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type Message, type ModelStrategy, type OutputField, type RerankedResult, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, anthropicLLM, dashboardConversationHistory, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, normalizeScriptBody, openaiLLM, queryCache, registerDashboardAgentCollection, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runScript, userPromptErrorLogger };
+export { type Action, type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type Harness, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, type ModelStrategy, type OutputContract, type OutputField, type OutputValidator, type RerankedResult, type RunAgentOptions, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, type Workspace, anthropicLLM, assertReadOnlySql, createCodexSession, createCodingAgentSession, dashboardConversationHistory, describeTriggers, emitAgentEvent, geminiLLM, getCodingAgent, getCodingAgentsConfig, groqLLM, hybridRerank, listCodingAgents, llmUsageLogger, logger, normalizeScriptBody, onAgentRun, openaiLLM, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runCodingAgent, runScript, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, writeBridgeShims };