@comma-agents/core 2.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CloAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @comma-agents/core
+
+Agent orchestration APIs for CommaAgents.
+
+```bash
+bun add @comma-agents/core@next
+```
+
+```ts
+import { createAgent } from "@comma-agents/core";
+
+const agent = createAgent({
+  name: "assistant",
+  model: "openai/gpt-4o",
+});
+```
+
+Requires Bun 1.3 or newer.

package/dist/abortable/abortable.d.ts

@@ -0,0 +1,5 @@
+import type { AbortableAsyncGenerator, AbortablePromise } from "./abortable.types";
+/** Create a cancellable promise backed by an `AbortController`. */
+export declare function createAbortablePromise<ResultType>(executor: (signal: AbortSignal) => Promise<ResultType>): AbortablePromise<ResultType>;
+/** Create a cancellable async generator backed by an `AbortController`. */
+export declare function createAbortableGenerator<YieldType>(generatorFactory: (signal: AbortSignal) => AsyncGenerator<YieldType, void, undefined>): AbortableAsyncGenerator<YieldType>;

package/dist/abortable/abortable.types.d.ts

@@ -0,0 +1,10 @@
+/** A promise that can be cancelled by calling `.abort()`. */
+export interface AbortablePromise<ResultType> extends Promise<ResultType> {
+    /** Cancel the in-flight operation. */
+    abort(): void;
+}
+/** An async generator that can be cancelled by calling `.abort()`. */
+export interface AbortableAsyncGenerator<YieldType> extends AsyncGenerator<YieldType, void, undefined> {
+    /** Cancel the in-flight stream. */
+    abort(): void;
+}

package/dist/abortable/index.d.ts

@@ -0,0 +1,2 @@
+export { createAbortableGenerator, createAbortablePromise, } from "./abortable";
+export type { AbortableAsyncGenerator, AbortablePromise, } from "./abortable.types";

package/dist/agents/agent/agent.constants.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Default maximum number of LLM round-trips (steps) per call.
+ * Each tool-call + response counts as one step.
+ */
+export declare const DEFAULT_MAX_STEPS = 100;

package/dist/agents/agent/agent.d.ts

@@ -0,0 +1,24 @@
+import type { Agent, AgentConfig } from "./agent.types";
+/**
+ * Create an LLM-backed agent using closure-based state management.
+ *
+ * Returns an `Agent` with all optional LLM fields populated (stream,
+ * getConversationContext, config).
+ *
+ * State (conversation history, first-call flag) is captured in closure.
+ *
+ * @example
+ * ```ts
+ * import { createAgent } from "@comma-agents/core";
+ *
+ * const agent = createAgent({
+ *   name: "writer",
+ *   model: "openai/gpt-4o",
+ *   systemPrompt: "You are a helpful code writer.",
+ * });
+ *
+ * const result = await agent.call("Write a hello world in TypeScript");
+ * console.log(result.text);
+ * ```
+ */
+export declare function createAgent(config: AgentConfig): Agent;

package/dist/agents/agent/agent.types.d.ts

