@cjhyy/code-shell-core 0.9.6 → 0.9.7

package/dist/automation/scheduler.d.ts

@@ -102,6 +102,8 @@ export interface UpdateJobPatch {
     projectId?: string | null;
     rootId?: string | null;
     permissionLevel?: CronPermissionLevel;
+    /** Existing Session to resume; null returns the job to standalone execution. */
+    resumeSessionId?: string | null;
 }
 export declare class CronScheduler {
     private jobs;
@@ -212,6 +214,7 @@ export declare class CronScheduler {
      * or null if the id is unknown.
      */
     update(id: string, patch: UpdateJobPatch): CronJob | null;
+    private assertBindingEditable;
     stopAll(): void;
     /**
      * Fire a job immediately, out of band of its schedule (the "Run now" button).

package/dist/automation/scheduler.js

@@ -75,6 +75,7 @@ function validateJobFields(input) {
     for (const [field, value] of [
         ["projectId", input.projectId],
         ["rootId", input.rootId],
+        ["resumeSessionId", input.resumeSessionId],
     ]) {
         if (value !== undefined &&
             value !== null &&
@@ -535,6 +536,7 @@ export class CronScheduler {
                     if (j.id !== id)
                         return j;
                     const job = { ...j };
+                    this.assertBindingEditable(job, patch);
                     const nextSchedule = patch.schedule ?? job.schedule;
                     const nextTimezone = patch.timezone ?? job.timezone;
                     if (patch.schedule !== undefined || patch.timezone !== undefined) {
@@ -560,6 +562,10 @@ export class CronScheduler {
                         delete job.rootId;
                     else if (patch.rootId !== undefined)
                         job.rootId = patch.rootId;
+                    if (patch.resumeSessionId === null)
+                        delete job.resumeSessionId;
+                    else if (patch.resumeSessionId !== undefined)
+                        job.resumeSessionId = patch.resumeSessionId;
                     if (patch.permissionLevel !== undefined)
                         job.permissionLevel = patch.permissionLevel;
                     if (scheduleChanged)
@@ -575,6 +581,7 @@ export class CronScheduler {
         const job = this.jobs.get(id);
         if (!job)
             return null;
+        this.assertBindingEditable(job, patch);
         // Validate a new schedule/timezone BEFORE mutating anything.
         const nextSchedule = patch.schedule ?? job.schedule;
         const nextTimezone = patch.timezone ?? job.timezone;
@@ -601,6 +608,10 @@ export class CronScheduler {
             delete job.rootId;
         else if (patch.rootId !== undefined)
             job.rootId = patch.rootId;
+        if (patch.resumeSessionId === null)
+            delete job.resumeSessionId;
+        else if (patch.resumeSessionId !== undefined)
+            job.resumeSessionId = patch.resumeSessionId;
         if (patch.permissionLevel !== undefined)
             job.permissionLevel = patch.permissionLevel;
         // Re-arm only when the schedule definition changed, or when an enabled job
@@ -617,6 +628,16 @@ export class CronScheduler {
         this.persist();
         return job;
     }
+    assertBindingEditable(job, patch) {
+        const bindingChanged = (patch.resumeSessionId !== undefined &&
+            (patch.resumeSessionId ?? null) !== (job.resumeSessionId ?? null)) ||
+            (patch.cwd !== undefined && patch.cwd !== job.cwd) ||
+            (patch.projectId !== undefined && (patch.projectId ?? null) !== (job.projectId ?? null)) ||
+            (patch.rootId !== undefined && (patch.rootId ?? null) !== (job.rootId ?? null));
+        if (bindingChanged && this.running.has(job.id)) {
+            throw new Error("automation is running; wait for it to finish before changing its Session or workspace binding");
+        }
+    }
     stopAll() {
         for (const timer of this.timers.values()) {
             clearTimeout(timer);

package/dist/context/manager.d.ts

@@ -31,7 +31,7 @@ export interface ContextManagerConfig {
  * Injected by the Engine so the ContextManager doesn't depend on LLM directly.
  */
 export type SummarizeFn = (prompt: string, signal?: AbortSignal) => Promise<string>;
-export type CompactStrategy = "micro" | "summary" | "window" | "snip" | "emergency" | "range";
+export type CompactStrategy = "micro" | "summary" | "window" | "snip" | "emergency" | "range" | "notes";
 export type OnCompactFn = (info: {
     strategy: CompactStrategy;
     before: number;
@@ -66,6 +66,10 @@ export declare class ContextManager {
     private toolResultsDir;
     constructor(config?: Partial<ContextManagerConfig>);
     setOnCompact(fn: OnCompactFn): void;
+    /** Reserve one model step for a working note before the normal compact gate. */
+    shouldPrepareNote(messages: Message[]): boolean;
+    /** A persisted notes checkpoint supersedes any cached summary/usage anchor. */
+    recordNotesCompaction(beforeMessages: Message[], afterMessages: Message[]): void;
     /**
      * Record actual token usage from API response.
      * Used for hybrid estimation: actual + estimate for new messages.
@@ -111,7 +115,9 @@ export declare class ContextManager {
      * Async context management — attempts LLM summarization before falling back.
      * Call this when you have access to the LLM (between turns).
      */
-    manageAsync(messages: Message[], signal?: AbortSignal): Promise<Message[]>;
+    manageAsync(messages: Message[], signal?: AbortSignal, options?: {
+        preferNotes?: boolean;
+    }): Promise<Message[]>;
     /**
      * Force maximum compaction, ignoring the ratio gates. This is what a manual
      * `/compact` invokes: the user explicitly asked to shrink NOW, so we don't

package/dist/context/manager.js

@@ -73,6 +73,23 @@ export class ContextManager {
     setOnCompact(fn) {
         this.onCompact = fn;
     }
+    /** Reserve one model step for a working note before the normal compact gate. */
+    shouldPrepareNote(messages) {
+        return this.checkLimits(messages).ratio >= Math.max(0.05, this.config.compactAtRatio - 0.1);
+    }
+    /** A persisted notes checkpoint supersedes any cached summary/usage anchor. */
+    recordNotesCompaction(beforeMessages, afterMessages) {
+        const before = this.estimateTokensHybrid(beforeMessages);
+        this.lastSummary = undefined;
+        this.lastActualTokens = undefined;
+        this.lastActualAtMessageCount = undefined;
+        this.lastActualAnchorEstimate = undefined;
+        this.lastActualRecordedAt = undefined;
+        this.lastActualProvider = undefined;
+        this.lastActualModel = undefined;
+        this.suppressNoOpMicroSummaryUntilCompact = false;
+        this.onCompact?.({ strategy: "notes", before, after: estimateTokens(afterMessages) });
+    }
     /**
      * Record actual token usage from API response.
      * Used for hybrid estimation: actual + estimate for new messages.
@@ -132,8 +149,7 @@ export class ContextManager {
      */
     estimateTokensHybridInfo(messages) {
         const currentEstimate = estimateTokens(messages);
-        if (this.lastActualTokens !== undefined &&
-            this.lastActualAtMessageCount !== undefined) {
+        if (this.lastActualTokens !== undefined && this.lastActualAtMessageCount !== undefined) {
             if (this.lastActualAtMessageCount < messages.length) {
                 const newMessages = messages.slice(this.lastActualAtMessageCount);
                 const newTokens = estimateTokens(newMessages);
@@ -358,7 +374,7 @@ export class ContextManager {
      * Async context management — attempts LLM summarization before falling back.
      * Call this when you have access to the LLM (between turns).
      */
-    async manageAsync(messages, signal) {
+    async manageAsync(messages, signal, options) {
         let result = messages;
         // Tier 0a: Persist large tool_results to disk + replace with preview.
         result = this.persistLargeToolResults(result);
@@ -421,7 +437,7 @@ export class ContextManager {
         const noOpMicroSpinBand = microNoOpAtFloor &&
             ratio >= this.config.microcompactFloorRatio &&
             ratio < this.config.compactAtRatio;
-        const shouldEscalateNoOpMicro = noOpMicroSpinBand && !this.suppressNoOpMicroSummaryUntilCompact;
+        const shouldEscalateNoOpMicro = !options?.preferNotes && noOpMicroSpinBand && !this.suppressNoOpMicroSummaryUntilCompact;
         const snipGate = this.config.maxTokens * this.config.compactAtRatio;
         const windowGate = this.config.maxTokens * (this.config.compactAtRatio + 0.05);
         const emergencyGate = this.config.maxTokens * this.config.summarizeAtRatio;

package/dist/context/notes.d.ts

@@ -0,0 +1,39 @@
+import type { Message, TranscriptEventType } from "../types.js";
+import { Transcript } from "../session/transcript.js";
+export declare const MAX_CONTEXT_NOTE_CHARS = 12000;
+export declare const MAX_CONTEXT_HISTORY_READ_CHARS = 12000;
+export declare const MAX_CONTEXT_HISTORY_RESULTS = 20;
+export interface ContextHistoryEntry {
+    eventId: string;
+    type: TranscriptEventType;
+    turnNumber: number;
+    text: string;
+    truncated: boolean;
+    untrusted: true;
+}
+/**
+ * One session's continuation notes. The model authors text; this class alone
+ * constructs replacement messages and commits them at a completed tool round.
+ */
+export declare class SessionContextNotes {
+    private readonly transcript;
+    private modelBoundaryEventId;
+    private pendingNoteId;
+    constructor(transcript: Transcript);
+    /** Keep the normal tool/turn boundary free of replay work when no switch was requested. */
+    hasPendingRollover(): boolean;
+    /** Call immediately before a model request, before its assistant/tool events. */
+    markModelBoundary(): void;
+    save(text: string): string;
+    /** Queues a switch; the tool call itself must not alter an in-flight batch. */
+    requestRollover(): void;
+    /**
+     * Invoke after all results from the assistant's tool batch have been appended.
+     * Every failure consumes the request and leaves the prior replay unchanged.
+     */
+    applyRollover(currentMessages?: readonly Message[], retainedMessages?: readonly Message[]): Message[] | undefined;
+    private commitRollover;
+    search(query: string, limit?: number, beforeEventId?: string): ContextHistoryEntry[];
+    read(eventId: string): ContextHistoryEntry | undefined;
+    private originalEvents;
+}

package/dist/context/notes.js

@@ -0,0 +1,314 @@
+import { Transcript, hasCompleteContextToolPairs } from "../session/transcript.js";
+import { downgradeImagePayloadsInHistory, estimateTokens } from "./compaction.js";
+import { logger } from "../logging/logger.js";
+export const MAX_CONTEXT_NOTE_CHARS = 12_000;
+export const MAX_CONTEXT_HISTORY_READ_CHARS = 12_000;
+export const MAX_CONTEXT_HISTORY_RESULTS = 20;
+const HISTORY_SNIPPET_CHARS = 600;
+const MODEL_BOUNDARY_EVENT_TYPES = new Set([
+    "message",
+    "tool_use",
+    "tool_result",
+    "summary",
+    "context_transfer",
+    "range_archive",
+    "context_note",
+    "context_checkpoint",
+]);
+/**
+ * One session's continuation notes. The model authors text; this class alone
+ * constructs replacement messages and commits them at a completed tool round.
+ */
+export class SessionContextNotes {
+    transcript;
+    modelBoundaryEventId;
+    pendingNoteId;
+    constructor(transcript) {
+        this.transcript = transcript;
+    }
+    /** Keep the normal tool/turn boundary free of replay work when no switch was requested. */
+    hasPendingRollover() {
+        return this.pendingNoteId !== undefined;
+    }
+    /** Call immediately before a model request, before its assistant/tool events. */
+    markModelBoundary() {
+        const events = this.transcript.getEvents();
+        // Skip audit-only receipts/metadata: forks intentionally omit those, and
+        // they do not represent any additional text the model has consumed.
+        const index = findLastEventIndex(events, (event) => MODEL_BOUNDARY_EVENT_TYPES.has(event.type));
+        this.modelBoundaryEventId = events[index]?.id;
+    }
+    save(text) {
+        if (typeof text !== "string" || text.trim().length === 0) {
+            throw new Error("A continuation note must contain non-empty text.");
+        }
+        if (text.length > MAX_CONTEXT_NOTE_CHARS) {
+            throw new Error(`A continuation note must not exceed ${MAX_CONTEXT_NOTE_CHARS} characters.`);
+        }
+        const cursor = this.modelBoundaryEventId;
+        if (!cursor || !this.transcript.getEvents().some((event) => event.id === cursor)) {
+            throw new Error("No model context boundary is available for this note.");
+        }
+        const note = this.transcript.appendContextNote(text, cursor);
+        if (!note)
+            throw new Error("The continuation note could not be saved; context was preserved.");
+        return note.id;
+    }
+    /** Queues a switch; the tool call itself must not alter an in-flight batch. */
+    requestRollover() {
+        const events = this.transcript.getEvents();
+        const noteIndex = findLastEventIndex(events, (event) => event.type === "context_note");
+        const note = events[noteIndex];
+        if (!note || !validNote(note)) {
+            throw new Error("Save a continuation note before starting a new context.");
+        }
+        if (events.slice(noteIndex + 1).some((event) => event.type === "context_checkpoint")) {
+            throw new Error("This note has already been used. Save a fresh continuation note first.");
+        }
+        if (this.transcript.flushFailed()) {
+            throw new Error("Transcript persistence is unavailable; the current context was preserved.");
+        }
+        this.pendingNoteId = note.id;
+    }
+    /**
+     * Invoke after all results from the assistant's tool batch have been appended.
+     * Every failure consumes the request and leaves the prior replay unchanged.
+     */
+    applyRollover(currentMessages, retainedMessages = []) {
+        const noteId = this.pendingNoteId;
+        this.pendingNoteId = undefined;
+        if (!noteId || this.transcript.flushFailed())
+            return undefined;
+        try {
+            return this.commitRollover(noteId, currentMessages, retainedMessages);
+        }
+        catch (error) {
+            logger.warn("context.notes.rollover_failed", {
+                noteId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    }
+    commitRollover(noteId, currentMessages, retainedMessages = []) {
+        const events = this.transcript.getEvents();
+        const noteIndex = events.findIndex((event) => event.id === noteId);
+        const note = events[noteIndex];
+        if (!note || !validNote(note))
+            return undefined;
+        if (events.slice(noteIndex + 1).some((event) => event.type === "context_checkpoint")) {
+            return undefined;
+        }
+        const cursor = note.data.coveredThroughEventId;
+        const boundaryIndex = events.findIndex((event) => event.id === cursor);
+        if (boundaryIndex < 0 || boundaryIndex >= noteIndex)
+            return undefined;
+        const tail = events.slice(boundaryIndex + 1);
+        // A misplaced boundary must not silently discard a late result whose
+        // opening call was before that boundary. Normal model boundaries never
+        // split a batch, but interrupted or corrupt transcripts can do so.
+        const tailToolIds = new Set();
+        for (const event of tail) {
+            if (event.type !== "message" || event.data.role !== "assistant")
+                continue;
+            if (!Array.isArray(event.data.content))
+                continue;
+            for (const block of event.data.content) {
+                if (block.type === "tool_use" && block.id)
+                    tailToolIds.add(block.id);
+            }
+        }
+        if (tail.some((event) => event.type === "tool_result" &&
+            (typeof event.data.toolCallId !== "string" || !tailToolIds.has(event.data.toolCallId))))
+            return undefined;
+        const latestUserIndex = findLastEventIndex(events, isRealUserMessage);
+        const latestUser = events[latestUserIndex];
+        const noteMessage = {
+            id: `continuation:${note.id}`,
+            type: "message",
+            turnNumber: note.turnNumber,
+            timestamp: note.timestamp,
+            data: {
+                role: "user",
+                injected: true,
+                authority: "agent",
+                content: "<context-note>\nThe runtime has started a new context in this same session using this note. " +
+                    "Continue the existing task; do not request another NewContext for this already-used note.\n" +
+                    "Continuation notes written earlier by the assistant. " +
+                    "These notes may be incomplete; consult the original session history for details.\n\n" +
+                    `${note.data.text}\n</context-note>`,
+            },
+        };
+        const rebuilt = Transcript.fromMemoryEvents("context-note-candidate", [
+            noteMessage,
+            ...(latestUser && latestUserIndex <= boundaryIndex ? [latestUser] : []),
+            ...tail,
+        ]).toMessagesWithIndex();
+        const current = currentMessages ?? this.transcript.toMessages();
+        // Carry forward already-budgeted tool outputs from the working context.
+        // Replaying raw events must not resurrect a large result or consumed image.
+        const liveResults = new Map();
+        for (const message of current) {
+            if (!Array.isArray(message.content))
+                continue;
+            for (const block of message.content) {
+                if (block.type === "tool_result" && block.tool_use_id) {
+                    liveResults.set(block.tool_use_id, block);
+                }
+            }
+        }
+        const snapshotMessages = downgradeImagePayloadsInHistory(rebuilt.messages.map((message) => ({
+            ...message,
+            content: Array.isArray(message.content)
+                ? message.content.map((block) => block.type === "tool_result" &&
+                    block.tool_use_id &&
+                    liveResults.has(block.tool_use_id)
+                    ? structuredClone(liveResults.get(block.tool_use_id))
+                    : block)
+                : message.content,
+        }))).messages;
+        if (!hasCompleteContextToolPairs(snapshotMessages))
+            return undefined;
+        // A stale note, or a prior emergency summary, can make this candidate
+        // larger than the live model context. Never replace it in that case.
+        if (estimateTokens([...retainedMessages, ...snapshotMessages]) >= estimateTokens([...current])) {
+            return undefined;
+        }
+        const checkpoint = this.transcript.appendContextCheckpoint({
+            version: 1,
+            noteId,
+            coveredThroughEventId: cursor,
+            messages: snapshotMessages,
+            clientMessageIds: [...rebuilt.liveIndexByClientMessageId],
+        });
+        return checkpoint ? snapshotMessages : undefined;
+    }
+    search(query, limit = 10, beforeEventId) {
+        if (typeof query !== "string" || !query.trim()) {
+            throw new Error("History search requires a non-empty query.");
+        }
+        if (query.length > MAX_CONTEXT_HISTORY_READ_CHARS) {
+            throw new Error("History search query is too long.");
+        }
+        const count = Math.min(MAX_CONTEXT_HISTORY_RESULTS, Math.max(1, Math.floor(limit)));
+        if (!Number.isFinite(count))
+            throw new Error("History search limit must be a finite number.");
+        const events = this.originalEvents();
+        const beforeIndex = beforeEventId
+            ? events.findIndex((event) => matchesHistoryEventId(event, beforeEventId))
+            : events.length;
+        if (beforeIndex < 0)
+            throw new Error("History cursor does not belong to this session.");
+        const needle = query.trim().toLocaleLowerCase();
+        const entries = [];
+        for (let index = beforeIndex - 1; index >= 0 && entries.length < count; index -= 1) {
+            const event = events[index];
+            const text = historyText(event);
+            if (!text)
+                continue;
+            const match = text.toLocaleLowerCase().indexOf(needle);
+            if (match < 0)
+                continue;
+            const start = Math.max(0, match - Math.floor(HISTORY_SNIPPET_CHARS / 3));
+            entries.push(historyEntry(event, text, start, HISTORY_SNIPPET_CHARS));
+        }
+        return entries;
+    }
+    read(eventId) {
+        const event = this.originalEvents().find((candidate) => matchesHistoryEventId(candidate, eventId));
+        if (!event)
+            return undefined;
+        const text = historyText(event);
+        return text === undefined
+            ? undefined
+            : historyEntry(event, text, 0, MAX_CONTEXT_HISTORY_READ_CHARS);
+    }
+    originalEvents() {
+        // Active transcripts can be loaded from a bounded tail. Retrieval uses
+        // only their own file and never accepts a model-supplied path/session id.
+        if (this.transcript.isPersistent()) {
+            const stored = Transcript.readEvents(this.transcript.getFilePath()).events;
+            const seen = new Set(stored.map((event) => event.id));
+            return [...stored, ...this.transcript.getEvents().filter((event) => !seen.has(event.id))];
+        }
+        return this.transcript.getEvents();
+    }
+}
+function findLastEventIndex(events, predicate) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        if (predicate(events[index]))
+            return index;
+    }
+    return -1;
+}
+function validNote(event) {
+    return (event.type === "context_note" &&
+        Boolean(event.data) &&
+        typeof event.data.text === "string" &&
+        event.data.text.trim().length > 0 &&
+        event.data.text.length <= MAX_CONTEXT_NOTE_CHARS &&
+        typeof event.data.coveredThroughEventId === "string");
+}
+function matchesHistoryEventId(event, eventId) {
+    return (event.id === eventId ||
+        (Array.isArray(event.data.contextHistorySourceIds) &&
+            event.data.contextHistorySourceIds.includes(eventId)));
+}
+function isRealUserMessage(event) {
+    return (event.type === "message" &&
+        event.data.role === "user" &&
+        event.data.injected !== true &&
+        (event.data.authority === undefined || event.data.authority === "user"));
+}
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((block) => {
+        if (!block || typeof block !== "object")
+            return "";
+        if (block.type === "text")
+            return block.text ?? "";
+        if (block.type === "image")
+            return "[image]";
+        if (block.type === "tool_use")
+            return `${block.name ?? "tool"}: ${JSON.stringify(block.input)}`;
+        if (block.type === "tool_result")
+            return contentText(block.content);
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+function historyText(event) {
+    switch (event.type) {
+        case "message":
+            return contentText(event.data.content);
+        case "tool_use":
+            return `${event.data.toolName ?? "tool"}: ${JSON.stringify(event.data.args)}`;
+        case "tool_result":
+            return [event.data.error, event.data.result, contentText(event.data.contentBlocks)]
+                .filter((value) => typeof value === "string" && value.length > 0)
+                .join("\n");
+        case "summary":
+        case "context_transfer":
+        case "range_archive":
+            return typeof event.data.summary === "string" ? event.data.summary : undefined;
+        case "context_note":
+            return typeof event.data.text === "string" ? event.data.text : undefined;
+        default:
+            return undefined;
+    }
+}
+function historyEntry(event, text, start, length) {
+    return {
+        eventId: event.id,
+        type: event.type,
+        turnNumber: event.turnNumber,
+        text: text.slice(start, start + length),
+        truncated: start > 0 || text.length > length,
+        untrusted: true,
+    };
+}

package/dist/engine/engine.d.ts

@@ -281,6 +281,7 @@ export declare class Engine {
      * clear "no browser panel" error.
      */
     setBrowserBridge(bridge: import("../tool-system/browser-bridge.js").BrowserBridge | undefined): void;
+    setChildHostBindings(factory: EngineConfig["createChildHostBindings"]): void;
     /** Inject the host-backed workspace bridge after construction. */
     setWorkspaceBridge(bridge: import("../tool-system/workspace-bridge.js").WorkspaceBridge | undefined): void;
     /** Inject the host-backed panel discovery/focus bridge after construction. */
@@ -366,6 +367,7 @@ export declare class Engine {
      * permission-boundary bypass.
      */
     private resolveBehaviorProfile;
+    private resolveContextStrategy;
     private runExclusive;
     /** A receipt write failure must not turn an already finalized model result
      * into a second synthetic failure (or reject the Engine.run contract). */
@@ -614,10 +616,9 @@ export declare class Engine {
     migrateSessionMainRoot(sessionId: string, project: import("../types.js").SessionProjectBinding, mainRoot: string): SessionWorkspace;
     releaseSessionWorkspace(sessionId: string): SessionWorkspace | null;
     injectContext(sessionId: string, content: string): void;
-    /**
-     * Force context compaction on a session.
-     * Returns token stats before/after.
-     */
+    /** Attempt the durable note path without issuing a separate model request. */
+    private tryNotesRollover;
+    /** Force context compaction and return token stats before/after. */
     forceCompact(sessionId?: string): Promise<{
         before: number;
         after: number;