@sema-agent/core 5.16.0 → 5.17.0

package/dist/core/shared-memory/tools.js

@@ -0,0 +1,289 @@
+import { Type } from "typebox";
+import { errorResult } from "../tools.js";
+import { CONNECTING_MESSAGE, GENERIC_FAILURE_MESSAGE, NO_STORES_MESSAGE, SHARED_STORE_FRAME, UNAVAILABLE_MESSAGE, datePrefixOf, echoUntrusted, foldReaderError, listPrefixArgument, normalizeEntries, normalizeMemoryPath, normalizeReadValue, normalizeSnapshot, pageDocuments, relativePathRefusal, sanitizeSharedContent, validateDocumentPath, validatePathPrefix, } from "./normalize.js";
+import { SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_READ_TOOL_NAME, } from "./types.js";
+const LIST_HINT = "List shared memory stores and their documents — check here before telling the user you do not have something.";
+const LIST_DESCRIPTION = [
+    LIST_HINT,
+    "",
+    `List the memory documents in a memory store, sorted by path — each line gives a document's path, size, ` +
+        `and last-updated date, but no content (use ${SHARED_MEMORY_READ_TOOL_NAME} for that). Pass store (the store's id) ` +
+        `to choose the store, path_prefix to list one directory, and the cursor from a previous call to continue a ` +
+        `long listing. Call with no arguments at all to list the memory stores connected to this session — their ids, ` +
+        `a one-line description, and whether each is writable or read-only; that set can change during the session, ` +
+        `so re-check it whenever you are unsure which store to use.`,
+    "",
+    "When store is omitted this call lists the stores themselves, and path_prefix and cursor are ignored.",
+    "",
+    `Call ${SHARED_MEMORY_LIST_TOOL_NAME} early when context about the project or the work in it would help — and ` +
+        `always before telling the user you do not have something. If a listed document looks relevant, ` +
+        `${SHARED_MEMORY_READ_TOOL_NAME} it.`,
+].join("\n");
+const READ_HINT = "Read one shared memory document by store id and path — treat it as a past snapshot, not the answer.";
+const READ_DESCRIPTION = [
+    READ_HINT,
+    "",
+    "Read one memory document from a memory store by its store id and path.",
+    "",
+    "Read your memory often so corrections stick. Treat memories as past snapshots to verify against current sources, not the definitive answer.",
+    "",
+    "## When to access memories",
+    "- When memories seem relevant, or the user references prior work with them or others in their organization.",
+    "- You MUST access memory when the user explicitly asks you to check, recall, or remember.",
+    `- Call ${SHARED_MEMORY_LIST_TOOL_NAME} early when context about the project would help, and always before telling ` +
+        `the user you do not have something; if a listed document looks relevant, ${SHARED_MEMORY_READ_TOOL_NAME} it.`,
+    "- If the user says to *ignore* or *not use* memory: Do not apply remembered facts, cite, compare against, or mention memory content.",
+    "- Memory records can become stale over time. Use memory as context for what was true at a given point in time. Before answering the user or building assumptions based solely on information in memory records, verify that the memory is still correct and up-to-date by reading the current state of the files or resources. If a recalled memory conflicts with current information, trust what you observe now — and update or remove the stale memory rather than acting on it.",
+    "",
+    "## Before recommending from memory",
+    "",
+    "A memory that names a specific function, file, or flag is a claim that it existed *when the memory was written*. It may have been renamed, removed, or never merged. Before recommending it:",
+    "",
+    "- If the memory names a file path: check the file exists.",
+    "- If the memory names a function or flag: grep for it.",
+    "- If the user is about to act on your recommendation (not just asking about history), verify first.",
+    "",
+    '"The memory says X exists" is not the same as "X exists now."',
+    "",
+    "A memory that summarizes repo state (activity logs, architecture snapshots) is frozen in time. If the user asks about *recent* or *current* state, prefer `git log` or reading the code over recalling the snapshot.",
+].join("\n");
+function renderStoreLine(info) {
+    return `${info.id}  (${info.description}, ${info.writable ? "writable" : "read-only"})`;
+}
+function renderEntryLine(entry) {
+    const size = entry.sizeBytes === undefined ? "" : `${entry.sizeBytes} bytes`;
+    const date = datePrefixOf(entry.updatedAt);
+    const updated = date === undefined ? "" : `updated ${date}`;
+    const meta = [size, updated].filter((s) => s !== "").join(", ");
+    const path = JSON.stringify(entry.path);
+    return meta === "" ? path : `${path}  (${meta})`;
+}
+function renderDocumentPage(page, remaining) {
+    if (page.length === 0)
+        return "(empty)";
+    const footer = remaining > 0
+        ? `\n… ${remaining} more — call again with cursor=${JSON.stringify(page.at(-1)?.path ?? "")} to continue.`
+        : "";
+    return `${SHARED_STORE_FRAME}\n\n${page.map(renderEntryLine).join("\n")}${footer}`;
+}
+function renderDocument(content, updatedAt) {
+    return `${SHARED_STORE_FRAME}\n[updated: ${datePrefixOf(updatedAt) ?? "unknown"}]\n${sanitizeSharedContent(content)}`;
+}
+function diagnosticsOf(droppedStores, droppedEntries) {
+    return {
+        ...(droppedStores > 0 ? { droppedStores } : {}),
+        ...(droppedEntries !== undefined && droppedEntries > 0 ? { droppedEntries } : {}),
+    };
+}
+const FAILED_ERROR = { reason: "error", message: GENERIC_FAILURE_MESSAGE };
+export function createSharedMemoryTools(opts) {
+    const { provider, context } = opts;
+    const takeSnapshot = async (signal) => {
+        try {
+            return normalizeSnapshot(await provider.snapshot({ ...context }, { signal }));
+        }
+        catch (err) {
+            if (signal?.aborted === true)
+                throw err;
+            return { kind: "malformed" };
+        }
+    };
+    const resolveStore = async (storeId, signal) => {
+        const snapshot = await takeSnapshot(signal);
+        if (snapshot.kind === "malformed")
+            return { kind: "failed", refusal: FAILED_ERROR, diagnostics: {} };
+        if (snapshot.kind === "unavailable") {
+            return {
+                kind: "refused",
+                refusal: { reason: "unavailable", message: snapshot.message ?? UNAVAILABLE_MESSAGE },
+                diagnostics: {},
+            };
+        }
+        if (snapshot.kind === "connecting") {
+            return { kind: "refused", refusal: { reason: "unbound", message: CONNECTING_MESSAGE }, diagnostics: {} };
+        }
+        const diagnostics = diagnosticsOf(snapshot.droppedStores);
+        if (snapshot.stores.length === 0) {
+            return { kind: "refused", refusal: { reason: "unbound", message: NO_STORES_MESSAGE }, diagnostics };
+        }
+        const store = snapshot.stores.find((s) => s.info.id === storeId);
+        if (store === undefined) {
+            const connected = snapshot.stores.map((s) => s.info.id).join(", ");
+            return {
+                kind: "refused",
+                refusal: {
+                    reason: "unknown_store",
+                    message: `No memory store with id "${echoUntrusted(storeId)}" is connected to this session. ` +
+                        `Connected stores: ${connected}. Call ${SHARED_MEMORY_LIST_TOOL_NAME} with no arguments to list them.`,
+                },
+                diagnostics,
+            };
+        }
+        return { kind: "resolved", store, diagnostics };
+    };
+    const listTool = {
+        name: SHARED_MEMORY_LIST_TOOL_NAME,
+        description: LIST_DESCRIPTION,
+        effect: "read",
+        defer: true,
+        offload: false,
+        contract: { contractId: "core.memory_list@1", implementationRevision: "1" },
+        parameters: Type.Object({
+            store: Type.Optional(Type.String({
+                description: "Id of the connected memory store to list. Omit to list the memory stores connected to this session (id, description, and writable or read-only).",
+            })),
+            path_prefix: Type.Optional(Type.String({
+                description: "Optional directory prefix to list only documents under it (e.g. /project/<project-id>/ lists only that project). Matching is directory-aligned (/x is the same as /x/). Omit to list the whole store.",
+            })),
+            cursor: Type.Optional(Type.String({ description: "Path of the last entry from a previous call. Returns entries after this path." })),
+        }, { additionalProperties: false }),
+        execute: async (args, ctx) => {
+            const { store, path_prefix: pathPrefix, cursor } = args;
+            const signal = ctx.signal;
+            if (store === undefined) {
+                const snapshot = await takeSnapshot(signal);
+                if (snapshot.kind === "malformed") {
+                    return refusedList(FAILED_ERROR, "failed", {}, undefined);
+                }
+                if (snapshot.kind === "unavailable") {
+                    return refusedList({ reason: "unavailable", message: snapshot.message ?? UNAVAILABLE_MESSAGE }, "refused", {}, undefined);
+                }
+                if (snapshot.kind === "connecting") {
+                    const details = { outcome: "ok", mode: "stores", stores: [], connecting: true };
+                    return { content: CONNECTING_MESSAGE, details };
+                }
+                const diagnostics = diagnosticsOf(snapshot.droppedStores);
+                const stores = snapshot.stores.map((s) => s.info);
+                const details = { ...diagnostics, outcome: "ok", mode: "stores", stores };
+                if (stores.length === 0)
+                    return { content: NO_STORES_MESSAGE, details };
+                return {
+                    content: `Connected memory stores — pass an id as store to list or read one:\n${stores.map(renderStoreLine).join("\n")}`,
+                    details,
+                };
+            }
+            const resolution = await resolveStore(store, signal);
+            if (resolution.kind !== "resolved") {
+                return refusedList(resolution.refusal, resolution.kind, resolution.diagnostics, store);
+            }
+            let normalizedPrefix;
+            if (pathPrefix !== undefined) {
+                normalizedPrefix = normalizeMemoryPath(pathPrefix);
+                const refusal = relativePathRefusal(pathPrefix) ?? validatePathPrefix(normalizedPrefix);
+                if (refusal)
+                    return refusedList(refusal, "refused", resolution.diagnostics, store);
+            }
+            let raw;
+            try {
+                raw = await resolution.store.list(normalizedPrefix === undefined ? undefined : listPrefixArgument(normalizedPrefix), { signal });
+            }
+            catch (err) {
+                if (signal?.aborted === true)
+                    throw err;
+                return refusedList(foldReaderError(err), "failed", resolution.diagnostics, store);
+            }
+            const normalized = normalizeEntries(raw);
+            if (normalized.kind === "malformed")
+                return refusedList(FAILED_ERROR, "failed", resolution.diagnostics, store);
+            const { page, remaining } = pageDocuments(normalized.entries, {
+                ...(normalizedPrefix !== undefined ? { normalizedPrefix } : {}),
+                ...(cursor !== undefined ? { cursor } : {}),
+            });
+            const details = {
+                ...diagnosticsOf(resolution.diagnostics.droppedStores ?? 0, normalized.droppedEntries),
+                outcome: "ok",
+                mode: "documents",
+                store,
+                entries: page,
+                remaining,
+            };
+            return { content: renderDocumentPage(page, remaining), details };
+        },
+    };
+    const readTool = {
+        name: SHARED_MEMORY_READ_TOOL_NAME,
+        description: READ_DESCRIPTION,
+        effect: "read",
+        defer: true,
+        offload: false,
+        contract: { contractId: "core.memory_read@1", implementationRevision: "1" },
+        parameters: Type.Object({
+            store: Type.String({
+                description: `Id of the connected memory store to read from (call ${SHARED_MEMORY_LIST_TOOL_NAME} with no arguments to see the connected stores).`,
+            }),
+            path: Type.String({
+                description: "Path of the memory document to read (e.g. /project/<project-id>/MEMORY.md).",
+            }),
+        }, { additionalProperties: false }),
+        execute: async (args, ctx) => {
+            const { store, path } = args;
+            const signal = ctx.signal;
+            const resolution = await resolveStore(store, signal);
+            if (resolution.kind !== "resolved") {
+                return refusedRead(resolution.refusal, resolution.kind, resolution.diagnostics, store, path);
+            }
+            const normalizedPath = normalizeMemoryPath(path);
+            const refusal = relativePathRefusal(path) ?? validateDocumentPath(normalizedPath);
+            if (refusal)
+                return refusedRead(refusal, "refused", resolution.diagnostics, store, normalizedPath);
+            let raw;
+            try {
+                raw = await resolution.store.read(normalizedPath, { signal });
+            }
+            catch (err) {
+                if (signal?.aborted === true)
+                    throw err;
+                return refusedRead(foldReaderError(err), "failed", resolution.diagnostics, store, normalizedPath);
+            }
+            const normalized = normalizeReadValue(raw);
+            if (normalized.kind === "malformed") {
+                return refusedRead(FAILED_ERROR, "failed", resolution.diagnostics, store, normalizedPath);
+            }
+            if (normalized.value === null) {
+                const details = {
+                    ...resolution.diagnostics,
+                    outcome: "not_found",
+                    store,
+                    path: normalizedPath,
+                };
+                return errorResult(`${SHARED_MEMORY_READ_TOOL_NAME} failed: not found`, details);
+            }
+            const bytes = Buffer.byteLength(normalized.value.content, "utf8");
+            if (bytes > SHARED_MEMORY_READ_CAP_BYTES) {
+                return refusedRead({
+                    reason: "too_large",
+                    message: `"${normalizedPath}" is ${bytes} bytes, over the ${SHARED_MEMORY_READ_CAP_BYTES}-byte read cap, so its content is not returned.`,
+                }, "refused", resolution.diagnostics, store, normalizedPath);
+            }
+            const details = {
+                ...resolution.diagnostics,
+                outcome: "ok",
+                store,
+                path: normalizedPath,
+                bytes,
+                ...(normalized.value.updatedAt !== undefined ? { updatedAt: normalized.value.updatedAt } : {}),
+            };
+            return { content: renderDocument(normalized.value.content, normalized.value.updatedAt), details };
+        },
+    };
+    return [listTool, readTool];
+}
+function refusedList(refusal, outcome, diagnostics, store) {
+    const details = {
+        ...diagnostics,
+        outcome,
+        reason: refusal.reason,
+        ...(store !== undefined ? { store } : {}),
+    };
+    return errorResult(refusal.message, details);
+}
+function refusedRead(refusal, outcome, diagnostics, store, path) {
+    const details = {
+        ...diagnostics,
+        outcome,
+        reason: refusal.reason,
+        ...(store !== undefined ? { store } : {}),
+        ...(path !== undefined ? { path } : {}),
+    };
+    return errorResult(refusal.message, details);
+}

