@caplets/core 0.23.0 → 0.24.0

package/dist/cli/code-mode.d.ts

@@ -6,11 +6,14 @@ export type CodeModeCliOptions = {
     inlineCode?: string | undefined;
     file?: string | undefined;
     timeoutMs?: number | undefined;
+    sessionId?: string | undefined;
+    recoveryRef?: string | undefined;
     json?: boolean | undefined;
     readStdin?: (() => Promise<string>) | undefined;
     writeOut: (value: string) => void;
     setExitCode: (code: number) => void;
 };
 export declare function runCodeModeCli(options: CodeModeCliOptions): Promise<void>;
+export declare function runCodeModeReplCli(options: Pick<CodeModeCliOptions, "env" | "configPath" | "projectConfigPath" | "authDir" | "sessionId" | "recoveryRef" | "json" | "writeOut" | "setExitCode">): Promise<void>;
 export declare function codeModeTypesCli(options: Pick<CodeModeCliOptions, "env" | "configPath" | "projectConfigPath" | "authDir" | "json" | "writeOut">): Promise<void>;
 export declare function readCodeModeCliCode(options: Pick<CodeModeCliOptions, "inlineCode" | "file" | "readStdin">): Promise<string>;

package/dist/code-mode/api.d.ts

@@ -1,5 +1,5 @@
 import type { NativeCapletsService } from "../native/service";
