@a3s-lab/code 2.1.0 → 2.3.0

package/README.md

@@ -17,7 +17,9 @@ async function main() {
   const agent = await Agent.create('agent.acl')
   const session = agent.session('/my-project')
 
-  const result = await session.send('What files handle authentication?')
+  const result = await session.send({
+    prompt: 'What files handle authentication?',
+  })
   console.log(result.text)
 }
 
@@ -68,18 +70,35 @@ When streaming, `task_updated` is the authoritative task-list snapshot for UI
 rendering. `planning_end` contains the initial plan, while `step_start` and
 `step_end` are fine-grained progress events.
 
+## Durable Request Shape
+
+`send(...)` and `stream(...)` accept either a prompt string or an object-shaped
+request. Use the object shape when the call needs history, attachments, or
+future request options:
+
+```js
+const result = await session.send({
+  prompt: 'Explain the auth module',
+  history: previousMessages,
+  attachments: [{ data: imageBuffer, mediaType: 'image/png' }],
+})
+```
+
+`sendRequest(...)`, `streamRequest(...)`, and attachment-specific positional
+overloads remain for compatibility.
+
 ## Delegation And Tool Introspection
 
 The SDK exposes the core `task` / `parallel_task` tools as direct helpers:
 
 ```js
-await session.delegateTask({
+await session.task({
   agent: 'explore',
   description: 'Find auth entry points',
   prompt: 'Inspect the repository and summarize the auth-related files.',
 })
 
-await session.parallelTask([
+await session.tasks([
   { agent: 'explore', description: 'Find tests', prompt: 'Locate auth tests.' },
   { agent: 'verification', description: 'Check risk', prompt: 'Review auth edge cases.' },
 ])
@@ -88,6 +107,122 @@ await session.parallelTask([
 Use `session.toolNames()` for names and `session.toolDefinitions()` when a UI
 needs the full model-visible schemas.
 
+## Object-Shaped Direct Tools
+
+New direct helpers use option objects when the command can grow over time:
+
+```js
+await session.git({ command: 'status' })
+await session.git({ command: 'worktree', subcommand: 'list' })
+```
+
+The older positional `git(...)` overload and `gitCommand(...)` remain for
+compatibility.
+
+## Disposable Worker Agents
+
+A3S Code treats subagents as cattle, not pets: define reproducible worker specs
+in code, register them on a session, and delegate by name through the existing
+`task` tool.
+
+```js
+const session = agent.session('/my-project', {
+  workerAgents: [
+    {
+      name: 'frontend-cow',
+      description: 'Small verified frontend fixes',
+      kind: 'implementer',
+      model: 'openai/gpt-4o',
+      maxSteps: 24,
+      prompt: 'Keep patches focused and run the narrowest relevant check.',
+    },
+    { name: 'review-cow', description: 'Adversarial review', kind: 'reviewer' },
+  ],
+})
+
+await session.task({
+  agent: 'frontend-cow',
+  description: 'Fix admin chat loading state',
+  prompt: 'Find and fix the loading-state regression, then summarize verification.',
+})
+```
+
+You can also register workers after the session is running:
+
+```js
+session.registerWorkerAgent({
+  name: 'verify-cow',
+  description: 'Run focused checks without editing files',
+  kind: 'verifier',
+})
+```
+
+For a worker as the top-level actor, use `agent.sessionForWorker(workspace, spec)`.
+
+## AHP-Supervised Advice
+
+Background advice belongs in the host or AHP harness. A3S Code forwards hooks,
+run lifecycle events, task updates, verification summaries, confirmations, idle
+signals, and errors; the harness decides when to surface suggestions, add host
+context, or propose PTC scripts.
+
+```js
+const session = agent.session('/my-project', {
+  ahpTransport: new HttpTransport('http://localhost:8080/ahp'),
+})
+```
+
+PTC scripts proposed by an AHP harness are not executed automatically. Run them
+explicitly through `session.program(...)` so existing permission, confirmation,
+and trace policies stay in force.
+
+## Live MCP Servers
+
+Prefer the object-shaped MCP API for new code. It keeps transport-specific
+fields grouped and leaves room for OAuth/env/timeout extensions:
+
+```js
+await session.addMcp({
+  name: 'github',
+  transport: {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-github'],
+  },
+  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN ?? '' },
+  timeoutMs: 30000,
+})
+
+console.log(await session.mcps())
+```
+
+The positional `addMcpServer(...)` overload and longer
+`addMcpServerConfig(...)` alias remain for compatibility.
+
+## HITL Confirmations
+
+Use `permissionPolicy` to decide which tools ask, then `confirmationPolicy` to
+control confirmation runtime behavior such as timeout and YOLO lanes.
+
+```js
+const session = agent.session('.', {
+  permissionPolicy: { ask: ['bash*'], defaultDecision: 'allow' },
+  confirmationPolicy: {
+    enabled: true,
+    defaultTimeoutMs: 30000,
+    timeoutAction: 'reject',
+    yoloLanes: ['query'],
+  },
+})
+
+for (const pending of await session.pendingConfirmations()) {
+  await session.confirmToolUse(pending.toolId, true, 'Reviewed')
+}
+```
+
+For the streaming event-driven loop used by UIs, see
+`examples/streaming/hitl_confirmation_loop.ts`.
+
 ## Run Replay
 
 Each `send(...)` or `stream(...)` call records a run snapshot and replayable
@@ -99,6 +234,7 @@ await session.send('Fix the failing test')
 const [run] = await session.runs()
 console.log(run.id, run.status)
 console.log(await session.runEvents(run.id))
+console.log(await session.activeTools())
 ```
 
 Use `session.currentRun()` while a stream is active to inspect the current run.

