@cjhyy/code-shell-core 0.8.13 → 0.9.0

package/dist/protocol/session-workspace-rpc.js

@@ -0,0 +1,171 @@
+import { canonicalKey } from "../workspace/canonical-key.js";
+import { validateWorkspaceContext, workspacePrimaryRoot, } from "../workspace/workspace-context.js";
+import { createErrorResponse, createResponse, ErrorCodes, } from "./types.js";
+/** Protocol boundary for Session workspace ownership and root migration. */
+export class SessionWorkspaceRpcHandlers {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    release(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        const manager = this.deps.getChatManager();
+        if (manager) {
+            const session = manager.get(params.sessionId);
+            if (!session) {
+                this.deps.transport.send(createResponse(req.id, { ok: true, workspace: null }));
+                return;
+            }
+            const workspace = session.engine.releaseSessionWorkspace?.(params.sessionId) ?? null;
+            this.deps.transport.send(createResponse(req.id, { ok: true, workspace }));
+            return;
+        }
+        const workspace = this.deps.getLegacyEngine()?.releaseSessionWorkspace?.(params.sessionId) ?? null;
+        this.deps.transport.send(createResponse(req.id, { ok: true, workspace }));
+    }
+    set(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        if (!params.workspace ||
+            typeof params.workspace !== "object" ||
+            typeof params.workspace.root !== "string" ||
+            params.workspace.root.length === 0 ||
+            (params.workspace.kind !== "main" && params.workspace.kind !== "worktree")) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid workspace is required"));
+            return;
+        }
+        const manager = this.deps.getChatManager();
+        const engine = manager ? manager.get(params.sessionId)?.engine : this.deps.getLegacyEngine();
+        if (!engine) {
+            this.deps.transport.send(createResponse(req.id, { ok: true, workspace: null }));
+            return;
+        }
+        const workspace = engine.setSessionWorkspace?.(params.sessionId, params.workspace);
+        this.deps.transport.send(createResponse(req.id, {
+            ok: workspace !== undefined && workspace !== null,
+            workspace: workspace ?? null,
+        }));
+    }
+    async migrateMainRoot(req) {
+        const params = (req.params ?? {});
+        if (!validMigrationParams(params)) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid Session root migration is required"));
+            return;
+        }
+        let workspaceContext;
+        try {
+            workspaceContext = validateWorkspaceContext(params.workspaceContext);
+            const primary = workspacePrimaryRoot(workspaceContext);
+            if (workspaceContext.projectId !== params.project.projectId ||
+                workspaceContext.sessionMainRootId !== params.project.mainRootId ||
+                canonicalKey(primary.path) !== canonicalKey(params.mainRoot)) {
+                throw new Error("migration target authority does not match the requested root");
+            }
+        }
+        catch (error) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, error instanceof Error ? error.message : "valid target authority is required"));
+            return;
+        }
+        const manager = this.deps.getChatManager();
+        let engine;
+        let residentSession;
+        if (manager) {
+            const ownership = manager.beginSessionMigration(params.sessionId, params.ownershipToken);
+            if (ownership.status === "not-resident") {
+                this.deps.transport.send(createResponse(req.id, {
+                    status: "not-resident",
+                    ownershipToken: ownership.ownershipToken,
+                }));
+                return;
+            }
+            if (ownership.status === "failed") {
+                this.deps.transport.send(createResponse(req.id, {
+                    status: "failed",
+                    error: ownership.error,
+                }));
+                return;
+            }
+            residentSession = ownership.session;
+            engine = residentSession.engine;
+        }
+        else {
+            engine = this.deps.getLegacyEngine();
+        }
+        if (!engine) {
+            this.deps.transport.send(createResponse(req.id, {
+                status: "failed",
+                error: "Session migration owner is unavailable",
+            }));
+            return;
+        }
+        try {
+            const workspace = residentSession
+                ? await manager.migrateResidentSessionMainRoot(params.sessionId, {
+                    project: params.project,
+                    mainRoot: params.mainRoot,
+                    workspaceContext,
+                    projectTrusted: params.projectTrusted,
+                })
+                : engine.migrateSessionMainRoot?.(params.sessionId, params.project, params.mainRoot);
+            if (!workspace)
+                throw new Error(`Session ${params.sessionId} migration was not committed`);
+            if (residentSession) {
+                this.deps.rememberSessionSlice(params.sessionId, {
+                    ...(this.deps.getLastSlice(params.sessionId) ?? {}),
+                    cwd: params.mainRoot,
+                    workspaceContext,
+                    projectTrusted: params.projectTrusted,
+                });
+                this.deps.wireInteractiveSession(residentSession, params.sessionId);
+            }
+            this.deps.transport.send(createResponse(req.id, {
+                status: "migrated",
+                workspace,
+            }));
+        }
+        catch (error) {
+            this.deps.transport.send(createResponse(req.id, {
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    completeMainRootMigration(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" ||
+            params.sessionId.length === 0 ||
+            typeof params.ownershipToken !== "string" ||
+            params.ownershipToken.length === 0 ||
+            params.ownershipToken.length > 128) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "valid migration claim is required"));
+            return;
+        }
+        if (!this.deps.getChatManager()?.completeSessionMigration(params.sessionId, params.ownershipToken)) {
+            this.deps.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "migration claim is not active"));
+            return;
+        }
+        this.deps.transport.send(createResponse(req.id, { released: true }));
+    }
+}
+function validMigrationParams(params) {
+    return (typeof params.sessionId === "string" &&
+        params.sessionId.length > 0 &&
+        Boolean(params.project) &&
+        typeof params.project?.projectId === "string" &&
+        params.project.projectId.length > 0 &&
+        typeof params.project.mainRootId === "string" &&
+        params.project.mainRootId.length > 0 &&
+        typeof params.mainRoot === "string" &&
+        params.mainRoot.length > 0 &&
+        typeof params.projectTrusted === "boolean" &&
+        typeof params.ownershipToken === "string" &&
+        params.ownershipToken.length > 0 &&
+        params.ownershipToken.length <= 128);
+}

