@stigmer/runner 3.2.2 → 3.3.0

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/datastore-attachment.ts

@@ -0,0 +1,166 @@
+/**
+ * The runner-synthesized datastore records attachment (T05, DD-001 SD-2).
+ *
+ * When an agent declares `datastore_usages`, the runner synthesizes ONE
+ * MCP attachment serving the five record tools (DD-005) — the agent
+ * builder writes a usage line and gets tools; no McpServer resource, no
+ * Environment, no credential in any manifest. Harness-agnostic like
+ * mcp-resolver.ts: both ExecuteCursor and ExecuteDeepAgent inject the
+ * synthesized entry through their existing ResolvedMcpServer paths.
+ *
+ * Two connection shapes, one roster (the bridge's records-only roster,
+ * T05 R1):
+ *   - Bridge endpoint configured (cloud): Streamable HTTP against the
+ *     bridge's /records route, with the execution's own session-scoped
+ *     credential as the Bearer token — the server's reach chain (DD-006
+ *     Path 1) authorizes from that token; the bridge stays a
+ *     non-validating passthrough.
+ *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
+ *     stdio child with STIGMER_MCP_ROSTER=records against the local
+ *     backend (zero new distribution — the CLI already embeds the
+ *     bridge). No credential: the local backend is unauthenticated and
+ *     OSS callers resolve as the local principal (T05 R2).
+ *
+ * Approval-free by construction (DD-001 SD-3): empty toolApprovals +
+ * pinnedToolApprovals mean mergeApprovalPolicies emits no entries for
+ * this server — zero classifier involvement. `discoveredCapabilitiesEmpty`
+ * is false and the attachment has no McpServerUsage, so the connect
+ * backfill (whose destructiveHint tightener would force-gate
+ * delete_record — silently skipped on channels under UNATTENDED mode)
+ * is structurally unable to touch it. Callers must still inject AFTER
+ * resolve + backfill; both harness call sites do.
+ */
+
+import type { DatastoreUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+
+/**
+ * The synthesized attachment's slug. Reserved: a user McpServer with
+ * this slug is shadowed by the synthesized attachment (the record tools
+ * must exist whenever `datastore_usages` says so), with a warning.
+ */
+export const DATASTORE_ATTACHMENT_SLUG = "stigmer-records";
+
+/** The bridge route serving the records-only roster (mcp-server T05 R1). */
+export const RECORDS_ROUTE = "/records";
+
+export interface DatastoreAttachmentOptions {
+  /**
+   * The bridge's HTTP endpoint (STIGMER_MCP_BRIDGE_ENDPOINT, e.g.
+   * https://mcp.stigmer.ai). Null selects the OSS stdio shape.
+   */
+  bridgeEndpoint: string | null;
+  /**
+   * The execution's session-scoped credential (the sandbox token a
+   * cloud runner holds, or the desktop runner's exchanged scoped
+   * token). Null attaches no Authorization header (OSS/local).
+   */
+  credential: string | null;
+  /**
+   * The stigmer backend endpoint the stdio child dials
+   * (config.stigmerBackendEndpoint). Only used for the OSS shape.
+   */
+  backendEndpoint: string;
+}
+
+/**
+ * Synthesize the records attachment for an agent's datastore usages.
+ * Returns undefined when the agent uses no datastores — the attachment
+ * exists exactly when the usage edge does.
+ */
+export function synthesizeDatastoreAttachment(
+  datastoreUsages: DatastoreUsage[],
+  options: DatastoreAttachmentOptions,
+): ResolvedMcpServer | undefined {
+  if (datastoreUsages.length === 0) {
+    return undefined;
+  }
+
+  // Approval-free by construction + backfill-proof: see file header.
+  const base = {
+    slug: DATASTORE_ATTACHMENT_SLUG,
+    toolApprovals: [],
+    pinnedToolApprovals: [],
+    discoveredCapabilitiesEmpty: false,
+  };
+
+  if (options.bridgeEndpoint !== null && options.bridgeEndpoint !== "") {
+    return {
+      ...base,
+      connectionType: "http",
+      url: options.bridgeEndpoint.replace(/\/+$/, "") + RECORDS_ROUTE,
+      headers: options.credential !== null && options.credential !== ""
+        ? { Authorization: `Bearer ${options.credential}` }
+        : undefined,
+    };
+  }
+
+  return {
+    ...base,
+    connectionType: "stdio",
+    command: "stigmer",
+    args: ["mcp-server"],
+    env: {
+      STIGMER_MCP_ROSTER: "records",
+      STIGMER_SERVER_ADDRESS: grpcTarget(options.backendEndpoint),
+    },
+  };
+}
+
+/**
+ * Inject the synthesized attachment into a resolved server list —
+ * AFTER resolve + backfill (see file header). A user server shadowing
+ * the reserved slug is replaced, loudly.
+ */
+export function injectDatastoreAttachment(
+  resolvedServers: ResolvedMcpServer[],
+  attachment: ResolvedMcpServer,
+): ResolvedMcpServer[] {
+  const shadowed = resolvedServers.some((s) => s.slug === attachment.slug);
+  if (shadowed) {
+    console.warn(
+      `MCP server slug "${attachment.slug}" is reserved for the datastore ` +
+      "records attachment; the user-defined server is replaced.",
+    );
+  }
+  return [
+    ...resolvedServers.filter((s) => s.slug !== attachment.slug),
+    attachment,
+  ];
+}
+
+/**
+ * The `<available_datastores>` prompt section (DD-005 SD-5, the
+ * skills-section precedent): names the attached datastores and points
+ * the model at describe_datastore first. Shared by both harnesses so
+ * the section text cannot drift (the sender-identity precedent).
+ */
+export function formatDatastoresSection(datastoreUsages: DatastoreUsage[]): string {
+  const slugs = datastoreUsages
+    .map((u) => u.datastoreRef?.slug)
+    .filter((s): s is string => !!s);
+  const entries = slugs.map((slug) => `- ${slug}`);
+  return [
+    "<available_datastores>",
+    "You have access to the following datastores through the record tools",
+    "(describe_datastore, find_records, insert_record, update_record, delete_record).",
+    "Before your first operation against a datastore, call describe_datastore to",
+    "learn its collections, field encodings, and which operations you are allowed",
+    "to perform.",
+    "",
+    ...entries,
+    "</available_datastores>",
+  ].join("\n");
+}
+
+/**
+ * The gRPC dial target (host:port) for a backend endpoint URL — the
+ * shape STIGMER_SERVER_ADDRESS wants (the bridge warns on schemes).
+ */
+function grpcTarget(endpoint: string): string {
+  try {
+    return new URL(endpoint).host;
+  } catch {
+    return endpoint;
+  }
+}

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.
  */