@cjhyy/code-shell-core 0.8.7 → 0.8.9

package/dist/session/session-manager.js

@@ -148,25 +148,34 @@ function adoptCompatibilityGoalMutation(state) {
 // disk. The storage root remains part of the key to preserve identity/data-root
 // isolation.
 const processLocalSessionBundles = new Map();
-const FORK_COPY_EVENT_TYPES = new Set([
-    "message",
-    "tool_use",
-    "tool_result",
-    "summary",
-    "context_transfer",
-    "content_replace",
-    "subagent",
-    "external_file_changes",
-    "goal_progress",
-    "turn_boundary",
-    "turn_stopped",
-    "error",
-]);
-const FORK_SKIP_EVENT_TYPES = new Set([
-    "session_meta",
-    "file_history",
-    "plan_operation",
-]);
+/**
+ * Every known transcript event must make an explicit fork decision. The
+ * `satisfies` constraint turns new TranscriptEventType additions into a
+ * compile-time error instead of a quick-chat failure discovered at runtime.
+ * The runtime fallback below still rejects unknown events from newer or
+ * malformed persisted transcripts.
+ */
+const FORK_EVENT_POLICY = {
+    message: "copy",
+    tool_use: "copy",
+    tool_result: "copy",
+    summary: "copy",
+    context_transfer: "copy",
+    range_archive: "copy",
+    content_replace: "copy",
+    file_history: "skip",
+    plan_operation: "skip",
+    session_meta: "skip",
+    subagent: "copy",
+    external_file_changes: "copy",
+    turn_boundary: "copy",
+    // Idempotency receipts belong to the source session and never contribute to
+    // model context. Copying them could replay a source response in the child.
+    run_result: "skip",
+    goal_progress: "copy",
+    turn_stopped: "copy",
+    error: "copy",
+};
 const FORK_STAGING_NAME = /^\.pending-fork-[A-Za-z0-9_.-]+-[A-Za-z0-9_-]{8}$/;
 const FORK_STAGING_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const FORK_STAGING_CLEANUP_LIMIT = 32;
@@ -365,7 +374,7 @@ export class SessionManager {
      * Create a session. `qchat-` sessions stay process-local; ordinary sessions
      * materialize state.json + transcript.jsonl before return.
      */
-    create(cwd, model, provider, explicitSessionId, parentSessionId, origin, kind = "work") {
+    create(cwd, model, provider, explicitSessionId, parentSessionId, origin, kind = "work", ephemeral = false) {
         // External callers may pass any string; nanoid output is trusted. Either
         // way the ID gets joined into a filesystem path, so the public entry
         // point validates before that join.
@@ -393,7 +402,7 @@ export class SessionManager {
             // new top-level session (key present, null) apart from a legacy session
             // (key absent) and from a sub-agent (key present, non-empty string).
             parentSessionId: parentSessionId ?? null,
-            ...(sessionId.startsWith("qchat-") ? { ephemeral: true } : {}),
+            ...(ephemeral || sessionId.startsWith("qchat-") ? { ephemeral: true } : {}),
             ...(origin ? { origin } : {}),
         };
         if (isEphemeralSessionState(state)) {
@@ -1048,6 +1057,10 @@ export class SessionManager {
             return undefined;
         }
     }
+    /** Whether a live or persisted Session is explicitly process-local. */
+    isEphemeralSession(sessionId) {
+        return this.readSessionState(sessionId)?.ephemeral === true;
+    }
     /**
      * Merge a field-level state update into the latest persisted snapshot.
      *
@@ -1568,7 +1581,10 @@ export class SessionManager {
         return this.freezeForkSnapshot(sourceSessionId, sourceState, parsed.events, throughEventId, snapshotMode);
     }
     freezeForkSnapshot(sourceSessionId, sourceState, events, throughEventId, snapshotMode) {
-        const sourceEvents = structuredClone([...events]);
+        // Both process-local and disk readers provide a snapshot array. Fork
+        // selection is synchronous, so keep event references here and clone once
+        // when the independently-owned target transcript is constructed below.
+        const sourceEvents = [...events];
         let frozen = sourceEvents;
         const effectiveCursor = snapshotMode === "completed" ? sourceState.completedThroughEventId : throughEventId;
         if (snapshotMode === "completed" && effectiveCursor === undefined) {
@@ -1599,12 +1615,13 @@ export class SessionManager {
         }
         const copiedEvents = [];
         for (const event of frozen) {
-            if (FORK_SKIP_EVENT_TYPES.has(event.type))
+            const policy = FORK_EVENT_POLICY[event.type];
+            if (policy === "skip")
                 continue;
-            if (!FORK_COPY_EVENT_TYPES.has(event.type)) {
+            if (policy !== "copy") {
                 throw new SessionError(`Unsupported transcript event in fork: ${String(event.type)}`);
             }
-            copiedEvents.push(structuredClone(event));
+            copiedEvents.push(event);
         }
         validateForkToolPairs(copiedEvents);
         return { sourceState: structuredClone(sourceState), copiedEvents };

package/dist/session/transcript.d.ts

@@ -106,12 +106,48 @@ export declare class Transcript {
      */
     appendTurnStopped(): TranscriptEvent | undefined;
     appendSummary(summary: string, metadata: SummaryAppendMetadata): TranscriptEvent;
+    /**
+     * Persist a range-archival boundary. Span is [fromClientMessageId,
+     * toClientMessageId) over message events; an absent from means "from the
+     * beginning". Idempotent on segmentId so a crash-replayed closure cannot
+     * double-archive.
+     */
+    appendRangeArchive(data: {
+        summary: string;
+        toClientMessageId: string;
+        fromClientMessageId?: string;
+        segmentId?: string;
+    }): TranscriptEvent | undefined;
     appendError(error: string, details?: Record<string, unknown>): TranscriptEvent;
     /**
      * Derive Message[] from transcript events for sending to the LLM.
      * This is the critical boundary: the LLM never sees the event log directly.
      */
     toMessages(): Message[];
+    /**
+     * Marker-aware replay that ALSO reports, for every emitted message event
+     * carrying a clientMessageId, the LIVE index (its position in the returned
+     * messages array) of its FIRST emission. This is how the engine resolves an
+     * anchored archival window: raw transcript indices grow forever and go stale
+     * the moment a range_archive marker trims the replay, so any caller-held
+     * index range is meaningless — only client-message-id anchors resolved over
+     * THIS replay identify the right span.
+     *
+     * Contract details:
+     * - Messages dropped inside an archived span get NO index entry — they are
+     *   not in the live list, so a window anchored on them cannot be built
+     *   (the engine fails open in that case).
+     * - Only the FIRST emission of a duplicated clientMessageId is recorded
+     *   (duplicates replay as plain messages per the one-shot span rule; the
+     *   first index is the meaningful one).
+     * - The clientMessageId is deliberately NOT attached to the Message objects
+     *   themselves: Message[] is exactly what gets serialized into LLM request
+     *   payloads, and transport metadata must not leak into them.
+     */
+    toMessagesWithIndex(): {
+        messages: Message[];
+        liveIndexByClientMessageId: Map<string, number>;
+    };
     getEvents(type?: TranscriptEventType): TranscriptEvent[];
     get turnNumber(): number;
     get eventCount(): number;

package/dist/session/transcript.js

@@ -12,6 +12,7 @@ const CONTEXT_EVENT_TYPES = new Set([
     "tool_result",
     "summary",
     "context_transfer",
+    "range_archive",
 ]);
 const INTERRUPTED_TOOL_RESULT_ERROR = "[Tool result missing due to interrupted session]";
 function isSyntheticInterruptedToolResult(event) {
@@ -212,6 +213,19 @@ export class Transcript {
             },
         });
     }
+    /**
+     * Persist a range-archival boundary. Span is [fromClientMessageId,
+     * toClientMessageId) over message events; an absent from means "from the
+     * beginning". Idempotent on segmentId so a crash-replayed closure cannot
+     * double-archive.
+     */
+    appendRangeArchive(data) {
+        if (data.segmentId &&
+            this.events.some((e) => e.type === "range_archive" && e.data.segmentId === data.segmentId)) {
+            return undefined;
+        }
+        return this.append("range_archive", { ...data });
+    }
     appendError(error, details) {
         return this.append("error", { error, ...details });
     }
@@ -220,12 +234,128 @@ export class Transcript {
      * This is the critical boundary: the LLM never sees the event log directly.
      */
     toMessages() {
+        return this.toMessagesWithIndex().messages;
+    }
+    /**
+     * Marker-aware replay that ALSO reports, for every emitted message event
+     * carrying a clientMessageId, the LIVE index (its position in the returned
+     * messages array) of its FIRST emission. This is how the engine resolves an
+     * anchored archival window: raw transcript indices grow forever and go stale
+     * the moment a range_archive marker trims the replay, so any caller-held
+     * index range is meaningless — only client-message-id anchors resolved over
+     * THIS replay identify the right span.
+     *
+     * Contract details:
+     * - Messages dropped inside an archived span get NO index entry — they are
+     *   not in the live list, so a window anchored on them cannot be built
+     *   (the engine fails open in that case).
+     * - Only the FIRST emission of a duplicated clientMessageId is recorded
+     *   (duplicates replay as plain messages per the one-shot span rule; the
+     *   first index is the meaningful one).
+     * - The clientMessageId is deliberately NOT attached to the Message objects
+     *   themselves: Message[] is exactly what gets serialized into LLM request
+     *   payloads, and transport metadata must not leak into them.
+     */
+    toMessagesWithIndex() {
         const messages = [];
+        const liveIndexByClientMessageId = new Map();
         const selectedToolResults = preferredToolResults(this.events);
+        const hasRangeArchive = this.events.some((e) => e.type === "range_archive");
+        const spansByFromId = new Map();
+        let openingSpan;
+        if (hasRangeArchive) {
+            // First-occurrence event index per client message id, so a marker whose
+            // `to` does not come strictly after its `from` (out of order, or a
+            // degenerate from === to) can be rejected. Without this check the span
+            // opens at `from` but its close condition (`to`) was already passed
+            // while scanning forward, so it would never close — silently swallowing
+            // the rest of the conversation. Fail open instead: ignore the marker.
+            const firstIndexByClientId = new Map();
+            for (const [index, event] of this.events.entries()) {
+                if (event.type === "message" && typeof event.data.clientMessageId === "string") {
+                    if (!firstIndexByClientId.has(event.data.clientMessageId)) {
+                        firstIndexByClientId.set(event.data.clientMessageId, index);
+                    }
+                }
+            }
+            const presentClientIds = new Set(firstIndexByClientId.keys());
+            for (const event of this.events) {
+                if (event.type !== "range_archive")
+                    continue;
+                const { summary, toClientMessageId, fromClientMessageId } = event.data;
+                if (typeof summary !== "string" || !presentClientIds.has(toClientMessageId))
+                    continue;
+                if (fromClientMessageId === undefined) {
+                    // Multiple from-less markers compete for this single opening-span
+                    // slot; the LAST one wins (matching spansByFromId's Map.set
+                    // semantics below). Last-wins is CORRECT by construction, not
+                    // merely a tiebreak: the engine resolves a from-less archival
+                    // window as [0, to) over the LIVE replay, so the window that
+                    // produced a LATER from-less marker began with the EARLIER
+                    // marker's replayed summary message, and summarizeRange merge-fed
+                    // that prior summary (extractAnchoredSummary) into the new one.
+                    // The later summary therefore already contains the earlier one's
+                    // content — dropping the earlier marker here loses nothing. (And
+                    // in production from-less windows only advance: each new marker
+                    // ends at a later boundary, so the surviving span is the widest.)
+                    openingSpan = { summary, toClientMessageId };
+                }
+                else if (presentClientIds.has(fromClientMessageId)) {
+                    const fromIndex = firstIndexByClientId.get(fromClientMessageId);
+                    const toIndex = firstIndexByClientId.get(toClientMessageId);
+                    if (toIndex <= fromIndex)
+                        continue; // out of order or degenerate: fail open
+                    spansByFromId.set(fromClientMessageId, { summary, toClientMessageId });
+                }
+            }
+        }
+        let activeSpan = null;
+        if (openingSpan) {
+            activeSpan = openingSpan;
+            messages.push({ role: "user", content: openingSpan.summary });
+        }
+        // tool_use ids actually emitted into assistant message content blocks so
+        // far. A tool_result whose tool_use_id isn't in this set — e.g. because
+        // its opening tool_use fell inside an archived span while the (later,
+        // preferred) real result landed outside it — would be an orphaned block
+        // that breaks provider validation; skip it instead of emitting it.
+        const emittedToolUseIds = new Set();
         for (const event of this.events) {
+            // Span bookkeeping runs on message events only: exit before entry so
+            // adjacent spans (A.to === B.from) hand over on the boundary message.
+            if (event.type === "message") {
+                const clientMessageId = typeof event.data.clientMessageId === "string" ? event.data.clientMessageId : undefined;
+                if (activeSpan && clientMessageId === activeSpan.toClientMessageId) {
+                    activeSpan = null;
+                }
+                if (!activeSpan && clientMessageId && spansByFromId.has(clientMessageId)) {
+                    activeSpan = spansByFromId.get(clientMessageId);
+                    // One-shot: a duplicate `from` message (e.g. from a torn JSONL
+                    // reload) must not reopen this span a second time — it would have
+                    // no more `to` ahead of it and swallow the rest of the transcript.
+                    spansByFromId.delete(clientMessageId);
+                    messages.push({ role: "user", content: activeSpan.summary });
+                }
+            }
+            if (activeSpan)
+                continue; // archived span: drop every context event inside
             switch (event.type) {
                 case "message": {
-                    const { role, content } = event.data;
+                    const { role, content, clientMessageId } = event.data;
+                    // Record the live index of this message's FIRST emission before
+                    // pushing it (the index it is about to occupy). Dropped-in-span
+                    // messages never reach this point, so they get no entry.
+                    if (typeof clientMessageId === "string" &&
+                        !liveIndexByClientMessageId.has(clientMessageId)) {
+                        liveIndexByClientMessageId.set(clientMessageId, messages.length);
+                    }
+                    if (role === "assistant" && Array.isArray(content)) {
+                        for (const block of content) {
+                            if (block.type === "tool_use" && typeof block.id === "string") {
+                                emittedToolUseIds.add(block.id);
+                            }
+                        }
+                    }
                     messages.push({ role: role, content });
                     break;
                 }
@@ -237,7 +367,8 @@ export class Transcript {
                 case "tool_result": {
                     const eventToolCallId = event.data.toolCallId;
                     if (typeof eventToolCallId !== "string" ||
-                        selectedToolResults.get(eventToolCallId) !== event) {
+                        selectedToolResults.get(eventToolCallId) !== event ||
+                        !emittedToolUseIds.has(eventToolCallId)) {
                         break;
                     }
                     const { toolCallId, result, error, contentBlocks } = event.data;
@@ -280,10 +411,12 @@ export class Transcript {
                     break;
                 }
                 // turn_boundary, run_result, session_meta, file_history, plan_operation, error
-                // are not included in LLM messages
+                // are not included in LLM messages. range_archive is handled entirely
+                // by the pre-pass above (it emits the summary at span entry and drops
+                // events inside the span); it never falls through to this switch.
             }
         }
-        return messages;
+        return { messages, liveIndexByClientMessageId };
     }
     getEvents(type) {
         if (!type)
@@ -448,6 +581,18 @@ export class Transcript {
                     });
                     break;
                 }
+                case "range_archive": {
+                    // A hand-picked context range is an explicit user selection: inject
+                    // the archive summary as context but do NOT replace/drop the
+                    // messages inside its span the way toMessages() does — the caller
+                    // asked for exactly this range and expects to see it in full.
+                    const { summary } = event.data;
+                    messages.push({
+                        role: "user",
+                        content: `<system-reminder>Archived summary for part of this range:\n${summary}</system-reminder>`,
+                    });
+                    break;
+                }
             }
         }
         return messages;

package/dist/tool-system/builtin/index.js

@@ -310,7 +310,10 @@ const BUILTIN_CONTRIBUTIONS = [
             timeoutMs: 1_800_000, // 30min — sub-agent runs may execute many tool calls
         },
         execute: agentTool,
-        exposure: expose(HARNESS_TAGS, { defaultPermissionRules: allow(agentToolDef.name) }),
+        exposure: expose(HARNESS_TAGS, {
+            defaultPermissionRules: allow(agentToolDef.name),
+            availability: (ctx) => ctx.behaviorProfile !== "quickChatRestricted",
+        }),
     },
     {
         definition: {

package/dist/tool-system/path-policy.js

@@ -449,8 +449,6 @@ function isRegisteredSkillResourceRead(resolved) {
         return false;
     if (isSkillTreeResource(resolved, join(codeShellRoot, "skills")))
         return true;
-    if (isInstalledPanelAppSkillResourceRead(resolved, codeShellRoot))
-        return true;
     let cacheRoot;
     try {
         cacheRoot = realpathSync(join(codeShellRoot, "plugins", "cache"));
@@ -479,20 +477,26 @@ function isRegisteredSkillResourceRead(resolved) {
     return false;
 }
 /**
- * Panel App Skills live under the otherwise-sensitive
- * `~/.code-shell/panel-apps` tree. Installation already reviews and copies the
- * package, and the Skill scanner exposes only entries declared by the app
- * manifest. Mirror that exact boundary here so reading a Skill reference does
- * not trigger a second approval prompt.
+ * Installed Panel Apps live under the otherwise-sensitive
+ * `~/.code-shell/panel-apps` tree. Their package contents are reviewed and
+ * copied by the installer, so ordinary source, manifests, assets and declared
+ * Agent resources should not require a second approval merely because their
+ * parent directory is `~/.code-shell`.
  *
- * Registry, app root, manifest, declared SKILL.md and target are all
- * realpathed and containment-checked. This deliberately does not trust an
- * undeclared Skill directory or a symlink escaping the installed app.
+ * Keep the exception read-only at the call site and require a valid installed
+ * registry entry plus a matching V2 manifest. Registry, app root, manifest and
+ * target are all realpathed and containment-checked. Credential-shaped files
+ * are still caught by `SENSITIVE_FILE_PATTERNS` before this exception, and a
+ * symlink escaping the installed package never inherits its read authority.
  */
-function isInstalledPanelAppSkillResourceRead(resolved, codeShellRoot) {
+function isInstalledPanelAppResourceRead(resolved) {
+    let codeShellRoot;
     let appsRoot;
     let registryPath;
     try {
+        codeShellRoot = realpathSync(join(configuredUserHome(), ".code-shell"));
+        if (!isInsideDir(resolved, codeShellRoot))
+            return false;
         appsRoot = realpathSync(join(codeShellRoot, "panel-apps"));
         if (!isInsideDir(appsRoot, codeShellRoot))
             return false;
@@ -526,29 +530,10 @@ function isInstalledPanelAppSkillResourceRead(resolved, codeShellRoot) {
             if (!isInsideDir(manifestPath, appRoot) || !statSync(manifestPath).isFile())
                 continue;
             const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-            if (manifest.schemaVersion !== 2 ||
-                manifest.id !== id ||
-                !Array.isArray(manifest.agent?.skills)) {
+            if (manifest.schemaVersion !== 2 || manifest.id !== id)
                 continue;
-            }
-            for (const skillEntry of manifest.agent.skills) {
-                if (typeof skillEntry !== "string")
-                    continue;
-                const segments = skillEntry.split("/");
-                if (segments.length !== 4 ||
-                    segments[0] !== "agent" ||
-                    segments[1] !== "skills" ||
-                    !/^[a-z][a-z0-9-]{0,63}$/.test(segments[2] ?? "") ||
-                    segments[3] !== "SKILL.md") {
-                    continue;
-                }
-                const skillManifest = realpathSync(join(appRoot, ...segments));
-                if (!isInsideDir(skillManifest, appRoot) || !statSync(skillManifest).isFile())
-                    continue;
-                const skillRoot = dirname(skillManifest);
-                if (isInsideDir(resolved, skillRoot))
-                    return true;
-            }
+            if (isInsideDir(resolved, appRoot))
+                return true;
         }
         catch {
             // A stale, malformed, or tampered Panel App entry grants no read access.
@@ -652,6 +637,13 @@ export function classifyPath(rawPath, opts) {
             resolvedPath: resolved,
         };
     }
+    if (opts.operation === "read" && !sensitiveFile && isInstalledPanelAppResourceRead(resolved)) {
+        return {
+            decision: "allow",
+            reason: "installed Panel App resource read",
+            resolvedPath: resolved,
+        };
+    }
     // Sensitive: write is always denied, read always asks. Workspace placement
     // doesn't soften the rule — an `.env` in the project still asks on read.
     if (sensitiveLabel) {

package/dist/types.d.ts

@@ -145,7 +145,7 @@ export interface RegisteredTool {
      */
     timeoutMs?: number;
 }
-export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "context_transfer" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "subagent" | "external_file_changes" | "turn_boundary" | "run_result" | "goal_progress" | "turn_stopped" | "error";
+export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "context_transfer" | "range_archive" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "subagent" | "external_file_changes" | "turn_boundary" | "run_result" | "goal_progress" | "turn_stopped" | "error";
 export interface TranscriptEvent {
     id: string;
     type: TranscriptEventType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",