package/dist/protocol/types.d.ts

@@ -7,7 +7,7 @@
  *   Server → Client: notifications (stream events, approval requests)
  *   Server → Client: responses (results of requests)
  */
-import type { InputAttachmentMeta, LegacyPetWorkspaceOption, LegacyPetWorkDelegation, StreamEvent, TokenUsage, TerminalReason, ApprovalRequest, ApprovalResult, PermissionMode, SessionForkLineage, SessionKind, SessionWorkspace } from "../types.js";
+import type { InputAttachmentMeta, LegacyPetWorkspaceOption, LegacyPetWorkDelegation, StreamEvent, TokenUsage, TerminalReason, ApprovalRequest, ApprovalResult, PermissionMode, SessionForkLineage, SessionKind, SessionProjectBinding, SessionWorkspace } from "../types.js";
 import type { RunBehaviorMode } from "../engine/run-types.js";
 import type { SessionMessageTarget } from "../session/session-message.js";
 export type PendingApprovalKind = "tool_approval" | "ask_user" | "internal";
@@ -69,6 +69,12 @@ export type { InputAttachmentKind, InputAttachmentOrigin, InputAttachmentMeta }
 export interface RunParams {
     sessionId: string;
     task: string;
+    /** Renderer/mobile project hint. Desktop Main resolves it to authoritative roots. */
+    projectId?: string;
+    /** Renderer/mobile root hint. Desktop Main resolves it within projectId. */
+    rootId?: string;
+    /** Trusted host-injected roots. Desktop Main strips any renderer/mobile supplied value. */
+    workspaceContext?: import("../workspace/workspace-context.js").WorkspaceContext;
     /**
      * Optional user-facing representation of `task`. The model still receives
      * the full task, while session feeds and transcript replay show this text.
@@ -87,6 +93,8 @@ export interface RunParams {
     archiveBeforeCurrentTurn?: {
         fromClientMessageId?: string;
         segmentId?: string;
+        /** Host-authored replacement for the archived span; skips the summarizer. */
+        summary?: string;
     };
     /** Desktop host ownership generation for process-local Quick Chat runs. */
     quickChatClaimId?: string;
