@stigmer/runner 3.2.2 → 3.2.3

package/src/activities/workflow-event-activities.ts

@@ -34,6 +34,7 @@ import {
   ArtifactCreatedPayloadSchema,
   HumanInputOutcomeInfoSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { ApiResourceAuditActorSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
 import { WorkflowExecutionStatusSchema, WorkflowTaskSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import {
   WorkflowExecutionUpdateStatusInputSchema,
@@ -309,6 +310,14 @@ export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEv
         case: "approvalResolved",
         value: create(ApprovalResolvedPayloadSchema, {
           resolvedBy: desc.resolvedBy,
+          resolvedByActor: desc.resolvedByActor
+            ? create(ApiResourceAuditActorSchema, {
+                id: desc.resolvedByActor.id,
+                displayName: desc.resolvedByActor.display_name ?? "",
+                email: desc.resolvedByActor.email ?? "",
+                avatar: desc.resolvedByActor.avatar ?? "",
+              })
+            : undefined,
           comment: desc.comment,
           waitDurationMs: BigInt(desc.waitDurationMs),
         }),

package/src/middleware/__tests__/approval-gate.test.ts

@@ -784,4 +784,99 @@ describe("ApprovalGateMiddleware", () => {
     expect(result).toBeInstanceOf(ToolMessage);
     expect((result as ToolMessage).content).toContain("unknown action");
   });
+
+  describe("unattended approval mode (DD-014)", () => {
+    const gatedMcpPolicies = new Map<string, MergedToolPolicy>([
+      ["srv/gated_tool", {
+        toolName: "gated_tool",
+        mcpServerSlug: "srv",
+        requiresApproval: true,
+        approvalMessage: "Run gated_tool",
+        source: "classifier_default",
+      }],
+    ]);
+
+    it("skips a gated MCP tool without interrupting and records it in the registry", async () => {
+      const unattendedSkips = new Set<string>();
+      const mw = createApprovalGateMiddleware(makeConfig({
+        policies: gatedMcpPolicies,
+        toolServerMap: new Map([["gated_tool", "srv"]]),
+        unattended: true,
+        unattendedSkips,
+      }));
+
+      const handler = vi.fn(passthrough);
+      const result = await mw.wrapToolCall!(
+        makeRequest({ name: "gated_tool", args: { target: "prod" } }),
+        handler,
+      );
+
+      // Gateway invariant: the side effect never ran, and no interrupt was
+      // raised — the turn continues instead of parking WAITING_FOR_APPROVAL.
+      expect(handler).not.toHaveBeenCalled();
+      expect(mockedInterrupt).not.toHaveBeenCalled();
+      expect((result as ToolMessage).content).toContain("skipped automatically");
+      expect(unattendedSkips.has("call_abc123")).toBe(true);
+    });
+
+    it("skips a gated built-in (shell) the same way", async () => {
+      const unattendedSkips = new Set<string>();
+      const mw = createApprovalGateMiddleware(makeConfig({
+        unattended: true,
+        unattendedSkips,
+      }));
+
+      const handler = vi.fn(passthrough);
+      const result = await mw.wrapToolCall!(
+        makeRequest({ name: "shell", args: { command: "rm -rf /" } }),
+        handler,
+      );
+
+      expect(handler).not.toHaveBeenCalled();
+      expect(mockedInterrupt).not.toHaveBeenCalled();
+      expect((result as ToolMessage).content).toContain("skipped automatically");
+      expect(unattendedSkips.has("call_abc123")).toBe(true);
+    });
+
+    it("still runs tools the policy chain auto-approved (un-gating stays the operator lever)", async () => {
+      // The operator's tool_approval_overrides path: an un-gated tool is
+      // absent from the policy map, so unattended mode never touches it.
+      const unattendedSkips = new Set<string>();
+      const mw = createApprovalGateMiddleware(makeConfig({
+        toolServerMap: new Map([["book_appointment", "clinic"]]),
+        unattended: true,
+        unattendedSkips,
+      }));
+
+      const result = await mw.wrapToolCall!(
+        makeRequest({ name: "book_appointment", args: { slot: "mon-10" } }),
+        passthrough,
+      );
+
+      expect((result as ToolMessage).content).toBe("tool result");
+      expect(unattendedSkips.size).toBe(0);
+      expect(mockedInterrupt).not.toHaveBeenCalled();
+    });
+
+    it("never emits an execution receipt for an unattended skip (no side effect)", async () => {
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        const mw = createApprovalGateMiddleware(makeConfig({
+          policies: gatedMcpPolicies,
+          toolServerMap: new Map([["gated_tool", "srv"]]),
+          unattended: true,
+          unattendedSkips: new Set<string>(),
+        }));
+
+        await mw.wrapToolCall!(makeRequest({ name: "gated_tool" }), passthrough);
+
+        const receipts = logSpy.mock.calls
+          .map((c) => String(c[0]))
+          .filter((line) => line.includes("[hitl-gateway] receipt"));
+        expect(receipts).toHaveLength(0);
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+  });
 });

package/src/middleware/approval-gate.ts

@@ -51,6 +51,7 @@ import {
   type PolicySource,
   POLICY_ENGINE_VERSION,
   resolveApprovalMessage,
+  unattendedSkipMessage,
 } from "../shared/approval-policy.js";
 import { toolApprovalCategory, type ToolApprovalCategory } from "../shared/tool-kind.js";
 import { extractFilePath } from "../shared/file-tools.js";
@@ -121,6 +122,26 @@ export interface ApprovalGateConfig {
    * secret; the CONTENT never leaves the workspace). Absent ⇒ nothing recorded.
    */
   readonly recordBlockedSecret?: (rawPath: string) => void;
+  /**
+   * Unattended approval mode (ExecutionConfig.approval_mode = UNATTENDED):
+   * the creating surface — a messaging channel, a guest share — has no
+   * approver, so a gated tool is resolved as an automatic SKIP (the model is
+   * told to adapt) instead of `interrupt()`. The execution never enters
+   * WAITING_FOR_APPROVAL. What is gated is unchanged — only the resolution
+   * differs; an operator un-gates a specific tool for the agent via
+   * tool_approval_overrides, not by weakening this mode.
+   */
+  readonly unattended?: boolean;
+  /**
+   * Registry of tool-call ids this gate auto-skipped under {@link unattended}
+   * — the gate is the single WRITER; `reconcileUnattendedSkips` (hitl.ts) is
+   * the reader that folds each id into a terminal TOOL_CALL_SKIPPED row with
+   * UNATTENDED_SKIP provenance after the stream. In-process, per-execution
+   * state keyed by the framework's own tool-call id (direct identity, no
+   * matching); inherited verbatim by sub-agent gates so their skips land in
+   * the same registry.
+   */
+  readonly unattendedSkips?: Set<string>;
 }
 
 interface ApprovalDecision {
@@ -249,6 +270,22 @@ export function createApprovalGateMiddleware(
         return await handler(request);
       }
 
+      // Unattended surfaces (channels, guest shares) have no approver, so a
+      // gate that would interrupt() here resolves as an automatic SKIP: the
+      // tool does NOT run (the gateway invariant holds — no side effect
+      // without a backing authorization), the model is told to adapt in plain
+      // language, and the turn continues to normal completion instead of
+      // parking in WAITING_FOR_APPROVAL forever. The registry entry lets the
+      // post-stream reconciler stamp the terminal SKIPPED row + provenance.
+      if (config.unattended) {
+        config.unattendedSkips?.add(toolCall.id);
+        return new ToolMessage({
+          content: unattendedSkipMessage(toolName),
+          tool_call_id: toolCall.id,
+          name: toolName,
+        });
+      }
+
       const approvalRequest = {
         tool_call_id: toolCall.id,
         tool_name: toolName,

package/src/shared/__tests__/with-timeout.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { withTimeout } from "../with-timeout.js";
+import { withTimeout, TimeoutError } from "../with-timeout.js";
 
 describe("withTimeout", () => {
   it("resolves with the function's result when it completes in time", async () => {
@@ -14,6 +14,21 @@ describe("withTimeout", () => {
     ).rejects.toThrow("Cursor agent create timed out after 20ms");
   });
 
+  it("rejects with a TimeoutError so callers can react to expiry by type", async () => {
+    const hang = () => new Promise<never>(() => {});
+    await expect(withTimeout(20, "expired", hang)).rejects.toBeInstanceOf(TimeoutError);
+  });
+
+  it("does not wrap the function's own rejection in a TimeoutError", async () => {
+    const boom = new Error("underlying failure");
+    let caught: unknown;
+    await withTimeout(1_000, "should not fire", () => Promise.reject(boom)).catch((err) => {
+      caught = err;
+    });
+    expect(caught).toBe(boom);
+    expect(caught).not.toBeInstanceOf(TimeoutError);
+  });
+
   it("evaluates a lazy message only on expiry", async () => {
     let evaluated = 0;
     const message = () => {

package/src/shared/approval-policy.ts

@@ -18,7 +18,7 @@
 import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import { ApprovalAction, ApprovalPolicySource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApprovalAction, ApprovalMode, ApprovalPolicySource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { toolApprovalCategory, type ToolApprovalCategory } from "./tool-kind.js";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
 
@@ -147,6 +147,42 @@ export function deriveActiveLeases(execution: AgentExecution): ActiveLeases {
   };
 }
 
+/**
+ * Whether this execution runs in UNATTENDED approval mode
+ * (ExecutionConfig.approval_mode): the creating surface — a messaging
+ * channel, a guest share — has no approver, so a gated tool is resolved as
+ * an automatic skip (the model is told to adapt) instead of pausing the
+ * execution for a decision that can never arrive.
+ *
+ * The mode changes HOW a gate resolves, never WHAT is gated: the four-level
+ * policy merge below is identical in both modes. Both harnesses read the
+ * mode through this one helper (the native gate skips instead of
+ * interrupting; the Cursor hook records a non-pausing "unattended" denial),
+ * so the surfaces can never diverge on what "unattended" means.
+ */
+export function isUnattendedApprovalMode(execution: AgentExecution): boolean {
+  return execution.spec?.executionConfig?.approvalMode === ApprovalMode.UNATTENDED;
+}
+
+/**
+ * The tool-result text for an unattended auto-skip — ONE definition for both
+ * harnesses (the native gate returns it as the skip ToolMessage; the Cursor
+ * turn boundary backfills it onto stamped SKIPPED rows), so the transcript
+ * reads identically wherever the skip happened. Deliberately instructs
+ * plain-language adaptation with NO tool/approval vocabulary reaching the end
+ * user (the channel/guest anti-leak posture).
+ */
+export function unattendedSkipMessage(toolName: string): string {
+  return (
+    `Tool '${toolName}' requires an approval that is not available in ` +
+    `this conversation, so it was skipped automatically. Do not retry ` +
+    `it or attempt a workaround. Adapt your plan, and explain to the ` +
+    `user in plain language what you could not do and what they can ` +
+    `do instead — never mention tools, approvals, or platform ` +
+    `mechanics.`
+  );
+}
+
 /**
  * Provenance of a gate decision: which policy layer (or decision point) is
  * responsible for the final requires-approval verdict.
@@ -170,7 +206,8 @@ export type PolicySource =
   | "approval_lease"                 // Layer 4: a run-lifetime scoped lease cleared this action
   | "builtin_category"               // Non-MCP built-in gated by the shared tool taxonomy
   | "file_capture"                   // Capture mode: a git-tracked built-in file edit flows, reviewed post-hoc via the file_review ledger (not gated; audit-only on the shadow receipt)
-  | "annotation_destructive_tighten"; // Layer 1 sub-case: connect-time destructiveHint tightener force-gated this MCP tool
+  | "annotation_destructive_tighten" // Layer 1 sub-case: connect-time destructiveHint tightener force-gated this MCP tool
+  | "unattended_skip";               // Layer 4 resolution: unattended approval mode auto-skipped this gated call (no approver on the creating surface)
 
 /**
  * Monotonic identifier of the policy-engine logic that produced a decision,
@@ -205,6 +242,8 @@ export function toProtoPolicySource(source: PolicySource | undefined): ApprovalP
       return ApprovalPolicySource.BUILTIN_CATEGORY;
     case "annotation_destructive_tighten":
       return ApprovalPolicySource.ANNOTATION_DESTRUCTIVE_TIGHTEN;
+    case "unattended_skip":
+      return ApprovalPolicySource.UNATTENDED_SKIP;
     case "file_capture":
       // Capture-mode flow is never persisted on a gated tool call (the file tool
       // is not gated — it has no WAITING_APPROVAL row); it exists only on the

package/src/shared/with-timeout.ts

@@ -15,6 +15,20 @@
  * `AbortSignal.timeout` and pass the signal to the callee instead.
  */
 
+/**
+ * Thrown when the bound expires before `fn` settles. A distinct class so
+ * callers can react to expiry specifically (`err instanceof TimeoutError`)
+ * instead of sniffing message text — e.g. the agent-resolution transport
+ * recovery retries on expiry but must let deterministic failures (auth,
+ * validation) propagate untouched.
+ */
+export class TimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}
+
 export async function withTimeout<T>(
   ms: number,
   timeoutMessage: string | (() => string),
@@ -23,7 +37,7 @@ export async function withTimeout<T>(
   return new Promise<T>((resolve, reject) => {
     const timer = setTimeout(() => {
       const message = typeof timeoutMessage === "function" ? timeoutMessage() : timeoutMessage;
-      reject(new Error(message));
+      reject(new TimeoutError(message));
     }, ms);
 
     fn()

package/src/workflow-engine/__tests__/tasks/human-input.test.ts

@@ -317,10 +317,50 @@ describe("executeHumanInputTask", () => {
       expect(resolved.taskName).toBe("gate");
       expect(resolved.outcome).toBe("reject");
       expect(resolved.resolvedBy).toBe("carol");
+      expect(resolved.resolvedByActor).toBeUndefined();
       expect(resolved.autoResolved).toBe(false);
       expect(resolved.waitDurationMs).toBeGreaterThanOrEqual(0);
     });
 
+    it("carries the reviewer_actor display snapshot into approval_resolved and the task output", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+      const reviewerActor = {
+        id: "ida_01abc",
+        display_name: "Ada Lovelace",
+        email: "ada@example.com",
+        avatar: "https://example.com/ada.png",
+      };
+      const awaitFn: AwaitHumanInputFn = async () => ({
+        outcome: "approve",
+        reviewer: "ida_01abc",
+        reviewer_actor: reviewerActor,
+        responded_at: "2026-05-20T10:00:00Z",
+      });
+
+      const taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Confirm?" },
+      };
+
+      const state = createState();
+      await executeHumanInputTask(taskDef, "gate", state, makeCtx(awaitFn, emitFn));
+
+      const resolved = emitted[1][0];
+      if (resolved.type !== "approval_resolved") throw new Error("unexpected");
+      expect(resolved.resolvedBy).toBe("ida_01abc");
+      expect(resolved.resolvedByActor).toEqual(reviewerActor);
+
+      // The whole signal payload IS the task output — the actor lands there
+      // for downstream tasks (e.g. notification templates) without copying.
+      expect(state.data.gate).toEqual({
+        outcome: "approve",
+        reviewer: "ida_01abc",
+        reviewer_actor: reviewerActor,
+        responded_at: "2026-05-20T10:00:00Z",
+      });
+    });
+
     it("does not error when emitEvents is undefined (backward compat)", async () => {
       const awaitFn: AwaitHumanInputFn = async () => ({ outcome: "approve" });
 

package/src/workflow-engine/tasks/human-input.ts

@@ -109,6 +109,7 @@ export async function executeHumanInputTask(
       occurredAt: new Date().toISOString(),
       outcome: result.outcome,
       resolvedBy: result.reviewer ?? "",
+      resolvedByActor: result.reviewer_actor,
       comment: "",
       waitDurationMs: Date.now() - approvalRequestedAt,
       autoResolved: result.auto_resolved ?? false,

package/src/workflow-engine/types.ts

@@ -563,13 +563,33 @@ export interface HumanInputExecutionConfig {
 
 export interface HumanInputResult {
   readonly outcome: string;
+  /** Canonical reviewer identity (identity-account ID). Empty/absent when unattributed. */
   readonly reviewer?: string;
+  /**
+   * Display snapshot of the reviewer, stamped server-side by the control
+   * plane at decision time. Rides the signal opaquely into the task output
+   * (for downstream tasks, e.g. notifications) and the approval_resolved
+   * event (for UIs). Absent when no attribution exists — never synthesized.
+   */
+  readonly reviewer_actor?: HumanInputReviewerActor;
   readonly responded_at?: string;
   readonly form_data?: Record<string, unknown>;
   readonly auto_resolved?: boolean;
   readonly reason?: string;
 }
 
+/** Write-time snapshot of the reviewer's display identity. */
+export interface HumanInputReviewerActor {
+  /** Canonical identity (matches HumanInputResult.reviewer). */
+  readonly id: string;
+  /** Human-readable name; empty when unknown. */
+  readonly display_name?: string;
+  /** Email address; empty when unknown. */
+  readonly email?: string;
+  /** Avatar URL; empty when unknown. */
+  readonly avatar?: string;
+}
+
 export interface HumanInputConfig {
   readonly prompt: string;
   readonly outcomes?: HumanInputOutcome[];
@@ -843,7 +863,10 @@ export interface ApprovalRequestedEvent extends EventBase {
 export interface ApprovalResolvedEvent extends EventBase {
   readonly type: "approval_resolved";
   readonly outcome: string;
+  /** Canonical reviewer identity. Empty when unattributed. */
   readonly resolvedBy: string;
+  /** Display snapshot of the reviewer from the signal payload, if stamped. */
+  readonly resolvedByActor?: HumanInputReviewerActor;
   readonly comment: string;
   readonly waitDurationMs: number;
   readonly autoResolved: boolean;

package/src/workflows/human-input-orchestrator.ts

@@ -8,7 +8,8 @@
  * - "approve": returns auto-approved output
  * - "deny": returns auto-denied output
  *
- * Signal payload shape: { outcome, form_data?, reviewer, responded_at }
+ * Signal payload shape:
+ * { outcome, form_data?, reviewer, reviewer_actor?, responded_at }
  *
  * TEMPORAL SANDBOX: This file runs inside the deterministic workflow isolate.
  */