@nexrall/code-core 1.4.12 → 1.4.14

package/dist/commands/loader.d.ts

@@ -10,9 +10,13 @@ export interface SlashCommand {
 export declare function loadSlashCommands(workDir: string): SlashCommand[];
 export declare function findSlashCommand(cmds: SlashCommand[], name: string): SlashCommand | undefined;
 /**
- * Expand a command body into a final prompt: argument substitution, @file
- * inlining, and !`cmd` shell capture. Shell/file errors are inlined as notes
- * rather than thrown so the prompt is always produced.
+ * Expand a command/skill body into a final prompt: argument substitution,
+ * @file inlining, and !`cmd` shell capture. Shell/file errors are inlined as
+ * notes rather than thrown so the prompt is always produced. Shared by both
+ * SlashCommand (this file) and Skill (agent/skills.ts) — they have the same
+ * `body` shape, just a richer frontmatter set on the Skill side.
  */
+export declare function expandBody(body: string, argString: string, workDir: string): string;
+/** @deprecated kept for backward compatibility — use expandBody(cmd.body, ...) directly. */
 export declare function expandCommand(cmd: SlashCommand, argString: string, workDir: string): string;
 //# sourceMappingURL=loader.d.ts.map

package/dist/commands/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/commands/loader.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;CACrD;AAiFD,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CASjE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAG7F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAuC3F"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/commands/loader.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;CACrD;AAiFD,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CASjE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAG7F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAuCnF;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,GAAG,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3F"}

package/dist/commands/loader.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadSlashCommands = loadSlashCommands;
 exports.findSlashCommand = findSlashCommand;
+exports.expandBody = expandBody;
 exports.expandCommand = expandCommand;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -140,14 +141,16 @@ function findSlashCommand(cmds, name) {
     return cmds.find((c) => c.name === want);
 }
 /**
- * Expand a command body into a final prompt: argument substitution, @file
- * inlining, and !`cmd` shell capture. Shell/file errors are inlined as notes
- * rather than thrown so the prompt is always produced.
+ * Expand a command/skill body into a final prompt: argument substitution,
+ * @file inlining, and !`cmd` shell capture. Shell/file errors are inlined as
+ * notes rather than thrown so the prompt is always produced. Shared by both
+ * SlashCommand (this file) and Skill (agent/skills.ts) — they have the same
+ * `body` shape, just a richer frontmatter set on the Skill side.
  */
