@evalops/maestro 0.10.18 → 0.10.20

package/README.md

@@ -58,7 +58,7 @@ export ANTHROPIC_API_KEY=sk-ant-...
 
 Maestro also supports OpenAI, OpenAI Codex with ChatGPT login, Google, OpenRouter, Azure OpenAI, GitHub Copilot, Groq, xAI, Cerebras, and managed EvalOps auth. See [Models](docs/MODELS.md) for provider-specific setup and overrides.
 
-For Codex subscription models, run `maestro codex login` or `/login openai-codex`, then select models under the `openai-codex` provider such as `openai-codex/gpt-5.5`.
+For Codex subscription models, run `maestro codex login` to Sign in with ChatGPT through the Codex app-server, then select models under the `openai-codex` provider such as `openai-codex/gpt-5.5`.
 
 2. Launch the interface you want:
 
@@ -75,6 +75,7 @@ maestro web
 - Keys and config: `~/.maestro/keys.json`, `~/.maestro/config.json`
 - MCP servers: `~/.maestro/mcp.json` or `.maestro/mcp.json`
 - Hooks: `~/.maestro/hooks.json` or `.maestro/hooks.json`
+- Skills: `maestro skill new <name>`, `maestro skill lint .maestro/skills`
 - Agent instructions: `AGENT.md`, `.maestro/APPEND_SYSTEM.md`, `~/.maestro/agent/AGENT.md`
 
 ## Safety Model
@@ -96,6 +97,7 @@ See [Safety](docs/SAFETY.md) and the [Threat Model](docs/THREAT_MODEL.md) for th
 | Understand approvals and sandboxing | [Safety](docs/SAFETY.md) |
 | Run the browser interface | [Web UI Guide](docs/WEB_UI.md) |
 | Set up MCP servers | [MCP Guide](docs/MCP_GUIDE.md) |
+| Package reusable skills | [Skill Cookbook](docs/cookbook/skills/README.md) |
 | Work on the repo as a contributor | [Contributor Runbook](docs/CONTRIBUTOR_RUNBOOK.md) |
 | Integrate Maestro headlessly | [Headless protocol](docs/protocols/headless.md) |
 | Bring any coding agent into EvalOps | [Any-Agent Control Plane](docs/design/ANY_AGENT_CONTROL_PLANE.md) |
@@ -110,10 +112,63 @@ git clone https://github.com/evalops/maestro.git
 cd maestro
 bun install
 npx nx run maestro:build --skip-nx-cache
+npm run smoke:local-e2e
 npx nx run maestro:test --skip-nx-cache
 npx nx run maestro:evals --skip-nx-cache
 ```
 
+`npm run smoke:local-e2e` is credential-free after build: it checks help,
+version, the headless protocol handshake, and deterministic mock-agent
+read/write/search/edit flows through the built CLI.
+
+For the browser UI without local API keys or Redis, use the local-only dev
+profile:
+
+```bash
+make web-local
+curl http://localhost:8080/api/models
+```
+
+To prove Maestro works against a local Cerebro stack, keep sibling checkouts and
+run:
+
+```bash
+gh repo clone evalops/cerebro ../cerebro
+make cerebro-e2e-doctor
+make cerebro-e2e
+```
+
+To actually use the two repos together locally, start Cerebro from Maestro and
+export the same Cerebro/MCP env into the Maestro terminal:
+
+```bash
+make cerebro-dev
+
+# In another Maestro terminal:
+eval "$(make -s cerebro-env)"
+make run-ts
+```
+
+That target delegates to Cerebro's `make local-maestro-e2e` with
+`LOCAL_MAESTRO_REPO` set to the current Maestro checkout. It builds and smokes
+Maestro, emits Maestro's canonical Platform replay, publishes it through local
+NATS, and verifies Cerebro graph projection plus MCP recall from the generated
+session traffic. `make cerebro-e2e-doctor` checks the Cerebro checkout, Docker
+Compose, the replay generator, and Cerebro's own local-E2E doctor before the
+full smoke starts. It also checks the effective local Cerebro URL, MCP URL, and
+workspace from `.env` or exported environment values, then verifies that the
+configured API port is free before the self-contained smoke starts. The default
+URL is `http://localhost:18080`; use `LOCAL_BASE_URL`/`MAESTRO_CEREBRO_URL` plus
+matching Cerebro `LOCAL_HTTP_PORT` overrides when that port is occupied. Set
+`LOCAL_CEREBRO_REPO=/path/to/cerebro` when the checkout is not a sibling
+directory. If your machine cannot surface OTEL collector debug logs, run
+`LOCAL_ASSERT_OTEL=false make cerebro-e2e`.
+
+For direct local Maestro runs against an already-running Cerebro dev stack,
+`make cerebro-env` prints copyable exports derived from `.env` or shell
+overrides. The Makefile exports those vars to `make` targets so `make run-ts`,
+`make web-local`, and local smokes all see the same configuration.
+
 Need Redis or PostgreSQL for a specific workflow? Start from `docker-compose.yml` and use the [Contributor Runbook](docs/CONTRIBUTOR_RUNBOOK.md) for the rest of the repo workflow.
 
 ## Repository Layout

