@nexrall/code-core 1.4.11 → 1.4.13

package/dist/agent/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EAMP,gBAAgB,EAChB,UAAU,EACX,MAAM,UAAU,CAAC;AAsKlB,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAWR;AA4TD,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAM7D;AAsBD,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,aAA+G,CAAC;AAC7I,gGAAgG;AAChG,eAAO,MAAM,aAAa,QAA2J,CAAC;AAEtL;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK5E;AAUD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAwBxD;AAoBD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,aAAa,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,qFAAqF;IACrF,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,IAAI,cAAc,CAE7C;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,EAAE,EAAE,OAAO,EACX,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAoDN;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA6B5D;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,eAAe,SAAI,GAAG,MAAM,CAgCpF;AAsHD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,OAAO,EAAE,EACnB,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC,GACA,OAAO,CAAC,OAAO,CAAC,CAqElB;AAID,wBAAsB,YAAY,CAChC,eAAe,EAAE,OAAO,EAAE,EAC1B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,OAAO,EAAE,CAAC,CA4nBpB"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EAMP,gBAAgB,EAChB,UAAU,EACX,MAAM,UAAU,CAAC;AAwKlB,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAWR;AA+TD,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAM7D;AAsBD,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,aAA+G,CAAC;AAC7I,gGAAgG;AAChG,eAAO,MAAM,aAAa,QAA2J,CAAC;AAEtL;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK5E;AAUD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAwBxD;AAoBD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,aAAa,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,qFAAqF;IACrF,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,IAAI,cAAc,CAE7C;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,EAAE,EAAE,OAAO,EACX,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAoDN;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA6B5D;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,eAAe,SAAI,GAAG,MAAM,CAgCpF;AA8JD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,OAAO,EAAE,EACnB,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC,GACA,OAAO,CAAC,OAAO,CAAC,CAqElB;AAID,wBAAsB,YAAY,CAChC,eAAe,EAAE,OAAO,EAAE,EAC1B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,OAAO,EAAE,CAAC,CA2oBpB"}

package/dist/agent/loop.js

@@ -48,12 +48,14 @@ exports.runAgentLoop = runAgentLoop;
 const client_1 = require("../api/client");
 const executor_1 = require("../tools/executor");
 const agentTypes_1 = require("./agentTypes");
+const skills_1 = require("./skills");
 const rules_1 = require("../permissions/rules");
 const sandbox_1 = require("../tools/sandbox");
 const index_1 = require("../plugins/index");
 const testIntegrity_1 = require("./testIntegrity");
 const flaky_1 = require("./flaky");
 const claimEvidence_1 = require("./claimEvidence");
+const memory_1 = require("./memory");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
@@ -299,6 +301,8 @@ function humanDescription(name, input) {
             const preview = typeof input.prompt === 'string' ? input.prompt.slice(0, 60) : '';
             return `Sub-task: ${desc || preview}${!desc && preview.length === 60 ? '…' : ''}`;
         }
+        case 'use_skill':
+            return `Use skill: /${input.name ?? '(unknown)'}`;
         case 'get_diagnostics':
             return input.path ? `Get diagnostics: ${input.path}` : 'Get workspace diagnostics';
         case 'go_to_definition':
@@ -831,6 +835,42 @@ async function autoCompactMessages(messages, options, ledger) {
     void kept;
     return true;
 }
+// ─── Periodic memory compaction ────────────────────────────────────────────
+// A memory file (project or global — see agent/memory.ts) can grow large over
+// many sessions since memory_write only ever appends. writeMemory() already
+// applies an immediate, synchronous byte-cap eviction (oldest entries dropped)
+// as a hard backstop, but that's a blunt instrument — this periodically
+// consolidates the file with a real LLM summarization pass instead, so old
+// facts are condensed into fewer, denser bullets rather than silently lost.
+// Checked opportunistically right after a successful memory_write (see the
+// call site below) rather than on every tool call — cheap to check (a single
+// file stat), and memory_write is the only thing that can push a file over
+// the trigger threshold in the first place.
+async function maybeCompactMemory(scope, options) {
+    try {
+        await (0, memory_1.compactMemoryIfNeeded)(scope, options.workDir, async (prompt) => {
+            const reply = await (0, client_1.streamChat)([{ role: 'user', content: [{ type: 'text', text: prompt }] }], {
+                // Same reasoning as autoCompactMessages' summariser: a mechanical
+                // consolidation task, always run on the cheapest 1M-context tier
+                // regardless of the user's chosen model for the actual conversation.
+                model: 'turbo',
+                mode: 'ask',
+                env: options.env,
+                clientType: options.clientType,
+                abortSignal: options.abortSignal,
+            }, () => { });
+            return reply.content
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text ?? '')
+                .join('');
+        });
+    }
+    catch {
+        // Best-effort — a failed/aborted compaction just means the file stays as-is
+        // until the next memory_write call tries again; writeMemory's synchronous
+        // byte cap already bounds worst-case growth in the meantime.
+    }
+}
 // ─── Resume-time proactive compaction ─────────────────────────────────────────
 //
 // The in-loop auto-compact above only reacts to `lastPromptTokens`, which is