-import type { CapletsResult, CodeModeCallableCaplet, Page, PageInput, ReadLogsInput, ReadLogsResult, ToolCallResult } from "./types";
+import type { CapletsResult, CodeModeCallableCaplet, Page, PageInput, ReadCodeModeRecoveryInput, ReadCodeModeRecoveryResult, ReadLogsInput, ReadLogsResult, ToolCallResult } from "./types";
 export type CodeModeCapletHandle = {
     readonly id: string;
     inspect(): Promise<unknown>;
@@ -19,6 +19,7 @@ export type CodeModeCapletHandle = {
 };
 export type CodeModeDebugApi = {
     readLogs(input: ReadLogsInput): Promise<ReadLogsResult>;
+    readRecovery(input: ReadCodeModeRecoveryInput): Promise<ReadCodeModeRecoveryResult>;
 };
 export type CodeModeCapletsApi = {
     [capletId: string]: CodeModeCapletHandle | CodeModeDebugApi | (CodeModeCapletHandle & CodeModeDebugApi);
@@ -27,6 +28,7 @@ export type CodeModeCapletsApi = {
 export type CreateCodeModeCapletsApiInput = {
     service: NativeCapletsService;
     readLogs?: (input: ReadLogsInput) => Promise<ReadLogsResult>;
+    readRecovery?: (input: ReadCodeModeRecoveryInput) => Promise<ReadCodeModeRecoveryResult>;
 };
 export declare function listCodeModeCallableCaplets(service: NativeCapletsService): CodeModeCallableCaplet[];
 export declare function createCodeModeCapletsApi(input: CreateCodeModeCapletsApiInput): CodeModeCapletsApi;

package/dist/code-mode/diagnostics.d.ts

@@ -4,5 +4,13 @@ export type DiagnoseCodeModeTypeScriptInput = {
     declaration: string;
     maxDiagnostics?: number;
     timeoutMs?: number;
+    session?: CodeModeDiagnosticsSession;
 };
 export declare function diagnoseCodeModeTypeScript(input: DiagnoseCodeModeTypeScriptInput): CodeModeDiagnostic[];
+export declare class CodeModeDiagnosticsSession {
+    #private;
+    declaration(): string;
+    recordSuccessfulCell(code: string, declaration?: string): void;
+    clear(): void;
+    private declarationExcluding;
+}

package/dist/code-mode/index.d.ts

@@ -1,3 +1,3 @@
 export { codeModeDeclarationHash, generateCodeModeDeclarations, generateCodeModeRunToolDescription, minifyCodeModeDeclarationText, } from "./declarations";
 export { hasDirectFetchCall, hasExecutableImport } from "./static-analysis";
-export type { CodeModeCallableCaplet, CodeModeDeclarationInput, CodeModeDiagnostic, CodeModeLogEntry, CodeModeLogs, CodeModeRunEnvelope, CodeModeRunError, CodeModeRunMeta, CodeModeTypesJson, JsonPrimitive, JsonValue, ReadLogsInput, ReadLogsResult, ToolCallError, ToolCallMeta, ToolCallResult, } from "./types";
+export type { CodeModeCallableCaplet, CodeModeDeclarationInput, CodeModeDiagnostic, CodeModeLogEntry, CodeModeLogs, CodeModeRecoveryClassification, CodeModeRecoveryEntry, CodeModeRunEnvelope, CodeModeRunError, CodeModeRunMeta, CodeModeSessionStatus, CodeModeTypesJson, JsonPrimitive, JsonValue, ReadCodeModeRecoveryInput, ReadCodeModeRecoveryResult, ReadLogsInput, ReadLogsResult, ToolCallError, ToolCallMeta, ToolCallResult, } from "./types";

package/dist/code-mode/journal.d.ts

@@ -0,0 +1,103 @@
+import type { CodeModeDiagnostic } from "./types";
+export type CodeModeRecoveryClassification = "setup_like" | "side_effecting" | "unknown";
+export type CodeModeJournalOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export type CodeModeJournalEntry = {
+    timestamp: string;
+    code: string;
+    declarationHash: string;
+    outcome: CodeModeJournalOutcome;
+    diagnostics: Array<Pick<CodeModeDiagnostic, "code" | "severity" | "message">>;
+    recoveryClassification: CodeModeRecoveryClassification;
+    logsStored?: boolean;
+    summary?: string;
+};
+export type StoreCodeModeJournalEntryInput = {
+    sessionId: string;
+    journalScope?: string;
+    code: string;
+    declarationHash: string;
+    outcome: CodeModeJournalOutcome;
+    diagnostics: CodeModeDiagnostic[];
+    recoveryClassification: CodeModeRecoveryClassification;
+    logRef?: string;
+    summary?: string;
+};
+export type StoreCodeModeJournalEntryResult = {
+    recoveryRef: string;
+    expiresAt: string;
+    journalKey: string;
+};
+export type ReadCodeModeRecoveryInput = {
+    recoveryRef: string;
+    cursor?: string;
+    limit?: number;
+};
+export type ReadCodeModeRecoveryResult = {
+    entries: CodeModeJournalEntry[];
+    nextCursor?: string;
+};
+export type CodeModeJournalLookupResult = {
+    expiresAt: string;
+    recoveryRef?: string;
+};
+export type CodeModeJournalStoreOptions = {
+    stateDir?: string;
+    now?: () => Date;
+    retentionMs?: number;
+    maxEntries?: number;
+    maxCodeBytes?: number;
+    maxSummaryBytes?: number;
+    secret?: string;
+};
+export declare class CodeModeJournalStore {
+    private readonly stateDir;
+    private readonly now;
+    private readonly retentionMs;
+    private readonly maxEntries;
+    private readonly maxCodeBytes;
+    private readonly maxSummaryBytes;
+    private readonly configuredSecret;
+    private secret;
+    private recoveryRefs;
+    private sessionRecoveryRefs;
+    private nextPruneAt;
+    constructor(options?: CodeModeJournalStoreOptions);
+    store(input: StoreCodeModeJournalEntryInput): Promise<StoreCodeModeJournalEntryResult>;
+    lookupSession(sessionId: string): Promise<CodeModeJournalLookupResult | undefined>;
+    lookupRecoveryRef(recoveryRef: string): Promise<CodeModeJournalLookupResult | undefined>;
+    readRecovery(input: ReadCodeModeRecoveryInput): Promise<ReadCodeModeRecoveryResult>;
+    private entryFromInput;
+    private findByRecoveryRefHash;
+    private findBySessionIdHash;
+    private findByRecoveryRefHashSlow;
+    private findBySessionIdHashSlow;
+    private writeIndex;
+    private readIndexPath;
+    private readJournalPath;
+    private writeJournal;
+    private pruneExpired;
+    private isExpired;
+    private journalKey;
+    private recoveryRefHash;
+    private recoveryRefForJournalKey;
+    private sessionIdHash;
+    private hmac;
+    private loadSecret;
+    private ensureJournalDir;
+    private journalDir;
+    private journalPath;
+    private recoveryIndexPath;
+    private sessionIndexPath;
+    private secretPath;
+}
+export declare function classifyCodeModeRecovery(input: {
+    code: string;
+    invokedCaplet: boolean;
+    sessionDisposedAfterRun?: boolean;
+}): CodeModeRecoveryClassification;

package/dist/code-mode/runner.d.ts

@@ -1,6 +1,8 @@
 import type { NativeCapletsService } from "../native/service";
 import { CodeModeLogStore } from "./logs";
+import { CodeModeJournalStore } from "./journal";
 import { type CodeModeSandbox } from "./sandbox";
+import { type CodeModeSessionManager } from "./sessions";
 import type { CodeModeRunEnvelope } from "./types";
 export type RunCodeModeInput = {
     code: string;
@@ -8,8 +10,11 @@ export type RunCodeModeInput = {
     timeoutMs?: number;
     maxTimeoutMs?: number;
     runtimeScope?: string;
+    sessionId?: string;
     logStore?: CodeModeLogStore;
+    journalStore?: CodeModeJournalStore;
     sandbox?: CodeModeSandbox;
+    sessionManager?: CodeModeSessionManager;
     returnedLogBytes?: number;
 };
 export declare function runCodeMode(input: RunCodeModeInput): Promise<CodeModeRunEnvelope>;

package/dist/code-mode/runtime-api.generated.d.ts

@@ -1 +1 @@
-export declare const CODE_MODE_RUNTIME_API_DECLARATION: "type JsonPrimitive=string|number|boolean|null;type JsonValue=JsonPrimitive|JsonValue[]|{[key:string]:JsonValue};interface CapletHandle<Id extends string>{readonly id:Id;/** Show this Caplet card,without tool/resource/prompt schemas. */ inspect():Promise<CapletCard<Id>>;/** Check backend readiness/auth;expected unavailable states return ok:false. */ check():Promise<CapletsResult<BackendCheckResult>>;/** List tool summaries for the discovery pass;may be empty. */ tools(input?:PageInput):Promise<Page<ToolSummary>>;/** Search tool summaries for the discovery pass;may be empty. */ searchTools(query:string,input?:PageInput):Promise<Page<ToolSummary>>;/** Get schema,callSignature,types,examples;prefer outputSchema/outputTypeScript over observed hints. */ describeTool(name:string):Promise<CapletsResult<ToolDescriptor>>;/** Call one tool;expected failures return ok:false. Filter bulky data in script before returning. */ callTool(name:string,args?:unknown):Promise<CapletsResult<unknown>>;/** List readable resources for the discovery pass;many backends expose none. */ resources(input?:PageInput):Promise<Page<ResourceSummary>>;/** Search readable resources for the discovery pass;many backends expose none. */ searchResources(query:string,input?:PageInput):Promise<Page<ResourceSummary>>;/** List resource templates for the discovery pass;many backends expose none. */ resourceTemplates(input?:PageInput):Promise<Page<ResourceTemplateSummary>>;/** Read one resource by URI;unsupported/missing resources return ok:false. */ readResource(uri:string):Promise<CapletsResult<ResourceReadResult>>;/** List reusable prompts for the discovery pass;many backends expose none. */ prompts(input?:PageInput):Promise<Page<PromptSummary>>;/** Search reusable prompts for the discovery pass;many backends expose none. */ searchPrompts(query:string,input?:PageInput):Promise<Page<PromptSummary>>;/** Get one prompt by name and args;unsupported/missing prompts return ok:false. */ getPrompt(name:string,args?:unknown):Promise<CapletsResult<PromptResult>>;/** Complete a prompt or resource-template argument. */ complete(input:CompleteInput):Promise<CapletsResult<CompleteResult>>;}interface DebugApi{readLogs(input:ReadLogsInput):Promise<ReadLogsResult>;}type CapletCard<Id extends string>={id:Id;name:string;description:string;useWhen?:string;avoidWhen?:string;tags?:string[];backend?:unknown;};type PageInput={limit?:number;cursor?:string};type Page<T>={items:T[];nextCursor?:string;truncated?:boolean};type CapletsResult<T>=|{ok:true;data:T;meta?:CapletsMeta}|{ok:false;error:CapletsError;meta?:CapletsMeta};type CapletsMeta={[key:string]:unknown};type CapletsError={code:string;message:string;details?:unknown};type BackendCheckResult=unknown;type ToolSummary={/** Exact downstream tool identifier for describeTool(name)and callTool(name,args). */ name:string;title?:string;description?:string;/** Optional author-supplied hint for when to prefer this tool. */ useWhen?:string;/** Optional author-supplied hint for when to avoid this tool. */ avoidWhen?:string;/** True when the tool declares that it only reads data. */ readOnlyHint?:boolean;/** True when the tool declares that it may perform destructive writes. */ destructiveHint?:boolean;};type ToolDescriptor={id?:string;tool?:unknown;inputSchema?:unknown;outputSchema?:unknown;callSignature?:string;inputTypeScript?:string;outputTypeScript?:string;observedOutputShape?:ObservedOutputShape;examples?:unknown[];};type ObservedOutputShape={version:1;source:\"observed\";observedAt:string;sampleCount:number;typeScript:string;jsonShape:JsonShape;truncated:boolean;};type JsonShape=|{kind:\"null\"}|{kind:\"boolean\"}|{kind:\"number\"}|{kind:\"string\"}|{kind:\"unknown\"}|{kind:\"array\";element?:JsonShape;truncated?:boolean}|{kind:\"object\";fields:Record<string,{optional:boolean;shape:JsonShape}>;truncated?:boolean;}|{kind:\"union\";variants:JsonShape[]};type ResourceSummary={uri?:string;name?:string;title?:string;description?:string};type ResourceTemplateSummary={uriTemplate?:string;name?:string;title?:string;description?:string;};type ResourceReadResult=unknown;type PromptSummary={name?:string;title?:string;description?:string};type PromptResult=unknown;type CompleteInput={ref:{type:\"prompt\";name:string}|{type:\"resourceTemplate\";uri:string};argument:{name:string;value:string};};type CompleteResult=unknown;type ReadLogsInput={logRef:string;cursor?:string;limit?:number};type ReadLogsResult={entries:CodeModeLogEntry[];nextCursor?:string};type CodeModeLogEntry={level:\"log\"|\"info\"|\"warn\"|\"error\"|\"debug\";message:string;timestamp:string;};interface Console{log(...values:unknown[]):void;info(...values:unknown[]):void;warn(...values:unknown[]):void;error(...values:unknown[]):void;debug(...values:unknown[]):void;}declare const console:Console;";
+export declare const CODE_MODE_RUNTIME_API_DECLARATION: "type JsonPrimitive=string|number|boolean|null;type JsonValue=JsonPrimitive|JsonValue[]|{[key:string]:JsonValue};interface CapletHandle<Id extends string>{readonly id:Id;/** Show this Caplet card,without tool/resource/prompt schemas. */ inspect():Promise<CapletCard<Id>>;/** Check backend readiness/auth;expected unavailable states return ok:false. */ check():Promise<CapletsResult<BackendCheckResult>>;/** List tool summaries for the discovery pass;may be empty. */ tools(input?:PageInput):Promise<Page<ToolSummary>>;/** Search tool summaries for the discovery pass;may be empty. */ searchTools(query:string,input?:PageInput):Promise<Page<ToolSummary>>;/** Get schema,callSignature,types,examples;prefer outputSchema/outputTypeScript over observed hints. */ describeTool(name:string):Promise<CapletsResult<ToolDescriptor>>;/** Call one tool;expected failures return ok:false. Filter bulky data in script before returning. */ callTool(name:string,args?:unknown):Promise<CapletsResult<unknown>>;/** List readable resources for the discovery pass;many backends expose none. */ resources(input?:PageInput):Promise<Page<ResourceSummary>>;/** Search readable resources for the discovery pass;many backends expose none. */ searchResources(query:string,input?:PageInput):Promise<Page<ResourceSummary>>;/** List resource templates for the discovery pass;many backends expose none. */ resourceTemplates(input?:PageInput):Promise<Page<ResourceTemplateSummary>>;/** Read one resource by URI;unsupported/missing resources return ok:false. */ readResource(uri:string):Promise<CapletsResult<ResourceReadResult>>;/** List reusable prompts for the discovery pass;many backends expose none. */ prompts(input?:PageInput):Promise<Page<PromptSummary>>;/** Search reusable prompts for the discovery pass;many backends expose none. */ searchPrompts(query:string,input?:PageInput):Promise<Page<PromptSummary>>;/** Get one prompt by name and args;unsupported/missing prompts return ok:false. */ getPrompt(name:string,args?:unknown):Promise<CapletsResult<PromptResult>>;/** Complete a prompt or resource-template argument. */ complete(input:CompleteInput):Promise<CapletsResult<CompleteResult>>;}interface DebugApi{readLogs(input:ReadLogsInput):Promise<ReadLogsResult>;readRecovery(input:ReadCodeModeRecoveryInput):Promise<ReadCodeModeRecoveryResult>;}type CapletCard<Id extends string>={id:Id;name:string;description:string;useWhen?:string;avoidWhen?:string;tags?:string[];backend?:unknown;};type PageInput={limit?:number;cursor?:string};type Page<T>={items:T[];nextCursor?:string;truncated?:boolean};type CapletsResult<T>=|{ok:true;data:T;meta?:CapletsMeta}|{ok:false;error:CapletsError;meta?:CapletsMeta};type CapletsMeta={[key:string]:unknown};type CapletsError={code:string;message:string;details?:unknown};type BackendCheckResult=unknown;type ToolSummary={/** Exact downstream tool identifier for describeTool(name)and callTool(name,args). */ name:string;title?:string;description?:string;/** Optional author-supplied hint for when to prefer this tool. */ useWhen?:string;/** Optional author-supplied hint for when to avoid this tool. */ avoidWhen?:string;/** True when the tool declares that it only reads data. */ readOnlyHint?:boolean;/** True when the tool declares that it may perform destructive writes. */ destructiveHint?:boolean;};type ToolDescriptor={id?:string;tool?:unknown;inputSchema?:unknown;outputSchema?:unknown;callSignature?:string;inputTypeScript?:string;outputTypeScript?:string;observedOutputShape?:ObservedOutputShape;examples?:unknown[];};type ObservedOutputShape={version:1;source:\"observed\";observedAt:string;sampleCount:number;typeScript:string;jsonShape:JsonShape;truncated:boolean;};type JsonShape=|{kind:\"null\"}|{kind:\"boolean\"}|{kind:\"number\"}|{kind:\"string\"}|{kind:\"unknown\"}|{kind:\"array\";element?:JsonShape;truncated?:boolean}|{kind:\"object\";fields:Record<string,{optional:boolean;shape:JsonShape}>;truncated?:boolean;}|{kind:\"union\";variants:JsonShape[]};type ResourceSummary={uri?:string;name?:string;title?:string;description?:string};type ResourceTemplateSummary={uriTemplate?:string;name?:string;title?:string;description?:string;};type ResourceReadResult=unknown;type PromptSummary={name?:string;title?:string;description?:string};type PromptResult=unknown;type CompleteInput={ref:{type:\"prompt\";name:string}|{type:\"resourceTemplate\";uri:string};argument:{name:string;value:string};};type CompleteResult=unknown;type ReadLogsInput={logRef:string;cursor?:string;limit?:number};type ReadLogsResult={entries:CodeModeLogEntry[];nextCursor?:string};type ReadCodeModeRecoveryInput={recoveryRef:string;cursor?:string;limit?:number};type CodeModeDiagnostic={code:string;message:string;severity:\"error\"|\"warning\"|\"info\";line?:number;column?:number;};type CodeModeRecoveryClassification=\"setup_like\"|\"side_effecting\"|\"unknown\";type CodeModeRecoveryEntry={timestamp:string;code:string;declarationHash:string;outcome:{ok:true}|{ok:false;code:string;message:string};diagnostics:Array<Pick<CodeModeDiagnostic,\"code\"|\"severity\"|\"message\">>;recoveryClassification:CodeModeRecoveryClassification;logsStored?:boolean;summary?:string;};type ReadCodeModeRecoveryResult={entries:CodeModeRecoveryEntry[];nextCursor?:string};type CodeModeLogEntry={level:\"log\"|\"info\"|\"warn\"|\"error\"|\"debug\";message:string;timestamp:string;};type CodeModeSessionStatus=\"created\"|\"reused\";type CodeModeRunMeta={runId:string;traceId:string;declarationHash:string;durationMs:number;timeoutMs:number;maxTimeoutMs:number;sessionId?:string|null;sessionStatus?:CodeModeSessionStatus|null;recoveryRef?:string|null;};interface Console{log(...values:unknown[]):void;info(...values:unknown[]):void;warn(...values:unknown[]):void;error(...values:unknown[]):void;debug(...values:unknown[]):void;}declare const console:Console;";

package/dist/code-mode/sandbox.d.ts

@@ -1,7 +1,8 @@
+import { type QuickJSRuntime } from "quickjs-emscripten";
 import type { CodeModeLogEntry } from "./types";
 export type CodeModeSandboxInvokeInput = {
     capletId: string;
-    method: "inspect" | "check" | "tools" | "searchTools" | "describeTool" | "callTool" | "resources" | "searchResources" | "resourceTemplates" | "readResource" | "prompts" | "searchPrompts" | "getPrompt" | "complete" | "readLogs";
+    method: "inspect" | "check" | "tools" | "searchTools" | "describeTool" | "callTool" | "resources" | "searchResources" | "resourceTemplates" | "readResource" | "prompts" | "searchPrompts" | "getPrompt" | "complete" | "readLogs" | "readRecovery";
     args: unknown[];
 };
 export type CodeModeSandboxInput = {
@@ -23,6 +24,18 @@ export type CodeModeSandboxResult = {
 export interface CodeModeSandbox {
     run(input: CodeModeSandboxInput): Promise<CodeModeSandboxResult>;
 }
+export interface CodeModeReplSession extends CodeModeSandbox {
+    dispose(): void;
+    isDisposed(): boolean;
+}
 export declare class QuickJsCodeModeSandbox implements CodeModeSandbox {
     run(input: CodeModeSandboxInput): Promise<CodeModeSandboxResult>;
+    createSession(): Promise<QuickJsCodeModeReplSession>;
+}
+export declare class QuickJsCodeModeReplSession implements CodeModeReplSession {
+    #private;
+    constructor(runtime: QuickJSRuntime);
+    run(input: CodeModeSandboxInput): Promise<CodeModeSandboxResult>;
+    dispose(): void;
+    isDisposed(): boolean;
 }

package/dist/code-mode/sessions.d.ts

@@ -0,0 +1,53 @@
+import { type CodeModeReplSession, type CodeModeSandboxResult, type CodeModeSandboxInput } from "./sandbox";
+import { CodeModeDiagnosticsSession } from "./diagnostics";
+import type { CodeModeSessionStatus } from "./types";
+export declare const CODE_MODE_SESSION_COMPATIBILITY_VERSION = 1;
+export declare const DEFAULT_CODE_MODE_SESSION_TTL_MS: number;
+export declare const DEFAULT_CODE_MODE_SESSION_LIMIT = 32;
+export type CodeModeSessionCompatibility = {
+    declarationHash: string;
+    platformRuntimeHash: string;
+    runtimeScope: string;
+    version?: number;
+};
+export type CodeModeSessionRunInput = CodeModeSandboxInput & {
+    sessionId?: string;
+    compatibility: CodeModeSessionCompatibility;
+    onSuccessfulCell?: (sessionId: string, code: string) => void;
+};
+export type CodeModeSessionRunResult = {
+    ok: true;
+    sessionId: string;
+    sessionStatus: CodeModeSessionStatus;
+    sessionDisposedAfterRun: boolean;
+    compatibilityKey: string;
+    result: CodeModeSandboxResult;
+} | {
+    ok: false;
+    sessionId: string;
+    sessionStatus: null;
+    error: "not_found" | "busy" | "closed";
+};
+export type CodeModeSessionManagerOptions = {
+    idGenerator?: () => string;
+    now?: () => number;
+    ttlMs?: number;
+    maxSessions?: number;
+    sandboxFactory?: () => CodeModeReplSessionFactory;
+};
+export type CodeModeReplSessionFactory = {
+    createSession(): Promise<CodeModeReplSession>;
+};
+export declare class CodeModeSessionManager {
+    #private;
+    readonly ttlMs: number;
+    readonly maxSessions: number;
+    constructor(options?: CodeModeSessionManagerOptions);
+    run(input: CodeModeSessionRunInput): Promise<CodeModeSessionRunResult>;
+    close(): void;
+    has(sessionId: string): boolean;
+    compatibilityKey(sessionId: string): string | undefined;
+    diagnosticsSession(sessionId: string, compatibility: CodeModeSessionCompatibility): CodeModeDiagnosticsSession | undefined;
+    isBusy(sessionId: string, compatibility: CodeModeSessionCompatibility): boolean;
+    recordSuccessfulCell(sessionId: string, code: string, declaration?: string): void;
+}

package/dist/code-mode/tool.d.ts

@@ -1,11 +1,16 @@
 import { z } from "zod";
+import type { CodeModeRunMeta } from "./types";
+export declare const CODE_MODE_SESSION_ID_DESCRIPTION = "Optional Code Mode session identifier. Omit to create a fresh reusable session; pass a known live session ID from meta.sessionId to reuse existing REPL state. Unknown or unavailable session IDs fail before code execution instead of starting an empty context.";
 export declare const codeModeRunInputSchema: z.ZodObject<{
     code: z.ZodString;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
+    sessionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const codeModeRunParamsSchema: {
     code: z.ZodString;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
+    sessionId: z.ZodOptional<z.ZodString>;
 };
 export declare function codeModeRunInputJsonSchema(): Record<string, unknown>;
 export declare function isCodeModeRunRequest(value: unknown): boolean;
+export declare function emptyCodeModeRunMeta(): CodeModeRunMeta;

package/dist/code-mode/types.d.ts

@@ -27,6 +27,7 @@ export type CodeModeDiagnostic = {
     line?: number;
     column?: number;
 };
+export type CodeModeSessionStatus = "created" | "reused";
 export type CodeModeRunMeta = {
     runId: string;
     traceId: string;
@@ -34,6 +35,9 @@ export type CodeModeRunMeta = {
     durationMs: number;
     timeoutMs: number;
     maxTimeoutMs: number;
+    sessionId?: string | null;
+    sessionStatus?: CodeModeSessionStatus | null;
+    recoveryRef?: string | null;
 };
 export type CodeModeRunError = {
     code: string;
@@ -119,3 +123,29 @@ export type ReadLogsResult = {
     entries: CodeModeLogEntry[];
     nextCursor?: string;
 };
+export type ReadCodeModeRecoveryInput = {
+    recoveryRef: string;
+    cursor?: string;
+    limit?: number;
+};
+export type CodeModeRecoveryClassification = "setup_like" | "side_effecting" | "unknown";
+export type CodeModeRecoveryEntry = {
+    timestamp: string;
+    code: string;
+    declarationHash: string;
+    outcome: {
+        ok: true;
+    } | {
+        ok: false;
+        code: string;
+        message: string;
+    };
+    diagnostics: Array<Pick<CodeModeDiagnostic, "code" | "severity" | "message">>;
+    recoveryClassification: CodeModeRecoveryClassification;
+    logsStored?: boolean;
+    summary?: string;
+};
+export type ReadCodeModeRecoveryResult = {
+    entries: CodeModeRecoveryEntry[];
+    nextCursor?: string;
+};

package/dist/code-mode.js

@@ -2,11 +2,12 @@
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
 //#region src/code-mode/runtime-api.generated.ts
-const CODE_MODE_RUNTIME_API_DECLARATION = "type JsonPrimitive=string|number|boolean|null;type JsonValue=JsonPrimitive|JsonValue[]|{[key:string]:JsonValue};interface CapletHandle<Id extends string>{readonly id:Id;/** Show this Caplet card,without tool/resource/prompt schemas. */ inspect():Promise<CapletCard<Id>>;/** Check backend readiness/auth;expected unavailable states return ok:false. */ check():Promise<CapletsResult<BackendCheckResult>>;/** List tool summaries for the discovery pass;may be empty. */ tools(input?:PageInput):Promise<Page<ToolSummary>>;/** Search tool summaries for the discovery pass;may be empty. */ searchTools(query:string,input?:PageInput):Promise<Page<ToolSummary>>;/** Get schema,callSignature,types,examples;prefer outputSchema/outputTypeScript over observed hints. */ describeTool(name:string):Promise<CapletsResult<ToolDescriptor>>;/** Call one tool;expected failures return ok:false. Filter bulky data in script before returning. */ callTool(name:string,args?:unknown):Promise<CapletsResult<unknown>>;/** List readable resources for the discovery pass;many backends expose none. */ resources(input?:PageInput):Promise<Page<ResourceSummary>>;/** Search readable resources for the discovery pass;many backends expose none. */ searchResources(query:string,input?:PageInput):Promise<Page<ResourceSummary>>;/** List resource templates for the discovery pass;many backends expose none. */ resourceTemplates(input?:PageInput):Promise<Page<ResourceTemplateSummary>>;/** Read one resource by URI;unsupported/missing resources return ok:false. */ readResource(uri:string):Promise<CapletsResult<ResourceReadResult>>;/** List reusable prompts for the discovery pass;many backends expose none. */ prompts(input?:PageInput):Promise<Page<PromptSummary>>;/** Search reusable prompts for the discovery pass;many backends expose none. */ searchPrompts(query:string,input?:PageInput):Promise<Page<PromptSummary>>;/** Get one prompt by name and args;unsupported/missing prompts return ok:false. */ getPrompt(name:string,args?:unknown):Promise<CapletsResult<PromptResult>>;/** Complete a prompt or resource-template argument. */ complete(input:CompleteInput):Promise<CapletsResult<CompleteResult>>;}interface DebugApi{readLogs(input:ReadLogsInput):Promise<ReadLogsResult>;}type CapletCard<Id extends string>={id:Id;name:string;description:string;useWhen?:string;avoidWhen?:string;tags?:string[];backend?:unknown;};type PageInput={limit?:number;cursor?:string};type Page<T>={items:T[];nextCursor?:string;truncated?:boolean};type CapletsResult<T>=|{ok:true;data:T;meta?:CapletsMeta}|{ok:false;error:CapletsError;meta?:CapletsMeta};type CapletsMeta={[key:string]:unknown};type CapletsError={code:string;message:string;details?:unknown};type BackendCheckResult=unknown;type ToolSummary={/** Exact downstream tool identifier for describeTool(name)and callTool(name,args). */ name:string;title?:string;description?:string;/** Optional author-supplied hint for when to prefer this tool. */ useWhen?:string;/** Optional author-supplied hint for when to avoid this tool. */ avoidWhen?:string;/** True when the tool declares that it only reads data. */ readOnlyHint?:boolean;/** True when the tool declares that it may perform destructive writes. */ destructiveHint?:boolean;};type ToolDescriptor={id?:string;tool?:unknown;inputSchema?:unknown;outputSchema?:unknown;callSignature?:string;inputTypeScript?:string;outputTypeScript?:string;observedOutputShape?:ObservedOutputShape;examples?:unknown[];};type ObservedOutputShape={version:1;source:\"observed\";observedAt:string;sampleCount:number;typeScript:string;jsonShape:JsonShape;truncated:boolean;};type JsonShape=|{kind:\"null\"}|{kind:\"boolean\"}|{kind:\"number\"}|{kind:\"string\"}|{kind:\"unknown\"}|{kind:\"array\";element?:JsonShape;truncated?:boolean}|{kind:\"object\";fields:Record<string,{optional:boolean;shape:JsonShape}>;truncated?:boolean;}|{kind:\"union\";variants:JsonShape[]};type ResourceSummary={uri?:string;name?:string;title?:string;description?:string};type ResourceTemplateSummary={uriTemplate?:string;name?:string;title?:string;description?:string;};type ResourceReadResult=unknown;type PromptSummary={name?:string;title?:string;description?:string};type PromptResult=unknown;type CompleteInput={ref:{type:\"prompt\";name:string}|{type:\"resourceTemplate\";uri:string};argument:{name:string;value:string};};type CompleteResult=unknown;type ReadLogsInput={logRef:string;cursor?:string;limit?:number};type ReadLogsResult={entries:CodeModeLogEntry[];nextCursor?:string};type CodeModeLogEntry={level:\"log\"|\"info\"|\"warn\"|\"error\"|\"debug\";message:string;timestamp:string;};interface Console{log(...values:unknown[]):void;info(...values:unknown[]):void;warn(...values:unknown[]):void;error(...values:unknown[]):void;debug(...values:unknown[]):void;}declare const console:Console;";
+const CODE_MODE_RUNTIME_API_DECLARATION = "type JsonPrimitive=string|number|boolean|null;type JsonValue=JsonPrimitive|JsonValue[]|{[key:string]:JsonValue};interface CapletHandle<Id extends string>{readonly id:Id;/** Show this Caplet card,without tool/resource/prompt schemas. */ inspect():Promise<CapletCard<Id>>;/** Check backend readiness/auth;expected unavailable states return ok:false. */ check():Promise<CapletsResult<BackendCheckResult>>;/** List tool summaries for the discovery pass;may be empty. */ tools(input?:PageInput):Promise<Page<ToolSummary>>;/** Search tool summaries for the discovery pass;may be empty. */ searchTools(query:string,input?:PageInput):Promise<Page<ToolSummary>>;/** Get schema,callSignature,types,examples;prefer outputSchema/outputTypeScript over observed hints. */ describeTool(name:string):Promise<CapletsResult<ToolDescriptor>>;/** Call one tool;expected failures return ok:false. Filter bulky data in script before returning. */ callTool(name:string,args?:unknown):Promise<CapletsResult<unknown>>;/** List readable resources for the discovery pass;many backends expose none. */ resources(input?:PageInput):Promise<Page<ResourceSummary>>;/** Search readable resources for the discovery pass;many backends expose none. */ searchResources(query:string,input?:PageInput):Promise<Page<ResourceSummary>>;/** List resource templates for the discovery pass;many backends expose none. */ resourceTemplates(input?:PageInput):Promise<Page<ResourceTemplateSummary>>;/** Read one resource by URI;unsupported/missing resources return ok:false. */ readResource(uri:string):Promise<CapletsResult<ResourceReadResult>>;/** List reusable prompts for the discovery pass;many backends expose none. */ prompts(input?:PageInput):Promise<Page<PromptSummary>>;/** Search reusable prompts for the discovery pass;many backends expose none. */ searchPrompts(query:string,input?:PageInput):Promise<Page<PromptSummary>>;/** Get one prompt by name and args;unsupported/missing prompts return ok:false. */ getPrompt(name:string,args?:unknown):Promise<CapletsResult<PromptResult>>;/** Complete a prompt or resource-template argument. */ complete(input:CompleteInput):Promise<CapletsResult<CompleteResult>>;}interface DebugApi{readLogs(input:ReadLogsInput):Promise<ReadLogsResult>;readRecovery(input:ReadCodeModeRecoveryInput):Promise<ReadCodeModeRecoveryResult>;}type CapletCard<Id extends string>={id:Id;name:string;description:string;useWhen?:string;avoidWhen?:string;tags?:string[];backend?:unknown;};type PageInput={limit?:number;cursor?:string};type Page<T>={items:T[];nextCursor?:string;truncated?:boolean};type CapletsResult<T>=|{ok:true;data:T;meta?:CapletsMeta}|{ok:false;error:CapletsError;meta?:CapletsMeta};type CapletsMeta={[key:string]:unknown};type CapletsError={code:string;message:string;details?:unknown};type BackendCheckResult=unknown;type ToolSummary={/** Exact downstream tool identifier for describeTool(name)and callTool(name,args). */ name:string;title?:string;description?:string;/** Optional author-supplied hint for when to prefer this tool. */ useWhen?:string;/** Optional author-supplied hint for when to avoid this tool. */ avoidWhen?:string;/** True when the tool declares that it only reads data. */ readOnlyHint?:boolean;/** True when the tool declares that it may perform destructive writes. */ destructiveHint?:boolean;};type ToolDescriptor={id?:string;tool?:unknown;inputSchema?:unknown;outputSchema?:unknown;callSignature?:string;inputTypeScript?:string;outputTypeScript?:string;observedOutputShape?:ObservedOutputShape;examples?:unknown[];};type ObservedOutputShape={version:1;source:\"observed\";observedAt:string;sampleCount:number;typeScript:string;jsonShape:JsonShape;truncated:boolean;};type JsonShape=|{kind:\"null\"}|{kind:\"boolean\"}|{kind:\"number\"}|{kind:\"string\"}|{kind:\"unknown\"}|{kind:\"array\";element?:JsonShape;truncated?:boolean}|{kind:\"object\";fields:Record<string,{optional:boolean;shape:JsonShape}>;truncated?:boolean;}|{kind:\"union\";variants:JsonShape[]};type ResourceSummary={uri?:string;name?:string;title?:string;description?:string};type ResourceTemplateSummary={uriTemplate?:string;name?:string;title?:string;description?:string;};type ResourceReadResult=unknown;type PromptSummary={name?:string;title?:string;description?:string};type PromptResult=unknown;type CompleteInput={ref:{type:\"prompt\";name:string}|{type:\"resourceTemplate\";uri:string};argument:{name:string;value:string};};type CompleteResult=unknown;type ReadLogsInput={logRef:string;cursor?:string;limit?:number};type ReadLogsResult={entries:CodeModeLogEntry[];nextCursor?:string};type ReadCodeModeRecoveryInput={recoveryRef:string;cursor?:string;limit?:number};type CodeModeDiagnostic={code:string;message:string;severity:\"error\"|\"warning\"|\"info\";line?:number;column?:number;};type CodeModeRecoveryClassification=\"setup_like\"|\"side_effecting\"|\"unknown\";type CodeModeRecoveryEntry={timestamp:string;code:string;declarationHash:string;outcome:{ok:true}|{ok:false;code:string;message:string};diagnostics:Array<Pick<CodeModeDiagnostic,\"code\"|\"severity\"|\"message\">>;recoveryClassification:CodeModeRecoveryClassification;logsStored?:boolean;summary?:string;};type ReadCodeModeRecoveryResult={entries:CodeModeRecoveryEntry[];nextCursor?:string};type CodeModeLogEntry={level:\"log\"|\"info\"|\"warn\"|\"error\"|\"debug\";message:string;timestamp:string;};type CodeModeSessionStatus=\"created\"|\"reused\";type CodeModeRunMeta={runId:string;traceId:string;declarationHash:string;durationMs:number;timeoutMs:number;maxTimeoutMs:number;sessionId?:string|null;sessionStatus?:CodeModeSessionStatus|null;recoveryRef?:string|null;};interface Console{log(...values:unknown[]):void;info(...values:unknown[]):void;warn(...values:unknown[]):void;error(...values:unknown[]):void;debug(...values:unknown[]):void;}declare const console:Console;";
 //#endregion
 //#region src/code-mode/declarations.ts
 const JS_IDENTIFIER = /^[A-Za-z_$][\w$]*$/u;
 const MAX_JSDOC_CHARS = 180;
+const CODE_MODE_REPL_GUIDANCE = "REPL reuse: omit `sessionId` to start a fresh reusable Code Mode session; after a successful run, keep `meta.sessionId` and pass it as `sessionId` on later calls when you want to reuse live state. Reused sessions preserve successful top-level `var` bindings, function declarations, and runtime state only while the live session remains available and compatible. A supplied `sessionId` that is unknown or no longer available fails before executing your code instead of starting an empty context. Use `meta.recoveryRef` with `caplets.debug.readRecovery({ recoveryRef })` for audit and manual reconstruction; do not automatically replay recovery history.";
 function generateCodeModeDeclarations(input) {
 	const caplets = [...input.caplets].sort((left, right) => left.id.localeCompare(right.id));
 	const properties = caplets.map((caplet) => {
@@ -26,6 +27,7 @@ function generateCodeModeDeclarations(input) {
 function generateCodeModeRunToolDescription(declaration) {
 	return [
 		"Run TypeScript with generated `caplets.<id>` handles and declaration hints below. Prefer a compact one-pass script for most tasks: discover, filter, execute, and synthesize inside Code Mode, then return only decision-ready JSON. Do not return full tool lists, full descriptors, schemas, raw tool payloads, or exploratory transcripts unless the user specifically needs them; keep bulky intermediate data inside the script. For discovery, use tools/searchTools for names and arg hints, then describeTool only for short-listed operations needing exact schemas, nested args, fields, or disambiguation. Never invent tool names, resource URIs, prompt names, input args, output fields, or schemas; use requiredArgs/acceptedArgs for simple calls, otherwise use describeTool for the exact callSignature/inputSchema/inputTypeScript. For fallback, check candidate handles first: `for(const h of candidates){const ready=await h.check();if(!ready.ok)continue;}`. For triage, list broad candidate records and filter in script before targeted searches so adjacent relevant items are not missed. Execute with exact args, handle `{ok:false}`, and derive final recommendations from all relevant records, not the first matching record. If records disagree or have ranges/statuses, compute the strictest applicable conclusion and preserve only the compact evidence used. Return summaries, key ids/names/titles/statuses/urls, derived fields, recommendation, caveats, and residual missing data. Before returning, remove unused descriptors/schemas/raw content. Pattern: `const h=caplets[\"caplet-id\"];const tools=await h.searchTools(\"query\");const d=needSchema?await h.describeTool(\"tool_name\"):undefined;const r=await h.callTool(\"tool_name\",args);return {facts:[...],evidence:[...]};`",
+		CODE_MODE_REPL_GUIDANCE,
 		"",
 		"Generated declaration hints:",
 		"```ts",

package/dist/{completion-BC4BNWo0.js → completion-CzHdM9B_.js}

@@ -1,4 +1,4 @@
-import { $ as loadConfigWithSources, Cn as __exportAll, Dt as resolveProjectConfigPath, Tt as resolveConfigPath, vt as DEFAULT_AUTH_DIR, wt as resolveCapletsRoot, yt as DEFAULT_COMPLETION_CACHE_DIR } from "./service-CSRCJfpA.js";
+import { Dt as resolveConfigPath, Et as resolveCapletsRoot, Tn as __exportAll, bt as DEFAULT_AUTH_DIR, kt as resolveProjectConfigPath, tt as loadConfigWithSources, xt as DEFAULT_COMPLETION_CACHE_DIR } from "./service-BCT_Ls_3.js";
 import { u as CapletsError } from "./validation-DgxCzt-A.js";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";