package/dist/agent/action-approval.d.ts

@@ -1,3 +1,5 @@
+import type { GuardedFilesPolicySettings } from "@evalops/contracts";
+import { type Clock } from "../utils/clock.js";
 /**
  * Action Approval System
  *
@@ -38,6 +40,8 @@ export interface ActionApprovalRequest {
     args: unknown;
     /** Human-readable reason why approval is required */
     reason: string;
+    /** Unix timestamp in milliseconds when this approval lifecycle was emitted */
+    startedAtMs?: number;
     /** Optional Platform correlation for shared approval and audit surfaces */
     platform?: {
         source: "approvals_service" | "tool_execution";
@@ -55,6 +59,8 @@ export interface ActionApprovalDecision {
     reason?: string;
     /** Who made the decision: automated policy or human user */
     resolvedBy: "policy" | "user";
+    /** Unix timestamp in milliseconds when this approval lifecycle resolved */
+    resolvedAtMs?: number;
 }
 /**
  * Serializable snapshot of PII tracking state.
@@ -96,6 +102,8 @@ export interface ActionApprovalContext {
             /** Tool interacts with external/untrusted systems */
             openWorldHint?: boolean;
         };
+        /** User/org guarded-files override policy for this run */
+        guardedFiles?: GuardedFilesPolicySettings;
     };
     /** User context for permission-based policies */
     user?: {
@@ -142,9 +150,10 @@ export type ActionFirewallVerdict = {
  */
 export declare class ActionApprovalService {
     private mode;
+    protected readonly clock: Clock;
     /** Map of request ID -> pending entry awaiting decision */
     private pending;
-    constructor(mode?: ApprovalMode);
+    constructor(mode?: ApprovalMode, clock?: Clock);
     /** Update the approval mode at runtime */
     setMode(mode: ApprovalMode): void;
     /** Get the current approval mode */
@@ -163,7 +172,7 @@ export declare class ActionApprovalService {
      * @param signal - Optional abort signal to cancel the request
      * @returns Promise that resolves with the approval decision
      */
-    requestApproval(request: ActionApprovalRequest, signal?: AbortSignal): Promise<ActionApprovalDecision>;
+    requestApproval(request: ActionApprovalRequest, signal?: AbortSignal, clock?: Pick<Clock, "now">): Promise<ActionApprovalDecision>;
     /**
      * Approve a pending request. Called by UI or API when user approves.
      * @returns true if request was found and resolved, false if not pending
@@ -194,5 +203,6 @@ export declare class ActionApprovalService {
      * Handles cleanup and removal from pending map.
      */
     private resolveEntry;
+    protected withResolvedAt(decision: ActionApprovalDecision, clock?: Pick<Clock, "now">): ActionApprovalDecision;
 }
 //# sourceMappingURL=action-approval.d.ts.map

package/dist/agent/action-approval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-approval.d.ts","sourceRoot":"","sources":["../../src/agent/action-approval.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"action-approval.d.ts","sourceRoot":"","sources":["../../src/agent/action-approval.ts"],"names":[],"mappings":"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"}

package/dist/agent/action-approval.js

@@ -1,23 +1,4 @@
-/**
- * Action Approval System
- *
- * This module implements the approval workflow for risky tool executions.
- * When tools are flagged as requiring approval (by the action firewall or
- * tool configuration), this system manages the approval lifecycle.
- *
- * Three approval modes are supported:
- * - auto: Automatically approve all requests (for trusted/automated workflows)
- * - prompt: Queue requests and wait for user decision (default for interactive)
- * - fail: Automatically reject all requests (for strict security contexts)
- *
- * The approval flow:
- * 1. Agent prepares a tool call
- * 2. Action firewall evaluates and may require approval
- * 3. ActionApprovalService.requestApproval() is called
- * 4. In "prompt" mode, request is queued and awaits user decision
- * 5. User approves/denies via the UI or API
- * 6. Decision is returned to the agent to proceed or abort
- */
+import { systemClock } from "../utils/clock.js";
 /**
  * Manages the approval workflow for risky tool executions.
  *
@@ -29,8 +10,9 @@
  * when the agent run is cancelled.
  */
 export class ActionApprovalService {
-    constructor(mode = "prompt") {
+    constructor(mode = "prompt", clock = systemClock) {
         this.mode = mode;
+        this.clock = clock;
         /** Map of request ID -> pending entry awaiting decision */
         this.pending = new Map();
     }
@@ -58,36 +40,37 @@ export class ActionApprovalService {
      * @param signal - Optional abort signal to cancel the request
      * @returns Promise that resolves with the approval decision
      */
-    async requestApproval(request, signal) {
+    async requestApproval(request, signal, clock = this.clock) {
         // Fast path for auto mode - no queuing needed
         if (this.mode === "auto") {
-            return {
+            return this.withResolvedAt({
                 approved: true,
                 reason: "Auto-approved by policy",
                 resolvedBy: "policy",
-            };
+            }, clock);
         }
         // Fast path for fail mode - immediate rejection
         if (this.mode === "fail") {
-            return {
+            return this.withResolvedAt({
                 approved: false,
                 reason: "Denied by approval policy",
                 resolvedBy: "policy",
-            };
+            }, clock);
         }
         // Check if already aborted before queuing
         if (signal?.aborted) {
-            return {
+            return this.withResolvedAt({
                 approved: false,
                 reason: "Run aborted",
                 resolvedBy: "policy",
-            };
+            }, clock);
         }
         // Prompt mode: queue the request and wait for user decision
         return await new Promise((resolve) => {
             const entry = {
                 request,
                 resolve: () => { }, // Placeholder, replaced below
+                stampResolvedAt: (decision) => this.withResolvedAt(decision, clock),
             };
             // Wrap resolver to ensure cleanup on resolution
             entry.resolve = (decision) => {
@@ -100,12 +83,11 @@ export class ActionApprovalService {
                     if (!this.pending.has(request.id))
                         return;
                     this.pending.delete(request.id);
-                    entry.cleanup?.();
-                    resolve({
+                    entry.resolve(entry.stampResolvedAt({
                         approved: false,
                         reason: "Run aborted",
                         resolvedBy: "policy",
-                    });
+                    }));
                 };
                 entry.cleanup = () => signal.removeEventListener("abort", onAbort);
                 signal.addEventListener("abort", onAbort, { once: true });
@@ -173,8 +155,13 @@ export class ActionApprovalService {
             return false;
         }
         this.pending.delete(id);
-        entry.resolve(decision);
+        entry.resolve(entry.stampResolvedAt(decision));
         return true;
     }
+    withResolvedAt(decision, clock = this.clock) {
+        return decision.resolvedAtMs === undefined
+            ? { ...decision, resolvedAtMs: clock.now() }
+            : decision;
+    }
 }
 //# sourceMappingURL=action-approval.js.map

package/dist/agent/action-approval.js.map

@@ -1 +1 @@
-{"version":3,"file":"action-approval.js","sourceRoot":"","sources":["../../src/agent/action-approval.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Action Approval System\n *\n * This module implements the approval workflow for risky tool executions.\n * When tools are flagged as requiring approval (by the action firewall or\n * tool configuration), this system manages the approval lifecycle.\n *\n * Three approval modes are supported:\n * - auto: Automatically approve all requests (for trusted/automated workflows)\n * - prompt: Queue requests and wait for user decision (default for interactive)\n * - fail: Automatically reject all requests (for strict security contexts)\n *\n * The approval flow:\n * 1. Agent prepares a tool call\n * 2. Action firewall evaluates and may require approval\n * 3. ActionApprovalService.requestApproval() is called\n * 4. In \"prompt\" mode, request is queued and awaits user decision\n * 5. User approves/denies via the UI or API\n * 6. Decision is returned to the agent to proceed or abort\n */\n\n/** Determines how approval requests are handled */\nexport type ApprovalMode = \"auto\" | \"prompt\" | \"fail\";\n\n/**\n * Represents a pending approval request for a tool execution.\n */\nexport interface ActionApprovalRequest {\n\t/** Unique identifier for this request */\n\tid: string;\n\t/** Name of the tool requesting approval */\n\ttoolName: string;\n\t/** Optional human-facing label for the tool */\n\tdisplayName?: string;\n\t/** Optional compact summary of the requested action */\n\tsummaryLabel?: string;\n\t/** Optional present-tense action description for approval UI */\n\tactionDescription?: string;\n\t/** Arguments the tool will be called with */\n\targs: unknown;\n\t/** Human-readable reason why approval is required */\n\treason: string;\n\t/** Optional Platform correlation for shared approval and audit surfaces */\n\tplatform?: {\n\t\tsource: \"approvals_service\" | \"tool_execution\";\n\t\ttoolExecutionId?: string;\n\t\tapprovalRequestId?: string;\n\t};\n}\n\n/**\n * The decision made for an approval request.\n */\nexport interface ActionApprovalDecision {\n\t/** Whether the action was approved */\n\tapproved: boolean;\n\t/** Optional explanation for the decision */\n\treason?: string;\n\t/** Who made the decision: automated policy or human user */\n\tresolvedBy: \"policy\" | \"user\";\n}\n\n/**\n * Serializable snapshot of PII tracking state.\n * Used to persist and restore workflow state across sessions.\n */\nexport interface WorkflowStateSnapshot {\n\t/** List of PII artifacts that are pending redaction */\n\tpendingPii: Array<{\n\t\tid: string;\n\t\tlabel: string;\n\t\tsourceToolCallId: string;\n\t\tredacted: boolean;\n\t\tparents?: string[];\n\t}>;\n\t/** Artifact IDs that were redacted but never captured (indicates bugs) */\n\torphanedRedactions: string[];\n}\n\n/**\n * Full context provided to the action firewall for approval decisions.\n * Includes the action itself plus ambient context about the workflow.\n */\nexport interface ActionApprovalContext {\n\t/** Name of the tool being executed */\n\ttoolName: string;\n\t/** Arguments for the tool call */\n\targs: unknown;\n\t/** Additional metadata for policy evaluation */\n\tmetadata?: {\n\t\t/** Current PII tracking state for data protection policies */\n\t\tworkflowState?: WorkflowStateSnapshot;\n\t\t/** MCP tool annotations that hint at tool behavior */\n\t\tannotations?: {\n\t\t\t/** Tool only reads data, doesn't modify state */\n\t\t\treadOnlyHint?: boolean;\n\t\t\t/** Tool may cause irreversible changes */\n\t\t\tdestructiveHint?: boolean;\n\t\t\t/** Tool can be safely retried */\n\t\t\tidempotentHint?: boolean;\n\t\t\t/** Tool interacts with external/untrusted systems */\n\t\t\topenWorldHint?: boolean;\n\t\t};\n\t};\n\t/** User context for permission-based policies */\n\tuser?: {\n\t\tid: string;\n\t\torgId: string;\n\t};\n\t/** Session context for time/scope-based policies */\n\tsession?: {\n\t\tid: string;\n\t\tstartedAt: Date;\n\t};\n\t/** The user's original request (for intent-matching policies) */\n\tuserIntent?: string;\n}\n\n/**\n * Verdict from the action firewall after evaluating a tool call.\n *\n * - allow: Tool can proceed without approval\n * - require_approval: Tool needs user approval before execution\n * - block: Tool is denied and cannot be executed\n */\nexport type ActionFirewallVerdict =\n\t| { action: \"allow\" }\n\t| { action: \"require_approval\"; ruleId: string; reason: string }\n\t| {\n\t\t\taction: \"block\";\n\t\t\truleId: string;\n\t\t\treason: string;\n\t\t\t/** Suggested steps to resolve the block */\n\t\t\tremediation?: string;\n\t  };\n\n/**\n * Internal entry for a pending approval request.\n * Stores the promise resolver and cleanup callback.\n */\ntype PendingEntry = {\n\t/** The approval request details */\n\trequest: ActionApprovalRequest;\n\t/** Resolver function to complete the approval promise */\n\tresolve: (decision: ActionApprovalDecision) => void;\n\t/** Cleanup callback to remove abort listeners */\n\tcleanup?: () => void;\n};\n\n/**\n * Manages the approval workflow for risky tool executions.\n *\n * In \"prompt\" mode, this service queues approval requests and returns\n * a promise that resolves when the user makes a decision. The UI/API\n * can call approve() or deny() to resolve pending requests.\n *\n * The service also handles abort signals to clean up pending requests\n * when the agent run is cancelled.\n */\nexport class ActionApprovalService {\n\t/** Map of request ID -> pending entry awaiting decision */\n\tprivate pending = new Map<string, PendingEntry>();\n\n\tconstructor(private mode: ApprovalMode = \"prompt\") {}\n\n\t/** Update the approval mode at runtime */\n\tsetMode(mode: ApprovalMode): void {\n\t\tthis.mode = mode;\n\t}\n\n\t/** Get the current approval mode */\n\tgetMode(): ApprovalMode {\n\t\treturn this.mode;\n\t}\n\n\t/** Check if this mode requires user interaction (UI should show prompts) */\n\trequiresUserInteraction(): boolean {\n\t\treturn this.mode === \"prompt\";\n\t}\n\n\t/**\n\t * Request approval for an action.\n\t *\n\t * Behavior depends on the current mode:\n\t * - auto: Immediately returns approved\n\t * - fail: Immediately returns denied\n\t * - prompt: Queues request and waits for user decision\n\t *\n\t * @param request - The approval request details\n\t * @param signal - Optional abort signal to cancel the request\n\t * @returns Promise that resolves with the approval decision\n\t */\n\tasync requestApproval(\n\t\trequest: ActionApprovalRequest,\n\t\tsignal?: AbortSignal,\n\t): Promise<ActionApprovalDecision> {\n\t\t// Fast path for auto mode - no queuing needed\n\t\tif (this.mode === \"auto\") {\n\t\t\treturn {\n\t\t\t\tapproved: true,\n\t\t\t\treason: \"Auto-approved by policy\",\n\t\t\t\tresolvedBy: \"policy\",\n\t\t\t};\n\t\t}\n\n\t\t// Fast path for fail mode - immediate rejection\n\t\tif (this.mode === \"fail\") {\n\t\t\treturn {\n\t\t\t\tapproved: false,\n\t\t\t\treason: \"Denied by approval policy\",\n\t\t\t\tresolvedBy: \"policy\",\n\t\t\t};\n\t\t}\n\n\t\t// Check if already aborted before queuing\n\t\tif (signal?.aborted) {\n\t\t\treturn {\n\t\t\t\tapproved: false,\n\t\t\t\treason: \"Run aborted\",\n\t\t\t\tresolvedBy: \"policy\",\n\t\t\t};\n\t\t}\n\n\t\t// Prompt mode: queue the request and wait for user decision\n\t\treturn await new Promise<ActionApprovalDecision>((resolve) => {\n\t\t\tconst entry: PendingEntry = {\n\t\t\t\trequest,\n\t\t\t\tresolve: () => {}, // Placeholder, replaced below\n\t\t\t};\n\n\t\t\t// Wrap resolver to ensure cleanup on resolution\n\t\t\tentry.resolve = (decision) => {\n\t\t\t\tentry.cleanup?.();\n\t\t\t\tresolve(decision);\n\t\t\t};\n\n\t\t\t// Set up abort handling to auto-deny if the run is cancelled\n\t\t\tif (signal) {\n\t\t\t\tconst onAbort = () => {\n\t\t\t\t\tif (!this.pending.has(request.id)) return;\n\t\t\t\t\tthis.pending.delete(request.id);\n\t\t\t\t\tentry.cleanup?.();\n\t\t\t\t\tresolve({\n\t\t\t\t\t\tapproved: false,\n\t\t\t\t\t\treason: \"Run aborted\",\n\t\t\t\t\t\tresolvedBy: \"policy\",\n\t\t\t\t\t});\n\t\t\t\t};\n\t\t\t\tentry.cleanup = () => signal.removeEventListener(\"abort\", onAbort);\n\t\t\t\tsignal.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\t}\n\n\t\t\t// Add to pending map - UI can query this to show approval prompts\n\t\t\tthis.pending.set(request.id, entry);\n\t\t});\n\t}\n\n\t/**\n\t * Approve a pending request. Called by UI or API when user approves.\n\t * @returns true if request was found and resolved, false if not pending\n\t */\n\tapprove(id: string, note?: string): boolean {\n\t\treturn this.resolve(id, {\n\t\t\tapproved: true,\n\t\t\treason: note ?? \"Approved\",\n\t\t\tresolvedBy: \"user\",\n\t\t});\n\t}\n\n\t/**\n\t * Deny a pending request. Called by UI or API when user denies.\n\t * @returns true if request was found and resolved, false if not pending\n\t */\n\tdeny(id: string, reason?: string): boolean {\n\t\treturn this.resolve(id, {\n\t\t\tapproved: false,\n\t\t\treason: reason ?? \"Denied\",\n\t\t\tresolvedBy: \"user\",\n\t\t});\n\t}\n\n\t/**\n\t * Resolve a pending request with an explicit decision.\n\t * Used by remote/server adapters that need policy-driven cancellation.\n\t */\n\tresolve(id: string, decision: ActionApprovalDecision): boolean {\n\t\treturn this.resolveEntry(id, decision);\n\t}\n\n\t/**\n\t * Clear all pending requests with a denial.\n\t * Called when the session ends or is reset.\n\t */\n\tclearPending(reason = \"Approval cancelled\"): void {\n\t\tfor (const id of Array.from(this.pending.keys())) {\n\t\t\tthis.resolve(id, {\n\t\t\t\tapproved: false,\n\t\t\t\treason: reason,\n\t\t\t\tresolvedBy: \"policy\",\n\t\t\t});\n\t\t}\n\t}\n\n\t/**\n\t * Get all currently pending approval requests.\n\t * Used by UI to display approval prompts.\n\t */\n\tgetPendingRequests(): ActionApprovalRequest[] {\n\t\treturn Array.from(this.pending.values()).map((entry) => entry.request);\n\t}\n\n\t/**\n\t * Internal helper to resolve a pending entry with a decision.\n\t * Handles cleanup and removal from pending map.\n\t */\n\tprivate resolveEntry(id: string, decision: ActionApprovalDecision): boolean {\n\t\tconst entry = this.pending.get(id);\n\t\tif (!entry) {\n\t\t\treturn false;\n\t\t}\n\t\tthis.pending.delete(id);\n\t\tentry.resolve(decision);\n\t\treturn true;\n\t}\n}\n"]}
+{"version":3,"file":"action-approval.js","sourceRoot":"","sources":["../../src/agent/action-approval.ts"],"names":[],"mappings":"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","sourcesContent":["import type { GuardedFilesPolicySettings } from \"@evalops/contracts\";\nimport { type Clock, systemClock } from \"../utils/clock.js\";\n\n/**\n * Action Approval System\n *\n * This module implements the approval workflow for risky tool executions.\n * When tools are flagged as requiring approval (by the action firewall or\n * tool configuration), this system manages the approval lifecycle.\n *\n * Three approval modes are supported:\n * - auto: Automatically approve all requests (for trusted/automated workflows)\n * - prompt: Queue requests and wait for user decision (default for interactive)\n * - fail: Automatically reject all requests (for strict security contexts)\n *\n * The approval flow:\n * 1. Agent prepares a tool call\n * 2. Action firewall evaluates and may require approval\n * 3. ActionApprovalService.requestApproval() is called\n * 4. In \"prompt\" mode, request is queued and awaits user decision\n * 5. User approves/denies via the UI or API\n * 6. Decision is returned to the agent to proceed or abort\n */\n\n/** Determines how approval requests are handled */\nexport type ApprovalMode = \"auto\" | \"prompt\" | \"fail\";\n\n/**\n * Represents a pending approval request for a tool execution.\n */\nexport interface ActionApprovalRequest {\n\t/** Unique identifier for this request */\n\tid: string;\n\t/** Name of the tool requesting approval */\n\ttoolName: string;\n\t/** Optional human-facing label for the tool */\n\tdisplayName?: string;\n\t/** Optional compact summary of the requested action */\n\tsummaryLabel?: string;\n\t/** Optional present-tense action description for approval UI */\n\tactionDescription?: string;\n\t/** Arguments the tool will be called with */\n\targs: unknown;\n\t/** Human-readable reason why approval is required */\n\treason: string;\n\t/** Unix timestamp in milliseconds when this approval lifecycle was emitted */\n\tstartedAtMs?: number;\n\t/** Optional Platform correlation for shared approval and audit surfaces */\n\tplatform?: {\n\t\tsource: \"approvals_service\" | \"tool_execution\";\n\t\ttoolExecutionId?: string;\n\t\tapprovalRequestId?: string;\n\t};\n}\n\n/**\n * The decision made for an approval request.\n */\nexport interface ActionApprovalDecision {\n\t/** Whether the action was approved */\n\tapproved: boolean;\n\t/** Optional explanation for the decision */\n\treason?: string;\n\t/** Who made the decision: automated policy or human user */\n\tresolvedBy: \"policy\" | \"user\";\n\t/** Unix timestamp in milliseconds when this approval lifecycle resolved */\n\tresolvedAtMs?: number;\n}\n\n/**\n * Serializable snapshot of PII tracking state.\n * Used to persist and restore workflow state across sessions.\n */\nexport interface WorkflowStateSnapshot {\n\t/** List of PII artifacts that are pending redaction */\n\tpendingPii: Array<{\n\t\tid: string;\n\t\tlabel: string;\n\t\tsourceToolCallId: string;\n\t\tredacted: boolean;\n\t\tparents?: string[];\n\t}>;\n\t/** Artifact IDs that were redacted but never captured (indicates bugs) */\n\torphanedRedactions: string[];\n}\n\n/**\n * Full context provided to the action firewall for approval decisions.\n * Includes the action itself plus ambient context about the workflow.\n */\nexport interface ActionApprovalContext {\n\t/** Name of the tool being executed */\n\ttoolName: string;\n\t/** Arguments for the tool call */\n\targs: unknown;\n\t/** Additional metadata for policy evaluation */\n\tmetadata?: {\n\t\t/** Current PII tracking state for data protection policies */\n\t\tworkflowState?: WorkflowStateSnapshot;\n\t\t/** MCP tool annotations that hint at tool behavior */\n\t\tannotations?: {\n\t\t\t/** Tool only reads data, doesn't modify state */\n\t\t\treadOnlyHint?: boolean;\n\t\t\t/** Tool may cause irreversible changes */\n\t\t\tdestructiveHint?: boolean;\n\t\t\t/** Tool can be safely retried */\n\t\t\tidempotentHint?: boolean;\n\t\t\t/** Tool interacts with external/untrusted systems */\n\t\t\topenWorldHint?: boolean;\n\t\t};\n\t\t/** User/org guarded-files override policy for this run */\n\t\tguardedFiles?: GuardedFilesPolicySettings;\n\t};\n\t/** User context for permission-based policies */\n\tuser?: {\n\t\tid: string;\n\t\torgId: string;\n\t};\n\t/** Session context for time/scope-based policies */\n\tsession?: {\n\t\tid: string;\n\t\tstartedAt: Date;\n\t};\n\t/** The user's original request (for intent-matching policies) */\n\tuserIntent?: string;\n}\n\n/**\n * Verdict from the action firewall after evaluating a tool call.\n *\n * - allow: Tool can proceed without approval\n * - require_approval: Tool needs user approval before execution\n * - block: Tool is denied and cannot be executed\n */\nexport type ActionFirewallVerdict =\n\t| { action: \"allow\" }\n\t| { action: \"require_approval\"; ruleId: string; reason: string }\n\t| {\n\t\t\taction: \"block\";\n\t\t\truleId: string;\n\t\t\treason: string;\n\t\t\t/** Suggested steps to resolve the block */\n\t\t\tremediation?: string;\n\t  };\n\n/**\n * Internal entry for a pending approval request.\n * Stores the promise resolver and cleanup callback.\n */\ntype PendingEntry = {\n\t/** The approval request details */\n\trequest: ActionApprovalRequest;\n\t/** Resolver function to complete the approval promise */\n\tresolve: (decision: ActionApprovalDecision) => void;\n\t/** Stamps the decision using the request's time source */\n\tstampResolvedAt: (decision: ActionApprovalDecision) => ActionApprovalDecision;\n\t/** Cleanup callback to remove abort listeners */\n\tcleanup?: () => void;\n};\n\n/**\n * Manages the approval workflow for risky tool executions.\n *\n * In \"prompt\" mode, this service queues approval requests and returns\n * a promise that resolves when the user makes a decision. The UI/API\n * can call approve() or deny() to resolve pending requests.\n *\n * The service also handles abort signals to clean up pending requests\n * when the agent run is cancelled.\n */\nexport class ActionApprovalService {\n\t/** Map of request ID -> pending entry awaiting decision */\n\tprivate pending = new Map<string, PendingEntry>();\n\n\tconstructor(\n\t\tprivate mode: ApprovalMode = \"prompt\",\n\t\tprotected readonly clock: Clock = systemClock,\n\t) {}\n\n\t/** Update the approval mode at runtime */\n\tsetMode(mode: ApprovalMode): void {\n\t\tthis.mode = mode;\n\t}\n\n\t/** Get the current approval mode */\n\tgetMode(): ApprovalMode {\n\t\treturn this.mode;\n\t}\n\n\t/** Check if this mode requires user interaction (UI should show prompts) */\n\trequiresUserInteraction(): boolean {\n\t\treturn this.mode === \"prompt\";\n\t}\n\n\t/**\n\t * Request approval for an action.\n\t *\n\t * Behavior depends on the current mode:\n\t * - auto: Immediately returns approved\n\t * - fail: Immediately returns denied\n\t * - prompt: Queues request and waits for user decision\n\t *\n\t * @param request - The approval request details\n\t * @param signal - Optional abort signal to cancel the request\n\t * @returns Promise that resolves with the approval decision\n\t */\n\tasync requestApproval(\n\t\trequest: ActionApprovalRequest,\n\t\tsignal?: AbortSignal,\n\t\tclock: Pick<Clock, \"now\"> = this.clock,\n\t): Promise<ActionApprovalDecision> {\n\t\t// Fast path for auto mode - no queuing needed\n\t\tif (this.mode === \"auto\") {\n\t\t\treturn this.withResolvedAt(\n\t\t\t\t{\n\t\t\t\t\tapproved: true,\n\t\t\t\t\treason: \"Auto-approved by policy\",\n\t\t\t\t\tresolvedBy: \"policy\",\n\t\t\t\t},\n\t\t\t\tclock,\n\t\t\t);\n\t\t}\n\n\t\t// Fast path for fail mode - immediate rejection\n\t\tif (this.mode === \"fail\") {\n\t\t\treturn this.withResolvedAt(\n\t\t\t\t{\n\t\t\t\t\tapproved: false,\n\t\t\t\t\treason: \"Denied by approval policy\",\n\t\t\t\t\tresolvedBy: \"policy\",\n\t\t\t\t},\n\t\t\t\tclock,\n\t\t\t);\n\t\t}\n\n\t\t// Check if already aborted before queuing\n\t\tif (signal?.aborted) {\n\t\t\treturn this.withResolvedAt(\n\t\t\t\t{\n\t\t\t\t\tapproved: false,\n\t\t\t\t\treason: \"Run aborted\",\n\t\t\t\t\tresolvedBy: \"policy\",\n\t\t\t\t},\n\t\t\t\tclock,\n\t\t\t);\n\t\t}\n\n\t\t// Prompt mode: queue the request and wait for user decision\n\t\treturn await new Promise<ActionApprovalDecision>((resolve) => {\n\t\t\tconst entry: PendingEntry = {\n\t\t\t\trequest,\n\t\t\t\tresolve: () => {}, // Placeholder, replaced below\n\t\t\t\tstampResolvedAt: (decision) => this.withResolvedAt(decision, clock),\n\t\t\t};\n\n\t\t\t// Wrap resolver to ensure cleanup on resolution\n\t\t\tentry.resolve = (decision) => {\n\t\t\t\tentry.cleanup?.();\n\t\t\t\tresolve(decision);\n\t\t\t};\n\n\t\t\t// Set up abort handling to auto-deny if the run is cancelled\n\t\t\tif (signal) {\n\t\t\t\tconst onAbort = () => {\n\t\t\t\t\tif (!this.pending.has(request.id)) return;\n\t\t\t\t\tthis.pending.delete(request.id);\n\t\t\t\t\tentry.resolve(\n\t\t\t\t\t\tentry.stampResolvedAt({\n\t\t\t\t\t\t\tapproved: false,\n\t\t\t\t\t\t\treason: \"Run aborted\",\n\t\t\t\t\t\t\tresolvedBy: \"policy\",\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t};\n\t\t\t\tentry.cleanup = () => signal.removeEventListener(\"abort\", onAbort);\n\t\t\t\tsignal.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\t}\n\n\t\t\t// Add to pending map - UI can query this to show approval prompts\n\t\t\tthis.pending.set(request.id, entry);\n\t\t});\n\t}\n\n\t/**\n\t * Approve a pending request. Called by UI or API when user approves.\n\t * @returns true if request was found and resolved, false if not pending\n\t */\n\tapprove(id: string, note?: string): boolean {\n\t\treturn this.resolve(id, {\n\t\t\tapproved: true,\n\t\t\treason: note ?? \"Approved\",\n\t\t\tresolvedBy: \"user\",\n\t\t});\n\t}\n\n\t/**\n\t * Deny a pending request. Called by UI or API when user denies.\n\t * @returns true if request was found and resolved, false if not pending\n\t */\n\tdeny(id: string, reason?: string): boolean {\n\t\treturn this.resolve(id, {\n\t\t\tapproved: false,\n\t\t\treason: reason ?? \"Denied\",\n\t\t\tresolvedBy: \"user\",\n\t\t});\n\t}\n\n\t/**\n\t * Resolve a pending request with an explicit decision.\n\t * Used by remote/server adapters that need policy-driven cancellation.\n\t */\n\tresolve(id: string, decision: ActionApprovalDecision): boolean {\n\t\treturn this.resolveEntry(id, decision);\n\t}\n\n\t/**\n\t * Clear all pending requests with a denial.\n\t * Called when the session ends or is reset.\n\t */\n\tclearPending(reason = \"Approval cancelled\"): void {\n\t\tfor (const id of Array.from(this.pending.keys())) {\n\t\t\tthis.resolve(id, {\n\t\t\t\tapproved: false,\n\t\t\t\treason: reason,\n\t\t\t\tresolvedBy: \"policy\",\n\t\t\t});\n\t\t}\n\t}\n\n\t/**\n\t * Get all currently pending approval requests.\n\t * Used by UI to display approval prompts.\n\t */\n\tgetPendingRequests(): ActionApprovalRequest[] {\n\t\treturn Array.from(this.pending.values()).map((entry) => entry.request);\n\t}\n\n\t/**\n\t * Internal helper to resolve a pending entry with a decision.\n\t * Handles cleanup and removal from pending map.\n\t */\n\tprivate resolveEntry(id: string, decision: ActionApprovalDecision): boolean {\n\t\tconst entry = this.pending.get(id);\n\t\tif (!entry) {\n\t\t\treturn false;\n\t\t}\n\t\tthis.pending.delete(id);\n\t\tentry.resolve(entry.stampResolvedAt(decision));\n\t\treturn true;\n\t}\n\n\tprotected withResolvedAt(\n\t\tdecision: ActionApprovalDecision,\n\t\tclock: Pick<Clock, \"now\"> = this.clock,\n\t): ActionApprovalDecision {\n\t\treturn decision.resolvedAtMs === undefined\n\t\t\t? { ...decision, resolvedAtMs: clock.now() }\n\t\t\t: decision;\n\t}\n}\n"]}

package/dist/agent/agent.d.ts

@@ -485,6 +485,7 @@ export declare class Agent {
     private enqueueFollowUpMessageSync;
     private primeToolBatch;
     private emitToolBatchSummary;
+    private handleToolPhaseSummary;
     private resolvePendingToolCalls;
     generateSummary(history: Message[], prompt: string, systemPrompt?: string, modelOverride?: Model<Api>, signal?: AbortSignal): Promise<AssistantMessage>;
 }

package/dist/agent/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent/agent.js

@@ -245,6 +245,18 @@ function buildPromptOnlyToolBatchSummaryMessage(summaryLabels) {
         timestamp: Date.now(),
     };
 }
+function buildPromptOnlyBatchShapingFeedbackMessage(hint) {
+    return {
+        role: "user",
+        content: [
+            {
+                type: "text",
+                text: `The following is transient tool batching feedback for the next assistant turn:\n- ${hint}`,
+            },
+        ],
+        timestamp: Date.now(),
+    };
+}
 /**
  * Ensures prior assistant messages remain provider-compatible when switching models mid-session.
  *
@@ -1331,6 +1343,10 @@ export class Agent {
                 else if (event.type === "tool_execution_end") {
                     this.handleToolExecutionEnd(event);
                 }
+                else if (event.type === "tool_phase_summary") {
+                    this.handleToolPhaseSummary(event);
+                    this.emit(event);
+                }
                 else if (event.type === "turn_end") {
                     if (this.shouldWithholdRecoverableOverflowError(event.message) ||
                         (isAssistantMessage(event.message) &&
@@ -1511,6 +1527,10 @@ export class Agent {
                 else if (event.type === "tool_execution_end") {
                     this.handleToolExecutionEnd(event);
                 }
+                else if (event.type === "tool_phase_summary") {
+                    this.handleToolPhaseSummary(event);
+                    this.emit(event);
+                }
                 else if (event.type === "turn_end") {
                     if (this.shouldWithholdRecoverableOverflowError(event.message) ||
                         (isAssistantMessage(event.message) &&
@@ -1933,6 +1953,12 @@ export class Agent {
             this.promptOnlyQueue.push(buildPromptOnlyToolBatchSummaryMessage(summaryLabels));
         }
     }
+    handleToolPhaseSummary(event) {
+        const feedback = event.batchShapingFeedback;
+        if (feedback?.avoidableSingleton && feedback.hint.trim().length > 0) {
+            this.promptOnlyQueue.push(buildPromptOnlyBatchShapingFeedbackMessage(feedback.hint.trim()));
+        }
+    }
     resolvePendingToolCalls(reason) {
         for (const [toolCallId, info] of this._state.pendingToolCalls.entries()) {
             const abortedResult = {