la-machina-engine 0.11.3 → 0.12.0

package/README.md

@@ -1861,6 +1861,7 @@ All features ported 1:1 from La-Machina's production runtime. Pure JS, Workers-c
 - [x] Bash error cascading (AbortController aborts sibling tools)
 - [x] 22 built-in tools
 - [x] Custom tool registration via `defineTool()`
+- [x] Gated tools via `defineGatedTool()` — pause the run on tool_use, resume via `engine.resumeAsync({toolResult})`. Full transcript preserved across the pause. Use for human-in-the-loop inputs, out-of-band approvals, anything where the result comes from a caller decision.
 - [x] Device path blocking (/dev/zero, /dev/random, /proc/kcore)
 - [x] Knowledge base (`SearchKnowledge` + `ReadKnowledge`) — opt-in, per-tenant vault under `workspaces/{ws}/knowledge/`, section-level indexing, format extractors (md/txt/json/csv/html native; pdf/docx via optional deps), external link headers with non-persistence guarantee
 

package/dist/{contract-BY-GqoYk.d.cts → contract-CK8kUyam.d.cts}

@@ -96,6 +96,20 @@ interface Tool<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
      * Do not set this manually.
      */
     readonly isCapabilityStub?: boolean;
+    /**
+     * Plan 043 — when true, the engine pauses the run as soon as the
+     * model calls this tool instead of dispatching `execute()`. The
+     * pending tool call (id, name, input) is captured in the snapshot;
+     * resume via `engine.resumeAsync({toolResult: {...}})` injects a
+     * synthetic `tool_result` message and continues the same loop with
+     * full transcript intact.
+     *
+     * Pauses emit `pauseReason: 'awaiting_tool_result'`.
+     *
+     * `execute` is never invoked on a gated tool — `defineGatedTool()`
+     * fills in a no-op stub so the Tool type stays consistent.
+     */
+    readonly gated?: boolean;
     execute(input: z.infer<TSchema>, context: ToolContext): Promise<ToolResult>;
 }
 /**
@@ -114,6 +128,29 @@ interface Tool<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
  * ```
  */
 declare function defineTool<TSchema extends z.ZodTypeAny>(tool: Tool<TSchema>): Tool<TSchema>;
+/**
+ * Plan 043 — define a tool that pauses the run instead of executing.
+ *
+ * The engine stops on `tool_use`, persists the pending call in the
+ * run snapshot, and waits for `engine.resumeAsync({toolResult: {...}})`
+ * to deliver the answer. Use this for human-in-the-loop inputs,
+ * out-of-band approvals, or any tool whose result comes from a
+ * caller decision rather than in-process computation.
+ *
+ * @example
+ * ```ts
+ * const AskHuman = defineGatedTool({
+ *   name: 'AskHuman',
+ *   description: 'Ask a human for information.',
+ *   inputSchema: z.object({ question: z.string() }),
+ * })
+ * ```
+ *
+ * `execute` is filled in with a no-op stub that flags the tool as
+ * "should not have been executed" if it's ever called — that
+ * indicates a code-path bug where the gated-tool pause was bypassed.
+ */
+declare function defineGatedTool<TSchema extends z.ZodTypeAny>(tool: Omit<Tool<TSchema>, 'execute' | 'gated'>): 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
@@ -130,4 +167,4 @@ declare class ToolRegistry {
     count(): number;
 }
 
-export { type ToolResult as T, ToolRegistry as a, type Tool as b, type ToolContext as c, defineTool as d };
+export { type ToolResult as T, ToolRegistry as a, type Tool as b, type ToolContext as c, defineGatedTool as d, defineTool as e };

package/dist/{contract-BY-GqoYk.d.ts → contract-CK8kUyam.d.ts}

@@ -96,6 +96,20 @@ interface Tool<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
      * Do not set this manually.
      */
     readonly isCapabilityStub?: boolean;
+    /**
+     * Plan 043 — when true, the engine pauses the run as soon as the
+     * model calls this tool instead of dispatching `execute()`. The
+     * pending tool call (id, name, input) is captured in the snapshot;
+     * resume via `engine.resumeAsync({toolResult: {...}})` injects a
+     * synthetic `tool_result` message and continues the same loop with
+     * full transcript intact.
+     *
+     * Pauses emit `pauseReason: 'awaiting_tool_result'`.
+     *
+     * `execute` is never invoked on a gated tool — `defineGatedTool()`
+     * fills in a no-op stub so the Tool type stays consistent.
+     */
+    readonly gated?: boolean;
     execute(input: z.infer<TSchema>, context: ToolContext): Promise<ToolResult>;
 }
 /**
@@ -114,6 +128,29 @@ interface Tool<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
  * ```
  */
 declare function defineTool<TSchema extends z.ZodTypeAny>(tool: Tool<TSchema>): Tool<TSchema>;