@@ -0,0 +1,408 @@
+import type { AbortableAsyncGenerator, AbortablePromise } from "../../abortable";
+import type { tool as aiTool, CallSettings, FlexibleSchema, LanguageModel, ModelMessage, StepResult, stepCountIs, streamText, ToolChoice } from "ai";
+import type { ContextUsage, ConversationContext, ConversationContextOptions, ConversationRetentionEvent, ResponseMessage } from "../../conversation-context";
+import type { LanguageService } from "../../language";
+import type { PromptTemplate, TemplateVariables } from "../../prompts";
+import type { Sandbox } from "../../sandbox/sandbox.types";
+import type { SkillRegistry } from "../../skills/skills.types";
+import type { LaunchStrategyHandle } from "../../tools/launch-strategy.types";
+import type { InputCollector } from "../built-in/user/user-agent.types";
+/**
+ * Model-level generation parameters forwarded to `streamText`.
+ *
+ * Derived from the AI SDK's `CallSettings` to stay in sync with
+ * upstream changes. Provider-specific features (extended thinking,
+ * reasoning effort) should use {@link AgentConfig.providerOptions} instead.
+ *
+ * Excludes runtime-only fields (`abortSignal`, `timeout`, `headers`,
+ * `stopSequences`) that are managed by the agent lifecycle, not user config.
+ */
+export type ModelOptions = Pick<CallSettings, "temperature" | "topP" | "topK" | "maxOutputTokens" | "maxRetries" | "frequencyPenalty" | "presencePenalty" | "seed">;
+/** Schema used to constrain and validate an agent's structured output. */
+export type AgentOutputSchema = FlexibleSchema<unknown>;
+/** Configuration for creating an LLM-backed agent via `createAgent()`. */
+export interface AgentConfig {
+    /** Unique name for this agent. */
+    readonly name: string;
+    /**
+     * Model identifier in "providerID/modelID" format (e.g., `"openai/gpt-4o"`).
+     * Resolved internally by `createAgent()` via the model registry and provider system.
+     * Optional if a custom `execute` override is provided.
+     */
+    readonly model?: string;
+    /**
+     * System prompt sent to the model at the start of every call.
+     * Accepts a static string or a `PromptTemplate` for dynamic interpolation.
+     * When a `PromptTemplate` is provided, its baked-in variables are used.
+     *
+     * @example
+     * ```ts
+     * // Static string
+     * const agent = createAgent({
+     *   name: "writer",
+     *   model: "openai/gpt-4o",
+     *   systemPrompt: "You are a helpful code writer.",
+     * });
+     *
+     * // Dynamic template
+     * import { createPromptTemplate } from "@comma-agents/core";
+     *
+     * const agent = createAgent({
+     *   name: "reviewer",
+     *   model: "openai/gpt-4o",
+     *   systemPrompt: createPromptTemplate({
+     *     template: "You are {{ role }}, reviewing {{ language }} code.",
+     *     variables: { role: "a senior engineer", language: "TypeScript" },
+     *   }),
+     * });
+     * ```
+     */
+    readonly systemPrompt?: string | PromptTemplate;
+    /**
+     * Tool names the agent can invoke during a call.
+     * Resolved internally by `createAgent()` via the tool registry.
+     */
+    readonly tools?: readonly string[];
+    /**
+     * Sandbox governing file-system access for all tools invoked by this agent.
+     * When omitted, a permissive sandbox (no restrictions, cwd = process.cwd())
+     * is used so that existing strategies remain unaffected.
+     */
+    readonly sandbox?: Sandbox;
+    /**
+     * Skill registry exposed to the `load_skill` tool when included in `tools`.
+     * When omitted, `load_skill` returns `skill_unavailable` for every call.
+     * Typically populated by the strategy loader from
+     * `<configRoot>/comma-agents/skills/` plus `./.comma/skills/`.
+     */
+    readonly skillRegistry?: SkillRegistry;
+    /**
+     * Per-invocation run identifier propagated to {@link ToolContext.runId}.
+     *
+     * Distinct from {@link AgentConfig.sessionId} — `runId` identifies one
+     * strategy invocation (top-level run *or* one `launch_strategy`
+     * sub-invocation), while `sessionId` identifies a broader user/daemon
+     * session that may span many runs. The two are deliberately separate:
+     * audit logs are session-scoped, but per-run isolation (notably the
+     * `todo_*` tools' shared run-level silo, which must not leak into
+     * recursive `launch_strategy` calls) keys on `runId`.
+     *
+     * The strategy loader sets this from {@link LoadStrategyOptions.runId};
+     * the daemon executor passes the top-level run id at the entry point
+     * and a fresh derived id for each sub-launch so recursive strategy
+     * invocations get isolated state.
+     *
+     * When omitted, runId-aware tools fall back to `agentName`-only keying
+     * (their original behaviour) — safe for tests and embedded callers
+     * that don't care about cross-launch isolation.
+     */
+    readonly runId?: string;
+    /**
+     * Input collector threaded into the {@link ToolContext} of every tool
+     * call. Used by tools (e.g., `launch_strategy`) that need to forward
+     * the parent strategy's input bridge into a spawned sub-strategy.
+     */
+    readonly inputCollector?: InputCollector;
+    /**
+     * Optional handle for spawning sub-strategies, threaded into every
+     * tool's {@link ToolContext}. Supplied by the strategy loader (which
+     * receives it via {@link LoadStrategyOptions}).
+     */
+    readonly launchStrategy?: LaunchStrategyHandle;
+    /**
+     * Runtime language service exposed to language-aware tools.
+     * Usually supplied by the daemon for a workspace.
+     */
+    readonly languageService?: LanguageService;
+    /**
+     * Per-call provider options forwarded to the model provider. Used to enable
+     * provider-specific behaviour such as reasoning / extended thinking.
+     *
+     * @example
+     * ```ts
+     * createAgent({
+     *   name: "planner",
+     *   model: "anthropic/claude-sonnet-4-5",
+     *   providerOptions: {
+     *     anthropic: { thinking: { type: "enabled", budgetTokens: 8000 } },
+     *   },
+     * });
+     * ```
+     */
+    readonly providerOptions?: Record<string, Record<string, unknown>>;
+    /**
+     * Model-level generation parameters forwarded to `streamText`.
+     *
+     * Provider-agnostic options like `temperature`, `maxOutputTokens`, `topP`, and
+     * `seed`. Provider-specific features should use `providerOptions` instead.
+     *
+     * @example
+     * ```ts
+     * createAgent({
+     *   name: "creative-writer",
+     *   model: "openai/gpt-4o",
+     *   modelOptions: { temperature: 0.9, maxOutputTokens: 4096 },
+     * });
+     * ```
+     */
+    readonly modelOptions?: ModelOptions;
+    /**
+     * Schema for structured agent output.
+     *
+     * Forwarded to `streamText` as `output: Output.object({ schema })`.
+     * Programmatic callers may pass a Zod schema or another AI SDK
+     * `FlexibleSchema`. YAML/JSON agent and strategy definitions accept a JSON
+     * Schema object.
+     */
+    readonly outputSchema?: AgentOutputSchema;
+    /**
+     * Maximum number of LLM round-trips (steps) per call.
+     * Each tool-call + response counts as one step.
+     * @default 10
+     */
+    readonly maxSteps?: number;
+    /**
+     * Custom execute override — replaces the LLM call with arbitrary logic.
+     *
+     * When set, `model` is not required. Return a plain `string` (a synthetic
+     * result with an `{ role: "assistant" }` message will be created
+     * automatically) or a full `AgentCallResult` for complete control.
+     *
+     * @example
+     * ```ts
+     * const echo = createAgent({
+     *   name: "echo",
+     *   execute: async (message) => `Echo: ${message}`,
+     * });
+     * ```
+     */
+    readonly execute?: (message: string) => Promise<string | AgentCallResult>;
+    /**
+     * Conversation context retention and compaction options. Transformations are
+     * non-destructive: superseded records are kept for export but excluded from
+     * the LLM-visible projection.
+     *
+     * YAML/JSON definitions can use serializable `rollingWindow` and
+     * `compaction` values. Programmatic callers may also pass `transformRecords`
+     * for custom behavior.
+     *
+     * @example
+     * ```ts
+     * createAgent({
+     *   name: "writer",
+     *   model: "anthropic/claude-opus-4-8",
+     *   context: { rollingWindow: 40, compaction: { keepRecent: 8 } },
+     * });
+     * ```
+     */
+    readonly context?: ConversationContextOptions;
+}
+/**
+ * The unified agent contract. Every agent — LLM-backed, human-in-the-loop,
+ * flow, or custom — implements this interface.
+ *
+ * **Required fields** (`name`, `call`, `reset`) are the polymorphic minimum
+ * that flows and orchestration depend on.
+ *
+ * **Optional fields** (`stream`, `getConversationContext`, `config`) are
+ * provided by LLM-backed agents created via `createAgent()`. Consumer code
+ * that needs LLM-specific features can check for their existence or work
+ * with a known `createAgent()` result.
+ *
+ * @example
+ * ```ts
+ * // Flows accept any Agent — only name, call, reset are required
+ * const flow = createSequentialFlow({
+ *   name: "pipeline",
+ *   agents: [llmAgent, userAgent, customAgent],
+ * });
+ *
+ * // LLM-specific features are optional
+ * const agent = createAgent({ name: "writer", model: "openai/gpt-4o" });
+ * const context = agent.getConversationContext();   // always present on createAgent results
+ * const messages = context.messages();               // flat ModelMessage[]
+ * const records = context.records();                 // structured records
+ * for await (const event of agent.stream("Hi")) { ... }
+ * ```
+ */
+export interface Agent {
+    /** Unique name for this agent. */
+    readonly name: string;
+    /** The agent's configuration. */
+    readonly config?: AgentConfig;
+    /**
+     * Call the agent with a message.
+     * Runs the full hook lifecycle around the core action.
+     * Returns an AbortablePromise — call `.abort()` to cancel the in-flight operation.
+     */
+    call(message: string): AbortablePromise<AgentCallResult>;
+    /**
+     * Stream a call, yielding events as they arrive.
+     * Returns an AbortableAsyncGenerator — call `.abort()` to cancel the stream.
+     */
+    stream?(message: string): AbortableAsyncGenerator<AgentStreamEvent>;
+    /**
+     * The agent's internal conversation context.
+     * Provides canonical conversation records, message projection, and import/export helpers.
+     */
+    getConversationContext?(): ConversationContext;
+    /** Reset internal state (history, first-call flag, etc.). */
+    reset(): void;
+    /**
+     * Update variables used by this agent's prompt template.
+     *
+     * When the agent was configured with a `PromptTemplate` (via
+     * `systemPrompt`), calling this merges new variables into the template's
+     * defaults — matching keys are overwritten, the rest are kept.
+     * If the agent uses a static string prompt, this is a no-op.
+     *
+     * @example
+     * ```ts
+     * const agent = createAgent({
+     *   name: "reviewer",
+     *   model: "openai/gpt-4o",
+     *   systemPrompt: createPromptTemplate({
+     *     template: "You are {{ role }}, reviewing {{ language }} code.",
+     *     variables: { role: "a reviewer" },
+     *   }),
+     * });
+     *
+     * agent.updatePromptVariables({ language: "TypeScript" });
+     * // Next call renders: "You are a reviewer, reviewing TypeScript code."
+     * ```
+     */
+    updatePromptVariables?(variables: TemplateVariables): void;
+    /**
+     * Append a hook callback to this agent's lifecycle.
+     * Used internally by `hookIntoAgent` — not part of the public API.
+     * @internal
+     */
+    appendHook?(hookName: string, callback: unknown): void;
+}
+/**
+ * Result from any agent call.
+ *
+ * Contains the response text, token usage, finish reason, and the full
+ * response message chain and step details. Non-LLM agents (mocks, flows,
+ * custom execute overrides) provide empty arrays for `responseMessages`
+ * and `steps`.
+ *
+ * @example
+ * ```ts
+ * const result = await agent.call("Hello");
+ * console.log(result.text);               // final text
+ * console.log(result.responseMessages);    // full message chain
+ * console.log(result.steps);              // tool calls, reasoning, etc.
+ * ```
+ */
+export interface AgentCallResult {
+    /** The final text response from the agent. */
+    readonly text: string;
+    /** Total token usage across all steps. Zero for non-LLM agents. */
+    readonly usage: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+    };
+    /** Final model-step context usage. */
+    readonly contextUsage?: ContextUsage;
+    /** Why the agent stopped (e.g., "stop", "tool-calls", "length"). */
+    readonly finishReason: string;
+    /**
+     * The full assistant + tool message chain, preserving tool calls,
+     * tool results, reasoning, and multi-modal content.
+     * Empty array for non-LLM agents.
+     */
+    readonly responseMessages: readonly ResponseMessage[];
+    /** All steps taken during this call (LLM calls + tool executions). Empty array for non-LLM agents. */
+    readonly steps: ReadonlyArray<StepResult<any>>;
+}
+/**
+ * Event emitted during a streaming agent call.
+ *
+ * Reasoning ("thinking") events come in three parts mirroring the AI SDK
+ * v6 stream: `thinking-start` opens a reasoning block, zero or more
+ * `thinking` deltas append text to it, and `thinking-end` closes it. The
+ * `id` is supplied by the model and lets multiple interleaved reasoning
+ * blocks within a single step be reassembled correctly downstream.
+ */
+/**
+ * Lifecycle status of a tool invocation. `running` is implicit (no
+ * `tool-result` has been emitted yet for the matching `toolCallId`);
+ * `completed` and `error` arrive on the `tool-result` event.
+ */
+export type ToolCallStatus = "completed" | "error";
+export type AgentStreamEvent = {
+    readonly type: "retention";
+    readonly event: ConversationRetentionEvent;
+} | {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "tool-call";
+    /**
+     * Correlation id assigned by the model. Pairs this call with its eventual
+     * `tool-result` event so consumers can render a single row per call
+     * even when calls run concurrently or interleave with text/thinking.
+     */
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: string;
+} | {
+    readonly type: "tool-result";
+    /** Correlates with the `tool-call` event that started this invocation. */
+    readonly toolCallId: string;
+    readonly toolName: string;
+    /**
+     * Raw tool output. For `status: "error"` results this is an empty
+     * string by default — the human-readable failure message lives on
+     * `error`.
+     */
+    readonly output: string;
+    /** Outcome of the tool invocation. */
+    readonly status: ToolCallStatus;
+    /** Failure message when `status === "error"`. */
+    readonly error?: string;
+} | {
+    readonly type: "thinking-start";
+    readonly id: string;
+} | {
+    readonly type: "thinking";
+    readonly id: string;
+    readonly text: string;
+} | {
+    readonly type: "thinking-end";
+    readonly id: string;
+} | {
+    readonly type: "step-start";
+} | {
+    readonly type: "done";
+    readonly result: AgentCallResult;
+};
+/** Common options passed to generateText / streamText. */
+export interface CallOptions {
+    readonly model: LanguageModel;
+    readonly system?: string | ModelMessage | ModelMessage[];
+    readonly messages: ModelMessage[];
+    readonly tools?: Record<string, ReturnType<typeof aiTool<any, any>>> | undefined;
+    readonly toolChoice?: ToolChoice<Record<string, unknown>> | undefined;
+    readonly abortSignal?: AbortSignal | undefined;
+    readonly timeout?: number | undefined;
+    readonly stopWhen?: ReturnType<typeof stepCountIs>;
+    /**
+     * Per-call provider options forwarded verbatim to `streamText`.
+     */
+    readonly providerOptions?: unknown;
+    /** Structured output specification forwarded to `streamText`. */
+    readonly output?: Parameters<typeof streamText>[0]["output"];
+    /**
+     * Model-level generation parameters forwarded to `streamText`.
+     */
+    readonly modelOptions?: ModelOptions;
+}
+/** Prepared model-call options plus retention events emitted before the call. */
+export interface BuildCallOptionsResult {
+    /** AI SDK call options passed to `streamText`. */
+    readonly callOptions: CallOptions;
+    /** Retention events emitted while preparing conversation context. */
+    readonly retentionEvents: readonly ConversationRetentionEvent[];
+}

