@nexrall/code-core 1.4.12 → 1.4.14

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

@@ -1,5 +1,5 @@
 import type { Message, SSEEvent, AuthConfig, EnvContext, EditorContext } from '../types';
-export declare const API_BASE = "https://api.nexrall.com";
+export declare const API_BASE: string;
 /**
  * Decide the final assistant `content` array to store in history for a completed
  * turn. Pure + exported so it can be unit-tested without a live SSE stream.
@@ -42,8 +42,40 @@ 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;
+    /**
+     * Opt in to restarting a turn that died AFTER partial output was rendered.
+     *
+     * Historically any transport failure past the first token was fatal: retrying
+     * would have re-streamed text the user could already see, duplicating it. That
+     * rule is correct but it protects almost nothing in practice — a long turn emits
+     * a thinking delta within seconds, so the retry machinery was effectively dead
+     * code exactly when it mattered most (deep into an expensive agentic run).
+     *
+     * When the caller can UNDO its rendered output for the current turn, it sets
+     * this and handles the `stream_restart` event by discarding that output. Then a
+     * mid-render disconnect becomes recoverable instead of turn-fatal. This is safe
+     * for side effects: tool calls are dispatched by the agent loop only after
+     * `message_complete`, and a restart by definition means that never arrived — so
+     * no tool ran and nothing but rendered characters is rolled back.
+     */
+    allowRestartAfterRender?: boolean;
 }
 export declare function streamChat(messages: Message[], options: StreamChatOptions, onEvent: (e: SSEEvent) => void): Promise<Message>;
+/**
+ * Ask the server to stop generating a turn.
+ *
+ * This is REQUIRED for Stop to work, not an optimisation. A dropped socket used to abort
+ * the model; now it detaches and keeps generating so a network blip doesn't discard the
+ * turn (see the resume machinery above). Since a deliberate Stop looks identical to a
+ * blip from the server's side, it has to be signalled explicitly — otherwise the model
+ * would run to completion and bill in full after the user pressed Stop.
+ *
+ * Best-effort and never throws: Stop must feel instant, and the server's detach grace
+ * bounds the cost if this request never lands.
+ */
+export declare function cancelTurn(turnId: string): Promise<void>;
 export declare function getBalance(): Promise<number>;
 export declare function exchangeVscodeCode(code: string): Promise<AuthConfig>;
 export declare function login(email: string, password: string): Promise<AuthConfig>;

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":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAA8B,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAiErH,eAAO,MAAM,QAAQ,QAAmB,CAAC;AAIzC;;;;;;;;;;;;;;;;;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,CAeL;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;IAChB;;;;;;;;;;;;;;;OAeG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAiDD,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,CA80BlB;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9D;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"}