@@ -271,6 +279,40 @@ export interface SetWorkspaceParams {
     sessionId: string;
     workspace: SessionWorkspace;
 }
+/** Atomically rebind every main-root field through the live Session owner. */
+export interface MigrateSessionMainRootParams {
+    sessionId: string;
+    project: SessionProjectBinding;
+    mainRoot: string;
+    /** Main-resolved target authority used to construct the replacement Engine. */
+    workspaceContext: import("../workspace/workspace-context.js").WorkspaceContext;
+    /** Trust decision for the target main root, resolved by the host trust store. */
+    projectTrusted: boolean;
+    /** Main-minted nonce used to fence and later release a non-resident handoff. */
+    ownershipToken: string;
+}
+/**
+ * Proven ownership result for a Session main-root migration.
+ *
+ * `not-resident` is the only result that authorizes a durable host fallback.
+ * The ownership token fences a concurrent getOrCreate until the host reports
+ * that its atomic disk commit (or failed attempt) has finished.
+ */
+export type MigrateSessionMainRootResult = {
+    status: "migrated";
+    workspace: SessionWorkspace;
+} | {
+    status: "not-resident";
+    ownershipToken: string;
+} | {
+    status: "failed";
+    error: string;
+};
+/** Release the non-resident ownership fence after Main's durable attempt. */
+export interface CompleteSessionMainRootMigrationParams {
+    sessionId: string;
+    ownershipToken: string;
+}
 /** Inject context into a session transcript. */
 export interface InjectParams {
     sessionId: string;
@@ -498,6 +540,10 @@ export declare const Methods: {
     readonly ReleaseWorkspace: "agent/releaseWorkspace";
     /** Persist a workspace pointer through the live session owner. */
     readonly SetWorkspace: "agent/setWorkspace";
+    /** Atomically migrate a Session's main-root authority through its live owner. */
+    readonly MigrateSessionMainRoot: "agent/migrateSessionMainRoot";
+    /** Release a non-resident migration fence after Main's durable attempt. */
+    readonly CompleteSessionMainRootMigration: "agent/completeSessionMainRootMigration";
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     readonly GoalExtend: "agent/goalExtend";
     /** Edit or pause/resume a session's persisted goal. */

package/dist/protocol/types.js

@@ -46,6 +46,10 @@ export const Methods = {
     ReleaseWorkspace: "agent/releaseWorkspace",
     /** Persist a workspace pointer through the live session owner. */
     SetWorkspace: "agent/setWorkspace",
+    /** Atomically migrate a Session's main-root authority through its live owner. */
+    MigrateSessionMainRoot: "agent/migrateSessionMainRoot",
+    /** Release a non-resident migration fence after Main's durable attempt. */
+    CompleteSessionMainRootMigration: "agent/completeSessionMainRootMigration",
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     GoalExtend: "agent/goalExtend",
     /** Edit or pause/resume a session's persisted goal. */

package/dist/session/session-manager.d.ts

@@ -118,6 +118,8 @@ export declare class SessionManager {
      * fallback when a worktree is unavailable or is being released.
      */
     readSessionMainRoot(sessionId: string): string | undefined;
+    /** Cheap durable project-binding read; absent for legacy/no-repo Sessions. */
+    readSessionProjectBinding(sessionId: string): import("../types.js").SessionProjectBinding | undefined;
     /** Cheap durable classification read. Legacy sessions are ordinary work sessions. */
     readSessionKind(sessionId: string): SessionKind | undefined;
     /** Cheap durable digital-human binding read. */
@@ -154,6 +156,22 @@ export declare class SessionManager {
      * is a safety pointer and resume breadcrumb.
      */
     setSessionWorkspace(sessionId: string, workspace: SessionWorkspace): number;
+    /**
+     * Commit a Session main-root migration as one state.json replacement.
+     *
+     * `cwd`, the durable project binding, and the execution workspace are one
+     * consistency unit: exposing any subset would let a resumed run combine the
+     * old authority with a new path. Derived availability such as dir_missing is
+     * deliberately absent from this patch and is recomputed by the host.
+     */
+    migrateSessionMainRoot(sessionId: string, project: import("../types.js").SessionProjectBinding, mainRoot: string): number;
+    /**
+     * Commit a host-owned offline migration only if the durable snapshot Main
+     * just revalidated is still current. Unlike the ordinary field-level writer,
+     * this must not retry onto a newer revision: a new writer means ownership is
+     * no longer provably unchanged, so the migration fails closed.
+     */
+    migrateSessionMainRootIfRevision(sessionId: string, project: import("../types.js").SessionProjectBinding, mainRoot: string, expectedStateRevision: number | undefined): number;
     /** Read the durable archival timestamp; undefined = not archived / unprovable. */
     readSessionArchivedAt(sessionId: string): number | undefined;
     /** Set (number) or clear (undefined) the durable archival marker. */
@@ -221,6 +239,13 @@ export declare class SessionManager {
         state: SessionState;
     } | undefined;
     resume(sessionId: string): SessionBundle;
+    /**
+     * Resume a model run with a bounded active replay for large Pet transcripts
+     * that already contain a full-history archive boundary. Audit/detail callers
+     * continue to use resume() and receive every persisted event.
+     */
+    resumeForRun(sessionId: string): SessionBundle;
+    private resumeWithTranscriptMode;
     /**
      * Return the exact persistence directory owned by this manager.
      *

package/dist/session/session-manager.js

@@ -505,6 +505,29 @@ export class SessionManager {
             return undefined;
         }
     }
+    /** Cheap durable project-binding read; absent for legacy/no-repo Sessions. */
+    readSessionProjectBinding(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+            const processLocal = this.processLocalBundle(sessionId);
+            const state = processLocal
+                ? processLocal.state
+                : sessionId.startsWith("qchat-")
+                    ? undefined
+                    : JSON.parse(readFileSync(join(this.sessionsDir, sessionId, "state.json"), "utf-8"));
+            const project = state?.project;
+            return project &&
+                typeof project.projectId === "string" &&
+                project.projectId.length > 0 &&
+                typeof project.mainRootId === "string" &&
+                project.mainRootId.length > 0
+                ? { projectId: project.projectId, mainRootId: project.mainRootId }
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Cheap durable classification read. Legacy sessions are ordinary work sessions. */
     readSessionKind(sessionId) {
         try {
@@ -686,6 +709,70 @@ export class SessionManager {
         }
         return this.updateSessionState(sessionId, { workspace });
     }
+    /**
+     * Commit a Session main-root migration as one state.json replacement.
+     *
+     * `cwd`, the durable project binding, and the execution workspace are one
+     * consistency unit: exposing any subset would let a resumed run combine the
+     * old authority with a new path. Derived availability such as dir_missing is
+     * deliberately absent from this patch and is recomputed by the host.
+     */
+    migrateSessionMainRoot(sessionId, project, mainRoot) {
+        if (!project ||
+            typeof project.projectId !== "string" ||
+            project.projectId.length === 0 ||
+            typeof project.mainRootId !== "string" ||
+            project.mainRootId.length === 0 ||
+            typeof mainRoot !== "string" ||
+            mainRoot.length === 0) {
+            throw new SessionError(`invalid main-root migration for ${sessionId}`);
+        }
+        return this.updateSessionState(sessionId, {
+            project: { ...project },
+            cwd: mainRoot,
+            workspace: { root: mainRoot, kind: "main" },
+        });
+    }
+    /**
+     * Commit a host-owned offline migration only if the durable snapshot Main
+     * just revalidated is still current. Unlike the ordinary field-level writer,
+     * this must not retry onto a newer revision: a new writer means ownership is
+     * no longer provably unchanged, so the migration fails closed.
+     */
+    migrateSessionMainRootIfRevision(sessionId, project, mainRoot, expectedStateRevision) {
+        assertSafeSessionId(sessionId);
+        if (!project ||
+            typeof project.projectId !== "string" ||
+            project.projectId.length === 0 ||
+            typeof project.mainRootId !== "string" ||
+            project.mainRootId.length === 0 ||
+            typeof mainRoot !== "string" ||
+            mainRoot.length === 0) {
+            throw new SessionError(`invalid main-root migration for ${sessionId}`);
+        }
+        const state = this.readPersistedState(sessionId);
+        if (state.stateRevision !== expectedStateRevision) {
+            throw new SessionError(`Session state revision conflict for ${sessionId}`);
+        }
+        Object.assign(state, {
+            project: { ...project },
+            cwd: mainRoot,
+            workspace: { root: mainRoot, kind: "main" },
+        });
+        const result = this.saveStateAttempt(state);
+        if (result.ok)
+            return state.stateRevision;
+        if (result.reason === "generation_conflict") {
+            throw new SessionError(`Session generation conflict for ${sessionId}`);
+        }
+        if (result.reason === "lock_conflict") {
+            throw new SessionError(`Session state lock contention for ${sessionId}`);
+        }
+        if (result.reason === "kind_conflict") {
+            throw new SessionError(`Session kind is immutable for ${sessionId}`);
+        }
+        throw new SessionError(`Session state revision conflict for ${sessionId}`);
+    }
     /** Read the durable archival timestamp; undefined = not archived / unprovable. */
     readSessionArchivedAt(sessionId) {
         try {
@@ -1001,6 +1088,17 @@ export class SessionManager {
         return undefined;
     }
     resume(sessionId) {
+        return this.resumeWithTranscriptMode(sessionId, false);
+    }
+    /**
+     * Resume a model run with a bounded active replay for large Pet transcripts
+     * that already contain a full-history archive boundary. Audit/detail callers
+     * continue to use resume() and receive every persisted event.
+     */
+    resumeForRun(sessionId) {
+        return this.resumeWithTranscriptMode(sessionId, true);
+    }
+    resumeWithTranscriptMode(sessionId, contextOnly) {
         assertSafeSessionId(sessionId);
         const processLocal = this.processLocalBundle(sessionId);
         if (processLocal) {
@@ -1037,8 +1135,10 @@ export class SessionManager {
             chmodSync(sessionDir, 0o700);
             chmodSync(stateFile, 0o600);
         }
-        const transcript = Transcript.loadFromFile(transcriptFile);
         state.kind = normalizedSessionKind(state.kind);
+        const transcript = contextOnly && state.kind === "pet"
+            ? Transcript.loadContextFromFile(transcriptFile)
+            : Transcript.loadFromFile(transcriptFile);
         state.status = "active";
         delete state.lastCompletionKind;
         Object.assign(state, normalizeCumulativeUsageCounters(state, state.tokenUsage));
@@ -1697,11 +1797,11 @@ export class SessionManager {
     list(limit = 20, opts) {
         if (!existsSync(this.sessionsDir))
             return [];
-        // Extension-owned session kinds stay out of generic lists. Defaults to
-        // hiding "pet" so default-arg callers keep today's behavior.
-        // TODO(pet-out-of-core): drop the default once every caller passes the
-        // host's hidden-kind union explicitly.
-        const excludeKinds = opts?.excludeKinds ?? ["pet"];
+        // Core is domain-agnostic: only the composition root knows which
+        // extension-owned kinds belong outside its generic list. AgentServer passes
+        // the resolved hidden-kind union explicitly; direct SDK callers see every
+        // kind unless they choose exclusions themselves.
+        const excludeKinds = opts?.excludeKinds ?? [];
         const dirs = readdirSync(this.sessionsDir, { withFileTypes: true })
             .filter((d) => d.isDirectory() && !d.name.startsWith(".pending-") && !d.name.startsWith("qchat-"))
             .map((d) => d.name);

package/dist/session/transcript.d.ts

@@ -184,6 +184,15 @@ export declare class Transcript {
      */
     static selectContextRange(events: readonly TranscriptEvent[], range: ContextEventRange): SelectedContextRange;
     static loadFromFile(filePath: string): Transcript;
+    /**
+     * Load the active replay for a model run while leaving the append-only audit
+     * transcript untouched on disk. A host-authored from-less range archive
+     * replaces everything before its `to` anchor, so a large Mimi transcript can
+     * retain only that boundary and the live tail in memory. If the boundary is
+     * absent, too old, malformed, or not self-contained in the bounded tail, we
+     * fail open to the full loader.
+     */
+    static loadContextFromFile(filePath: string, maxTailBytes?: number): Transcript;
     private loadEvents;
 }
 export {};

package/dist/session/transcript.js

@@ -6,6 +6,7 @@ import { appendFileSync, chmodSync, closeSync, existsSync, fchmodSync, fstatSync
 import { dirname } from "node:path";
 import { nanoid } from "nanoid";
 import { logger } from "../logging/logger.js";
+const DEFAULT_CONTEXT_TAIL_SCAN_BYTES = 32 * 1024 * 1024;
 function appendTranscriptLine(filePath, data) {
     // Use one append-mode descriptor so concurrent OS writers cannot overwrite
     // one another. Also repair the record boundary after a crash-torn final line;
@@ -678,6 +679,86 @@ export class Transcript {
         transcript.repairToolResultPairs();
         return transcript;
     }
+    /**
+     * Load the active replay for a model run while leaving the append-only audit
+     * transcript untouched on disk. A host-authored from-less range archive
+     * replaces everything before its `to` anchor, so a large Mimi transcript can
+     * retain only that boundary and the live tail in memory. If the boundary is
+     * absent, too old, malformed, or not self-contained in the bounded tail, we
+     * fail open to the full loader.
+     */
+    static loadContextFromFile(filePath, maxTailBytes = DEFAULT_CONTEXT_TAIL_SCAN_BYTES) {
+        if (!existsSync(filePath))
+            return new Transcript(filePath);
+        let tail;
+        try {
+            const fd = openSync(filePath, "r");
+            try {
+                const fileSize = fstatSync(fd).size;
+                if (fileSize <= maxTailBytes)
+                    return Transcript.loadFromFile(filePath);
+                const length = Math.min(fileSize, Math.max(1, maxTailBytes));
+                const buffer = Buffer.allocUnsafe(length);
+                const bytesRead = readSync(fd, buffer, 0, length, fileSize - length);
+                let window = buffer.subarray(0, bytesRead);
+                const newline = window.indexOf(0x0a);
+                if (newline < 0)
+                    return Transcript.loadFromFile(filePath);
+                window = window.subarray(newline + 1);
+                tail = window.toString("utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        catch {
+            return Transcript.loadFromFile(filePath);
+        }
+        const events = [];
+        for (const line of tail.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                // A malformed tail must not turn a partial window into authoritative
+                // context. The normal loader keeps its established skip behavior.
+                return Transcript.loadFromFile(filePath);
+            }
+        }
+        let markerIndex = -1;
+        let toClientMessageId;
+        for (const [index, event] of events.entries()) {
+            if (event.type !== "range_archive")
+                continue;
+            const data = event.data;
+            if (data.fromClientMessageId === undefined &&
+                typeof data.summary === "string" &&
+                typeof data.toClientMessageId === "string") {
+                markerIndex = index;
+                toClientMessageId = data.toClientMessageId;
+            }
+        }
+        if (markerIndex < 0 || !toClientMessageId)
+            return Transcript.loadFromFile(filePath);
+        const anchorIndex = events.findIndex((event, index) => index < markerIndex &&
+            event.type === "message" &&
+            event.data.clientMessageId === toClientMessageId);
+        if (anchorIndex < 0)
+            return Transcript.loadFromFile(filePath);
+        let startIndex = anchorIndex;
+        for (let index = anchorIndex - 1; index >= 0; index -= 1) {
+            if (events[index]?.type !== "turn_boundary")
+                continue;
+            startIndex = index;
+            break;
+        }
+        const transcript = new Transcript(filePath);
+        transcript.loadEvents(events.slice(startIndex));
+        transcript.repairToolResultPairs();
+        return transcript;
+    }
     loadEvents(events) {
         this.events = structuredClone([...events]);
         this.currentTurn = 0;

package/dist/settings/manager.d.ts

@@ -153,6 +153,18 @@ export declare class SettingsManager {
      * be shared with collaborators.
      */
     saveLocalSetting(key: string, value: unknown, cwd: string): void;
+    /**
+     * Mutate one writable settings layer under the same cross-process lock used
+     * by the desktop settings service. Domain tools use this when two related
+     * fields must change atomically (for example modelConnections + defaults):
+     * composing multiple save*Setting calls would expose an intermediate state
+     * and could interleave with another process between writes.
+     *
+     * The callback receives only the selected layer's raw object, not the merged
+     * settings view. The result is schema-validated before it replaces the file.
+     * Returning false makes the operation a no-op.
+     */
+    mutateSettingsForScope(scope: "user" | "project", cwd: string, mutate: (current: Record<string, unknown>) => boolean | void): void;
     /**
      * Delete a single dotted key from the PROJECT-level config file. Used to
      * express "inherit" — we don't persist the literal "inherit"; we remove the

package/dist/settings/manager.js

@@ -417,6 +417,37 @@ export class SettingsManager {
         });
         this.invalidate();
     }
+    /**
+     * Mutate one writable settings layer under the same cross-process lock used
+     * by the desktop settings service. Domain tools use this when two related
+     * fields must change atomically (for example modelConnections + defaults):
+     * composing multiple save*Setting calls would expose an intermediate state
+     * and could interleave with another process between writes.
+     *
+     * The callback receives only the selected layer's raw object, not the merged
+     * settings view. The result is schema-validated before it replaces the file.
+     * Returning false makes the operation a no-op.
+     */
+    mutateSettingsForScope(scope, cwd, mutate) {
+        const path = scope === "user"
+            ? join(this.userConfigDir(), "settings.json")
+            : this.projectSettingsPath(cwd);
+        if (scope === "project") {
+            this.validateProjectCwd(cwd, "project");
+            if (!existsSync(cwd))
+                throw new Error(`project directory does not exist: ${cwd}`);
+        }
+        this.mutateSettingsFile(path, (current) => {
+            if (mutate(current) === false)
+                return false;
+            // Validate the complete resulting layer before persistence. We keep the
+            // original object for serialization so forward-compatible unknown keys
+            // are preserved instead of being stripped by Zod's parsed result.
+            validateSettings(current);
+            return true;
+        });
+        this.invalidate();
+    }
     /**
      * Delete a single dotted key from the PROJECT-level config file. Used to
      * express "inherit" — we don't persist the literal "inherit"; we remove the

package/dist/tool-system/builtin/configure-model-connection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ConfigureModelConnection — safely materialize one catalog model into the
+ * unified settings.modelConnections store without exposing or copying API
+ * keys. The write is schema-validated, lock-protected, atomic, and updates the
+ * selected tag default in the same transaction when requested.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+import { SettingsManager } from "../../settings/manager.js";
+import { type CatalogEntry } from "../../model-catalog/index.js";
+import { createLLMClient } from "../../llm/client-factory.js";
+import { type Credential, type ModelInstance } from "../../model-catalog/resolve.js";
+interface ConfigureModelConnectionDeps {
+    makeSettingsManager(cwd: string, scope: "full" | "project"): SettingsManager;
+    getCatalog(): CatalogEntry[];
+    notifySettingsChanged(): void;
+    testTextConnection(connection: ModelInstance, credentials: Credential[], catalog: CatalogEntry[]): Promise<ConnectionTestResult>;
+}
+interface ConnectionTestResult {
+    ok: boolean;
+    response?: string;
+    stopReason?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    error?: string;
+}
+export declare function probeTextModelConnection(connection: ModelInstance, credentials: Credential[], catalog: CatalogEntry[], options?: {
+    fetch?: typeof globalThis.fetch;
+    createClient?: typeof createLLMClient;
+}): Promise<ConnectionTestResult>;
+export declare const configureModelConnectionToolDef: ToolDefinition;
+export declare function configureModelConnectionTool(args: Record<string, unknown>, ctx?: ToolContext, deps?: ConfigureModelConnectionDeps): Promise<string>;
+export {};