la-machina-engine 0.7.10 → 0.9.0

package/README.md

@@ -73,7 +73,38 @@ npm install la-machina-engine
 
 Requires Node 20+. Works in Bun, Cloudflare Workers (with R2 storage).
 
-The package is published as a single bundled module (~330 KB ESM, ~340 KB CJS) with full TypeScript types. Built with [tsup](https://tsup.egoist.dev/), CI publishes with [Sigstore provenance](https://docs.npmjs.com/generating-provenance-statements).
+The package is published as a single bundled module (~330 KB ESM, ~340 KB CJS) with full TypeScript types plus two Node-only subpaths (`/node-tools`, `/node-mcp`). Built with [tsup](https://tsup.egoist.dev/), CI publishes with [Sigstore provenance](https://docs.npmjs.com/generating-provenance-statements).
+
+### 0.7.x → 0.8.0 migration
+
+0.8.0 makes the engine fully runtime-agnostic. The default bundle no longer auto-registers `Bash` or auto-stubs MCP stdio servers based on `process.versions.node` probing — the caller now decides which Tools the engine sees per environment. See `plans/031-runtime-agnostic-engine.md` for the full design.
+
+Two changes consumers may need:
+
+```ts
+// Workers callers — Bash via capabilityStub (model sees it; engine
+// pauses with handoff_to_runner when called):
+import { initEngine, capabilityStub } from 'la-machina-engine'
+initEngine({
+  tools: { custom: [capabilityStub({ name: 'Bash', description: '...' })] },
+})
+
+// Node callers — real Bash via the new node-tools subpath:
+import { initEngine } from 'la-machina-engine'
+import { createBashTool } from 'la-machina-engine/node-tools'
+initEngine({ tools: { custom: [createBashTool()] } })
+
+// Stdio MCP on Node — pass a transport factory:
+import { createStdioTransportFactory } from 'la-machina-engine/node-mcp'
+initEngine({
+  mcp: {
+    servers: { local: { type: 'stdio', command: 'npx', args: ['mcp-server-x'], ... } },
+    stdioTransport: createStdioTransportFactory(),
+  },
+})
+```
+
+Without `mcp.stdioTransport`, configuring a stdio MCP server fails at connect with a clean error pointing at the subpath (see `plans/031-runtime-agnostic-engine.md`).
 
 ---
 
@@ -1270,6 +1301,28 @@ model cannot spoof `Authorization` via `input.headers`).
 dispatch with `{ service, method, path, status, latencyMs, bytesIn }`
 — no secrets — for metering, billing, audit logs.
 
+**Raw-body uploads (0.9.0):** set `bodyEncoding: 'raw'` on the call to
+send a string body verbatim — no `JSON.stringify`. Use for upload APIs
+that take binary or text-blob bodies (Drive media upload, S3
+PutObject, image push, log ingestion, etc.). The caller-supplied
+`Content-Type` header wins; default falls back to `text/plain`.
+
+```ts
+ApiCall({
+  service: 'gdrive',
+  method: 'PATCH',
+  path: `/upload/drive/v3/files/${fileId}?uploadType=media`,
+  headers: { 'Content-Type': 'text/markdown' },
+  body: '# Hello world',
+  bodyEncoding: 'raw',
+})
+```
+
+`bodyEncoding: 'raw'` requires the body to be a string — passing an
+object returns `ERR_API_RAW_BODY_NOT_STRING` and never makes the
+fetch. The default `'json'` encoding behaves exactly as in 0.8.x.
+`maxBodyBytes` is enforced under both encodings.
+
 **Disabling:** `tools.disabled: ['ApiCall']` turns it off even when
 services are configured. Absent `config.api` → tool never registered,
 no prompt mention.

package/dist/contract-BY-GqoYk.d.cts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+
+/**
+ * Tool contract — the shape every tool implements, plus a registry to
+ * collect them by name.
+ *
+ * The contract is intentionally minimal:
+ *
+ *   1. A tool has a `name`, a `description`, and a Zod `inputSchema`.
+ *      Zod gives both runtime validation and a TypeScript-inferred
+ *      input type for `execute()`.
+ *   2. `execute(input, context)` returns a `ToolResult` (or rejects).
+ *      The runtime catches rejections and turns them into error
+ *      results — a misbehaving tool can never crash the agent loop.
+ *   3. The runtime supplies a `ToolContext` carrying at least an
+ *      `AbortSignal` for cancellation.
+ *
+ * Phase 5 ships the types and the registry. Phase 6 fills the registry
+ * with the core tool set (Bash, Read, Write, Edit, Glob, Grep, WebFetch).
+ * Custom tools come from `config.tools.custom` at engine init time.
+ */
+
+/**
+ * The execution context passed to every tool. Phase 5 keeps this
+ * minimal — only an AbortSignal — so the contract stays portable.
+ * Later phases extend with storage, run/node ids, hook handles, etc.
+ */
+interface ToolContext {
+    readonly signal: AbortSignal;
+}
+/**
+ * The result of a single tool invocation. The runtime wraps thrown
+ * errors in this shape so the agent loop only ever sees success/error
+ * as data, not exceptions.
+ */
+interface ToolResult {
+    /** Human- and model-readable output. The agent's next turn sees this. */
+    readonly content: string;
+    /** True when the tool failed. */
+    readonly isError?: boolean;
+    /** Optional structured metadata for hooks / observability. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A tool definition. Generic on a Zod schema so that `execute()`'s
+ * input parameter is statically typed via `z.infer<TSchema>`.
+ *
+ * Tool authors normally use `defineTool()` to get the inference
+ * without writing the generic by hand.
+ */
+interface Tool<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: TSchema;
+    /**
+     * Optional raw JSON Schema to send to the Anthropic API as
+     * `input_schema`, bypassing Zod-to-JSON-Schema conversion. Used by
+     * MCP-sourced tools whose schema is authored in JSON Schema directly
+     * and whose Zod schema is a `z.unknown()` passthrough.
+     *
+     * When set, `toAnthropicTool()` in the agent loop prefers this over
+     * running `zodToJsonSchema(inputSchema)`. Normal in-process tools
+     * defined via `defineTool()` should leave this undefined.
+     */
+    readonly anthropicSchemaOverride?: Record<string, unknown>;
+    /**
+     * Returns true if this tool is safe to run concurrently with other
+     * concurrency-safe tools. Read-only tools (Read, Glob, Grep, etc.)
+     * should return true; mutating tools (Write, Edit, Bash) should
+     * return false. Default: false (fail-closed).
+     *
+     * The agent loop uses this to batch consecutive safe tool calls
+     * into a single `Promise.all()` for parallel execution, while
+     * running unsafe tools serially.
+     *
+     * Input is typed as `unknown` (not `z.infer<TSchema>`) so that
+     * `Tool<ZodObject<...>>` remains assignable to `Tool<ZodTypeAny>`
+     * under `exactOptionalPropertyTypes`.
+     */
+    isConcurrencySafe?: ((input: unknown) => boolean) | undefined;
+    /**
+     * Declares that this tool needs Node-only capabilities
+     * (`node:child_process`, the real filesystem, stdio-based MCP, etc.)
+     * When true AND the runtime can't support them, the engine replaces
+     * this tool with a capability stub (see `src/tools/capabilityStub.ts`)
+     * that returns a structured `isError` result instead of crashing.
+     *
+     * Leave undefined / false for tools that work anywhere (Read, Write,
+     * WebFetch, http-based MCP). Default: false.
+     */
+    readonly requiresNode?: boolean;
+    /**
+     * Internal marker set by `capabilityStub()` so the agent-loop's
+     * runner-handoff check (Plan 019 §4) can distinguish a stubbed tool
+     * from a real one without reflecting on the implementation.
+     * Do not set this manually.
+     */
+    readonly isCapabilityStub?: boolean;
+    execute(input: z.infer<TSchema>, context: ToolContext): Promise<ToolResult>;
+}
+/**
+ * Identity helper that locks in the schema generic so callers don't have
+ * to write it. Use this whenever defining a tool — it costs nothing at
+ * runtime and gives you full inference inside `execute()`.
+ *
+ * @example
+ * ```ts
+ * const Echo = defineTool({
+ *   name: 'Echo',
+ *   description: 'Echoes its input back',
+ *   inputSchema: z.object({ msg: z.string() }),
+ *   execute: async ({ msg }) => ({ content: msg }),
+ * })
+ * ```
+ */
+declare function defineTool<TSchema extends z.ZodTypeAny>(tool: Tool<TSchema>): Tool<TSchema>;
+/**
+ * In-memory registry of tools by name. Used by the engine's tool runtime
+ * to dispatch tool calls. Re-registering the same name throws so typos
+ * surface immediately rather than silently shadowing.
+ */
+declare class ToolRegistry {
+    private readonly tools;
+    register(tool: Tool): void;
+    registerAll(tools: ReadonlyArray<Tool>): void;
+    unregister(name: string): void;
+    get(name: string): Tool | undefined;
+    has(name: string): boolean;
+    list(): Tool[];
+    count(): number;
+}
+
+export { type ToolResult as T, ToolRegistry as a, type Tool as b, type ToolContext as c, defineTool as d };

package/dist/contract-BY-GqoYk.d.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+
+/**
+ * Tool contract — the shape every tool implements, plus a registry to
+ * collect them by name.
+ *
+ * The contract is intentionally minimal:
+ *
+ *   1. A tool has a `name`, a `description`, and a Zod `inputSchema`.
+ *      Zod gives both runtime validation and a TypeScript-inferred
+ *      input type for `execute()`.
+ *   2. `execute(input, context)` returns a `ToolResult` (or rejects).
+ *      The runtime catches rejections and turns them into error
+ *      results — a misbehaving tool can never crash the agent loop.
+ *   3. The runtime supplies a `ToolContext` carrying at least an
+ *      `AbortSignal` for cancellation.
+ *
+ * Phase 5 ships the types and the registry. Phase 6 fills the registry
+ * with the core tool set (Bash, Read, Write, Edit, Glob, Grep, WebFetch).
+ * Custom tools come from `config.tools.custom` at engine init time.
+ */
+
+/**
+ * The execution context passed to every tool. Phase 5 keeps this
+ * minimal — only an AbortSignal — so the contract stays portable.
+ * Later phases extend with storage, run/node ids, hook handles, etc.
+ */
+interface ToolContext {
+    readonly signal: AbortSignal;
+}
+/**
+ * The result of a single tool invocation. The runtime wraps thrown
+ * errors in this shape so the agent loop only ever sees success/error
+ * as data, not exceptions.
+ */
+interface ToolResult {
+    /** Human- and model-readable output. The agent's next turn sees this. */
+    readonly content: string;
+    /** True when the tool failed. */
+    readonly isError?: boolean;
+    /** Optional structured metadata for hooks / observability. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A tool definition. Generic on a Zod schema so that `execute()`'s
+ * input parameter is statically typed via `z.infer<TSchema>`.
+ *
+ * Tool authors normally use `defineTool()` to get the inference
+ * without writing the generic by hand.
+ */
+interface Tool<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: TSchema;
+    /**
+     * Optional raw JSON Schema to send to the Anthropic API as
+     * `input_schema`, bypassing Zod-to-JSON-Schema conversion. Used by
+     * MCP-sourced tools whose schema is authored in JSON Schema directly
+     * and whose Zod schema is a `z.unknown()` passthrough.
+     *
+     * When set, `toAnthropicTool()` in the agent loop prefers this over
+     * running `zodToJsonSchema(inputSchema)`. Normal in-process tools
+     * defined via `defineTool()` should leave this undefined.
+     */
+    readonly anthropicSchemaOverride?: Record<string, unknown>;
+    /**
+     * Returns true if this tool is safe to run concurrently with other
+     * concurrency-safe tools. Read-only tools (Read, Glob, Grep, etc.)
+     * should return true; mutating tools (Write, Edit, Bash) should
+     * return false. Default: false (fail-closed).
+     *
+     * The agent loop uses this to batch consecutive safe tool calls
+     * into a single `Promise.all()` for parallel execution, while
+     * running unsafe tools serially.
+     *
+     * Input is typed as `unknown` (not `z.infer<TSchema>`) so that
+     * `Tool<ZodObject<...>>` remains assignable to `Tool<ZodTypeAny>`
+     * under `exactOptionalPropertyTypes`.
+     */
+    isConcurrencySafe?: ((input: unknown) => boolean) | undefined;
+    /**
+     * Declares that this tool needs Node-only capabilities
+     * (`node:child_process`, the real filesystem, stdio-based MCP, etc.)
+     * When true AND the runtime can't support them, the engine replaces
+     * this tool with a capability stub (see `src/tools/capabilityStub.ts`)
+     * that returns a structured `isError` result instead of crashing.
+     *
+     * Leave undefined / false for tools that work anywhere (Read, Write,
+     * WebFetch, http-based MCP). Default: false.
+     */
+    readonly requiresNode?: boolean;
+    /**
+     * Internal marker set by `capabilityStub()` so the agent-loop's
+     * runner-handoff check (Plan 019 §4) can distinguish a stubbed tool
+     * from a real one without reflecting on the implementation.
+     * Do not set this manually.
+     */
+    readonly isCapabilityStub?: boolean;
+    execute(input: z.infer<TSchema>, context: ToolContext): Promise<ToolResult>;
+}
+/**
+ * Identity helper that locks in the schema generic so callers don't have
+ * to write it. Use this whenever defining a tool — it costs nothing at
+ * runtime and gives you full inference inside `execute()`.
+ *
+ * @example
+ * ```ts
+ * const Echo = defineTool({
+ *   name: 'Echo',
+ *   description: 'Echoes its input back',
+ *   inputSchema: z.object({ msg: z.string() }),
+ *   execute: async ({ msg }) => ({ content: msg }),
+ * })
+ * ```
+ */
+declare function defineTool<TSchema extends z.ZodTypeAny>(tool: Tool<TSchema>): Tool<TSchema>;
+/**
+ * In-memory registry of tools by name. Used by the engine's tool runtime
+ * to dispatch tool calls. Re-registering the same name throws so typos
+ * surface immediately rather than silently shadowing.
+ */
+declare class ToolRegistry {
+    private readonly tools;
+    register(tool: Tool): void;
+    registerAll(tools: ReadonlyArray<Tool>): void;
+    unregister(name: string): void;
+    get(name: string): Tool | undefined;
+    has(name: string): boolean;
+    list(): Tool[];
+    count(): number;
+}
+
+export { type ToolResult as T, ToolRegistry as a, type Tool as b, type ToolContext as c, defineTool as d };