@a3s-lab/code 2.0.0 → 2.0.1

package/README.md

@@ -28,6 +28,32 @@ main().catch(console.error)
 
 `session.tool(...)` returns a `ToolResult` enriched with parsed metadata helpers.
 
+## Programmatic Tool Calling
+
+`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 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 },
+})
+
+console.log(result.output)
+```
+
+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 Parse LLM Blocks
 
 When `agentic_parse` runs with a query, the SDK exposes the exact structured

package/index.d.ts

@@ -108,6 +108,26 @@ export interface ToolResult {
   /** Convenience JSON view of `metadata.document_runtime` when present. */
   documentRuntimeJson?: string
 }
+export interface ProgramScriptLimits {
+  /** Wall-clock timeout for the embedded QuickJS script. */
+  timeoutMs?: number
+  /** Maximum number of ctx tool calls the script may perform. */
+  maxToolCalls?: number
+  /** Maximum bytes returned in the program result output. */
+  maxOutputBytes?: number
+}
+export interface ProgramScriptOptions {
+  /** Inline JavaScript source. Define `async function run(ctx, inputs)` or export it as default. */
+  source?: string
+  /** Workspace-relative `.js` or `.mjs` script path. */
+  path?: string
+  /** JSON-serializable inputs passed to `run(ctx, inputs)`. */
+  inputs?: any
+  /** Optional tool allow-list. Defaults to every registered tool except `program`. */
+  allowedTools?: Array<string>
+  /** Execution limits for the script. */
+  limits?: ProgramScriptLimits
+}
 /** Parameters for the web_search tool. */
 export interface JsWebSearchParams {
   /** The search query. */
@@ -859,6 +879,8 @@ export declare class Session {
   history(): Array<MessageObject>
   /** Execute a tool by name, bypassing the LLM. */
   tool(name: string, args: any): 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/code",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A3S Code - Native Node.js bindings for the coding-agent runtime",
   "main": "index.js",
   "types": "index.d.ts",
@@ -43,11 +43,11 @@
     "test:agentic-parse-llm-blocks": "node examples/search/test-agentic-parse-llm-blocks.js"
   },
   "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.0.1",
+    "@a3s-lab/code-linux-x64-gnu": "2.0.1",
+    "@a3s-lab/code-linux-x64-musl": "2.0.1",
+    "@a3s-lab/code-linux-arm64-gnu": "2.0.1",
+    "@a3s-lab/code-linux-arm64-musl": "2.0.1",
+    "@a3s-lab/code-win32-x64-msvc": "2.0.1"
   }
 }