-function expandCommand(cmd, argString, workDir) {
+function expandBody(body, argString, workDir) {
     const args = argString.trim();
     const positional = args ? args.split(/\s+/) : [];
-    let out = cmd.body;
+    let out = body;
     // !`shell command` → captured stdout
     out = out.replace(/!`([^`]+)`/g, (_m, c) => {
         try {
@@ -175,9 +178,13 @@ function expandCommand(cmd, argString, workDir) {
     const hadArgsToken = /\$ARGUMENTS/.test(out);
     out = out.replace(/\$ARGUMENTS/g, args);
     // If the template never referenced its args, append them so they aren't lost.
-    if (!hadArgsToken && !/\$\d+/.test(cmd.body) && args) {
+    if (!hadArgsToken && !/\$\d+/.test(body) && args) {
         out = `${out}\n\n${args}`;
     }
     return out.trim();
 }
+/** @deprecated kept for backward compatibility — use expandBody(cmd.body, ...) directly. */
+function expandCommand(cmd, argString, workDir) {
+    return expandBody(cmd.body, argString, workDir);
+}
 //# sourceMappingURL=loader.js.map

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export * from './agent/editCompleteness';
 export * from './agent/crossFile';
 export * from './agent/flaky';
 export * from './agent/claimEvidence';
+export * from './agent/memory';
+export * from './agent/skills';
 export * from './mcp/client';
 export * from './mcp/httpClient';
 export * from './mcp/manager';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -24,6 +24,8 @@ __exportStar(require("./agent/editCompleteness"), exports);
 __exportStar(require("./agent/crossFile"), exports);
 __exportStar(require("./agent/flaky"), exports);
 __exportStar(require("./agent/claimEvidence"), exports);
+__exportStar(require("./agent/memory"), exports);
+__exportStar(require("./agent/skills"), exports);
 __exportStar(require("./mcp/client"), exports);
 __exportStar(require("./mcp/httpClient"), exports);
 __exportStar(require("./mcp/manager"), exports);

package/dist/plugins/index.d.ts

@@ -10,7 +10,7 @@ export interface PluginInfo {
 /** Discover installed plugins (project scope shadows global on name clash). */
 export declare function loadPlugins(workDir: string): PluginInfo[];
 /** Subdirectories of every installed plugin that hold `kind` assets (existing only). */
-export declare function pluginAssetDirs(workDir: string, kind: 'commands' | 'agents'): string[];
+export declare function pluginAssetDirs(workDir: string, kind: 'commands' | 'agents' | 'skills'): string[];
 /** Merge hooks.json from every plugin into a single hooks config (arrays concatenated). */
 export declare function pluginHooks(workDir: string): Record<string, unknown[]>;
 /** MCP server maps declared by plugins: { serverName → config } (first plugin wins on clash). */

package/dist/plugins/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAsCD,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAKzD;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,EAAE,CAMtF;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAetE;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAsCD,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAKzD;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,EAAE,CAMjG;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAetE;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazE"}

package/dist/tools/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/tools/executor.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AA6iEtE,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EAClC,OAAO,CAAC,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAiBrB"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/tools/executor.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAkkEtE,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EAClC,OAAO,CAAC,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAiBrB"}

package/dist/tools/executor.js

@@ -44,6 +44,8 @@ const child_process_1 = require("child_process");
 const sandbox_1 = require("./sandbox");
 const auth_1 = require("../auth");
 const editCompleteness_1 = require("../agent/editCompleteness");
+const memory_1 = require("../agent/memory");
+const skills_1 = require("../agent/skills");
 const testIntegrity_1 = require("../agent/testIntegrity");
 const crossFile_1 = require("../agent/crossFile");
 const client_1 = require("../api/client");
@@ -2028,39 +2030,58 @@ async function stockPhoto(input, workDir) {
     return { output: `Found ${photos.length} photo(s) for "${query}":\n${lines.join('\n')}` };
 }
 // ─── Memory tools ─────────────────────────────────────────────────────────────
-const MEMORY_FILE = path.join(os.homedir(), '.nexrall', 'memory.md');
-async function memoryWrite(input) {
+// Implementation lives in agent/memory.ts (project vs global scope, size caps,
+// LLM-summarizing compaction, file locking) — this is just the tool-call glue.
+function memoryScopeOf(input) {
+    return input.scope === 'global' ? 'global' : 'project';
+}
+async function memoryWrite(input, workDir) {
     const content = typeof input.content === 'string' ? input.content.trim() : '';
     if (!content)
         return { error: 'content is required' };
-    const dir = path.dirname(MEMORY_FILE);
-    fs.mkdirSync(dir, { recursive: true });
-    // Dedup: skip if an entry with the same first 60 chars already exists.
-    // The old check used full substring match which blocked "React + TypeScript"
-    // if "React" was already stored. Now we only deduplicate near-identical entries.
-    if (fs.existsSync(MEMORY_FILE)) {
-        const existing = fs.readFileSync(MEMORY_FILE, 'utf-8').toLowerCase();
-        const fingerprint = content.toLowerCase().slice(0, 60);
-        if (existing.includes(fingerprint)) {
-            return { output: `Memory already recorded (skipped duplicate): ${content}` };
-        }
-    }
-    const timestamp = new Date().toISOString().slice(0, 10);
-    const entry = `\n- [${timestamp}] ${content}`;
-    fs.appendFileSync(MEMORY_FILE, entry, 'utf-8');
-    return { output: `Memory saved: ${content}` };
+    const scope = memoryScopeOf(input);
+    const r = await (0, memory_1.writeMemory)(content, scope, workDir);
+    if (!r.ok)
+        return { error: 'failed to save memory' };
+    return { output: r.already ? `Memory already recorded (skipped duplicate): ${content}` : `Memory saved (${scope}): ${content}` };
 }
-async function memoryRead(_input) {
+async function memoryRead(input, workDir) {
     try {
-        if (!fs.existsSync(MEMORY_FILE))
-            return { output: 'No memories saved yet.' };
-        const content = fs.readFileSync(MEMORY_FILE, 'utf-8').trim();
-        return { output: content || 'No memories saved yet.' };
+        // No explicit scope requested → merge both (what the model actually needs
+        // when re-orienting mid-conversation); an explicit scope narrows to just that file.
+        if (input && (input.scope === 'project' || input.scope === 'global')) {
+            const mem = (0, memory_1.readMemory)(input.scope, workDir);
+            return { output: mem || 'No memories saved yet.' };
+        }
+        const mem = (0, memory_1.readAllMemory)(workDir);
+        return { output: mem || 'No memories saved yet.' };
     }
     catch (err) {
         return { error: err.message };
     }
 }
+// ─── Skills ───────────────────────────────────────────────────────────────────
+//
+// use_skill loads a skill's playbook into context so the model can follow it —
+// same idea as memory_read returning saved notes, just for a named, reusable
+// procedure instead of accumulated learnings. The expanded body (with
+// $ARGUMENTS/@file/!`cmd` substitution already applied) comes back as the tool
+// result; the model then proceeds using its normal tools to carry it out.
+async function useSkill(input, workDir) {
+    const name = typeof input.name === 'string' ? input.name.trim() : '';
+    if (!name)
+        return { error: 'name is required (the skill to invoke)' };
+    const dir = workDir ?? process.cwd();
+    const skills = (0, skills_1.loadSkills)(dir);
+    const skill = (0, skills_1.findSkill)(skills, name);
+    if (!skill) {
+        const known = skills.map((s) => s.name).join(', ') || '(none defined)';
+        return { error: `Unknown skill "${name}". Available: ${known}.` };
+    }
+    const args = typeof input.args === 'string' ? input.args : '';
+    const expanded = (0, skills_1.expandSkill)(skill, args, dir);
+    return { output: `[Skill "${skill.name}" loaded — follow these instructions:]\n\n${expanded}` };
+}
 function semanticPreamble(input, workDir) {
     const p = typeof input.path === 'string' ? input.path : '';
     const line = typeof input.line === 'number' ? Math.floor(input.line) : 0;
@@ -2123,6 +2144,7 @@ const TOOL_MAP = {
     notebook_edit: notebookEdit,
     memory_write: memoryWrite,
     memory_read: memoryRead,
+    use_skill: useSkill,
     bash_output: bashOutput,
     kill_shell: killShell,
     // LSP-lite fallback (regex-based). In VS Code these names are intercepted by
@@ -2144,6 +2166,7 @@ const WORKDIR_TOOLS = new Set([
     'generate_image', 'stock_photo',
     'get_symbols', 'get_workspace_symbols',
     'go_to_definition', 'find_references', 'get_hover',
+    'memory_write', 'memory_read', 'use_skill',
 ]);
 async function executeTool(name, input, abortSignal, sandbox, workDir, agentScope) {
     if (!TOOL_MAP[name])

package/dist/types.d.ts

@@ -46,6 +46,24 @@ export interface SSEMessageCompleteEvent {
 export interface SSEUsageEvent {
     type: 'usage';
     usage: UsageInfo;
+    /**
+     * True when these tokens belong to an attempt that was CUT SHORT (the client
+     * disconnected or the turn was restarted) rather than to the turn's completed
+     * response. They were still billed — the upstream vendor charged for every token
+     * generated before the cut — so this is real spend, but a UI that shows "this
+     * turn's output" should not add it to the successful attempt's count or it will
+     * appear to double-report. Sum it for COST, keep it out of a single turn's token
+     * total. Absent/false for an ordinary completed turn.
+     */
+    partial?: boolean;
+    /**
+     * True when this usage is a RE-REPORT of a turn that was already billed. The previous
+     * attempt completed and was charged, but its `done` never reached the client, so the
+     * client retried and the backend served the stored answer from its turn-idempotency
+     * cache instead of re-invoking the model. No new charge occurred — a cost display must
+     * not add these tokens again. Mutually exclusive with `partial`.
+     */
+    replayed?: boolean;
 }
 export interface SSEDoneEvent {
     type: 'done';
@@ -97,7 +115,40 @@ export interface SSEBalanceStatusEvent {
     balance: number;
     zero: boolean;
 }
-export type SSEEvent = SSETextEvent | SSEToolUseEvent | SSEMessageCompleteEvent | SSEUsageEvent | SSEDoneEvent | SSEErrorEvent | SSEThinkingEvent | SSEThinkingProgressEvent | SSEThinkingDeltaEvent | SSERetryEvent | SSERetryResolvedEvent | SSEBalanceStatusEvent;
+/**
+ * Emitted when a stream attempt died AFTER partial output had already been
+ * rendered, and the network layer is restarting the SAME turn from scratch.
+ *
+ * Unlike `retry` (which only ever fires when nothing was shown yet, so the UI
+ * merely needs a "reconnecting…" hint), this one carries a hard requirement:
+ * the consumer MUST discard the partial assistant output it has rendered for
+ * this turn — the text/thinking streamed so far will be re-sent in full by the
+ * new attempt, so keeping it would duplicate it on screen.
+ *
+ * LOCAL side effects are safe: tool calls are dispatched by the agent loop from
+ * the COMPLETED message, after `streamChat` returns, and a restart means it threw
+ * instead — so no tool ran, no file changed, no checkpoint or hook fired.
+ *
+ * BILLING IS NOT ROLLED BACK, and callers should not assume otherwise. The
+ * backend charges whatever tokens the model produced before the cut (its stream
+ * `abort` handler), because the upstream vendor charged us for them. A restarted
+ * turn therefore costs more than one attempt's worth of tokens — bounded by the
+ * reconnect budget, but real. The backend emits a `usage` event tagged
+ * `partial: true` for the discarded attempt so a cost display can stay accurate.
+ */
+export interface SSEStreamRestartEvent {
+    type: 'stream_restart';
+    /** Human-readable cause, for an optional dim status line. */
+    reason: string;
+    /**
+     * How many characters of rendered output this attempt had already emitted — counting
+     * both visible text AND streamed thinking, since consumers display both and both must
+     * be discarded. Only ever 0 when the attempt rendered nothing at all, in which case a
+     * plain `retry` is emitted instead of this event.
+     */
+    discardedChars: number;
+}
+export type SSEEvent = SSETextEvent | SSEToolUseEvent | SSEMessageCompleteEvent | SSEUsageEvent | SSEDoneEvent | SSEErrorEvent | SSEThinkingEvent | SSEThinkingProgressEvent | SSEThinkingDeltaEvent | SSERetryEvent | SSERetryResolvedEvent | SSEStreamRestartEvent | SSEBalanceStatusEvent;
 export interface UsageInfo {
     input_tokens: number;
     output_tokens: number;
@@ -173,7 +224,13 @@ export interface AgentLoopOptions {
     onThinkingProgress?: (tokens: number) => void;
     onToolUse: (name: string, input: Record<string, unknown>, isSubTask?: boolean) => void;
     onToolResult: (name: string, result: ToolResult, isSubTask?: boolean) => void;
-    onUsage: (u: UsageInfo) => void;
+    /**
+     * Token usage for a model call. `partial` marks tokens from an attempt that was cut
+     * short and restarted — real, already-billed spend that should be counted toward
+     * COST, but kept out of any "tokens this turn produced" display (see SSEUsageEvent).
+     * Optional second argument, so existing implementations keep compiling unchanged.
+     */
+    onUsage: (u: UsageInfo, partial?: boolean) => void;
     /**
      * Fired when the network layer is about to transparently retry a turn after
      * a transient disconnect (network drop, machine sleep/wake, overloaded
@@ -184,6 +241,17 @@ export interface AgentLoopOptions {
     onRetry?: (attempt: number, maxAttempts: number, reason: string) => void;
     /** Fired once a retried attempt starts receiving data again — clear any "reconnecting…" UI. */
     onRetryResolved?: () => void;
+    /**
+     * Fired when a stream died mid-render and the SAME turn is being restarted.
+     * The consumer MUST discard whatever partial assistant text/thinking it has
+     * already displayed for this turn — the new attempt re-sends it in full, so
+     * keeping the old fragment would duplicate it. No tool has executed at this
+     * point (tools only run after `message_complete`), so nothing beyond the
+     * rendered output needs undoing. If a caller does not implement this, the
+     * loop falls back to NOT retrying post-render failures, preserving the old
+     * (safe but turn-killing) behaviour.
+     */
+    onStreamRestart?: (reason: string, discardedChars: number) => void;
     /**
      * Fired when the backend reports the wallet balance dropped under the
      * low-balance threshold ($5) after billing a turn, or when a turn couldn't
@@ -270,4 +338,45 @@ export interface AgentLoopOptions {
      */
     _agentScope?: string;
 }
+/**
+ * Thrown by `runAgentLoop` when a turn cannot continue (stream died, upstream
+ * error, etc.) but real work HAS already been completed in this turn.
+ *
+ * Why this exists: the loop operates on its own copy of the history
+ * (`[...initialMessages]`), so a plain `throw` used to leave the CALLER's array
+ * still holding only the original user message. An agent that had already run
+ * 25 tool calls over eight minutes would lose every one of them — the user was
+ * billed for the work, then had to start from scratch because "continue" had no
+ * memory of it. Carrying the partial history on the error lets the caller
+ * salvage it, so the very next "continue" resumes exactly where it stopped.
+ *
+ * `messages` is always a VALID history to resend: the loop only ever appends in
+ * complete (assistant → tool_result) pairs, so it never ends on an assistant
+ * turn with unanswered tool_use blocks.
+ */
+export declare class AgentTurnError extends Error {
+    /** The turn's history up to the point of failure — safe to resend to the API. */
+    readonly messages: Message[];
+    /**
+     * How many turn steps completed before the failure (0 = nothing salvageable).
+     *
+     * Supplied by the loop as an explicit counter rather than derived from array
+     * lengths: auto-compaction SPLICES the history down mid-turn, so a long run that
+     * compacted and then died can end up SHORTER than it started. A length delta would
+     * read as "no progress" and discard exactly the expensive, long-running sessions
+     * this class exists to protect.
+     */
+    readonly progressCount: number;
+    /** The original underlying error, if any. */
+    readonly cause?: unknown;
+    constructor(message: string, messages: Message[], progressCount: number, cause?: unknown);
+}
+/** Type guard — narrows an unknown catch binding to an AgentTurnError. */
+export declare function isAgentTurnError(err: unknown): err is AgentTurnError;
+/**
+ * Salvage a partial history out of a failed turn. Returns the partial history
+ * when the error carried one AND real progress was made, otherwise `null`.
+ * Callers use it as: `messages = salvageHistory(err) ?? messages;`
+ */
+export declare function salvageHistory(err: unknown): Message[] | null;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,4 +1,48 @@
 "use strict";
 // ─── Content Blocks ───────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTurnError = void 0;
+exports.isAgentTurnError = isAgentTurnError;
+exports.salvageHistory = salvageHistory;
+// ─── Turn failure that preserves work already done ───────────────────────────
+/**
+ * Thrown by `runAgentLoop` when a turn cannot continue (stream died, upstream
+ * error, etc.) but real work HAS already been completed in this turn.
+ *
+ * Why this exists: the loop operates on its own copy of the history
+ * (`[...initialMessages]`), so a plain `throw` used to leave the CALLER's array
+ * still holding only the original user message. An agent that had already run
+ * 25 tool calls over eight minutes would lose every one of them — the user was
+ * billed for the work, then had to start from scratch because "continue" had no
+ * memory of it. Carrying the partial history on the error lets the caller
+ * salvage it, so the very next "continue" resumes exactly where it stopped.
+ *
+ * `messages` is always a VALID history to resend: the loop only ever appends in
+ * complete (assistant → tool_result) pairs, so it never ends on an assistant
+ * turn with unanswered tool_use blocks.
+ */
+class AgentTurnError extends Error {
+    constructor(message, messages, progressCount, cause) {
+        super(message);
+        this.name = 'AgentTurnError';
+        this.messages = messages;
+        this.progressCount = Math.max(0, progressCount);
+        this.cause = cause;
+    }
+}
+exports.AgentTurnError = AgentTurnError;
+/** Type guard — narrows an unknown catch binding to an AgentTurnError. */
+function isAgentTurnError(err) {
+    return err instanceof AgentTurnError;
+}
+/**
+ * Salvage a partial history out of a failed turn. Returns the partial history
+ * when the error carried one AND real progress was made, otherwise `null`.
+ * Callers use it as: `messages = salvageHistory(err) ?? messages;`
+ */
+function salvageHistory(err) {
+    if (!isAgentTurnError(err))
+        return null;
+    return err.progressCount > 0 ? err.messages : null;
+}
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexrall/code-core",
-  "version": "1.4.12",
+  "version": "1.4.14",
   "description": "Core agent loop, tools, and extension primitives for Nexrall Code — embed an AI coding agent in any Node.js application.",
   "license": "MIT",
   "author": "Nexrall <support@nexrall.com> (https://nexrall.com)",