@sema-agent/core 2.11.0 → 2.13.0

package/dist/agents/agent-transcript-tool.d.ts

@@ -8,6 +8,7 @@ export interface AgentTranscriptToolOptions {
     owner?: string;
     scope?: string;
     sessionId?: string;
+    enrichCtx?: import("../core/tools.js").ToolCtxEnricher;
 }
 export declare function createAgentTranscriptTool(opts: AgentTranscriptToolOptions): import("../internal/harness-types.js").AgentTool<Type.TObject<{
     id: Type.TString;

package/dist/agents/agent-transcript-tool.js

@@ -118,5 +118,5 @@ export function createAgentTranscriptTool(opts) {
                 details: { type: "agent-transcript", id, steps },
             };
         },
-    });
+    }, opts.enrichCtx !== undefined ? { enrichCtx: opts.enrichCtx } : {});
 }

package/dist/brain/stream-engine.js

@@ -43,6 +43,9 @@ function emptyAssistant(model) {
 function isAbortError(err) {
     return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
 }
+function isWalltimeCutoff(err) {
+    return err instanceof Error && err.message === WALLTIME_CUTOFF_MESSAGE;
+}
 function sleep(ms, signal) {
     return new Promise((resolve) => {
         if (signal?.aborted)
@@ -85,7 +88,7 @@ export function runStreamingBrain(args) {
         .catch((err) => {
         const aborted = signal?.aborted === true || isAbortError(err);
         terminalRetryPhase = "gave_up";
-        terminalRetryDetail = aborted ? "cancelled while retrying" : "retries exhausted";
+        terminalRetryDetail = aborted ? "cancelled while retrying" : isWalltimeCutoff(err) ? "wall-clock deadline reached while retrying" : "retries exhausted";
         const errorMsg = emptyAssistant(model);
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = err instanceof Error ? err.message : String(err);

package/dist/core/auto-promote.js

@@ -1,4 +1,5 @@
 import { extractSymbols } from "../tools/fs/repo-map.js";
+import { parseSkillToolEntry } from "./skill-tool-specifier.js";
 export function decideAutoPromote(i) {
     if (i.tripwire.escalate)
         return "needs_human";
@@ -58,7 +59,7 @@ export function deriveTripwire(artifactText, declared, profileTokens) {
     const reasons = [];
     let escalate = false;
     try {
-        const allow = new Set(declared.allowTools ?? []);
+        const allow = new Set((declared.allowTools ?? []).map((entry) => parseSkillToolEntry(entry).name));
         const symbols = extractSymbols(artifactText);
         for (const sym of symbols) {
             if (!allow.has(sym)) {

package/dist/core/checkpoint-store.d.ts

@@ -242,6 +242,7 @@ export interface CheckpointSummary {
     contentKind?: "content_ask";
     createdAt?: number;
     toolInput?: string;
+    restoreMode?: "snapshot" | "park_only";
     preview?: unknown;
 }
 export declare function summarizeCheckpoint(cp: Checkpoint): CheckpointSummary;

package/dist/core/checkpoint-store.js

@@ -181,6 +181,9 @@ export function summarizeCheckpoint(cp) {
         ...(tool !== undefined ? { toolCallId: tool.toolCallId, toolName: tool.toolName } : {}),
         ...(tool?.toolName === ASK_USER_QUESTION_TOOL_NAME ? { contentKind: "content_ask" } : {}),
         ...(toolInput !== undefined ? { toolInput } : {}),
+        ...(cp.state.workspaceHandle !== undefined
+            ? { restoreMode: cp.state.workspaceHandle.restoreMode === "park_only" ? "park_only" : "snapshot" }
+            : {}),
         ...(tool?.preview !== undefined ? { preview: tool.preview } : {}),
     };
 }

package/dist/core/git-worktree-env.js

@@ -28,6 +28,11 @@ export async function addWorktree(baseEnv, opts) {
         const detail = add.ok ? add.value.stderr || add.value.stdout : String(add.error);
         throw new Error(`git worktree add failed: ${detail}`);
     }
+    const excludeLine = shq(`/${WORKTREE_PARENT}/`);
+    await baseEnv
+        .exec(`ex="$(git rev-parse --git-path info/exclude)" && mkdir -p "$(dirname "$ex")" && ` +
+        `{ grep -qxF ${excludeLine} "$ex" 2>/dev/null || printf '%s\\n' ${excludeLine} >> "$ex"; }`, { cwd: opts.repoRoot })
+        .catch(() => undefined);
     let inner;
     try {
         inner = await opts.rootEnvAt(worktreeDir);

package/dist/core/mcp.d.ts

@@ -57,6 +57,7 @@ export interface McpServerStatus {
     };
     toolNames?: string[];
     error?: string;
+    transportClosed?: boolean;
 }
 export declare const MCP_PREFIX = "mcp__";
 export declare function resolveMcpDeclaredResultSize(meta: Record<string, unknown> | undefined): number | undefined;
@@ -69,6 +70,8 @@ export declare const MCP_IDLE_TIMEOUT_STDIO_DEFAULT_MS: number;
 export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
 export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
+export declare function collapseMcpErrorPrefix(message: string): string;
+export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
 export declare function normalizeMcpName(name: string): string;
 export declare function clampNameSegment(seg: string, max?: number): string;
 export * from "./image-downsample.js";

package/dist/core/mcp.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -145,8 +145,24 @@ const MCP_SPEC_ERROR_CODE_NAMES = new Map([
 export function describeMcpSpecErrorCode(code) {
     return typeof code === "number" ? MCP_SPEC_ERROR_CODE_NAMES.get(code) : undefined;
 }
+export function collapseMcpErrorPrefix(message) {
+    let out = message;
+    for (;;) {
+        const m = /^MCP error (-?\d+): (?=MCP error \1: )/.exec(out);
+        if (m === null)
+            return out;
+        out = out.slice(m[0].length);
+    }
+}
+function collapseMcpErrorStampInPlace(err) {
+    if (!(err instanceof McpError))
+        return;
+    const collapsed = collapseMcpErrorPrefix(err.message);
+    if (collapsed !== err.message)
+        err.message = collapsed;
+}
 function namedMcpFailureText(err) {
-    const detail = err instanceof Error ? err.message : String(err);
+    const detail = err instanceof Error ? collapseMcpErrorPrefix(err.message) : String(err);
     const condition = err instanceof McpError ? describeMcpSpecErrorCode(err.code) : undefined;
     return condition !== undefined ? `${condition}: ${detail}` : detail;
 }
@@ -155,6 +171,53 @@ function isTransportLost(err) {
         return true;
     return err instanceof Error && /not connected|connection closed/i.test(err.message);
 }
+const NETWORK_CODES_NEVER_DELIVERED = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+export function networkErrorCode(err, depth = 0) {
+    if (depth > 5 || !(err instanceof Error))
+        return undefined;
+    const code = err.code;
+    if (typeof code === "string" && /^(?:E[A-Z_]+|UND_ERR_[A-Z_]+)$/.test(code))
+        return code;
+    if (err instanceof AggregateError) {
+        for (const inner of err.errors) {
+            const found = networkErrorCode(inner, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return networkErrorCode(err.cause, depth + 1);
+}
+function describeHttpTransportFailure(err) {
+    if (err instanceof McpError)
+        return undefined;
+    if (err instanceof StreamableHTTPError) {
+        const status = typeof err.code === "number" && err.code > 0 ? err.code : undefined;
+        return {
+            condition: status !== undefined
+                ? `its HTTP endpoint answered ${status} instead of an MCP response`
+                : "its HTTP endpoint answered something that is not an MCP response",
+            delivered: "unknown",
+            ...(status !== undefined ? { httpStatus: status } : {}),
+        };
+    }
+    const code = networkErrorCode(err);
+    if (code !== undefined) {
+        return NETWORK_CODES_NEVER_DELIVERED.has(code)
+            ? { condition: `its HTTP endpoint could not be reached (${code})`, delivered: "no" }
+            : { condition: `the connection to its HTTP endpoint failed (${code})`, delivered: "unknown" };
+    }
+    if (err instanceof TypeError && /fetch failed|terminated|network/i.test(err.message)) {
+        return { condition: "the HTTP request to its endpoint failed at the network layer", delivered: "unknown" };
+    }
+    return undefined;
+}
 function writeEffectWarning(writeEffect) {
     return writeEffect
         ? " This tool is write-capable: treat its side effects as POSSIBLY APPLIED and verify the actual state before retrying."
@@ -173,6 +236,7 @@ function rethrowHonestMcpError(err, ctx) {
     }
     if (ctx.signal?.aborted)
         throw err;
+    collapseMcpErrorStampInPlace(err);
     const serverLabel = inlineUntrusted(ctx.server);
     if (err instanceof McpError && err.code === ErrorCode.RequestTimeout) {
         const data = err.data;
@@ -193,6 +257,21 @@ function rethrowHonestMcpError(err, ctx) {
         e.details = { transportLost: true, server: ctx.server };
         throw e;
     }
+    const httpFailure = describeHttpTransportFailure(err);
+    if (httpFailure !== undefined) {
+        const detail = err instanceof Error ? err.message : String(err);
+        const fenced = `\nThe transport error follows as external/untrusted data:\n${delimitUntrusted(`${ctx.server} transport error`, truncateMcpErrorText(detail))}`;
+        const e = new Error(httpFailure.delivered === "no"
+            ? `${ctx.what} could not reach MCP server "${serverLabel}": ${httpFailure.condition}. The request was not delivered, so the server did not execute it. This server's tools and resources will keep failing until its endpoint is reachable again — do not retry them; use an alternative if one exists.${fenced}`
+            : `${ctx.what} failed at the transport layer of MCP server "${serverLabel}": ${httpFailure.condition}. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`, { cause: err });
+        e.errorKind = httpFailure.delivered === "no" ? "server_disconnected" : "transport_lost";
+        e.details = {
+            server: ctx.server,
+            ...(httpFailure.delivered === "no" ? {} : { transportLost: true }),
+            ...(httpFailure.httpStatus !== undefined ? { httpStatus: httpFailure.httpStatus } : {}),
+        };
+        throw e;
+    }
     if (err instanceof McpError) {
         const condition = describeMcpSpecErrorCode(err.code);
         if (condition !== undefined) {
@@ -546,12 +625,16 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     serverInstructions.push({ server: spec.name, text: s.instructions });
                 }
                 const hasInstructions = s.instructions !== undefined;
-                s.announce.fn = () => {
-                    if (!disposing && hasInstructions)
+                const announceClose = () => {
+                    if (disposing)
+                        return;
+                    s.status.transportClosed = true;
+                    if (hasInstructions)
                         instructionsDelta.pendingRemovals.push(spec.name);
                 };
-                if (s.health.dead && hasInstructions)
-                    instructionsDelta.pendingRemovals.push(spec.name);
+                s.announce.fn = announceClose;
+                if (s.health.dead)
+                    announceClose();
                 if (s.resourceServer)
                     resourceServers.push(s.resourceServer);
                 for (const d of s.dropped)
@@ -703,7 +786,8 @@ async function readDirViaExtension(rs, uri, signal, timeoutMs, watchdog) {
             if (err instanceof McpError && err.code === ErrorCode.InvalidParams) {
                 if (pages > 0)
                     return { kind: "ok", resources, cursorInvalid: true };
-                return { kind: classifyDirReadInvalidParams(err.message), detail: err.message };
+                const detail = collapseMcpErrorPrefix(err.message);
+                return { kind: classifyDirReadInvalidParams(detail), detail };
             }
             if (err instanceof McpError && err.code === ErrorCode.MethodNotFound)
                 return { kind: "unsupported" };

package/dist/core/remote-env.d.ts

@@ -44,6 +44,8 @@ export interface ExecStreamOptions {
     maxOutputBytes?: number;
 }
 export type RemoteExecutionErrorCode = "suspended" | "command_in_flight" | "connect_failed" | "post_resume_failed" | "aborted" | "timeout" | "unsupported" | "auth_transient" | "auth_failed" | "transport_lost" | "unknown";
+export declare const RETRYABLE_REMOTE_ERROR_CODES: readonly RemoteExecutionErrorCode[];
+export declare function isRetryableRemoteErrorCode(code: RemoteExecutionErrorCode): boolean;
 export declare class RemoteExecutionError extends Error {
     readonly code: RemoteExecutionErrorCode;
     constructor(code: RemoteExecutionErrorCode, message: string, cause?: Error);
@@ -101,5 +103,6 @@ export interface ExecutionEnvFactoryContext {
 export type ExecutionEnvFactory = (ctx: ExecutionEnvFactoryContext) => ExecutionEnv | Promise<ExecutionEnv>;
 export declare function hasDestroy(env: ExecutionEnv): env is ExecutionEnv & Pick<RemoteExecutionEnv, "destroy">;
 export declare function isRemoteExecutionEnv(env: ExecutionEnv): env is RemoteExecutionEnv;
+export declare function missingRestoreSurface(env: ExecutionEnv): readonly ("resumeVM" | "postResumeInit")[];
 export declare function isSuspendable(env: ExecutionEnv): env is RemoteExecutionEnv;
 export declare function isIsolated(env: ExecutionEnv): boolean;

package/dist/core/remote-env.js

@@ -1,3 +1,12 @@
+export const RETRYABLE_REMOTE_ERROR_CODES = [
+    "auth_transient",
+    "connect_failed",
+    "timeout",
+    "transport_lost",
+];
+export function isRetryableRemoteErrorCode(code) {
+    return RETRYABLE_REMOTE_ERROR_CODES.includes(code);
+}
 export class RemoteExecutionError extends Error {
     code;
     constructor(code, message, cause) {
@@ -18,8 +27,17 @@ export function isRemoteExecutionEnv(env) {
         typeof e.capabilities === "object" &&
         e.capabilities !== null);
 }
+export function missingRestoreSurface(env) {
+    const e = env;
+    const missing = [];
+    if (typeof e.resumeVM !== "function")
+        missing.push("resumeVM");
+    if (typeof e.postResumeInit !== "function")
+        missing.push("postResumeInit");
+    return missing;
+}
 export function isSuspendable(env) {
-    return isRemoteExecutionEnv(env) && env.capabilities.suspendable;
+    return isRemoteExecutionEnv(env) && env.capabilities.suspendable && missingRestoreSurface(env).length === 0;
 }
 export function isIsolated(env) {
     return isRemoteExecutionEnv(env) ? env.capabilities.isolation : false;

package/dist/core/runner/active-skill-scope.js

@@ -1,5 +1,6 @@
 import { canonicalizeTarget, fileArgPath } from "../../tools/fs/safety.js";
 import { canonicalToolName } from "../tool-name-aliases.js";
+import { parseSkillToolEntry, skillSpecifierRejection } from "../skill-tool-specifier.js";
 export class ActiveSkillScope {
     frames = [];
     push(frame) {
@@ -47,12 +48,19 @@ export function createActiveSkillScopePolicy(opts) {
                 };
             }
             const manifests = frames.flatMap((f) => (f.kind === "manifest" ? [f.manifest] : []));
-            let allowed;
-            for (const m of manifests) {
-                const here = new Set(m.allowTools.map(canonicalToolName));
-                allowed = allowed === undefined ? here : new Set([...allowed].filter((t) => here.has(t)));
-            }
-            if (!allowed || !allowed.has(toolName)) {
+            const perFrame = manifests.map((m) => {
+                const byName = new Map();
+                for (const raw of m.allowTools) {
+                    const entry = parseSkillToolEntry(raw);
+                    const bucket = byName.get(entry.name);
+                    if (bucket)
+                        bucket.push(entry);
+                    else
+                        byName.set(entry.name, [entry]);
+                }
+                return { manifest: m, byName };
+            });
+            if (perFrame.length === 0 || perFrame.some((f) => !f.byName.has(toolName))) {
                 const ids = manifests.map((m) => m.lineageId).join(", ");
                 return {
                     action: "deny",
@@ -60,6 +68,26 @@ export function createActiveSkillScopePolicy(opts) {
                     decisionReason: "safety",
                 };
             }
+            for (const frame of perFrame) {
+                const alternatives = frame.byName.get(toolName) ?? [];
+                const rejections = [];
+                let admitted = false;
+                for (const entry of alternatives) {
+                    const rejection = skillSpecifierRejection(entry, req.args);
+                    if (rejection === undefined) {
+                        admitted = true;
+                        break;
+                    }
+                    rejections.push(rejection);
+                }
+                if (!admitted) {
+                    return {
+                        action: "deny",
+                        reason: `tool "${req.toolName}" is narrowed by skill manifest "${frame.manifest.lineageId}": ${rejections.join("; ")}`,
+                        decisionReason: "safety",
+                    };
+                }
+            }
             const pathConstrainingActive = manifests.some((m) => m.allowPaths && m.allowPaths.length > 0);
             if (pathConstrainingActive && !PATH_WRITE_TOOLS.has(toolName)) {
                 const eff = toolEffects?.get(toolName) ?? "write";

package/dist/core/runner/assemble-result.d.ts

@@ -70,6 +70,7 @@ export interface ResultFlags {
     model?: string;
     unpricedSpend?: boolean;
     rewindNotes?: TaskResult["rewindNotes"];
+    remoteEnvFailures?: TaskResult["remoteEnvFailures"];
     abortedForTimeout: boolean;
     abortedForTurns: boolean;
     abortedLive?: boolean;
@@ -81,10 +82,12 @@ export interface ResultFlags {
     suspendRef?: {
         token: import("../checkpoint-store.js").CheckpointToken;
         gate: import("../checkpoint-store.js").CheckpointGate;
+        restoreMode?: "snapshot" | "park_only";
     };
     reviewRef?: {
         token: import("../checkpoint-store.js").CheckpointToken;
         gate: import("../checkpoint-store.js").CheckpointGate;
+        restoreMode?: "snapshot" | "park_only";
     };
 }
 export declare function errorCodeOf(err: unknown): string | undefined;

package/dist/core/runner/assemble-result.js

@@ -54,6 +54,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     let salvagedOutput;
     let checkpointToken;
     let checkpointGate;
+    let workspaceRestoreMode;
     const isDegenerate = final?.stopReason === "error" && final.errorMessage === DEGENERATE_MESSAGE;
     const isWalltimeCutoff = final?.stopReason === "error" && final.errorMessage === WALLTIME_CUTOFF_MESSAGE;
     if (flags.outputInvalid) {
@@ -105,12 +106,14 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
         status = "suspended";
         checkpointToken = flags.suspendRef.token;
         checkpointGate = flags.suspendRef.gate;
+        workspaceRestoreMode = flags.suspendRef.restoreMode;
     }
     else if (flags.reviewRef) {
         status = "needs_review";
         errorCode = "review.pending";
         checkpointToken = flags.reviewRef.token;
         checkpointGate = flags.reviewRef.gate;
+        workspaceRestoreMode = flags.reviewRef.restoreMode;
     }
     else if (flags.abortedLive || final?.stopReason === "aborted") {
         status = flags.abortedForTimeout ? "timeout" : "failed";
@@ -143,5 +146,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     void _internalCompaction;
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
-    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, checkpointToken, checkpointGate, ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), stats: publicStats };
+    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, checkpointToken, checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: flags.remoteEnvFailures } : {}), stats: publicStats };
 }

package/dist/core/runner/prepare-task.d.ts

@@ -127,12 +127,15 @@ export interface Prepared {
         token?: CheckpointToken;
         gate?: CheckpointGate;
         scope?: string;
+        restoreMode?: "snapshot" | "park_only";
     };
     reviewRef: {
         token?: CheckpointToken;
         gate?: CheckpointGate;
         scope?: string;
+        restoreMode?: "snapshot" | "park_only";
     };
+    remoteEnvFailures: NonNullable<TaskResult["remoteEnvFailures"]>;
     suspendLoopRef: {
         hit: boolean;
     };
@@ -340,4 +343,5 @@ export declare function batchContextAt(messages: AgentMessage[], currentId: stri
     completedCallIds: string[];
 };
 export declare function rebaseWorkspacePath(p: string, fromRaw: string, toRaw: string): string;
+export declare function rebaseWorkspacePathAcross(p: string, froms: readonly string[], to: string): string;
 export declare function prepareTask(spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume?: PrepareResume, internals?: RunInternals, runnerSelf?: Runner): Promise<Prepared>;