@@ -940,6 +980,11 @@ async function runAgentLoop(initialMessages, options) {
     // catalogue (sub-agents can't spawn further), but every level resolves types.
     const agentTypes = (0, agentTypes_1.loadAgentTypes)(options.workDir);
     const agentsCatalogue = depth === 0 ? (0, agentTypes_1.summariseAgents)(agentTypes) : '';
+    // Skills catalogue — unlike agentsCatalogue, available at every depth: a skill is
+    // just a reusable prompt template (via use_skill), not another spawn point, so
+    // sub-agents benefit from the same playbooks without the recursion concerns that
+    // gate agentsCatalogue to the top level.
+    const skillsCatalogue = (0, skills_1.summariseSkills)((0, skills_1.loadSkills)(options.workDir));
     // Optional OS-level bash sandbox (opt-in via settings.json "sandbox").
     const settings = (0, rules_1.loadSettings)(options.workDir);
     const sandboxCfg = (0, sandbox_1.parseSandboxConfig)(settings.raw.sandbox) ?? undefined;
@@ -1130,6 +1175,7 @@ async function runAgentLoop(initialMessages, options) {
                     abortSignal: options.abortSignal,
                     extraTools: options.mcpManager?.getAnthropicTools(),
                     agents: agentsCatalogue || undefined,
+                    skills: skillsCatalogue || undefined,
                 }, onEvent);
             }
             catch (err) {
@@ -1393,6 +1439,14 @@ async function runAgentLoop(initialMessages, options) {
                         catch (err) {
                             result = { error: `Tool execution failed: ${err.message}` };
                         }
+                        // Opportunistic memory compaction — memory_write is the only tool that can
+                        // grow a memory file, so this is the cheapest point to check whether it just
+                        // crossed the compaction threshold. Fire-and-forget: never blocks the turn,
+                        // never surfaces its own errors to the model (see maybeCompactMemory).
+                        if (name === 'memory_write' && result.error === undefined) {
+                            const scope = input.scope === 'global' ? 'global' : 'project';
+                            void maybeCompactMemory(scope, options);
+                        }
                         // PostToolUse can inject context for the model or flag a problem.
                         const post = runToolHooks(hooks.PostToolUse, 'PostToolUse', name, input, options.workDir, result);
                         const injected = [pre.context, post.context].filter(Boolean).join('\n');

package/dist/agent/memory.d.ts

@@ -0,0 +1,45 @@
+export type MemoryScope = 'project' | 'global';
+/** Per-workDir file, keyed the same way CheckpointManager keys its store
+ *  (sha1 of the resolved absolute path) so two differently-named checkouts of
+ *  the same repo don't collide, and the same repo always maps to the same file
+ *  regardless of cwd casing/trailing-slash quirks. */
+export declare function memoryFilePath(scope: MemoryScope, workDir?: string): string;
+export declare const MEMORY_ENTRY_MAX_CHARS = 400;
+export declare const MEMORY_MAX_BYTES = 12000;
+export declare const MEMORY_COMPACT_TRIGGER_BYTES = 16000;
+export declare const MEMORY_HARD_CAP_BYTES: number;
+export interface MemoryWriteResult {
+    ok: boolean;
+    already: boolean;
+    scope: MemoryScope;
+    file: string;
+}
+export declare function writeMemory(content: string, scope: MemoryScope, workDir?: string): Promise<MemoryWriteResult>;
+export declare function readMemory(scope: MemoryScope, workDir?: string): string;
+/** Merge BOTH scopes for prompt injection — project-specific first (most
+ *  relevant to what the agent is doing right now), global preferences after. */
+export declare function readAllMemory(workDir?: string): string;
+export declare function clearMemory(scope: MemoryScope, workDir?: string): void;
+export declare function memoryStats(scope: MemoryScope, workDir?: string): {
+    file: string;
+    bytes: number;
+    entries: number;
+};
+/**
+ * Summarize the OLDEST half of a memory file into a few consolidated bullets via
+ * an LLM call, keeping the most recent entries verbatim — same "compact, don't
+ * silently drop" instinct as the conversation-history auto-compactor, applied to
+ * memory instead of a transcript. This is the EXPECTED bounding mechanism for
+ * memory file size — called opportunistically (fire-and-forget) right after a
+ * successful memory_write (see maybeCompactMemory in loop.ts) once a file crosses
+ * MEMORY_COMPACT_TRIGGER_BYTES. writeMemory's own emergency synchronous eviction
+ * (MEMORY_HARD_CAP_BYTES) sits well above this threshold specifically so this
+ * summarizing pass gets the chance to run first in the common case; the blunt
+ * eviction is a last resort for if compaction has been failing/unavailable.
+ *
+ * `summarize` is injected (rather than importing streamChat directly) to avoid
+ * pulling api/client.ts's network/auth machinery into every consumer of this
+ * module and to keep this file trivially unit-testable.
+ */
+export declare function compactMemoryIfNeeded(scope: MemoryScope, workDir: string | undefined, summarize: (prompt: string) => Promise<string>): Promise<boolean>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/agent/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/agent/memory.ts"],"names":[],"mappings":"AAiCA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE/C;;;sDAGsD;AACtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3E;AAED,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,gBAAgB,QAAS,CAAC;AACvC,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAMnD,eAAO,MAAM,qBAAqB,QAAmC,CAAC;AA4CtE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuBnH;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAGvE;AAED;gFACgF;AAChF,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAStD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAGtE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAKlH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC7C,OAAO,CAAC,OAAO,CAAC,CA+BlB"}

package/dist/agent/memory.js

@@ -0,0 +1,243 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEMORY_HARD_CAP_BYTES = exports.MEMORY_COMPACT_TRIGGER_BYTES = exports.MEMORY_MAX_BYTES = exports.MEMORY_ENTRY_MAX_CHARS = void 0;
+exports.memoryFilePath = memoryFilePath;
+exports.writeMemory = writeMemory;
+exports.readMemory = readMemory;
+exports.readAllMemory = readAllMemory;
+exports.clearMemory = clearMemory;
+exports.memoryStats = memoryStats;
+exports.compactMemoryIfNeeded = compactMemoryIfNeeded;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+// ─── Persistent agent memory ───────────────────────────────────────────────
+//
+// Two scopes, mirroring nexrall.md's own global/project split:
+//   - 'project' (default) — facts specific to the repo currently open
+//     (tech stack, build/deploy commands, project-specific conventions).
+//     Stored per-workDir so an unrelated project never sees it.
+//   - 'global'  — facts that hold across EVERY project (communication-style
+//     preferences, cross-cutting habits like "always confirm before force-push").
+//
+// Previously everything lived in one un-scoped ~/.nexrall/memory.md, read into
+// EVERY session regardless of which project was open — a fact about one repo's
+// deploy command showed up as context noise in a totally unrelated project, and
+// the single file grew without bound (a real one measured 312KB / ~245 entries
+// after a few weeks, entries averaging ~1000 chars despite the tool's own
+// instruction to keep each one to "1-2 sentences").
+//
+// Fixes applied here (see MEMORY_MAX_BYTES / MEMORY_ENTRY_MAX_CHARS / compaction
+// below): hard per-entry length cap (not just a prompt instruction), hard total
+// file-size cap with LLM-summarizing compaction of the oldest half instead of
+// blind truncation (which would silently discard facts instead of condensing
+// them), and a real file lock around the read-dedupe-write sequence so two
+// concurrent CLI/VS Code sessions can't race into a duplicate entry.
+// NEXRALL_MEMORY_DIR overrides the store root — used by tests to avoid touching
+// the real ~/.nexrall/memory (mirrors CheckpointManager's NEXRALL_CHECKPOINT_DIR).
+const MEMORY_ROOT = process.env.NEXRALL_MEMORY_DIR || path.join(os.homedir(), '.nexrall', 'memory');
+const GLOBAL_FILE = path.join(MEMORY_ROOT, 'global.md');
+/** Per-workDir file, keyed the same way CheckpointManager keys its store
+ *  (sha1 of the resolved absolute path) so two differently-named checkouts of
+ *  the same repo don't collide, and the same repo always maps to the same file
+ *  regardless of cwd casing/trailing-slash quirks. */
+function memoryFilePath(scope, workDir) {
+    if (scope === 'global' || !workDir)
+        return GLOBAL_FILE;
+    const key = crypto.createHash('sha1').update(path.resolve(workDir)).digest('hex').slice(0, 16);
+    return path.join(MEMORY_ROOT, `project-${key}.md`);
+}
+exports.MEMORY_ENTRY_MAX_CHARS = 400; // hard cap per entry — the "1-2 sentences" instruction is a request, this is the backstop
+exports.MEMORY_MAX_BYTES = 12000; // ~3k tokens — target size compaction summarizes DOWN TO
+exports.MEMORY_COMPACT_TRIGGER_BYTES = 16000; // LLM compaction (see compactMemoryIfNeeded) fires once past this
+// Emergency-only synchronous fallback inside writeMemory itself, MUCH higher than the compact
+// trigger — gives compactMemoryIfNeeded plenty of headroom to run (it's called opportunistically,
+// fire-and-forget, from loop.ts right after a memory_write) before this ever kicks in. Only bites
+// if compaction has been unavailable/failing for a while (e.g. offline, API errors), so the file
+// still can't grow completely unbounded even in that worst case.
+exports.MEMORY_HARD_CAP_BYTES = 4 * exports.MEMORY_COMPACT_TRIGGER_BYTES;
+const FINGERPRINT_LEN = 60; // near-duplicate heuristic: same as before, first N chars, case-insensitive
+// ─── Simple per-file async lock ────────────────────────────────────────────
+// Fixes the read→dedupe-check→append race: two concurrent memoryWrite() calls
+// (two CLI processes, or a sub-agent + the main agent) could both read "fact
+// not present yet" before either had written, and both append duplicates.
+// In-process locking is enough for the common case (same CLI/VS Code process);
+// cross-process races are rarer and, worst case, produce a duplicate line that
+// the NEXT memory_write's dedupe check or a compaction pass will clean up.
+const _locks = new Map();
+async function withLock(key, fn) {
+    const prev = _locks.get(key) ?? Promise.resolve();
+    let release;
+    const next = new Promise((res) => { release = res; });
+    _locks.set(key, prev.then(() => next));
+    try {
+        await prev;
+        return await fn();
+    }
+    finally {
+        release();
+        if (_locks.get(key) === next)
+            _locks.delete(key);
+    }
+}
+function readMemoryFile(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+function writeMemoryFile(file, content) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content, 'utf-8');
+}
+/** Evict the OLDEST entries (top of file) until under the byte cap. Used as a
+ *  cheap fallback when LLM compaction is unavailable/fails — see compactMemory
+ *  below for the preferred summarizing path. */
+function evictOldest(content, maxBytes) {
+    if (Buffer.byteLength(content, 'utf-8') <= maxBytes)
+        return content;
+    const lines = content.split('\n').filter((l) => l.trim().length > 0);
+    while (lines.length > 1 && Buffer.byteLength(lines.join('\n'), 'utf-8') > maxBytes)
+        lines.shift();
+    return '\n' + lines.join('\n');
+}
+async function writeMemory(content, scope, workDir) {
+    let trimmed = content.trim();
+    if (!trimmed)
+        return { ok: false, already: false, scope, file: '' };
+    if (trimmed.length > exports.MEMORY_ENTRY_MAX_CHARS)
+        trimmed = trimmed.slice(0, exports.MEMORY_ENTRY_MAX_CHARS - 1).trimEnd() + '…';
+    const file = memoryFilePath(scope, workDir);
+    return withLock(file, async () => {
+        const existing = readMemoryFile(file);
+        const fingerprint = trimmed.toLowerCase().slice(0, FINGERPRINT_LEN);
+        if (existing.toLowerCase().includes(fingerprint)) {
+            return { ok: true, already: true, scope, file };
+        }
+        const today = new Date().toISOString().slice(0, 10);
+        let next = existing + `\n- [${today}] ${trimmed}`;
+        // Emergency-only backstop — see MEMORY_HARD_CAP_BYTES. The EXPECTED bounding
+        // mechanism is compactMemoryIfNeeded (LLM summarization, called opportunistically
+        // right after this from loop.ts); this only fires if compaction hasn't kept up.
+        if (Buffer.byteLength(next, 'utf-8') > exports.MEMORY_HARD_CAP_BYTES) {
+            next = evictOldest(next, exports.MEMORY_MAX_BYTES);
+        }
+        writeMemoryFile(file, next);
+        return { ok: true, already: false, scope, file };
+    });
+}
+function readMemory(scope, workDir) {
+    const file = memoryFilePath(scope, workDir);
+    return readMemoryFile(file).trim();
+}
+/** Merge BOTH scopes for prompt injection — project-specific first (most
+ *  relevant to what the agent is doing right now), global preferences after. */
+function readAllMemory(workDir) {
+    const parts = [];
+    const globalMem = readMemory('global');
+    if (globalMem)
+        parts.push(`[Global memories — apply to every project]\n${globalMem}`);
+    if (workDir) {
+        const projMem = readMemory('project', workDir);
+        if (projMem)
+            parts.push(`[Project memories — ${path.basename(path.resolve(workDir))}]\n${projMem}`);
+    }
+    return parts.join('\n\n');
+}
+function clearMemory(scope, workDir) {
+    const file = memoryFilePath(scope, workDir);
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch { /* ignore */ }
+}
+function memoryStats(scope, workDir) {
+    const file = memoryFilePath(scope, workDir);
+    const content = readMemoryFile(file);
+    const entries = content.split('\n').filter((l) => /^-\s\[\d{4}-\d{2}-\d{2}\]/.test(l)).length;
+    return { file, bytes: Buffer.byteLength(content, 'utf-8'), entries };
+}
+/**
+ * Summarize the OLDEST half of a memory file into a few consolidated bullets via
+ * an LLM call, keeping the most recent entries verbatim — same "compact, don't
+ * silently drop" instinct as the conversation-history auto-compactor, applied to
+ * memory instead of a transcript. This is the EXPECTED bounding mechanism for
+ * memory file size — called opportunistically (fire-and-forget) right after a
+ * successful memory_write (see maybeCompactMemory in loop.ts) once a file crosses
+ * MEMORY_COMPACT_TRIGGER_BYTES. writeMemory's own emergency synchronous eviction
+ * (MEMORY_HARD_CAP_BYTES) sits well above this threshold specifically so this
+ * summarizing pass gets the chance to run first in the common case; the blunt
+ * eviction is a last resort for if compaction has been failing/unavailable.
+ *
+ * `summarize` is injected (rather than importing streamChat directly) to avoid
+ * pulling api/client.ts's network/auth machinery into every consumer of this
+ * module and to keep this file trivially unit-testable.
+ */
+async function compactMemoryIfNeeded(scope, workDir, summarize) {
+    const file = memoryFilePath(scope, workDir);
+    return withLock(file, async () => {
+        const content = readMemoryFile(file);
+        if (Buffer.byteLength(content, 'utf-8') <= exports.MEMORY_COMPACT_TRIGGER_BYTES)
+            return false;
+        const lines = content.split('\n').filter((l) => l.trim().length > 0);
+        if (lines.length < 8)
+            return false; // too few entries to bother — evictOldest already keeps it bounded
+        const cut = Math.floor(lines.length / 2);
+        const older = lines.slice(0, cut);
+        const recent = lines.slice(cut);
+        const prompt = `Consolidate these persistent-memory bullet entries into a shorter set of bullets, ` +
+            `merging duplicates/near-duplicates and dropping anything clearly stale or superseded ` +
+            `by a later entry. Keep each resulting bullet under ${exports.MEMORY_ENTRY_MAX_CHARS} characters, ` +
+            `one fact per line, prefixed "- [YYYY-MM-DD] " using the LATEST date among the entries it ` +
+            `draws from. Output ONLY the bullet lines, nothing else.\n\n${older.join('\n')}`;
+        let summarized;
+        try {
+            summarized = (await summarize(prompt)).trim();
+        }
+        catch {
+            return false; // summarization failed — leave the file as-is; the sync evictOldest cap still bounds it
+        }
+        if (!summarized)
+            return false;
+        const next = summarized + '\n' + recent.join('\n');
+        writeMemoryFile(file, Buffer.byteLength(next, 'utf-8') > exports.MEMORY_MAX_BYTES ? evictOldest(next, exports.MEMORY_MAX_BYTES) : next);
+        return true;
+    });
+}
+//# sourceMappingURL=memory.js.map

package/dist/agent/skills.d.ts

@@ -0,0 +1,35 @@
+export interface Skill {
+    name: string;
+    description: string;
+    model?: 'turbo' | 'pro' | 'ultra';
+    mode?: string;
+    body: string;
+    source: 'project' | 'global' | 'builtin' | 'plugin';
+    /** Absolute path to the skill's own directory, for resolving supporting files. Undefined for flat command-style skills (no directory). */
+    dir?: string;
+    /** true → only `/name` invokes it; the model must not auto-trigger it (side-effecting workflows like /deploy). */
+    disableModelInvocation: boolean;
+    /** false → only the model may invoke it (auto-load only, not meant to be typed as a command). */
+    userInvocable: boolean;
+}
+/** Discover all skills (project overrides global overrides plugin overrides builtin).
+ *  Directory-style `.nexrall/skills/<name>/SKILL.md` beats a flat `.nexrall/commands/<name>.md`
+ *  of the same name within the same precedence tier. */
+export declare function loadSkills(workDir: string): Skill[];
+export declare function findSkill(skills: Skill[], name: string): Skill | undefined;
+/** Skills the MODEL may auto-invoke via the use_skill tool (excludes disable-model-invocation:true ones). */
+export declare function autoInvokableSkills(skills: Skill[]): Skill[];
+/** Skills the USER may invoke via /name (excludes user-invocable:false ones). */
+export declare function userInvokableSkills(skills: Skill[]): Skill[];
+/** A compact catalogue injected into the system prompt so the model knows what it can auto-invoke via use_skill. */
+export declare function summariseSkills(skills: Skill[]): string;
+/**
+ * Expand a skill body into a final prompt (same $ARGUMENTS / @file / !`cmd`
+ * substitution as slash commands — see commands/loader.ts#expandBody), then
+ * prepend a short header pointing at the skill's own directory (if any) so
+ * the model knows where to find supporting files it may need to read_file
+ * on demand, mirroring Claude Code's "reference files from your SKILL.md"
+ * guidance without loading them into context up front.
+ */
+export declare function expandSkill(skill: Skill, argString: string, workDir: string): string;
+//# sourceMappingURL=skills.d.ts.map

package/dist/agent/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/agent/skills.ts"],"names":[],"mappings":"AA2CA,MAAM,WAAW,KAAK;IACpB,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;IACpD,0IAA0I;IAC1I,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kHAAkH;IAClH,sBAAsB,EAAE,OAAO,CAAC;IAChC,iGAAiG;IACjG,aAAa,EAAE,OAAO,CAAC;CACxB;AAyID;;wDAEwD;AACxD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,CAanD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAG1E;AAED,6GAA6G;AAC7G,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAE5D;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAE5D;AAED,oHAAoH;AACpH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAIvD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAcpF"}

package/dist/agent/skills.js

@@ -0,0 +1,253 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSkills = loadSkills;
+exports.findSkill = findSkill;
+exports.autoInvokableSkills = autoInvokableSkills;
+exports.userInvokableSkills = userInvokableSkills;
+exports.summariseSkills = summariseSkills;
+exports.expandSkill = expandSkill;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const index_1 = require("../plugins/index");
+const loader_1 = require("../commands/loader");
+function parseFrontmatter(raw) {
+    const m = /^\s*---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    if (!m)
+        return { meta: {}, body: raw.trim() };
+    const meta = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line.trim());
+        if (kv)
+            meta[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, '');
+    }
+    return { meta, body: (m[2] ?? '').trim() };
+}
+function parseBool(v, fallback) {
+    if (v === undefined)
+        return fallback;
+    const s = v.trim().toLowerCase();
+    if (s === 'true' || s === '1' || s === 'yes')
+        return true;
+    if (s === 'false' || s === '0' || s === 'no')
+        return false;
+    return fallback;
+}
+function toSkill(meta, body, name, source, dir) {
+    const model = ['turbo', 'pro', 'ultra'].find((x) => x === (meta.model ?? '').toLowerCase());
+    return {
+        name,
+        description: meta.description || `Custom /${name} skill`,
+        model,
+        mode: meta.mode || undefined,
+        body,
+        source,
+        dir,
+        disableModelInvocation: parseBool(meta['disable-model-invocation'], false),
+        userInvocable: parseBool(meta['user-invocable'], true),
+    };
+}
+// Legacy flat-file skills: .nexrall/commands/<name>.md (and plugin commands/).
+// Kept as its own loader (rather than merged into loadSkillDir below) since the
+// naming/precedence rule ("skill directory wins over a same-name flat command")
+// requires knowing about both shapes before the caller merges them.
+function loadFlatCommandDir(dir, source, into) {
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+    }
+    catch {
+        return;
+    }
+    for (const file of files) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, file), 'utf-8');
+            const { meta, body } = parseFrontmatter(raw);
+            const name = (meta.name || path.basename(file, '.md')).trim().toLowerCase();
+            if (!name)
+                continue;
+            if (source !== 'project' && into.has(name))
+                continue; // earlier tiers win
+            into.set(name, toSkill(meta, body, name, source));
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+}
+// Directory-style skills: .nexrall/skills/<name>/SKILL.md (+ optional supporting files).
+function loadSkillDir(root, source, into) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        const skillDir = path.join(root, entry.name);
+        const skillFile = path.join(skillDir, 'SKILL.md');
+        try {
+            if (!fs.statSync(skillFile).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        try {
+            const raw = fs.readFileSync(skillFile, 'utf-8');
+            const { meta, body } = parseFrontmatter(raw);
+            const name = (meta.name || entry.name).trim().toLowerCase();
+            if (!name)
+                continue;
+            // A directory-style skill always wins over an earlier flat command of
+            // the same name (from the SAME precedence tier), and — like commands —
+            // project tier always wins outright regardless of load order.
+            if (source !== 'project' && into.has(name))
+                continue;
+            into.set(name, toSkill(meta, body, name, source, skillDir));
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+}
+// ── Built-in skills ───────────────────────────────────────────────────────────
+// Shipped defaults; lowest precedence (project > global > plugin > builtin), so
+// a user can override any of them with a same-name skill or command file.
+const BUILTIN_SKILLS = [
+    {
+        name: 'review',
+        description: 'Review uncommitted changes (or a PR/branch diff) for correctness bugs, edge cases, and security issues. ' +
+            'Use when the user asks to review a diff, check their changes before committing, or audit a PR.',
+        source: 'builtin',
+        disableModelInvocation: false,
+        userInvocable: true,
+        body: [
+            'Review the following diff like a meticulous senior engineer. Target: $ARGUMENTS',
+            '(If no target given, review the uncommitted working-tree changes below. If a branch or PR',
+            'number is given, run the appropriate `git diff <base>...` or `gh pr diff <n>` yourself first.)',
+            '',
+            'Branch: !`git branch --show-current`',
+            'Status: !`git status --short`',
+            '',
+            'Diff (uncommitted):',
+            '```diff',
+            '!`git diff HEAD --unified=5 --no-color | head -4000`',
+            '```',
+            '',
+            'Review methodology:',
+            '1. Read the surrounding code of every changed hunk (read_file with offset/limit) — never judge a hunk in isolation.',
+            '2. Look for: correctness bugs, edge cases (empty/null/unicode/concurrency), security issues',
+            '   (injection, path traversal, secrets), breaking API changes (find_references / search callers),',
+            '   silent behaviour changes, and missing error handling.',
+            '3. Check tests: do existing tests cover the change? Are assertions weakened?',
+            '',
+            'Output format:',
+            '- 🔴 Critical (must fix before merge) — with file:line and a concrete fix',
+            '- 🟡 Warning (should fix) — with file:line',
+            '- 🟢 Suggestion (nice to have)',
+            '- Verdict: APPROVE / REQUEST CHANGES with a one-paragraph summary.',
+            'Do NOT modify any files — this is a read-only review.',
+        ].join('\n'),
+    },
+];
+/** Discover all skills (project overrides global overrides plugin overrides builtin).
+ *  Directory-style `.nexrall/skills/<name>/SKILL.md` beats a flat `.nexrall/commands/<name>.md`
+ *  of the same name within the same precedence tier. */
+function loadSkills(workDir) {
+    const out = new Map();
+    // Flat commands first (so a same-tier skill directory below can override them).
+    loadFlatCommandDir(path.join(workDir, '.nexrall', 'commands'), 'project', out);
+    loadSkillDir(path.join(workDir, '.nexrall', 'skills'), 'project', out);
+    loadFlatCommandDir(path.join(os.homedir(), '.nexrall', 'commands'), 'global', out);
+    loadSkillDir(path.join(os.homedir(), '.nexrall', 'skills'), 'global', out);
+    for (const dir of (0, index_1.pluginAssetDirs)(workDir, 'commands'))
+        loadFlatCommandDir(dir, 'plugin', out);
+    for (const dir of (0, index_1.pluginAssetDirs)(workDir, 'skills'))
+        loadSkillDir(dir, 'plugin', out);
+    for (const skill of BUILTIN_SKILLS) {
+        if (!out.has(skill.name))
+            out.set(skill.name, skill);
+    }
+    return [...out.values()];
+}
+function findSkill(skills, name) {
+    const want = name.replace(/^\//, '').trim().toLowerCase();
+    return skills.find((s) => s.name === want);
+}
+/** Skills the MODEL may auto-invoke via the use_skill tool (excludes disable-model-invocation:true ones). */
+function autoInvokableSkills(skills) {
+    return skills.filter((s) => !s.disableModelInvocation);
+}
+/** Skills the USER may invoke via /name (excludes user-invocable:false ones). */
+function userInvokableSkills(skills) {
+    return skills.filter((s) => s.userInvocable);
+}
+/** A compact catalogue injected into the system prompt so the model knows what it can auto-invoke via use_skill. */
+function summariseSkills(skills) {
+    const list = autoInvokableSkills(skills);
+    if (!list.length)
+        return '';
+    return list.map((s) => `- ${s.name}: ${s.description}`).join('\n');
+}
+/**
+ * Expand a skill body into a final prompt (same $ARGUMENTS / @file / !`cmd`
+ * substitution as slash commands — see commands/loader.ts#expandBody), then
+ * prepend a short header pointing at the skill's own directory (if any) so
+ * the model knows where to find supporting files it may need to read_file
+ * on demand, mirroring Claude Code's "reference files from your SKILL.md"
+ * guidance without loading them into context up front.
+ */
+function expandSkill(skill, argString, workDir) {
+    const expanded = (0, loader_1.expandBody)(skill.body, argString, workDir);
+    if (!skill.dir)
+        return expanded;
+    let siblings = [];
+    try {
+        siblings = fs.readdirSync(skill.dir).filter((f) => f !== 'SKILL.md');
+    }
+    catch {
+        /* directory unreadable — proceed without the file listing */
+    }
+    if (!siblings.length)
+        return expanded;
+    return (`[Skill "${skill.name}" — supporting files available in ${skill.dir} (use read_file with an absolute path to load ` +
+        `any of these only if the instructions below need them): ${siblings.join(', ')}]\n\n${expanded}`);
+}
+//# sourceMappingURL=skills.js.map

package/dist/api/client.d.ts

@@ -42,6 +42,8 @@ export interface StreamChatOptions {
     }>;
     /** Catalogue of custom sub-agent types — injected into the system prompt. */
     agents?: string;
+    /** Catalogue of auto-invokable skills (description only) — injected into the system prompt so the model can call use_skill when relevant. */
+    skills?: string;
 }
 export declare function streamChat(messages: Message[], options: StreamChatOptions, onEvent: (e: SSEEvent) => void): Promise<Message>;
 export declare function getBalance(): Promise<number>;

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAA8B,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAKrH,eAAO,MAAM,QAAQ,4BAA4B,CAAC;AAIlD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5D,OAAO,EAAE,CAAC,EAAE,EACZ,UAAU,EAAE,KAAK,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACtD,CAAC,EAAE,CAML;AAeD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACnC,oFAAoF;IACpF,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACjG,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA0BD,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAC7B,OAAO,CAAC,OAAO,CAAC,CA4clB;AAID,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAalD;AAID,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgB1E;AAID,wBAAsB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBhF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAA8B,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAKrH,eAAO,MAAM,QAAQ,4BAA4B,CAAC;AAIlD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5D,OAAO,EAAE,CAAC,EAAE,EACZ,UAAU,EAAE,KAAK,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACtD,CAAC,EAAE,CAML;AAeD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACnC,oFAAoF;IACpF,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACjG,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6IAA6I;IAC7I,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA0BD,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAC7B,OAAO,CAAC,OAAO,CAAC,CA4clB;AAID,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAalD;AAID,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgB1E;AAID,wBAAsB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBhF"}

package/dist/api/client.js

@@ -69,7 +69,7 @@ function sleep(ms) {
  *  meaningful "attempt N of M" to the UI — not a hard limit by itself. */
 const MAX_TOTAL_ATTEMPTS = (MAX_RETRIES + 1) * (MAX_RETRIES + 1);
 async function streamChat(messages, options, onEvent) {
-    const { model, env, editorContext, nexrallMd, mode, effort, clientType, abortSignal, extraTools, agents } = options;
+    const { model, env, editorContext, nexrallMd, mode, effort, clientType, abortSignal, extraTools, agents, skills } = options;
     // Bridge custom abort signal → native AbortController so fetch is cancelled immediately
     const controller = new AbortController();
     if (abortSignal?.aborted)
@@ -84,7 +84,7 @@ async function streamChat(messages, options, onEvent) {
         {
             method: 'POST',
             headers: authHeaders(),
-            body: JSON.stringify({ messages, model, env, editorContext, nexrallMd, mode, effort, clientType, extraTools, agents }),
+            body: JSON.stringify({ messages, model, env, editorContext, nexrallMd, mode, effort, clientType, extraTools, agents, skills }),
             signal: controller.signal,
         },
     ];

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;AAsgEtE,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");
@@ -52,8 +54,24 @@ const tsLangService_1 = require("./tsLangService");
 // ─── Constants ────────────────────────────────────────────────────────────────
 const DEFAULT_TIMEOUT_MS = 60000;
 const MAX_FETCH_BYTES = 200 * 1024; // 200 KB
-const MAX_READ_BYTES = 500 * 1024; // 500 KB
+const MAX_READ_BYTES = 500 * 1024; // 500 KB — still used by notebook_read (JSON.parse needs it whole)
 const MAX_OUTPUT_CHARS = 100000; // bash / grep output cap (~100 KB)
+// read_file has NO byte-size gate (unlike the old 500KB cutoff) — like Claude
+// Code, a file of any size can be read; it's always streamed line-by-line so
+// memory is bounded regardless of file size. Instead there are two independent
+// caps per call, mirroring Claude Code's Read tool:
+//   - MAX_READ_LINES:  a hard line-count ceiling (default window AND clamp on
+//     an explicit limit) so one call never floods context with thousands of
+//     short lines (JSON/minified/logs) just because the file is small in bytes.
+//   - MAX_READ_TOKENS: a hard token budget (rough chars/4 estimate). If the
+//     requested window would exceed it, we either return a PARTIAL page (no
+//     explicit limit — same UX as Claude Code's "first page + how to continue"
+//     notice) or an error (explicit limit given and it still doesn't fit —
+//     caller must shrink the limit or use search_files instead).
+const MAX_READ_LINES = 2000;
+const MAX_READ_TOKENS = 25000;
+const READ_CHARS_PER_TOKEN = 4; // rough, conservative — consistent with loop.ts's resume estimator
+const MAX_READ_CHARS = MAX_READ_TOKENS * READ_CHARS_PER_TOKEN; // 100,000 chars
 // GAP B — output spillover. The inline bash result keeps only HEAD+TAIL (~100 KB),
 // which loses the MIDDLE of a large log — often exactly where a stack trace's root
 // cause or a failing assertion lives. To make the full log recoverable WITHOUT
@@ -217,51 +235,99 @@ function isBinaryFile(filePath) {
         return false;
     }
 }
+function formatNumberedLine(offset, indexInKept, line) {
+    return `${String(offset + indexInKept + 1).padStart(4, ' ')}\t${line}`;
+}
 /**
- * Read a bounded line window [offset, offset+limit) from a file too large to load
- * whole, by streaming it in chunks and keeping only the requested lines. Memory is
- * bounded by (limit lines actually kept) + one chunk, never the whole file — so a
- * 20MB bash-output spill file can be inspected section-by-section. (GAP B.)
+ * Read a bounded window [offset, offset+limit) of a file by streaming it in
+ * chunks — memory is bounded by what's actually kept, never the whole file, so
+ * this is safe for files of ANY size (there is no byte-size gate on read_file
+ * at all, matching Claude Code). Two independent hard caps apply per call:
+ *   - MAX_READ_LINES lines
+ *   - MAX_READ_TOKENS tokens (~MAX_READ_CHARS chars) of formatted output
+ * If an explicit `requestedLimit` was given and the token cap is hit before
+ * that many lines were produced, the call fails with an actionable error
+ * (mirrors Claude Code: "a read that passes an explicit offset or limit and
+ * still exceeds the token limit returns an error"). Otherwise (default,
+ * no explicit limit) it silently returns a partial page with a continuation
+ * note — never an error just for being a big file.
  */
-async function readLargeFileWindow(resolved, offset, limit, kb) {
+async function readFileWindowed(resolved, offset, requestedLimit) {
     return new Promise((resolve) => {
-        const endLine = offset + limit; // exclusive, 0-based
+        const explicitLimit = requestedLimit > 0;
+        const lineScanCap = explicitLimit ? Math.min(requestedLimit, MAX_READ_LINES) : MAX_READ_LINES;
+        const hardEndLine = offset + lineScanCap; // exclusive, 0-based
         const kept = [];
+        let keptChars = 0;
         let lineNo = 0; // 0-based index of the NEXT line to be completed
         let carry = ''; // partial line spanning chunk boundaries
         let stopped = false;
+        let hitTokenCap = false;
+        let sawEof = false;
         const stream = fs.createReadStream(resolved, { encoding: 'utf-8', highWaterMark: 256 * 1024 });
+        // Returns false if adding this line would exceed the token budget (line NOT kept).
+        const tryPushLine = (line) => {
+            const formatted = formatNumberedLine(offset, kept.length, line);
+            const added = formatted.length + 1; // +1 for the join newline
+            if (keptChars + added > MAX_READ_CHARS) {
+                hitTokenCap = true;
+                return false;
+            }
+            kept.push(line);
+            keptChars += added;
+            return true;
+        };
         const finish = () => {
             if (stopped)
                 return;
             stopped = true;
             stream.destroy();
+            if (hitTokenCap && explicitLimit) {
+                resolve({
+                    error: `Requested range (offset:${offset}, limit:${requestedLimit}) is too large — exceeds ${MAX_READ_TOKENS} tokens. ` +
+                        `Pass a smaller limit, or use search_files to locate the relevant part first.`,
+                });
+                return;
+            }
             const first = offset + 1;
             const last = offset + kept.length;
-            const numbered = kept.map((l, i) => `${String(offset + i + 1).padStart(4, ' ')}\t${l}`).join('\n');
-            const note = kept.length < limit
+            const numbered = kept.map((l, i) => formatNumberedLine(offset, i, l)).join('\n');
+            const totalNote = sawEof ? `/${lineNo}` : '';
+            const note = sawEof
                 ? ` (reached end of file at line ${last})`
-                : ` (more lines follow — increase offset to continue)`;
-            resolve({ output: `[File: ${resolved} — ${kb} KB, showing lines ${first}-${last}${note}]\n${numbered}` });
+                : ` (more lines follow — pass offset:${last} to continue, or search_files to locate the relevant part)`;
+            resolve({ output: `[File: ${resolved} — lines ${first}-${last}${totalNote}${note}]\n${numbered}` });
         };
         stream.on('data', (chunk) => {
             const text = carry + (typeof chunk === 'string' ? chunk : chunk.toString('utf-8'));
             const lines = text.split('\n');
             carry = lines.pop() ?? ''; // last element is an incomplete line (or '')
             for (const line of lines) {
-                if (lineNo >= offset && lineNo < endLine)
-                    kept.push(line);
-                lineNo++;
-                if (lineNo >= endLine) {
-                    finish();
-                    return;
+                if (lineNo >= offset) {
+                    if (lineNo >= hardEndLine) {
+                        finish();
+                        return;
+                    }
+                    if (!tryPushLine(line)) {
+                        finish();
+                        return;
+                    }
                 }
+                lineNo++;
             }
         });
         stream.on('end', () => {
+            if (stopped)
+                return;
             // Flush the final carry (file not ending in newline) if it's in range.
-            if (!stopped && carry !== '' && lineNo >= offset && lineNo < endLine)
-                kept.push(carry);
+            if (carry !== '' && lineNo >= offset && lineNo < hardEndLine) {
+                if (!tryPushLine(carry)) {
+                    finish();
+                    return;
+                }
+                lineNo++;
+            }
+            sawEof = true;
             finish();
         });
         stream.on('error', (err) => { if (!stopped) {
@@ -278,38 +344,19 @@ async function readFile(input, workDir) {
         return { error: 'Missing required parameter: path' };
     try {
         const resolved = resolvePath(filePath, workDir);
-        const stat = fs.statSync(resolved);
+        fs.statSync(resolved); // throws ENOENT/EISDIR etc with a clear message if the path is bad
         // Reject binary files early — reading them as UTF-8 produces garbage.
+        // (isBinaryFile only samples the first 8KB, so this is cheap regardless of file size.)
         if (isBinaryFile(resolved)) {
             const ext = path.extname(resolved).toLowerCase();
             return { error: `Cannot read binary file: ${resolved} (${ext || 'no extension'}). Use a text-based tool or convert it first.` };
         }
-        // Large-file path: when the file exceeds the in-memory cap, a full readFileSync
-        // would OOM — but we must still be able to inspect SECTIONS (this is what makes a
-        // 20MB bash-output spill file usable, GAP B). If offset+limit are given we stream
-        // line-by-line and materialise only the requested window; otherwise we require it.
-        if (stat.size > MAX_READ_BYTES) {
-            const kb = (stat.size / 1024).toFixed(0);
-            if (limit <= 0) {
-                return { error: `File too large (${kb} KB, max ${MAX_READ_BYTES / 1024} KB). Pass offset + limit to read a section (e.g. {offset:0, limit:500}), or search_files to locate the relevant part first.` };
-            }
-            return await readLargeFileWindow(resolved, offset, limit, kb);
-        }
-        const content = fs.readFileSync(resolved, 'utf-8');
-        const allLines = content.split('\n');
-        const totalLines = allLines.length;
-        const startLine = offset; // 0-based
-        const endLine = limit > 0 ? Math.min(startLine + limit, totalLines) : totalLines;
-        const slice = allLines.slice(startLine, endLine);
-        // Prefix each line with its 1-based line number (like cat -n / Claude Code view)
-        const numbered = slice.map((l, i) => {
-            const lineNo = String(startLine + i + 1).padStart(4, ' ');
-            return `${lineNo}\t${l}`;
-        }).join('\n');
-        const rangeNote = (offset > 0 || limit > 0)
-            ? ` lines ${startLine + 1}-${endLine}/${totalLines}`
-            : ` ${totalLines} lines`;
-        return { output: `[File: ${resolved} (${rangeNote})]\n${numbered}` };
+        // No byte-size gate — a file of any size can be read; it's always streamed
+        // line-by-line so memory is bounded regardless of file size (matches Claude
+        // Code, which has no separate "too large" error either). Instead, one call
+        // is capped at MAX_READ_LINES lines and MAX_READ_TOKENS tokens (see
+        // readFileWindowed for exact semantics of each cap).
+        return await readFileWindowed(resolved, offset, limit);
     }
     catch (err) {
         return { error: err.message };
@@ -1983,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;
@@ -2078,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
@@ -2099,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexrall/code-core",
-  "version": "1.4.11",
+  "version": "1.4.13",
   "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)",