package/dist/agents/agent/agent.utils.d.ts

@@ -0,0 +1,107 @@
+import { tool as aiTool } from "ai";
+import type { ConversationContext, ResponseMessage, SummarizeRecords } from "../../conversation-context";
+import type { SideEffectHook, TransformHook } from "../../hooks/hooks.types";
+import type { LanguageService } from "../../language";
+import type { Sandbox } from "../../sandbox/sandbox.types";
+import type { SkillRegistry } from "../../skills/skills.types";
+import type { AuditSink } from "../../tools/io/audit.types";
+import type { LaunchStrategyHandle } from "../../tools/launch-strategy.types";
+import type { ToolContext, ToolDefinition } from "../../tools/tool.types";
+import type { InputCollector } from "../built-in/user/user-agent.types";
+import type { ToolHooks } from "../hooks";
+import type { AgentCallResult, AgentConfig, AgentStreamEvent, BuildCallOptionsResult } from "./agent.types";
+export type AgentHookStore = {
+    alterFirstCallMessage: Array<TransformHook<string>> | undefined;
+    beforeFirstCall: Array<SideEffectHook<string>> | undefined;
+    afterFirstCallResult: Array<SideEffectHook<AgentCallResult>> | undefined;
+    alterFirstResponse: Array<TransformHook<string>> | undefined;
+    alterCallMessage: Array<TransformHook<string>> | undefined;
+    beforeCall: Array<SideEffectHook<string>> | undefined;
+    alterResponse: Array<TransformHook<string>> | undefined;
+    afterCallResult: Array<SideEffectHook<AgentCallResult>> | undefined;
+    onStreamEvent: Array<SideEffectHook<AgentStreamEvent>> | undefined;
+    beforeToolCall: Array<SideEffectHook<{
+        readonly name: string;
+        readonly args: string;
+        readonly toolContext: ToolContext;
+    }>> | undefined;
+    afterToolCall: Array<SideEffectHook<{
+        readonly name: string;
+        readonly args: string;
+        readonly result: string;
+        readonly toolContext: ToolContext;
+    }>> | undefined;
+};
+/** Build a ToolHooks view from the mutable store for passing to buildCallOptions. */
+export declare function getToolHooks(hooks: AgentHookStore): ToolHooks;
+/**
+ * Run the pre-call hook lifecycle and return the altered message.
+ */
+export declare function runPreCallHooks(hooks: AgentHookStore, message: string, isFirst: boolean): Promise<string>;
+/**
+ * Run the post-call hook lifecycle and return the result with altered text.
+ */
+export declare function runPostCallHooks(hooks: AgentHookStore, result: AgentCallResult, isFirst: boolean): Promise<AgentCallResult>;
+/**
+ * Converts a ToolDef map into the AI SDK's tool format.
+ * Wraps each tool's execute with ToolHooks and a centralized
+ * SandboxViolationError → ToolError catch.
+ *
+ * Each tool gets its own per-tool Guard from `sandbox.guardFor(toolName)`.
+ * Tools call `ctx.guard.authorize()` for path resolution, jail enforcement,
+ * and policy evaluation.
+ *
+ * @param toolDefinitions - The tool definitions to wrap.
+ * @param agentName - Surfaced on `ToolContext.agentName` and audit entries.
+ * @param toolHooks - Optional side-effect hooks invoked around each call.
+ * @param sandbox - Guard registry; falls back to a permissive sandbox.
+ * @param sessionId - Propagated to `ToolContext.sessionId`. Identifies a
+ *   broader user/daemon session; used by audit log / trash metadata.
+ * @param auditSink - Explicit audit sink. When omitted but `sessionId` is set,
+ *   a `createFileAuditSink(sandbox.cwd)` is constructed automatically.
+ * @param skillRegistry - Propagated to `ToolContext.skillRegistry`.
+ * @param inputCollector - Propagated to `ToolContext.inputCollector`.
+ * @param launchStrategy - Propagated to `ToolContext.launchStrategy`.
+ * @param languageService - Propagated to `ToolContext.languageService`.
+ * @param runId - Propagated to `ToolContext.runId`. Identifies a single
+ *   strategy invocation (top-level run *or* one `launch_strategy`
+ *   sub-load). Tools that need per-launch isolation (notably `todo_*`)
+ *   silo on this. Kept distinct from `sessionId`.
+ */
+export declare function buildAgentToolSet(toolDefinitions: Readonly<Record<string, ToolDefinition>> | undefined, agentName: string, toolHooks?: ToolHooks, sandbox?: Sandbox, sessionId?: string, auditSink?: AuditSink, skillRegistry?: SkillRegistry, inputCollector?: InputCollector, launchStrategy?: LaunchStrategyHandle, languageService?: LanguageService, runId?: string): Record<string, ReturnType<typeof aiTool<any, any>>> | undefined;
+/**
+ * Build the full AI SDK call options from agent config + current message.
+ * Resolves the model string to a LanguageModel, tool names to tool definitions,
+ * then builds messages and system prompt into a single options object.
+ *
+ * @param config - The agent configuration.
+ * @param message - The current user message.
+ * @param context - The conversation context.
+ * @param toolHooks - Tool hooks from the agent's mutable closure store.
+ *   Dynamically appended hooks (via `hookIntoAgent`) take effect here.
+ * @param abortSignal - Optional AbortSignal for cancellation.
+ *
+ * @throws {Error} if config.model is not set.
+ * @throws {ModelResolutionError} if the model string cannot be resolved.
+ */
+export declare function buildCallOptions(config: AgentConfig, message: string, context: ConversationContext, toolHooks?: ToolHooks, abortSignal?: AbortSignal): Promise<BuildCallOptionsResult>;
+/**
+ * Build the default summarizer used by context compaction. Resolves the model
+ * lazily so unused summarizers cost nothing.
+ *
+ * @param model - Model identifier in "providerID/modelID" format.
+ */
+export declare function createModelSummarizer(model: string): SummarizeRecords;
+/**
+ * Maps an AI SDK stream part to an AgentStreamEvent.
+ * Returns undefined for parts we don't surface (e.g., finish, error).
+ */
+export declare function mapStreamPart(streamPart: any): AgentStreamEvent | undefined;
+/**
+ * Build an AgentCallResult from consumed stream results.
+ * Used by the shared `runStream` generator inside createAgent.
+ */
+export declare function buildStreamCallResult(text: string, responseMessages: readonly ResponseMessage[], steps: ReadonlyArray<any>, totalUsage: {
+    readonly inputTokens: number | undefined;
+    readonly outputTokens: number | undefined;
+}, finishReason: string | null | undefined): AgentCallResult;

package/dist/agents/built-in/user/user-agent.d.ts

@@ -0,0 +1,32 @@
+import type { Agent } from "../../agent/agent.types";
+import type { UserAgentConfig } from "./user-agent.types";
+export type { InputCollector, InputRequest, UserAgentConfig, } from "./user-agent.types";
+/**
+ * Create a human-in-the-loop agent.
+ *
+ * Returns an Agent that collects input from the user (or returns a preset
+ * message) instead of calling an LLM. Supports the full hook lifecycle
+ * by delegating to `createAgent` with a custom `execute` override.
+ *
+ * @example
+ * ```ts
+ * import { createUserAgent } from "@comma-agents/core";
+ *
+ * // Interactive — prompts user for input
+ * const interactive = createUserAgent({
+ *   name: "user",
+ *   requireInput: true,
+ * });
+ *
+ * // Preset — always returns the same message
+ * const preset = createUserAgent({
+ *   name: "user",
+ *   requireInput: false,
+ *   presetMessage: "Please review the code above.",
+ * });
+ *
+ * // Both satisfy the Agent interface — usable in any flow
+ * const result = await interactive.call("");
+ * ```
+ */
+export declare function createUserAgent(config: UserAgentConfig): Agent;