package/dist/core/shared-memory/types.d.ts

@@ -0,0 +1,95 @@
+export declare const SHARED_MEMORY_LIST_TOOL_NAME = "memory_list";
+export declare const SHARED_MEMORY_READ_TOOL_NAME = "memory_read";
+export declare const SHARED_MEMORY_TOOL_NAMES: readonly ["memory_list", "memory_read"];
+export declare const SHARED_MEMORY_READ_CAP_BYTES = 102400;
+export declare const SHARED_MEMORY_LIST_PAGE_SIZE = 50;
+export declare const SHARED_MEMORY_MAX_STORES = 64;
+export declare const SHARED_MEMORY_DESCRIPTION_MAX = 160;
+export interface SharedMemoryStoreInfo {
+    id: string;
+    description: string;
+    writable: boolean;
+}
+export interface SharedMemoryDocumentEntry {
+    path: string;
+    sizeBytes?: number;
+    updatedAt?: string;
+}
+export interface SharedMemoryStoreReader {
+    list(prefix: string | undefined, opts: {
+        signal?: AbortSignal;
+    }): Promise<SharedMemoryDocumentEntry[]>;
+    read(path: string, opts: {
+        signal?: AbortSignal;
+    }): Promise<{
+        content: string;
+        updatedAt?: string;
+    } | null>;
+}
+export interface SharedMemoryRequestContext {
+    sessionId: string;
+    taskId: string;
+    principal?: string;
+}
+export type SharedMemorySnapshot = {
+    state: "connecting";
+} | {
+    state: "unavailable";
+    message?: string;
+} | {
+    state: "connected";
+    stores: ReadonlyArray<{
+        info: SharedMemoryStoreInfo;
+        reader: SharedMemoryStoreReader;
+    }>;
+};
+export interface SharedMemoryStoreProvider {
+    snapshot(ctx: SharedMemoryRequestContext, opts: {
+        signal?: AbortSignal;
+    }): Promise<SharedMemorySnapshot> | SharedMemorySnapshot;
+}
+export declare class SharedMemoryStoreError extends Error {
+    readonly kind: "store_not_found" | "refused" | "transient";
+    readonly reason?: string;
+    constructor(kind: SharedMemoryStoreError["kind"], opts?: {
+        reason?: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+export interface SharedMemoryDiagnostics {
+    droppedStores?: number;
+    droppedEntries?: number;
+}
+export type MemoryListDetails = SharedMemoryDiagnostics & ({
+    outcome: "ok";
+    mode: "stores";
+    stores: SharedMemoryStoreInfo[];
+    connecting?: true;
+} | {
+    outcome: "ok";
+    mode: "documents";
+    store: string;
+    entries: SharedMemoryDocumentEntry[];
+    remaining: number;
+} | {
+    outcome: "refused" | "failed";
+    reason: string;
+    store?: string;
+});
+export type MemoryReadDetails = SharedMemoryDiagnostics & ({
+    outcome: "ok";
+    store: string;
+    path: string;
+    bytes: number;
+    updatedAt?: string;
+} | {
+    outcome: "not_found";
+    store: string;
+    path: string;
+} | {
+    outcome: "refused" | "failed";
+    reason: string;
+    store?: string;
+    path?: string;
+});

package/dist/core/shared-memory/types.js

@@ -0,0 +1,18 @@
+export const SHARED_MEMORY_LIST_TOOL_NAME = "memory_list";
+export const SHARED_MEMORY_READ_TOOL_NAME = "memory_read";
+export const SHARED_MEMORY_TOOL_NAMES = [SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_TOOL_NAME];
+export const SHARED_MEMORY_READ_CAP_BYTES = 102400;
+export const SHARED_MEMORY_LIST_PAGE_SIZE = 50;
+export const SHARED_MEMORY_MAX_STORES = 64;
+export const SHARED_MEMORY_DESCRIPTION_MAX = 160;
+export class SharedMemoryStoreError extends Error {
+    kind;
+    reason;
+    constructor(kind, opts) {
+        super(opts?.message ?? kind, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = "SharedMemoryStoreError";
+        this.kind = kind;
+        if (opts?.reason !== undefined)
+            this.reason = opts.reason;
+    }
+}

package/dist/core/task-notification.d.ts

@@ -23,6 +23,9 @@ export interface TaskNotificationPayload {
     editedFiles?: import("../agents/subagent-steps.js").SubagentEditedFile[];
     resumable?: boolean;
     completionId?: string;
+    peer?: {
+        hopChain: string[];
+    };
 }
 export interface ExternalNotificationInput {
     task_id: string;

package/dist/core/task-registry-agent.d.ts

@@ -120,7 +120,7 @@ export declare function deliverToRunningAgentLane(core: DurableAgentCore, id: st
     disposition: "queued" | "parked" | "pending";
 } | {
     ok: false;
-    reason: "not_found" | "not_running" | "no_channel";
+    reason: "not_found" | "not_running" | "no_channel" | "queue_full";
 }>;
 export declare function runningBackgroundAgentLabelsLane(core: DurableAgentCore, access: TaskAccess): string[];
 export declare function runningAgentFooterLane(core: DurableAgentCore, access: TaskAccess): {

package/dist/core/task-registry-agent.js

@@ -982,6 +982,7 @@ export async function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.errorRetryAfterMs = undefined;
     handle.resultIsPartial = undefined;
     handle.stopSource = undefined;
+    handle.stoppedBy = undefined;
     handle.completionId = undefined;
     handle.terminalNotified = undefined;
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
@@ -1102,7 +1103,7 @@ export async function deliverToRunningAgentLane(core, id, access, notification,
             return { ok: false, reason: "no_channel" };
         const q = (handle.preAttachQueue ??= []);
         if (q.length >= 8)
-            return { ok: false, reason: "no_channel" };
+            return { ok: false, reason: "queue_full" };
         return bounded(new Promise((resolve) => {
             q.push([notification, opts, resolve]);
         }), { ok: true, disposition: "pending" });

package/dist/core/task-registry.d.ts

@@ -195,7 +195,7 @@ export declare class TaskRegistry {
         disposition: "queued" | "parked" | "pending";
     } | {
         ok: false;
-        reason: "not_found" | "not_running" | "no_channel";
+        reason: "not_found" | "not_running" | "no_channel" | "queue_full";
     }>;
     runningBackgroundAgentLabels(access: TaskAccess): string[];
     private pollBackgroundAgent;

package/dist/core/task-registry.js

@@ -957,6 +957,8 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
         for (const [id, handle] of this.handles) {
             if (handle.status === "running" || handle.status === "pending")
                 continue;
+            if (this.claimingHandles.has(id) || this.reapingHandles.has(id))
+                continue;
             if (now - handle.updatedAt < terminalTtlMs)
                 continue;
             this.handles.delete(id);

package/dist/core/tool-policy.d.ts

@@ -100,6 +100,15 @@ export type AskOutcome = boolean | "unavailable" | {
 };
 export declare function withDelegationProvenance(onAsk: OnAsk, delegation: AskDelegationProvenance): OnAsk;
 export declare function askApproverIdentity(onAsk: unknown): unknown;
+export declare function tryCloneArgs<T>(v: T): {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+    cause?: unknown;
+};
+export declare function describeThrown(err: unknown): string;
 export type ResolvedAsk = PermissionResult & {
     approverUnavailable?: true;
     presentedInput?: unknown;

package/dist/core/tool-policy.js

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
 import { boundInputHashOf } from "./canonical-json.js";
+import { inlineUntrusted } from "./untrusted-text.js";
 import { writeTargetPath } from "../tools/fs/safety.js";
 export function decisionText(d) {
     return d.message;
@@ -90,7 +91,7 @@ export function createApprovalPolicy(opts) {
                 catch (err) {
                     return {
                         action: "deny",
-                        message: `approval errored for "${req.toolName}": ${err instanceof Error ? err.message : String(err)}`,
+                        message: `approval errored for "${req.toolName}": ${describeThrown(err)}`,
                     };
                 }
                 const okRaw = ok;
@@ -528,17 +529,36 @@ export function withDelegationProvenance(onAsk, delegation) {
 export function askApproverIdentity(onAsk) {
     return typeof onAsk === "function" ? (delegatedApproverRoot.get(onAsk) ?? onAsk) : onAsk;
 }
-function tryCloneArgs(v) {
+export function tryCloneArgs(v) {
     try {
         const value = structuredClone(v);
         if (containsSharedMemory(value))
-            return { ok: false };
+            return { ok: false, reason: "the value carries shared memory (SharedArrayBuffer), which a clone still aliases" };
         return { ok: true, value };
     }
+    catch (err) {
+        return { ok: false, reason: describeThrown(err), cause: err };
+    }
+}
+export function describeThrown(err) {
+    try {
+        if (typeof err === "string")
+            return containThrownText(err);
+        if (err instanceof Error) {
+            const message = err.message;
+            if (typeof message === "string" && message !== "")
+                return containThrownText(message);
+        }
+        return `a non-Error value was thrown (${err === null ? "null" : typeof err})`;
+    }
     catch {
-        return { ok: false };
+        return "the value could not be described";
     }
 }
+const THROWN_TEXT_MAX = 300;
+function containThrownText(text) {
+    return inlineUntrusted(text, THROWN_TEXT_MAX);
+}
 function containsSharedMemory(v, seen = new Set()) {
     if (typeof SharedArrayBuffer !== "undefined" && v instanceof SharedArrayBuffer)
         return true;
@@ -593,7 +613,7 @@ export async function resolveAsk(req, onAsk, signal) {
     if (!presented.ok) {
         return {
             action: "deny",
-            message: `approval for "${req.toolName}" could not present the args safely (unclonable value) — denied fail-closed`,
+            message: `approval for "${req.toolName}" could not present the args safely (unclonable value: ${presented.reason}) — denied fail-closed`,
             decisionReason: "mode",
         };
     }
@@ -603,7 +623,7 @@ export async function resolveAsk(req, onAsk, signal) {
         if (!approverView.ok) {
             return {
                 action: "deny",
-                message: `approval for "${req.toolName}" could not present the args safely (unclonable value) — denied fail-closed`,
+                message: `approval for "${req.toolName}" could not present the args safely (unclonable value: ${approverView.reason}) — denied fail-closed`,
                 decisionReason: "mode",
             };
         }
@@ -612,7 +632,7 @@ export async function resolveAsk(req, onAsk, signal) {
     catch (err) {
         return {
             action: "deny",
-            message: `approval errored for "${req.toolName}": ${err instanceof Error ? err.message : String(err)}`,
+            message: `approval errored for "${req.toolName}": ${describeThrown(err)}`,
             decisionReason: "mode",
         };
     }
@@ -635,7 +655,7 @@ export async function resolveAsk(req, onAsk, signal) {
         if (!edit.ok) {
             return {
                 action: "deny",
-                message: `the approved edit for "${req.toolName}" is not safely clonable — denied fail-closed`,
+                message: `the approved edit for "${req.toolName}" is not safely clonable (${edit.reason}) — denied fail-closed`,
                 decisionReason: "mode",
             };
         }

package/dist/core/types.d.ts

@@ -90,8 +90,13 @@ export interface ToolExecuteContext {
             outcome: import("./checkpoint-store.js").ResumeOutcome;
             inheritedGate?: import("./runner/prepare-task.js").InheritedGate;
         };
+        peerSeed?: {
+            hopChain: string[];
+        };
     };
     spawnedAgentName?: string;
+    peerSelfRef?: import("../agents/peer-admission.js").PeerSelfRef;
+    peerInboundChainRef?: import("../agents/peer-admission.js").PeerInboundChainRef;
     roster?: import("../agents/roster-store.js").RosterStore;
     hostSessionFork?: () => Promise<{
         sessionId: string;
@@ -169,6 +174,7 @@ export interface HandsBandOptions {
     readImageDownsampler?: ((input: Buffer, mimeType: string) => Promise<import("./mcp.js").DownsampledImage | undefined>) | false;
     beforeWrite?: BeforeWriteHook;
     autoBackgroundOnTimeout?: boolean;
+    readCyberReminder?: boolean;
 }
 export interface AgentDefinition {
     name: string;
@@ -792,6 +798,7 @@ export interface RunnerDeps {
     workflowRunStore?: import("./workflow-run-store.js").WorkflowRunStore;
     backgroundAgentStore?: import("./background-agent-store.js").BackgroundAgentStore;
     mailboxStore?: import("./mailbox-store.js").MailboxStore;
+    peerAdmission?: Partial<import("../agents/peer-admission.js").PeerAdmissionConfig>;
     usageWindows?: readonly import("./usage-window-store.js").UsageWindow[];
     usageWindowStore?: import("./usage-window-store.js").UsageWindowStore;
     workflowJournalStore?: import("./workflow-journal-store.js").WorkflowJournalStore;
@@ -802,6 +809,7 @@ export interface RunnerDeps {
     brainCallGuardrailMs?: import("../brain/timeout.js").BrainCallGuardrailKnob;
     now?: () => number;
     memoryBackend?: import("./memory-engine/types.js").MemoryBackend;
+    sharedMemoryStores?: import("./shared-memory/types.js").SharedMemoryStoreProvider;
     memoryEngineDir?: string;
     onMemoryHarvestReport?: (report: import("./memory-engine/types.js").HarvestReport, info: {
         sessionId: string;

package/dist/core/untrusted-text.d.ts

@@ -23,5 +23,6 @@ export declare function cutEngineSegments(text: string, segments: unknown): {
 };
 export declare function flattenableUserText(content: unknown): string | undefined;
 export declare function defuseFenceMarkers(body: string): string;
+export declare function defuseControlChars(text: string): string;
 export declare function inlineUntrusted(text: string, maxLen?: number): string;
 export declare function delimitUntrusted(label: string, text: string, maxBody?: number): string;

package/dist/core/untrusted-text.js

@@ -87,6 +87,16 @@ export function flattenableUserText(content) {
 export function defuseFenceMarkers(body) {
     return body.replace(/<{3,}|>{3,}/g, (run) => run.match(/.{1,2}/g).join(ZWSP));
 }
+const REPLACEMENT = "�";
+export function defuseControlChars(text) {
+    let out = "";
+    for (const ch of text.replace(/\r\n?/g, "\n")) {
+        const cp = ch.codePointAt(0) ?? 0;
+        const control = cp !== 9 && cp !== 10 && (cp < 32 || (cp >= 127 && cp <= 159));
+        out += control ? REPLACEMENT : ch;
+    }
+    return out;
+}
 const LABEL_MAX = 160;
 export function inlineUntrusted(text, maxLen = LABEL_MAX) {
     const oneLine = text.replace(/[\s\u0000-\u001f\u007f\u0085]+/g, " ").trim();

package/dist/core/wiring-manifest.js

@@ -19,9 +19,9 @@ export function deriveAskEffective(form, parkEffective) {
         case "callback":
             return "human_reachable";
         case "allow":
-            return "auto_allow";
+            return parkEffective === true ? "park_only" : parkEffective === "unresolved" ? "unresolved" : "auto_allow";
         case "deny":
-            return "auto_deny";
+            return parkEffective === true ? "park_only" : parkEffective === "unresolved" ? "unresolved" : "auto_deny";
         case "absent":
             return parkEffective === true ? "park_only" : parkEffective === "unresolved" ? "unresolved" : "auto_deny";
         default: {

package/dist/engine/harness/agent-harness.d.ts

@@ -36,6 +36,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private model;
     private thinkingLevel;
     onUndrainedEngineNotes?: (payloads: unknown[]) => void;
+    onEngineNoteConsumed?: (payload: unknown) => void;
     recoverUndrainedEngineNotes(): void;
     private sweepUndrainedEngineNotes;
     private systemPrompt;