@a3s-lab/code 2.0.0 → 2.1.0

package/README.md

@@ -24,62 +24,83 @@ async function main() {
 main().catch(console.error)
 ```
 
-## Tool Metadata Helpers
+## Programmatic Tool Calling
 
-`session.tool(...)` returns a `ToolResult` enriched with parsed metadata helpers.
-
-### Agentic Parse LLM Blocks
-
-When `agentic_parse` runs with a query, the SDK exposes the exact structured
-document blocks selected for the LLM input.
+`session.program(...)` runs a bounded JavaScript script in the embedded QuickJS
+runtime. It is the SDK-friendly wrapper around the core `program` tool.
 
 ```js
-const tool = await session.tool('agentic_parse', {
-  path: 'docs/scanned.pdf',
-  query: 'overview',
+const result = await session.program({
+  source: `
+    export default async function run(ctx, inputs) {
+      const hits = await ctx.grep(inputs.query, { glob: '*.ts' })
+      const files = await ctx.glob('src/**/*.ts')
+      return { hits, files: files.slice(0, 10) }
+    }
+  `,
+  inputs: { query: 'PermissionPolicy' },
+  allowedTools: ['grep', 'glob'],
+  limits: { timeoutMs: 30000, maxToolCalls: 20, maxOutputBytes: 65536 },
 })
 
-for (const block of tool.agenticParseLlmBlocks ?? []) {
-  console.log(block.index, block.kind, block.label, block.location?.display)
-}
+console.log(result.output)
 ```
 
-### Agentic Search Match Locators
+Omit `allowedTools` to allow every registered session tool except `program`.
+Scripts can also be loaded from workspace-relative `.js` or `.mjs` files with
+`{ path: 'scripts/ptc/search.js' }`.
 
-`agentic_search` results expose typed match metadata, including page / section
-locators derived from `CompositeDocumentParser` blocks.
+## Planning Events
 
-```js
-const search = await session.tool('agentic_search', {
-  query: 'overview',
-  mode: 'fast',
-})
+Planning is automatic by default. Prefer the explicit tri-state
+`planningMode` contract for SDK callers:
 
-for (const result of search.agenticSearchResults ?? []) {
-  for (const match of result.matches ?? []) {
-    console.log(match.lineNumber, match.locator, match.content)
-  }
-}
+```js
+agent.session('/my-project', { planningMode: 'auto' })     // default
+agent.session('/my-project', { planningMode: 'enabled' })  // force planning
+agent.session('/my-project', { planningMode: 'disabled' }) // explicitly off
 ```
 
-Deep search also exposes `sampledLines` with `locator`, `distance`, and `weight`.
+The legacy boolean shortcut still works: `{ planning: true }` forces planning
+and `{ planning: false }` disables it.
+
+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.
+
+## Delegation And Tool Introspection
+
+The SDK exposes the core `task` / `parallel_task` tools as direct helpers:
 
 ```js
-const deep = await session.tool('agentic_search', {
-  query: 'overview',
-  mode: 'deep',
+await session.delegateTask({
+  agent: 'explore',
+  description: 'Find auth entry points',
+  prompt: 'Inspect the repository and summarize the auth-related files.',
 })
 
-for (const result of deep.agenticSearchResults ?? []) {
-  for (const sampled of result.sampledLines ?? []) {
-    console.log(sampled.lineNumber, sampled.locator, sampled.distance, sampled.weight)
-  }
-}
+await session.parallelTask([
+  { agent: 'explore', description: 'Find tests', prompt: 'Locate auth tests.' },
+  { agent: 'verification', description: 'Check risk', prompt: 'Review auth edge cases.' },
+])
 ```
 
-## Examples
+Use `session.toolNames()` for names and `session.toolDefinitions()` when a UI
+needs the full model-visible schemas.
+
+## Run Replay
+
+Each `send(...)` or `stream(...)` call records a run snapshot and replayable
+runtime events:
+
+```js
+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))
+```
 
-- `examples/test-agentic-parse-llm-blocks.js`
-- `examples/test-agentic-search-locators.js`
-- `examples/test-agentic-search-sampled-lines.js`
-- `examples/test-agentic-search-sdk.js`
+Use `session.currentRun()` while a stream is active to inspect the current run.
+Use `session.cancelRun(run.id)` to cancel only that run; stale IDs will not
+cancel a newer operation.

package/index.d.ts

@@ -108,6 +108,28 @@ export interface ToolResult {
   /** Convenience JSON view of `metadata.document_runtime` when present. */
   documentRuntimeJson?: string
 }
+/** Execution limits for `Session.program`. */
+export interface ProgramScriptLimits {
+  timeoutMs?: number
+  maxToolCalls?: number
+  maxOutputBytes?: number
+}
+/** Options for `Session.program`. */
+export interface ProgramScriptOptions {
+  source?: string
+  path?: string
+  inputs?: any
+  allowedTools?: Array<string>
+  limits?: ProgramScriptLimits
+}
+/** Options for `Session.delegateTask`. */
+export interface DelegateTaskOptions {
+  agent: string
+  description: string
+  prompt: string
+  background?: boolean
+  maxSteps?: number
+}
 /** Parameters for the web_search tool. */
 export interface JsWebSearchParams {
   /** The search query. */
@@ -153,20 +175,6 @@ export interface JsSessionStore {
 export interface JsSecurityProvider {
   kind: string
 }
-/**
- * A plugin descriptor passed in `SessionOptions.plugins`.
- *
- * Use `new SkillPlugin(...)` to create plugin instances — do not construct
- * this object directly.
- */
-export interface JsPlugin {
-  /** Plugin kind: currently only `"skill_plugin"`. */
-  kind: string
-  /** Plugin name (used by SkillPlugin). */
-  pluginName?: string
-  /** Skill YAML/markdown content strings (used by SkillPlugin). */
-  skills?: Array<string>
-}
 /**
  * Union type for AHP transport configuration.
  * Accepts any of: StdioTransport, HttpTransport, WebSocketTransport, UnixSocketTransport.
@@ -194,7 +202,7 @@ export interface PermissionPolicy {
 export interface SessionOptions {
   /** Override the default model. Format: "provider/model" (e.g., "openai/gpt-4o"). */
   model?: string
-  /** Enable built-in skills (7 skills: code-search, code-review, explain-code, find-bugs, builtin-tools, delegate-task, find-skills). */
+  /** Enable built-in skills (4 skills: code-search, code-review, explain-code, find-bugs). */
   builtinSkills?: boolean
   /** Extra directories to scan for skill files (.md with YAML frontmatter). */
   skillDirs?: Array<string>
@@ -208,7 +216,14 @@ export interface SessionOptions {
   queueConfig?: SessionQueueConfig
   /** Explicit permission policy for tool execution. */
   permissionPolicy?: PermissionPolicy
-  /** Enable planning mode (default: false). */
+  /**
+   * Explicit planning mode: "auto", "enabled", or "disabled".
+   *
+   * Prefer this over `planning` when the caller needs an unambiguous SDK contract.
+   * If both are set, `planningMode` wins.
+   */
+  planningMode?: string
+  /** Legacy planning shortcut. Omit for auto planning, true to force planning, false to disable. */
   planning?: boolean
   /** Enable goal tracking (default: false). */
   goalTracking?: boolean
@@ -255,12 +270,6 @@ export interface SessionOptions {
    * ```
    */
   securityProvider?: JsSecurityProvider
-  /**
-   * Plugins to mount onto this session.
-   *
-   * Pass instances such as `new SkillPlugin(...)` to inject custom skills.
-   */
-  plugins?: Array<JsPlugin>
   /**
    * Custom role/identity prepended before the core agentic prompt.
    * Example: "You are a senior Python developer specializing in FastAPI."
@@ -525,55 +534,6 @@ export interface SearchConfig {
   engines: Record<string, SearchEngineConfig>
   headless?: HeadlessConfig
 }
-/** SubAgent configuration for the advanced orchestrator control plane. */
-export interface SubAgentConfig {
-  /** Agent type (general, explore, plan, etc.) */
-  agentType: string
-  /** Task description */
-  description: string
-  /** Execution prompt */
-  prompt: string
-  /** Maximum execution steps */
-  maxSteps?: number
-  /** Execution timeout (milliseconds) */
-  timeoutMs?: number
-  /** Parent SubAgent ID (for nesting) */
-  parentId?: string
-  /** Workspace directory for the SubAgent (defaults to ".") */
-  workspace?: string
-  /** Extra directories to scan for agent definition files */
-  agentDirs?: Array<string>
-  /** Extra directories to scan for skill definition files */
-  skillDirs?: Array<string>
-}
-/** SubAgent activity type */
-export interface SubAgentActivity {
-  /** Activity type: idle, calling_tool, requesting_llm, waiting_for_control */
-  activityType: string
-  /** Activity data (JSON string) */
-  data?: string
-}
-/** SubAgent information with metadata and current activity */
-export interface SubAgentInfo {
-  id: string
-  agentType: string
-  description: string
-  state: string
-  parentId?: string
-  createdAt: number
-  updatedAt: number
-  currentActivity?: SubAgentActivity
-}
-/** SubAgent activity entry (id + activity) */
-export interface SubAgentActivityEntry {
-  id: string
-  activity: SubAgentActivity
-}
-/** SubAgent state entry (id + state) */
-export interface SubAgentStateEntry {
-  id: string
-  state: string
-}
 /** Streaming event iterator. Use `for await (const event of stream)` or call `.next()` manually. */
 export declare class EventStream {
   /**
@@ -638,35 +598,6 @@ export declare class DefaultSecurityProvider {
   kind: string
   constructor()
 }
-/**
- * Skill-only plugin — injects custom skills into the session's skill registry
- * without registering any tools.
- *
- * Use this to add custom LLM guidance (instructions, tool restrictions,
- * prompting strategies) directly from Node.js. For tools, use MCP servers.
- *
- * ```js
- * import { SkillPlugin } from '@a3s-lab/code';
- *
- * const plugin = new SkillPlugin('my-plugin', [`
- * ---
- * name: my-skill
- * description: Use bash cautiously
- * allowed-tools: "bash(*)"
- * kind: instruction
- * ---
- * Always explain what command you're about to run before executing it.
- * `]);
- *
- * agent.session('.', { plugins: [plugin] });
- * ```
- */
-export declare class SkillPlugin {
-  kind: string
-  pluginName?: string
-  skills?: Array<string>
-  constructor(name: string, skills: Array<string>)
-}
 /**
  * Stdio transport for AHP (Agent Harness Protocol).
  *
@@ -857,8 +788,24 @@ export declare class Session {
   streamWithAttachments(prompt: string, attachments: Array<AttachmentObject>, history?: Array<MessageObject> | undefined | null): Promise<EventStream>
   /** Return the session's conversation history. */
   history(): Array<MessageObject>
+  /** Return run snapshots recorded by this session. */
+  runs(): Promise<any>
+  /** Return a run snapshot by ID, or null when it is unknown. */
+  runSnapshot(runId: string): Promise<any>
+  /** Return recorded runtime events for a run. */
+  runEvents(runId: string): Promise<any>
+  /** Return the currently running operation, or null when idle. */
+  currentRun(): 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. */
+  delegateTask(options: 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>
   /** Read a file from the workspace. */
   readFile(path: string): Promise<string>
   /** Execute a bash command in the workspace. */
@@ -961,6 +908,8 @@ export declare class Session {
    * @returns Array of tool name strings
    */
   toolNames(): Array<string>
+  /** Return full model-visible tool definitions currently registered on this session. */
+  toolDefinitions(): any
   /**
    * Register a hook for lifecycle event interception.
    *
@@ -1121,61 +1070,3 @@ export declare class Session {
    */
   close(): void
 }
-/** SubAgent handle for control and monitoring. */
-export declare class SubAgentHandle {
-  /** Get SubAgent ID */
-  get id(): string
-  /** Get current state (non-blocking) */
-  state(): string
-  /** Get current activity */
-  activity(): SubAgentActivity
-  /** Pause execution */
-  pause(): void
-  /** Resume execution */
-  resume(): void
-  /** Cancel execution */
-  cancel(): void
-  /** Wait for completion and get result */
-  wait(): string
-  /** Subscribe to sub-agent events. */
-  events(): SubAgentEventStream
-}
-/** SubAgent event stream for monitoring sub-agent events. */
-export declare class SubAgentEventStream {
-  /** Receive the next sub-agent event, or `null` on timeout / end-of-stream. */
-  recv(timeoutMs?: number | undefined | null): Promise<any | null>
-}
-/**
- * Advanced orchestrator for explicit SubAgent lifecycle control.
- *
- * Routine multi-agent work should use `task` / `parallelTask` delegation; this
- * API is for monitoring and controlling long-running SubAgents directly.
- */
-export declare class Orchestrator {
-  /**
-   * Create a new orchestrator.
-   *
-   * @param agent - `Agent` instance used to execute spawned SubAgents.
-   */
-  static create(agent: Agent): Orchestrator
-  /** Spawn a new SubAgent */
-  spawnSubagent(config: SubAgentConfig): SubAgentHandle
-  /** Get active SubAgent count */
-  activeCount(): number
-  /** Get all SubAgent information list */
-  listSubagents(): Array<SubAgentInfo>
-  /** Get specific SubAgent information */
-  getSubagentInfo(id: string): SubAgentInfo | null
-  /** Get all active SubAgent activities */
-  getActiveActivities(): Array<SubAgentActivityEntry>
-  /** Get all SubAgent states */
-  getAllStates(): Array<SubAgentStateEntry>
-  /** Pause a SubAgent */
-  pauseSubagent(id: string): void
-  /** Resume a SubAgent */
-  resumeSubagent(id: string): void
-  /** Cancel a SubAgent */
-  cancelSubagent(id: string): void
-  /** Wait for all SubAgents to complete */
-  waitAll(): void
-}

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { formatVerificationSummary, EventStream, FileMemoryStore, FileSessionStore, MemorySessionStore, DefaultSecurityProvider, SkillPlugin, StdioTransport, HttpTransport, WebSocketTransport, UnixSocketTransport, Agent, Session, builtinSkills, BrowserBackend, SubAgentHandle, SubAgentEventStream, Orchestrator } = nativeBinding
+const { formatVerificationSummary, EventStream, FileMemoryStore, FileSessionStore, MemorySessionStore, DefaultSecurityProvider, StdioTransport, HttpTransport, WebSocketTransport, UnixSocketTransport, Agent, Session, builtinSkills, BrowserBackend } = nativeBinding
 
 module.exports.formatVerificationSummary = formatVerificationSummary
 module.exports.EventStream = EventStream
@@ -318,7 +318,6 @@ module.exports.FileMemoryStore = FileMemoryStore
 module.exports.FileSessionStore = FileSessionStore
 module.exports.MemorySessionStore = MemorySessionStore
 module.exports.DefaultSecurityProvider = DefaultSecurityProvider
-module.exports.SkillPlugin = SkillPlugin
 module.exports.StdioTransport = StdioTransport
 module.exports.HttpTransport = HttpTransport
 module.exports.WebSocketTransport = WebSocketTransport
@@ -327,6 +326,3 @@ module.exports.Agent = Agent
 module.exports.Session = Session
 module.exports.builtinSkills = builtinSkills
 module.exports.BrowserBackend = BrowserBackend
-module.exports.SubAgentHandle = SubAgentHandle
-module.exports.SubAgentEventStream = SubAgentEventStream
-module.exports.Orchestrator = Orchestrator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/code",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A3S Code - Native Node.js bindings for the coding-agent runtime",
   "main": "index.js",
   "types": "index.d.ts",
@@ -37,17 +37,14 @@
     "build:debug": "napi build --platform --js index.js --dts index.d.ts",
     "prepublishOnly": "napi prepublish -t npm",
     "test": "node test.mjs",
-    "test:helpers": "node test-helpers.mjs",
-    "test:agentic-search-locators": "node examples/search/test-agentic-search-locators.js",
-    "test:agentic-search-sampled-lines": "node examples/search/test-agentic-search-sampled-lines.js",
-    "test:agentic-parse-llm-blocks": "node examples/search/test-agentic-parse-llm-blocks.js"
+    "test:helpers": "node test-helpers.mjs"
   },
   "optionalDependencies": {
-    "@a3s-lab/code-darwin-arm64": "2.0.0",
-    "@a3s-lab/code-linux-x64-gnu": "2.0.0",
-    "@a3s-lab/code-linux-x64-musl": "2.0.0",
-    "@a3s-lab/code-linux-arm64-gnu": "2.0.0",
-    "@a3s-lab/code-linux-arm64-musl": "2.0.0",
-    "@a3s-lab/code-win32-x64-msvc": "2.0.0"
+    "@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"
   }
 }