package/index.d.ts

@@ -56,21 +56,6 @@ export interface AgentResult {
   verificationSummaryText: string
 }
 export declare function formatVerificationSummary(summary: any): string
-/**
- * Result of a `/btw` ephemeral side question.
- *
- * The answer is never added to conversation history.
- */
-export interface BtwResult {
-  /** The original question. */
-  question: string
-  /** The LLM's answer. */
-  answer: string
-  /** Token usage for this ephemeral call. */
-  promptTokens: number
-  completionTokens: number
-  totalTokens: number
-}
 export interface AgentEvent {
   type: string
   text?: string
@@ -84,10 +69,6 @@ export interface AgentEvent {
   totalTokens?: number
   verificationSummaryJson?: string
   verificationSummaryText?: string
-  /** For btw_answer event: the original question */
-  question?: string
-  /** For btw_answer event: the LLM's answer */
-  answer?: string
   /** Extra data for events that don't map to standard fields (JSON-encoded) */
   data?: string
 }
@@ -130,6 +111,27 @@ export interface DelegateTaskOptions {
   background?: boolean
   maxSteps?: number
 }
+/** Object-shaped request for `Session.sendRequest` and `Session.streamRequest`. */
+export interface SessionRequestOptions {
+  prompt: string
+  history?: Array<MessageObject>
+  attachments?: Array<AttachmentObject>
+}
+export interface GitCommandOptions {
+  command: string
+  subcommand?: string
+  name?: string
+  path?: string
+  newBranch?: boolean
+  base?: string
+  force?: boolean
+  maxCount?: number
+  message?: string
+  includeUntracked?: boolean
+  target?: string
+  ref?: string
+  reference?: string
+}
 /** Parameters for the web_search tool. */
 export interface JsWebSearchParams {
   /** The search query. */
@@ -199,6 +201,67 @@ export interface PermissionPolicy {
   /** Whether this policy is enabled. Defaults to true. */
   enabled?: boolean
 }
+/**
+ * Reproducible recipe for a disposable worker/subagent.
+ *
+ * This is the Node.js cattle-mode interface: define workers in data, pass them
+ * to SessionOptions.workerAgents, Agent.sessionForWorker(), or
+ * Session.registerWorkerAgent(). The Rust core compiles each spec into the
+ * normal delegated-agent runtime definition.
+ */
+export interface WorkerAgentSpec {
+  /** Stable worker name used by task delegation. */
+  name: string
+  /** Human-readable worker purpose. */
+  description: string
+  /** Preset role: "read_only", "planner", "implementer", "verifier", "reviewer", or "custom". */
+  kind?: string
+  /** Hide from UI lists while allowing explicit delegation. */
+  hidden?: boolean
+  /** Optional permission policy override. */
+  permissions?: PermissionPolicy
+  /** Optional model override in "provider/model" format. */
+  model?: string
+  /** Optional worker-specific prompt. */
+  prompt?: string
+  /** Maximum execution steps/tool rounds. */
+  maxSteps?: number
+}
+export interface AgentDefinition {
+  name: string
+  description: string
+  native: boolean
+  hidden: boolean
+  model?: string
+  prompt?: string
+  maxSteps?: number
+}
+/**
+ * HITL confirmation policy configuration.
+ *
+ * Controls the runtime behavior of Human-in-the-Loop confirmation flow.
+ */
+export interface ConfirmationPolicy {
+  /** Whether HITL is enabled (default: false, all tools auto-approved). */
+  enabled?: boolean
+  /** Default timeout in milliseconds (default: 30000 = 30s). */
+  defaultTimeoutMs?: number
+  /** Action to take on timeout: "reject" or "auto_approve" (default: "reject"). */
+  timeoutAction?: string
+  /** Lanes that should auto-approve without confirmation: "control", "query", "execute", or "generate". */
+  yoloLanes?: Array<string>
+}
+/** Snapshot of a pending HITL tool confirmation. */
+export interface PendingConfirmation {
+  /** Tool call ID to pass to `confirmToolUse`. */
+  toolId: string
+  /** Tool name awaiting confirmation. */
+  toolName: string
+  /** Tool arguments for display in a confirmation UI. */
+  args: any
+  /** Milliseconds remaining before the confirmation times out. */
+  remainingMs: number
+}
 export interface SessionOptions {
   /** Override the default model. Format: "provider/model" (e.g., "openai/gpt-4o"). */
   model?: string
@@ -208,6 +271,8 @@ export interface SessionOptions {
   skillDirs?: Array<string>
   /** Extra directories to scan for agent files. */
   agentDirs?: Array<string>
+  /** Reproducible disposable workers to register for task delegation. */
+  workerAgents?: Array<WorkerAgentSpec>
   /**
    * Optional advanced queue configuration for explicit external/hybrid lane dispatch.
    *
@@ -342,6 +407,37 @@ export interface SessionOptions {
    * ```
    */
   ahpTransport?: JsAhpTransport
+  /**
+   * HITL confirmation policy configuration.
+   *
+   * Pass a confirmation policy to enable Human-in-the-Loop confirmation for tool execution.
+   * When enabled, tools that require confirmation will emit ConfirmationRequired events
+   * and wait for user approval before executing.
+   *
+   * ```js
+   * agent.session('.', {
+   *   confirmationPolicy: {
+   *     enabled: true,
+   *     defaultTimeoutMs: 30000,
+   *     timeoutAction: 'reject'
+   *   }
+   * });
+   * ```
+   */
+  confirmationPolicy?: ConfirmationPolicy
+  /**
+   * Maximum execution time in milliseconds.
+   *
+   * When set, the execution loop will abort if it exceeds this duration.
+   * This prevents runaway executions and excessive API costs.
+   *
+   * ```js
+   * agent.session('.', {
+   *   maxExecutionTimeMs: 300000  // 5 minutes
+   * });
+   * ```
+   */
+  maxExecutionTimeMs?: number
 }
 /** A single message in conversation history. */
 export interface MessageObject {
@@ -733,40 +829,45 @@ export declare class Agent {
    * @param options - Optional session overrides layered on top of the agent definition
    */
   sessionForAgent(workspace: string, agentName: string, agentDirs?: Array<string> | undefined | null, options?: SessionOptions | undefined | null): Session
-}
-/** Workspace-bound session. All LLM and tool operations happen here. */
-export declare class Session {
   /**
-   * Send a prompt and wait for the complete response.
+   * Create a session pre-configured from a disposable worker spec.
    *
-   * @param prompt - The prompt to send
-   * @param history - Optional conversation history
+   * This avoids writing temporary agent files for one-off cattle workers.
+   *
+   * @param workspace - Path to the workspace directory
+   * @param worker - Worker spec to compile into an agent definition
+   * @param options - Optional session overrides layered on top of the worker definition
    */
-  send(prompt: string, history?: Array<MessageObject> | undefined | null): Promise<AgentResult>
+  sessionForWorker(workspace: string, worker: WorkerAgentSpec, options?: SessionOptions | undefined | null): Session
+}
+/** Workspace-bound session. All LLM and tool operations happen here. */
+export declare class Session {
   /**
-   * Ask an ephemeral side question without affecting conversation history.
-   *
-   * Takes a read-only snapshot of the current history, makes a separate LLM
-   * call with no tools, and returns the answer. History is never modified.
-   *
-   * Safe to call concurrently with an ongoing `send()` — the snapshot only
-   * acquires a read lock on the internal history.
+   * Send a prompt or request and wait for the complete response.
    *
-   * @param question - The side question to ask
-   * @returns BtwResult with question, answer, and token usage
+   * `send("prompt")` is the compact prompt-first form. `send({ prompt,
+   * history, attachments })` is the compact object-shaped form for growth.
    */
-  btw(question: string): Promise<BtwResult>
+  send(request: string | SessionRequestOptions, history?: Array<MessageObject> | null): Promise<AgentResult>
+  /** Alias for `send(...)` with a name that matches run/replay terminology. */
+  run(request: string | SessionRequestOptions, history?: Array<MessageObject> | null): Promise<AgentResult>
   /**
-   * Send a prompt and get a streaming event iterator.
+   * Send a prompt or request and get a streaming event iterator.
    *
    * Returns an `EventStream`. Use `for await (const event of stream)` or call `.next()` manually.
    * When `history` is omitted, the session history and verification evidence are
    * updated after the stream completes. Supplying `history` keeps the stream isolated.
+   */
+  stream(request: string | SessionRequestOptions, history?: Array<MessageObject> | null): Promise<EventStream>
+  /**
+   * Send a request using the long-lived object-shaped API.
    *
-   * @param prompt - The prompt to send
-   * @param history - Optional conversation history
+   * Prefer this for new integrations when the call may need history,
+   * attachments, or future request options.
    */
-  stream(prompt: string, history?: Array<MessageObject> | undefined | null): Promise<EventStream>
+  sendRequest(request: SessionRequestOptions): Promise<AgentResult>
+  /** Stream a request using the long-lived object-shaped API. */
+  streamRequest(request: SessionRequestOptions): Promise<EventStream>
   /**
    * Send a prompt with image attachments and wait for the complete response.
    *
@@ -796,13 +897,19 @@ export declare class Session {
   runEvents(runId: string): Promise<any>
   /** Return the currently running operation, or null when idle. */
   currentRun(): Promise<any>
+  /** Return active tool calls observed for the currently running operation. */
+  activeTools(): Promise<any>
   /** Cancel a specific run only if it is still the active run. */
   cancelRun(runId: string): Promise<boolean>
   /** Execute a tool by name, bypassing the LLM. */
   tool(name: string, args: any): Promise<ToolResult>
   /** Delegate a bounded task to a child agent through the built-in `task` tool. */
+  task(options: DelegateTaskOptions): Promise<ToolResult>
+  /** Delegate a bounded task to a child agent through the built-in `task` tool. */
   delegateTask(options: DelegateTaskOptions): Promise<ToolResult>
   /** Execute several delegated child-agent tasks concurrently through `parallel_task`. */
+  tasks(tasks: DelegateTaskOptions[]): Promise<ToolResult>
+  /** Execute several delegated child-agent tasks concurrently through `parallel_task`. */
   parallelTask(tasks: DelegateTaskOptions[]): Promise<ToolResult>
   /** Run a bounded JavaScript script through the embedded QuickJS `program` tool. */
   program(options: ProgramScriptOptions): Promise<ToolResult>
@@ -816,8 +923,24 @@ export declare class Session {
   grep(pattern: string): Promise<string>
   /** Search the web using multiple search engines. */
   webSearch(params: JsWebSearchParams): Promise<ToolResult>
-  /** Execute a git command (status, log, branch, checkout, diff, stash, remote, worktree). */
-  git(command: string, subcommand?: string | undefined | null, name?: string | undefined | null, path?: string | undefined | null, newBranch?: boolean | undefined | null, base?: string | undefined | null, force?: boolean | undefined | null, maxCount?: number | undefined | null, message?: string | undefined | null, includeUntracked?: boolean | undefined | null, target?: string | undefined | null, reference?: string | undefined | null): Promise<ToolResult>
+  /**
+   * Execute a git command.
+   *
+   * Prefer `git({ command: "status" })`; positional arguments remain for
+   * compatibility.
+   */
+  git(command: string | GitCommandOptions, subcommand?: string | null, name?: string | null, path?: string | null, newBranch?: boolean | null, base?: string | null, force?: boolean | null, maxCount?: number | null, message?: string | null, includeUntracked?: boolean | null, target?: string | null, reference?: string | null): Promise<ToolResult>
+  /**
+   * Execute a git command with an object-shaped API.
+   *
+   * Preferred over the positional `git(...)` overload for new callers.
+   *
+   * ```js
+   * await session.gitCommand({ command: 'status' })
+   * await session.gitCommand({ command: 'worktree', subcommand: 'list' })
+   * ```
+   */
+  gitCommand(args: GitCommandOptions): Promise<ToolResult>
   /** Check if this session has an advanced lane queue configured. */
   hasQueue(): boolean
   /**
@@ -837,6 +960,19 @@ export declare class Session {
   completeExternalTask(taskId: string, result: ExternalTaskResult): Promise<boolean>
   /** Get pending external queue tasks. */
   pendingExternalTasks(): Promise<any>
+  /** Return pending HITL tool confirmations for this session. */
+  pendingConfirmations(): Promise<Array<PendingConfirmation>>
+  /**
+   * Resolve a pending HITL tool confirmation.
+   *
+   * @param toolId - Tool call ID from a `confirmation_required` event.
+   * @param approved - Whether the tool execution should proceed.
+   * @param reason - Optional human-readable reason for audit/UI display.
+   * @returns true if a pending confirmation was found and completed.
+   */
+  confirmToolUse(toolId: string, approved: boolean, reason?: string | undefined | null): Promise<boolean>
+  /** Cancel all pending HITL confirmations for this session. */
+  cancelConfirmations(): Promise<number>
   /** Get optional queue statistics. */
   queueStats(): Promise<QueueStats>
   /** Return compact execution trace events recorded for this session. */
@@ -878,6 +1014,23 @@ export declare class Session {
    * @returns Number of tools registered from the server
    */
   addMcpServer(name: string, transport?: 'stdio' | 'http' | 'streamable-http', command?: string | undefined | null, args?: Array<string> | undefined | null, url?: string | undefined | null, headers?: Record<string, string> | undefined | null, env?: Record<string, string> | undefined | null, timeoutMs?: number | undefined | null): Promise<number>
+  /**
+   * Add an MCP server with a typed object config.
+   *
+   * Preferred over the positional overload for new SDK callers.
+   *
+   * ```js
+   * await session.addMcpServerConfig({
+   *   name: 'github',
+   *   transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
+   *   env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
+   *   timeoutMs: 30000,
+   * })
+   * ```
+   */
+  addMcpServerConfig(config: McpServerConfig): Promise<number>
+  /** Add an MCP server with the compact object-shaped API. */
+  addMcp(config: McpServerConfig): Promise<number>
   /**
    * Dynamically register agent definitions from a directory into the live session.
    *
@@ -890,18 +1043,38 @@ export declare class Session {
    * @returns Number of agents successfully loaded
    */
   registerAgentDir(path: string): number
+  /**
+   * Register a disposable worker agent into the live session.
+   *
+   * The worker is immediately callable through the model-visible `task` tool.
+   *
+   * @param worker - Worker spec to register
+   * @returns Compiled agent definition
+   */
+  registerWorkerAgent(worker: WorkerAgentSpec): AgentDefinition
+  /**
+   * Register many disposable workers into the live session.
+   *
+   * @param workers - Worker specs to register
+   * @returns Compiled agent definitions
+   */
+  registerWorkerAgents(workers: Array<WorkerAgentSpec>): Array<AgentDefinition>
   /**
    * Disconnect and unregister an MCP server, removing its tools from the session.
    *
    * @param name - Server name (must match the name used in addMcpServer)
    */
   removeMcpServer(name: string): Promise<void>
+  /** Remove an MCP server with the compact API. */
+  removeMcp(name: string): Promise<void>
   /**
    * Return connection status for all MCP servers registered on this session.
    *
    * @returns Array of `{ name, connected, toolCount }` entries
    */
   mcpStatus(): Promise<Array<McpServerStatusEntry>>
+  /** Return MCP server status with the compact API. */
+  mcps(): Promise<Array<McpServerStatusEntry>>
   /**
    * Return the names of all tools currently registered on this session.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/code",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "A3S Code - Native Node.js bindings for the coding-agent runtime",
   "main": "index.js",
   "types": "index.d.ts",
@@ -40,11 +40,11 @@
     "test:helpers": "node test-helpers.mjs"
   },
   "optionalDependencies": {
-    "@a3s-lab/code-darwin-arm64": "2.1.0",
-    "@a3s-lab/code-linux-x64-gnu": "2.1.0",
-    "@a3s-lab/code-linux-x64-musl": "2.1.0",
-    "@a3s-lab/code-linux-arm64-gnu": "2.1.0",
-    "@a3s-lab/code-linux-arm64-musl": "2.1.0",
-    "@a3s-lab/code-win32-x64-msvc": "2.1.0"
+    "@a3s-lab/code-darwin-arm64": "2.3.0",
+    "@a3s-lab/code-linux-x64-gnu": "2.3.0",
+    "@a3s-lab/code-linux-x64-musl": "2.3.0",
+    "@a3s-lab/code-linux-arm64-gnu": "2.3.0",
+    "@a3s-lab/code-linux-arm64-musl": "2.3.0",
+    "@a3s-lab/code-win32-x64-msvc": "2.3.0"
   }
 }