@cjhyy/code-shell-core 0.7.0 → 0.7.1

package/dist/context/tool-result-storage.js

@@ -22,7 +22,8 @@
  *     parallel Read results), persist the largest ones first until under.
  */
 import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
 import { logger } from "../logging/logger.js";
 // ─── Tunables ───────────────────────────────────────────────────────
 /** Per-result threshold. Larger than this → persist + replace. */
@@ -77,12 +78,32 @@ function ensureDir(dir) {
     }
 }
 /**
- * Write content to <dir>/<toolUseId>.txt. Idempotent: skips if the file
- * already exists (tool_use_id is a UUID, content is deterministic per id).
+ * Convert an externally supplied tool_use_id to a bounded internal filename.
+ * The original id remains the key in ContentReplacementState/onPersist; it is
+ * never used as a path component.
  */
+export function safeToolResultFilename(toolUseId) {
+    if (toolUseId.length > 256) {
+        throw new RangeError("tool_use_id exceeds the 256 character limit");
+    }
+    if (isAbsolute(toolUseId) ||
+        win32.isAbsolute(toolUseId) ||
+        toolUseId.includes("/") ||
+        toolUseId.includes("\\")) {
+        throw new Error("tool_use_id must not contain a path");
+    }
+    return `${createHash("sha256").update(toolUseId, "utf8").digest("hex")}.txt`;
+}
+/** Write content to the contained hashed path. Idempotent by original id. */
 function persistToFile(dir, toolUseId, content) {
+    const root = resolve(dir);
+    const filename = safeToolResultFilename(toolUseId);
+    const filepath = resolve(root, filename);
+    const rel = relative(root, filepath);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error("tool_result path escaped its storage root");
+    }
     ensureDir(dir);
-    const filepath = join(dir, `${toolUseId}.txt`);
     try {
         // 'wx' = fail if exists. Skipping on collision is correct: same id =
         // same content. Avoids re-writing the same bytes every turn.

package/dist/credentials/access.d.ts

@@ -1,4 +1,4 @@
-import type { Credential, CredentialType } from "./types.js";
+import { type Credential, type CredentialType } from "./types.js";
 import type { SettingsScope } from "../settings/manager.js";
 import type { Transport } from "../protocol/transport.js";
 export type CredentialAccessScope = "full" | "project";
@@ -24,6 +24,15 @@ export interface CredentialAccess {
         scope: CredentialAccessScope;
         purpose: "use" | "mcp";
     }): Promise<string>;