+/**
+ * Plan 043 — define a tool that pauses the run instead of executing.
+ *
+ * The engine stops on `tool_use`, persists the pending call in the
+ * run snapshot, and waits for `engine.resumeAsync({toolResult: {...}})`
+ * to deliver the answer. Use this for human-in-the-loop inputs,
+ * out-of-band approvals, or any tool whose result comes from a
+ * caller decision rather than in-process computation.
+ *
+ * @example
+ * ```ts
+ * const AskHuman = defineGatedTool({
+ *   name: 'AskHuman',
+ *   description: 'Ask a human for information.',
+ *   inputSchema: z.object({ question: z.string() }),
+ * })
+ * ```
+ *
+ * `execute` is filled in with a no-op stub that flags the tool as
+ * "should not have been executed" if it's ever called — that
+ * indicates a code-path bug where the gated-tool pause was bypassed.
+ */
+declare function defineGatedTool<TSchema extends z.ZodTypeAny>(tool: Omit<Tool<TSchema>, 'execute' | 'gated'>): 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
@@ -130,4 +167,4 @@ declare class ToolRegistry {
     count(): number;
 }
 
-export { type ToolResult as T, ToolRegistry as a, type Tool as b, type ToolContext as c, defineTool as d };
+export { type ToolResult as T, ToolRegistry as a, type Tool as b, type ToolContext as c, defineGatedTool as d, defineTool as e };

package/dist/index.cjs

@@ -41,6 +41,16 @@ var init_cjs_shims = __esm({
 function defineTool(tool) {
   return tool;
 }
+function defineGatedTool(tool) {
+  return {
+    ...tool,
+    gated: true,
+    execute: async () => ({
+      content: `gated tool "${tool.name}" should not have been executed \u2014 the engine was supposed to pause on its invocation (Plan 043). File a bug against la-machina-engine.`,
+      isError: true
+    })
+  };
+}
 var ToolRegistry;
 var init_contract = __esm({
   "src/tools/contract.ts"() {
@@ -889,6 +899,7 @@ __export(src_exports, {
   createSmartMemory: () => createSmartMemory,
   defaultSamplingHandler: () => defaultSamplingHandler,
   defaultToolResultSummarizer: () => defaultToolResultSummarizer,
+  defineGatedTool: () => defineGatedTool,
   defineTool: () => defineTool,
   detectRuntime: () => detectRuntime,
   getCoordinatorBasePrompt: () => getCoordinatorBasePrompt,
@@ -2389,6 +2400,8 @@ var RunSnapshotSchema = import_zod2.z.lazy(
       "gate_required",
       "subagent_gate_required",
       "handoff_to_runner",
+      // Plan 043 — caller pauses for a gated tool's human-supplied result.
+      "awaiting_tool_result",
       "max_turns",
       "explicit",
       "timeout"
@@ -3345,6 +3358,25 @@ async function agentLoop(options) {
           }
         }
       }
+      for (const call of toolCallsToDispatch) {
+        const tool = options.registry?.get(call.name);
+        if (tool?.gated === true) {
+          const paused = await pauseHere({
+            ctx,
+            transcript,
+            reason: "awaiting_tool_result",
+            pendingToolCall: {
+              toolName: call.name,
+              toolUseId: call.id,
+              input: call.input,
+              calledAt: (/* @__PURE__ */ new Date()).toISOString()
+            },
+            storage: options.storage,
+            subagentRegistry: options.subagentRegistry
+          });
+          return paused;
+        }
+      }
       if (options.handoffToRunner === true) {
         for (const call of toolCallsToDispatch) {
           const tool = options.registry?.get(call.name);
@@ -10883,7 +10915,25 @@ var Engine = class {
       });
       if (snapshot.pendingToolCall) {
         const pending = snapshot.pendingToolCall;
-        if (options.gateAnswer !== void 0) {
+        if (snapshot.pauseReason === "awaiting_tool_result") {
+          if (options.toolResult === void 0) {
+            throw new EngineError(
+              "ERR_GATED_RESUME_NO_RESULT",
+              "resume of `awaiting_tool_result` pause requires `toolResult` in ResumeOptions"
+            );
+          }
+          if (options.toolResult.id !== pending.toolUseId) {
+            throw new EngineError(
+              "ERR_GATED_RESUME_ID_MISMATCH",
+              `toolResult.id "${options.toolResult.id}" does not match pending toolUseId "${pending.toolUseId}" \u2014 resume aborted`
+            );
+          }
+          await ctx.addToolResult(
+            pending.toolUseId,
+            options.toolResult.content,
+            options.toolResult.isError ?? false
+          );
+        } else if (options.gateAnswer !== void 0) {
           const answer = typeof options.gateAnswer === "string" ? options.gateAnswer : JSON.stringify(options.gateAnswer);
           await ctx.addToolResult(pending.toolUseId, answer, false);
         } else {
@@ -12255,6 +12305,7 @@ function resolveApiKey(config) {
   createSmartMemory,
   defaultSamplingHandler,
   defaultToolResultSummarizer,
+  defineGatedTool,
   defineTool,
   detectRuntime,
   getCoordinatorBasePrompt,