+    /** Resolve only the bearer material needed by an MCP request. */
+    resolveOAuthAccess?(req: {
+        id: string;
+        scope: "full";
+        forceRefresh?: boolean;
+    }): Promise<{
+        accessToken: string;
+        expiresAt?: string;
+    }>;
     materializeCookie?(req: {
         cwd?: string;
         id: string;

package/dist/credentials/access.js

@@ -2,9 +2,11 @@ import { existsSync, readdirSync, rmSync, statSync, writeFileSync } from "node:f
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { credentialAllowsEnvExposure, credentialSecretHint, } from "./types.js";
 import { CredentialStore } from "./store.js";
 import { formatNetscapeCookies, parseCookieJar } from "./cookie-jar.js";
-import { summarizeOAuthCredentialSecret } from "./oauth.js";
+import { parseOAuthCredentialSecret, shouldRefreshOAuthCredential, summarizeOAuthCredentialSecret, } from "./oauth.js";
+import { refreshToken } from "../services/oauth.js";
 const COOKIE_FILE_PREFIX = "codeshell-cred-cookie-";
 const COOKIE_FILE_MAX_AGE_MS = 30 * 60 * 1000;
 let defaultCredentialAccess = null;
@@ -85,6 +87,16 @@ export function createIpcCredentialAccess(transport) {
                 throw new Error(`credential "${req.id}" is unavailable`);
             return result.value;
         },
+        async resolveOAuthAccess(req) {
+            const result = (await request("desktop/oauthAccessResolve", req));
+            if (typeof result?.accessToken !== "string") {
+                throw new Error(`oauth credential "${req.id}" requires login`);
+            }
+            return {
+                accessToken: result.accessToken,
+                expiresAt: typeof result.expiresAt === "string" ? result.expiresAt : undefined,
+            };
+        },
         async materializeCookie(req) {
             const result = (await request("desktop/credentialMaterializeCookie", req));
             if (typeof result?.cookiesFile !== "string" || typeof result.count !== "number") {
@@ -106,8 +118,9 @@ function toMetadata(cred) {
     const { secret: _secret, ...rest } = cred;
     return {
         ...rest,
+        ...(credentialAllowsEnvExposure(cred.type) ? {} : { exposeAsEnv: undefined }),
         hasSecret: available,
-        secretHint: available ? (secret.length > 4 ? `****${secret.slice(-4)}` : "****") : undefined,
+        secretHint: available ? credentialSecretHint(cred.type, secret) : undefined,
         ...(cred.type === "oauth" ? { oauthStatus: summarizeOAuthCredentialSecret(secret) } : {}),
     };
 }
@@ -129,6 +142,8 @@ export const localCredentialAccess = {
         const out = {};
         const creds = storeFor(cwd).list(scope);
         for (const cred of creds) {
+            if (!credentialAllowsEnvExposure(cred.type))
+                continue;
             const name = cred.exposeAsEnv?.trim();
             if (name && isCredentialSecretAvailable(cred.secret))
                 out[name] = cred.secret;
@@ -142,6 +157,9 @@ export const localCredentialAccess = {
         }
         return cred.secret;
     },
+    async resolveOAuthAccess(req) {
+        return resolveLocalOAuthAccess(req.id, Boolean(req.forceRefresh));
+    },
     async materializeCookie(req) {
         const cred = storeFor(req.cwd).resolve(req.id, req.scope);
         if (!cred || cred.type !== "cookie" || !isCredentialSecretAvailable(cred.secret)) {
@@ -150,6 +168,62 @@ export const localCredentialAccess = {
         return materializeCookieSecret(cred.id, cred.secret);
     },
 };
+const localOAuthRefreshes = new Map();
+async function resolveLocalOAuthAccess(id, forceRefresh) {
+    const store = new CredentialStore(undefined);
+    const cred = store.resolve(id, "full");
+    if (!cred || cred.type !== "oauth" || !isCredentialSecretAvailable(cred.secret)) {
+        throw new Error(`oauth credential "${id}" requires login`);
+    }
+    const parsed = parseOAuthCredentialSecret(cred.secret);
+    const decision = shouldRefreshOAuthCredential(parsed);
+    if (!forceRefresh && decision === "no") {
+        return { accessToken: parsed.accessToken, expiresAt: parsed.expiresAt };
+    }
+    if (!parsed.refreshToken || !parsed.tokenEndpoint || !parsed.clientId) {
+        throw new Error(`oauth credential "${id}" requires login`);
+    }
+    const inflight = localOAuthRefreshes.get(id);
+    if (inflight)
+        return inflight;
+    const pending = (async () => {
+        const latestCred = store.resolve(id, "full");
+        if (!latestCred || latestCred.type !== "oauth" || !latestCred.secret) {
+            throw new Error(`oauth credential "${id}" requires login`);
+        }
+        const latest = parseOAuthCredentialSecret(latestCred.secret);
+        if (!forceRefresh && shouldRefreshOAuthCredential(latest) === "no") {
+            return { accessToken: latest.accessToken, expiresAt: latest.expiresAt };
+        }
+        if (!latest.refreshToken || !latest.tokenEndpoint || !latest.clientId) {
+            throw new Error(`oauth credential "${id}" requires login`);
+        }
+        const tokens = await refreshToken({
+            clientId: latest.clientId,
+            clientSecret: latest.clientSecret,
+            tokenEndpoint: latest.tokenEndpoint,
+            authorizationEndpoint: "",
+            scopes: latest.scopes,
+            resource: latest.resource,
+        }, latest.refreshToken);
+        const next = {
+            ...latest,
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken ?? latest.refreshToken,
+            expiresAt: tokens.expiresAt ? new Date(tokens.expiresAt).toISOString() : undefined,
+            tokenType: tokens.tokenType,
+            scope: tokens.scope ?? latest.scope,
+        };
+        store.save("user", {
+            ...latestCred,
+            secret: JSON.stringify(next),
+            meta: { ...latestCred.meta, lastRefreshAt: new Date().toISOString() },
+        });
+        return { accessToken: next.accessToken, expiresAt: next.expiresAt };
+    })().finally(() => localOAuthRefreshes.delete(id));
+    localOAuthRefreshes.set(id, pending);
+    return pending;
+}
 export function materializeCookieSecret(credentialId, secret) {
     const jar = parseCookieJar(secret);
     if (jar.length === 0)

package/dist/credentials/index.d.ts

@@ -2,8 +2,9 @@ export { CredentialStore } from "./store.js";
 export type { CredentialScope, MaskedCredential } from "./store.js";
 export { type EncryptionCipher, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./cipher.js";
 export { getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, isCredentialSecretAvailable, materializeCookieSecret, type CredentialAccess, type CredentialAccessScope, type CredentialMetadata, type CredentialSnapshot, type CredentialSnapshotEntry, } from "./access.js";
-export type { Credential, CredentialType, CredentialStoreFile, OAuthCredentialPublicStatus, OAuthCredentialSecret, } from "./types.js";
-export { buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, summarizeOAuthCredentialSecret, type OAuthClockOptions, type OAuthRefreshHandler, type OAuthRefreshRequest, } from "./oauth.js";
+export type { Credential, CredentialType, CredentialStoreFile, OAuthCredentialPublicStatus, OAuthCredentialSecret, OAuthTokenResponse, } from "./types.js";
+export { credentialAllowsEnvExposure, credentialSecretHint } from "./types.js";
+export { buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, mergeOAuthTokenResponse, shouldRefreshOAuthCredential, summarizeOAuthCredentialSecret, type OAuthClockOptions, type OAuthRefreshHandler, type OAuthRefreshRequest, } from "./oauth.js";
 export { formatNetscapeCookies, parseCookieJar, type CookieLike } from "./cookie-jar.js";
 export { useCredentialToolDef, useCredentialToolDefFor, useCredentialTool, sweepStaleCredentialCookies, } from "./use-credential-tool.js";
 export { credentialUseGate } from "./use-gate.js";

package/dist/credentials/index.js

@@ -1,7 +1,8 @@
 export { CredentialStore } from "./store.js";
 export { PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./cipher.js";
 export { getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, isCredentialSecretAvailable, materializeCookieSecret, } from "./access.js";
-export { buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, summarizeOAuthCredentialSecret, } from "./oauth.js";
+export { credentialAllowsEnvExposure, credentialSecretHint } from "./types.js";
+export { buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, mergeOAuthTokenResponse, shouldRefreshOAuthCredential, summarizeOAuthCredentialSecret, } from "./oauth.js";
 export { formatNetscapeCookies, parseCookieJar } from "./cookie-jar.js";
 export { useCredentialToolDef, useCredentialToolDefFor, useCredentialTool, sweepStaleCredentialCookies, } from "./use-credential-tool.js";
 export { credentialUseGate } from "./use-gate.js";

package/dist/credentials/oauth.d.ts

@@ -1,4 +1,4 @@
-import type { OAuthCredentialPublicStatus, OAuthCredentialSecret } from "./types.js";
+import type { OAuthCredentialPublicStatus, OAuthCredentialSecret, OAuthTokenResponse } from "./types.js";
 export interface OAuthClockOptions {
     now?: number | (() => number);
     skewMs?: number;
@@ -14,6 +14,11 @@ export interface OAuthRefreshRequest {
 }
 export type OAuthRefreshHandler = (req: OAuthRefreshRequest) => Promise<OAuthCredentialSecret>;
 export declare function parseOAuthCredentialSecret(secret: string): OAuthCredentialSecret;
+/** Merge and validate an OAuth token endpoint response without losing rotation state. */
+export declare function mergeOAuthTokenResponse(previous: OAuthCredentialSecret | undefined, response: OAuthTokenResponse, opts?: {
+    now?: number;
+}): OAuthCredentialSecret;
+export declare function shouldRefreshOAuthCredential(secret: OAuthCredentialSecret, opts?: OAuthClockOptions): "no" | "refresh" | "login_required";
 export declare function isOAuthAccessTokenExpired(secret: Pick<OAuthCredentialSecret, "accessToken" | "expiresAt">, opts?: OAuthClockOptions): boolean;
 export declare function oauthCredentialStatus(secret: Pick<OAuthCredentialSecret, "accessToken" | "expiresAt">, opts?: OAuthClockOptions): Pick<OAuthCredentialPublicStatus, "state" | "expiresAt" | "expiresInMs">;
 export declare function buildOAuthRefreshRequest(credentialId: string, secret: OAuthCredentialSecret): OAuthRefreshRequest | undefined;

package/dist/credentials/oauth.js

@@ -15,6 +15,17 @@ function optionalStringArray(value) {
     const out = value.filter((x) => typeof x === "string" && x.length > 0);
     return out.length > 0 ? out : undefined;
 }
+function optionalFiniteNumber(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error("OAuth token response expires_in must be a finite non-negative number");
+    }
+    if (value < 0) {
+        throw new Error("OAuth token response expires_in must be a finite non-negative number");
+    }
+    return value;
+}
 function parseExpiresAt(value) {
     if (!value)
         return undefined;
@@ -45,19 +56,73 @@ export function parseOAuthCredentialSecret(secret) {
     }
     const expiresAt = optionalString(raw.expiresAt);
     parseExpiresAt(expiresAt);
+    const tokenType = optionalString(raw.tokenType);
+    if (tokenType && tokenType.toLowerCase() !== "bearer") {
+        throw new Error("OAuth credential tokenType must be Bearer");
+    }
     return {
         version: raw.version === 1 ? 1 : undefined,
         accessToken,
         refreshToken: optionalString(raw.refreshToken),
         expiresAt,
-        tokenType: optionalString(raw.tokenType),
+        tokenType,
         scope: optionalString(raw.scope),
         scopes: optionalStringArray(raw.scopes),
         tokenEndpoint: optionalString(raw.tokenEndpoint),
         clientId: optionalString(raw.clientId),
         clientSecret: optionalString(raw.clientSecret),
+        issuer: optionalString(raw.issuer),
+        resource: optionalString(raw.resource),
+        revocationEndpoint: optionalString(raw.revocationEndpoint),
+        clientRegistration: raw.clientRegistration &&
+            typeof raw.clientRegistration === "object" &&
+            !Array.isArray(raw.clientRegistration) &&
+            optionalString(raw.clientRegistration.clientId)
+            ? {
+                clientId: optionalString(raw.clientRegistration.clientId),
+                clientSecret: optionalString(raw.clientRegistration.clientSecret),
+                clientIdIssuedAt: typeof raw.clientRegistration.clientIdIssuedAt ===
+                    "number"
+                    ? raw.clientRegistration.clientIdIssuedAt
+                    : undefined,
+                clientSecretExpiresAt: typeof raw.clientRegistration.clientSecretExpiresAt ===
+                    "number"
+                    ? raw.clientRegistration
+                        .clientSecretExpiresAt
+                    : undefined,
+            }
+            : undefined,
     };
 }
+/** Merge and validate an OAuth token endpoint response without losing rotation state. */
+export function mergeOAuthTokenResponse(previous, response, opts = {}) {
+    const accessToken = optionalString(response.access_token);
+    if (!accessToken)
+        throw new Error("OAuth token response must include access_token");
+    const tokenType = optionalString(response.token_type) ?? "Bearer";
+    if (tokenType.toLowerCase() !== "bearer") {
+        throw new Error(`OAuth token response token_type must be Bearer`);
+    }
+    const expiresIn = optionalFiniteNumber(response.expires_in);
+    const now = opts.now ?? Date.now();
+    const responseScope = optionalString(response.scope);
+    const refreshToken = optionalString(response.refresh_token) ?? previous?.refreshToken;
+    return {
+        ...previous,
+        version: 1,
+        accessToken,
+        refreshToken,
+        expiresAt: expiresIn === undefined ? undefined : new Date(now + expiresIn * 1000).toISOString(),
+        tokenType: "Bearer",
+        scope: responseScope ?? previous?.scope,
+        scopes: responseScope ? responseScope.split(/\s+/).filter(Boolean) : previous?.scopes,
+    };
+}
+export function shouldRefreshOAuthCredential(secret, opts = {}) {
+    if (!isOAuthAccessTokenExpired(secret, opts))
+        return "no";
+    return secret.refreshToken && secret.tokenEndpoint ? "refresh" : "login_required";
+}
 export function isOAuthAccessTokenExpired(secret, opts = {}) {
     const expiresAtMs = parseExpiresAt(secret.expiresAt);
     if (expiresAtMs === undefined)

package/dist/credentials/store.d.ts

@@ -1,4 +1,4 @@
-import type { Credential } from "./types.js";
+import { type Credential } from "./types.js";
 import { type EncryptionCipher } from "./cipher.js";
 export type CredentialScope = "user" | "project";
 export interface MaskedCredential extends Omit<Credential, "secret"> {

package/dist/credentials/store.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
+import { credentialAllowsEnvExposure, credentialSecretHint, } from "./types.js";
 import { getDefaultCredentialCipher } from "./cipher.js";
 import { logger } from "../logging/logger.js";
 import { summarizeOAuthCredentialSecret } from "./oauth.js";
@@ -93,11 +94,14 @@ export class CredentialStore {
     /** Upsert by id within a scope. */
     save(scope, cred) {
         const file = this.read(scope);
+        const safeCredential = credentialAllowsEnvExposure(cred.type)
+            ? cred
+            : { ...cred, exposeAsEnv: undefined };
         const idx = file.credentials.findIndex((c) => c.id === cred.id);
         if (idx >= 0)
-            file.credentials[idx] = cred;
+            file.credentials[idx] = safeCredential;
         else
-            file.credentials.push(cred);
+            file.credentials.push(safeCredential);
         this.write(scope, file);
     }
     /**
@@ -110,7 +114,12 @@ export class CredentialStore {
         const idx = file.credentials.findIndex((c) => c.id === id);
         if (idx < 0)
             return;
-        file.credentials[idx] = { ...file.credentials[idx], ...fields };
+        const current = file.credentials[idx];
+        file.credentials[idx] = {
+            ...current,
+            ...fields,
+            ...(credentialAllowsEnvExposure(current.type) ? {} : { exposeAsEnv: undefined }),
+        };
         this.write(scope, file);
     }
     remove(scope, id) {
@@ -161,6 +170,8 @@ export class CredentialStore {
             : [this.read("user").credentials, this.read("project").credentials];
         for (const layer of layers) {
             for (const c of layer) {
+                if (!credentialAllowsEnvExposure(c.type))
+                    continue;
                 const name = c.exposeAsEnv?.trim();
                 if (name && typeof c.secret === "string" && c.secret.length > 0) {
                     out[name] = c.secret;
@@ -174,11 +185,9 @@ export class CredentialStore {
             const { secret, ...rest } = c;
             return {
                 ...rest,
+                ...(credentialAllowsEnvExposure(c.type) ? {} : { exposeAsEnv: undefined }),
                 hasSecret: typeof secret === "string" && secret.length > 0,
-                // Reveal at most the last 4 chars — and ONLY when the secret is longer
-                // than 4, so those chars aren't the whole secret. `"ab".slice(-4)` is
-                // "ab", so a short secret would otherwise leak in full through the hint.
-                secretHint: secret ? (secret.length > 4 ? `****${secret.slice(-4)}` : "****") : undefined,
+                secretHint: credentialSecretHint(c.type, secret),
                 ...(c.type === "oauth" ? { oauthStatus: summarizeOAuthCredentialSecret(secret) } : {}),
             };
         });

package/dist/credentials/types.d.ts

@@ -4,6 +4,14 @@
  *   (用户主动按域拓取存,支持同域多账号),见 credential-use-gate 设计稿。
  */
 export type CredentialType = "token" | "link" | "cookie" | "oauth";
+/**
+ * Only established single-value credentials may be copied into a process
+ * environment. OAuth records and cookie jars are structured multi-secret
+ * values and must remain behind the credential resolver boundary.
+ */
+export declare function credentialAllowsEnvExposure(type: CredentialType): boolean;
+/** Build a renderer-safe hint without deriving bytes from structured JSON. */
+export declare function credentialSecretHint(type: CredentialType, secret: string | undefined): string | undefined;
 export interface OAuthCredentialSecret {
     /** Schema version for the JSON stored in Credential.secret. */
     version?: 1;
@@ -25,6 +33,26 @@ export interface OAuthCredentialSecret {
     clientId?: string;
     /** Optional confidential client secret, if the integration requires it. */
     clientSecret?: string;
+    /** OAuth issuer discovered for the MCP protected resource. */
+    issuer?: string;
+    /** RFC 8707 resource indicator used for authorization/token requests. */
+    resource?: string;
+    /** Optional endpoint used to revoke the refresh/access token on logout. */
+    revocationEndpoint?: string;
+    /** Dynamic registration result, retained with the encrypted secret. */
+    clientRegistration?: {
+        clientId: string;
+        clientSecret?: string;
+        clientIdIssuedAt?: number;
+        clientSecretExpiresAt?: number;
+    };
+}
+export interface OAuthTokenResponse {
+    access_token: unknown;
+    refresh_token?: unknown;
+    expires_in?: unknown;
+    token_type?: unknown;
+    scope?: unknown;
 }
 export interface OAuthCredentialPublicStatus {
     state: "valid" | "expired" | "missing" | "invalid";
@@ -84,6 +112,11 @@ export interface Credential {
         switchMode?: "clear" | "merge";
         /** OAuth provider/integration id, e.g. "figma". */
         oauthProvider?: string;
+        /** MCP server identity associated with an advanced OAuth login. */
+        mcpServerName?: string;
+        mcpServerUrl?: string;
+        issuer?: string;
+        resource?: string;
         /** OAuth authorization endpoint, used by UI/login launchers. */
         authUrl?: string;
         /** OAuth token endpoint, duplicated from secret for non-secret UI display. */
@@ -92,8 +125,12 @@ export interface Credential {
         clientId?: string;
         /** OAuth scopes requested for this credential. */
         scopes?: string[];
-        /** Last successful refresh time; refresh wiring is reserved for a later step. */
+        revocationEndpoint?: string;
+        /** Last successful refresh time. */
         lastRefreshAt?: string;
+        /** Normalized refresh diagnostics; never contains endpoint response bodies. */
+        lastRefreshFailedAt?: string;
+        lastRefreshErrorCode?: "invalid_grant" | "network" | "server_error" | "invalid_response";
     };
 }
 export interface CredentialStoreFile {

package/dist/credentials/types.js

@@ -1 +1,16 @@
-export {};
+/**
+ * Only established single-value credentials may be copied into a process
+ * environment. OAuth records and cookie jars are structured multi-secret
+ * values and must remain behind the credential resolver boundary.
+ */
+export function credentialAllowsEnvExposure(type) {
+    return type === "token" || type === "link";
+}
+/** Build a renderer-safe hint without deriving bytes from structured JSON. */
+export function credentialSecretHint(type, secret) {
+    if (!secret)
+        return undefined;
+    if (type === "oauth" || type === "cookie")
+        return "****";
+    return secret.length > 4 ? `****${secret.slice(-4)}` : "****";
+}

package/dist/engine/engine.d.ts

@@ -4,10 +4,11 @@
 import type { LLMConfig, StreamCallback } from "../types.js";
 import { ToolRegistry } from "../tool-system/registry.js";
 import { type BuiltinToolFn } from "../tool-system/builtin/index.js";
+import { type ApprovalRouter } from "../tool-system/permission.js";
 import { HookRegistry } from "../hooks/registry.js";
 import { type GoalConfig, type GoalExtension } from "./goal.js";
 import { type CompactStrategy } from "../context/manager.js";
-import { SessionManager } from "../session/session-manager.js";
+import { SessionManager, type ForkSessionOptions, type ForkSessionResult } from "../session/session-manager.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
 import type { CapabilityOverride } from "../settings/schema.js";
 import { type FeatureFlagName } from "../settings/feature-flags.js";
@@ -34,6 +35,38 @@ export interface EnqueueSteerResult {
     accepted: boolean;
     id: string;
 }
+interface EngineRunOptions {
+    cwd?: string;
+    onStream?: StreamCallback;
+    signal?: AbortSignal;
+    sessionId?: string;
+    /** Immutable permission context for this run only. Omitted uses Engine config. */
+    permissionMode?: NonNullable<EngineConfig["permissionMode"]>;
+    /** Immutable plan context for this run only. Omitted follows permissionMode. */
+    planMode?: boolean;
+    /** Protocol connection's approval owner router for this run. */
+    approvalRouter?: ApprovalRouter;
+    /**
+     * Goal mode for this run: the engine registers a GoalStopHook so the
+     * turn loop runs until the session model judges this goal met. Falls
+     * back to config.goal. Orthogonal to permissionMode. Accepts a raw
+     * string or a full GoalConfig; normalized once at the run boundary.
+     */
+    goal?: string | GoalConfig;
+    /**
+     * Marks this turn's task as a SYNTHETIC system-reminder injection (e.g. a
+     * background-job completion notification the server re-injects to wake an
+     * idle session) rather than the user's own input. The task is still sent
+     * to the model as a `role:"user"` message, but it is persisted with an
+     * `injected` flag so the disk reader skips rendering it as a user bubble
+     * on replay (matching the live UI, which shows only the assistant reply).
+     */
+    injected?: boolean;
+    /** Stable id for this user-intent, used to make duplicate submits idempotent. */
+    clientMessageId?: string;
+    /** Structured input attachments. Legacy `<codeshell-image>` blocks remain supported. */
+    attachments?: InputAttachmentMeta[];
+}
 export { diskDefaultsFrom, type DiskDefaultPatch } from "../settings/disk-defaults.js";
 /**
  * Resolve the LLM config for a spawned child Engine.
@@ -122,6 +155,8 @@ export declare class Engine {
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     readonly runtime: EngineRuntime | null;
     private readonly sandboxCache;
+    private readonly interactiveBackends;
+    private activeApprovalRouter;
     /** Active permission mode for this Engine instance. */
     permissionMode: NonNullable<EngineConfig["permissionMode"]>;
     /** True when permissionMode === "plan". */
@@ -188,6 +223,19 @@ export declare class Engine {
      * Null when idle; set at run start, cleared in run's finally.
      */
     private activeRunSession;
+    /**
+     * Same-instance run guard. Engine owns single-valued live controls and one
+     * HookRegistry, so a second run must not enter until the first has completed
+     * all state persistence and end hooks. This prevents handle contamination and
+     * whole-state saveState overlap only within this Engine instance. It does not
+     * coordinate different Engine instances sharing a sessionId, Workers, or
+     * processes; session-level locking/CAS for those cases is a separate finding.
+     */
+    private runInProgress;
+    /** Permission update requested while runInProgress. Applied in run() finally. */
+    private pendingPermissionMode;
+    /** Plan update paired with pendingPermissionMode for one atomic boundary apply. */
+    private pendingPlanMode;
     /** Public accessor so UI/clients can read the resolved per-model window. */
     get maxContextTokens(): number;
     private resolveMaxContextTokens;
@@ -306,35 +354,14 @@ export declare class Engine {
      * against a blank session. A stat probe, not a load.
      */
     sessionExistsOnDisk(sessionId: string): boolean;
+    forkSession(sourceSessionId: string, options?: ForkSessionOptions): ForkSessionResult;
     /**
-     * Run a task from start to finish.
-     */
-    run(task: string, options?: {
-        cwd?: string;
-        onStream?: StreamCallback;
-        signal?: AbortSignal;
-        sessionId?: string;
-        /**
-         * Goal mode for this run: the engine registers a GoalStopHook so the
-         * turn loop runs until the session model judges this goal met. Falls
-         * back to config.goal. Orthogonal to permissionMode. Accepts a raw
-         * string or a full GoalConfig; normalized once at the run boundary.
-         */
-        goal?: string | GoalConfig;
-        /**
-         * Marks this turn's task as a SYNTHETIC system-reminder injection (e.g. a
-         * background-job completion notification the server re-injects to wake an
-         * idle session) rather than the user's own input. The task is still sent
-         * to the model as a `role:"user"` message, but it is persisted with an
-         * `injected` flag so the disk reader skips rendering it as a user bubble
-         * on replay (matching the live UI, which shows only the assistant reply).
-         */
-        injected?: boolean;
-        /** Stable id for this user-intent, used to make duplicate submits idempotent. */
-        clientMessageId?: string;
-        /** Structured input attachments. Legacy `<codeshell-image>` blocks remain supported. */
-        attachments?: InputAttachmentMeta[];
-    }): Promise<EngineResult>;
+     * Run a task from start to finish. Rejects immediately when this Engine
+     * instance already has a run in progress; hosts that want queueing own that
+     * policy (for example ChatSession's FIFO queue).
+     */
+    run(task: string, options?: EngineRunOptions): Promise<EngineResult>;
+    private runExclusive;
     /**
      * Run the end-of-session memory pipeline as a fire-and-forget background
      * task. Extracts durable memories from the transcript, saves a session
@@ -499,12 +526,14 @@ export declare class Engine {
     readSetting(key: string): unknown;
     private buildPermissionConfig;
     /**
-     * Switch permission mode at runtime. Takes effect immediately for any
-     * in-flight ToolExecutor (which holds a reference to the same classifier),
-     * and the new mode is used for any subsequent run() calls.
+     * Switch permission mode at runtime. Idle updates apply immediately; busy
+     * updates are committed atomically when the current run settles, so its
+     * classifier and ToolContext retain the immutable start-of-run snapshot.
      * Session-only — does not persist to settings.
      */
     setPermissionMode(mode: NonNullable<EngineConfig["permissionMode"]>): void;
+    private applyPermissionState;
+    private applyPendingPermissionState;
     getPermissionMode(): NonNullable<EngineConfig["permissionMode"]>;
     /**
      * Extend the in-flight run's turn ceiling and/or goal budgets (TODO 3.1 —