@ashlr/hub 3.7.0 → 3.9.0

package/dist/core/verse/project-memory.js

@@ -0,0 +1,295 @@
+/**
+ * Shared project memory — one private directory per project that EVERY seat
+ * working on that project reads (and, where the CLI can be granted a writable
+ * root, maintains):
+ *
+ *   <verse root>/memory/<basename-slug>-<sha256(realpath)[0:12]>/MEMORY.md
+ *   (default verse root: ~/.ashlr/verse — dir 0700, files 0600)
+ *
+ * WHY VERSE OWNS IT rather than each CLI's native memory: every seat runs in an
+ * isolated home (`native-profiles/<seat>/native-state`), so Claude's auto
+ * memory, Codex's `memories` and Grok's `memory/` are per ACCOUNT, and none of
+ * them crosses engines. A plain Markdown file in a directory Verse controls is
+ * the one surface all four engines can be pointed at, costs nothing (no
+ * background extraction model runs — those spend automatically), and stays
+ * OUTSIDE the repository, so nothing an agent writes here lands in a diff.
+ * (docs/VERSE-CONTEXT.md, research frontier-native-memory.)
+ *
+ * HOW A SESSION SEES IT: `prepareProjectMemory` returns `{dir, block,
+ * writable}`, which the API snapshots into the private launch record at
+ * creation. The adapters send the SAME `block` on every turn (claude/local:
+ * `--append-system-prompt`; codex/grok per their adapters) — byte-identical, so
+ * the provider's prompt cache survives turn after turn. The block carries the
+ * MEMORY.md of the moment the chat began; agents that can reach `dir` read the
+ * live file for anything newer.
+ *
+ * SAFETY
+ *  - The directory key is a hash of the canonical path, so two projects with
+ *    the same basename never share memory and a path cannot traverse out.
+ *  - MEMORY.md is read without following symlinks: an agent that replaced it
+ *    with a link to ~/.ssh/id_ed25519 would otherwise have that file echoed to
+ *    the UI and into every future system prompt.
+ *  - The block is `scrubSecrets`'d and capped at VERSE_MEMORY_BLOCK_MAX_BYTES.
+ *    The instructions tell agents never to store secrets; the scrub is the
+ *    backstop, not the policy.
+ *  - The block is ARGV-SAFE: C0/C1 control characters (NUL above all) are
+ *    stripped. The block rides on argv (`--append-system-prompt=…`,
+ *    `--rules=…`) and Node's spawn throws ERR_INVALID_ARG_VALUE for any argv
+ *    element containing NUL. Agents write MEMORY.md directly (not through
+ *    `writeProjectMemory`'s NUL check), and the block is pinned into the
+ *    launch record — so one stray NUL would otherwise make every new chat in
+ *    the project unable to start, permanently.
+ *
+ * Spends nothing and starts no process.
+ */
+import { createHash } from 'node:crypto';
+import { lstatSync, readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { scrubSecrets } from '../util/scrub.js';
+import { canonicalProjectPath, defaultVerseRoot, ensurePrivateDirectory, loadVersePreferences, memoryEnabledFor, readPrivateFileCapped, utf8Prefix, VerseServiceError, writePrivateFileAtomic, } from './preferences.js';
+import { VERSE_MEMORY_BLOCK_MAX_BYTES, VERSE_MEMORY_MAX_BYTES } from './types.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const VERSE_MEMORY_DIRNAME = 'memory';
+export const VERSE_MEMORY_FILE = 'MEMORY.md';
+/** Hard cap on the system-prompt block, instructions included. */
+export { VERSE_MEMORY_BLOCK_MAX_BYTES }; // defined in types.ts so the browser mirrors it exactly
+/** Longest MEMORY.md the UI is shown; agents can outgrow the write cap, and a view must not truncate silently below it. */
+const MEMORY_READ_CAP_BYTES = 4 * VERSE_MEMORY_MAX_BYTES;
+/** Names listed from the memory directory. */
+const MAX_LISTED_FILES = 200;
+const SLUG_MAX_CHARS = 40;
+/** Marker appended where the snapshot in the block was cut. */
+export const VERSE_MEMORY_TRUNCATION_MARKER = `[… ${VERSE_MEMORY_FILE} continues — read the file for the rest]`;
+// ---------------------------------------------------------------------------
+// Locating a project's memory
+// ---------------------------------------------------------------------------
+function slugOf(name) {
+    const slug = name
+        .normalize('NFKD')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, SLUG_MAX_CHARS)
+        .replace(/-+$/g, '');
+    return slug.length > 0 ? slug : 'project';
+}
+/**
+ * The memory directory for a project. Pure path arithmetic (no I/O beyond the
+ * realpath canonicalisation); does not create anything.
+ *
+ * @param root the Verse store root (default `~/.ashlr/verse`), the same root
+ *             the session engine and preferences use.
+ */
+export function projectMemoryDir(projectPath, root = defaultVerseRoot()) {
+    const canonical = canonicalProjectPath(projectPath);
+    const hash = createHash('sha256').update(canonical).digest('hex').slice(0, 12);
+    return join(root, VERSE_MEMORY_DIRNAME, `${slugOf(basename(canonical))}-${hash}`);
+}
+// ---------------------------------------------------------------------------
+// The system-prompt block
+// ---------------------------------------------------------------------------
+/**
+ * Every C0 control except TAB (\x09) and LF (\x0A), plus DEL and the C1 range.
+ * CR is included: callers normalise CRLF to LF first, and a lone CR left in a
+ * system prompt only garbles how the text renders.
+ */
+// eslint-disable-next-line no-control-regex
+const UNSAFE_CONTROL_CHARS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g;
+/**
+ * Text made safe to pass as (part of) an argv element and to show as prose:
+ * CRLF → LF, then every control character except `\n` and `\t` removed.
+ * Exported so the engine can repair a snapshot pinned before this existed
+ * (a launch record carrying a NUL must be healed, not rejected — rejecting it
+ * would brick the session it belongs to).
+ */
+export function stripUnsafeControlChars(text) {
+    return text.replace(/\r\n?/g, '\n').replace(UNSAFE_CONTROL_CHARS, '');
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+/** Cut `text` to at most `maxBytes`, preferring a line boundary, never splitting a character. */
+function cutToBytes(text, maxBytes) {
+    if (byteLength(text) <= maxBytes)
+        return text;
+    const prefix = utf8Prefix(Buffer.from(text, 'utf8').subarray(0, Math.max(0, maxBytes)));
+    const lastNewline = prefix.lastIndexOf('\n');
+    // Only back up to a line boundary when that keeps most of the budget.
+    return lastNewline >= prefix.length * 0.6 ? prefix.slice(0, lastNewline) : prefix;
+}
+/**
+ * The fixed instructions. SHORT and DIRECTIVE on purpose: it rides on every
+ * turn's system prompt, so each sentence is paid for again and again (cheaply,
+ * from cache — which is why it must never vary between turns of one chat).
+ */
+function memoryInstructions(dir, projectName, writable) {
+    const file = join(dir, VERSE_MEMORY_FILE);
+    const lines = [
+        '# Shared project memory (Ashlr Verse)',
+        '',
+        `Every AI seat that works on "${projectName}" shares one memory directory, kept outside the repository:`,
+        `  ${dir}`,
+        `Its index is ${file}.`,
+        '',
+    ];
+    if (writable) {
+        lines.push(`- Before substantial work, read ${VERSE_MEMORY_FILE}: the file on disk may be newer than the snapshot below.`, `- Keep ${VERSE_MEMORY_FILE} a concise index (at most 200 lines) of DURABLE facts, each with its reason: decisions and why they were made, conventions, gotchas, and the status of the current plan. Put detail in other files in the same directory and link them from the index.`, '- Update it at milestones (a decision made, a plan step finished, a gotcha found), not after every edit. Edit in place and delete facts that are no longer true.', '- Never store secrets, credentials, tokens or personal data there.');
+    }
+    else {
+        lines.push('- This seat may only READ the memory: rely on the snapshot below (and the directory, if your tools can reach it). Do not try to write there.', '- If you learn something durable — a decision and its reason, a convention, a gotcha, plan status — say so in your reply so it can be recorded.', '- Never repeat secrets, credentials, tokens or personal data from it.');
+    }
+    lines.push('', `## ${VERSE_MEMORY_FILE} when this chat began`, '');
+    return lines.join('\n');
+}
+/**
+ * Deterministic: the same (dir, content, writable) always yields the same
+ * bytes, so a block snapshotted into a launch record keeps the prompt prefix
+ * cache-stable for the whole conversation.
+ */
+export function renderMemoryBlock(input) {
+    // The project name is a directory basename: legal on disk with control
+    // bytes in it, never legal on argv with a NUL. `dir` is a real path (no NUL
+    // possible) and must stay byte-exact, so it is left alone.
+    const head = memoryInstructions(input.dir, stripUnsafeControlChars(input.projectName), input.writable);
+    // Strip BEFORE scrubbing and trimming, so a control byte can neither split a
+    // secret the scrubber would have matched nor survive at an edge.
+    const body = scrubSecrets(stripUnsafeControlChars(input.content)).trim();
+    if (body.length === 0) {
+        return cutToBytes(`${head}(empty — nothing recorded yet)`, VERSE_MEMORY_BLOCK_MAX_BYTES);
+    }
+    const budget = VERSE_MEMORY_BLOCK_MAX_BYTES - byteLength(head);
+    if (byteLength(body) <= budget)
+        return `${head}${body}`;
+    const room = budget - byteLength(`\n${VERSE_MEMORY_TRUNCATION_MARKER}`);
+    if (room <= 0)
+        return cutToBytes(head, VERSE_MEMORY_BLOCK_MAX_BYTES);
+    return `${head}${cutToBytes(body, room).trimEnd()}\n${VERSE_MEMORY_TRUNCATION_MARKER}`;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+function ensureMemoryDir(dir, root) {
+    ensurePrivateDirectory(root);
+    ensurePrivateDirectory(join(root, VERSE_MEMORY_DIRNAME));
+    ensurePrivateDirectory(dir);
+}
+/** MEMORY.md, safely: regular file only, never through a symlink. */
+function readMemoryFile(dir) {
+    const file = readPrivateFileCapped(join(dir, VERSE_MEMORY_FILE), MEMORY_READ_CAP_BYTES);
+    return file ? { text: file.text, bytes: file.bytes, mtimeMs: file.mtimeMs } : null;
+}
+/** Everything else the agents keep beside MEMORY.md (names only; dirs end in '/'). */
+function listOtherFiles(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.sort()) {
+        if (out.length >= MAX_LISTED_FILES)
+            break;
+        if (name === VERSE_MEMORY_FILE)
+            continue;
+        // Our own atomic-write temporaries (and any other dot-temp) are not content.
+        if (name.startsWith('.') && name.endsWith('.tmp'))
+            continue;
+        try {
+            const stat = lstatSync(join(dir, name));
+            if (stat.isDirectory())
+                out.push(`${name}/`);
+            else if (stat.isFile())
+                out.push(name);
+            // Symlinks, sockets, fifos are not listed: nothing here should be one.
+        }
+        catch {
+            // Vanished between readdir and lstat.
+        }
+    }
+    return out;
+}
+/**
+ * Create the project's memory directory (0700) and render the block a new
+ * session will carry. Called once, at session creation; the result is pinned
+ * in the launch record (`VerseSeatLaunch.memory`).
+ *
+ * `writable` is the SEAT's capability, decided by the caller from the engine:
+ * claude/local (`--add-dir`) and codex (writable root) can write; grok, which
+ * reaches only its `--cwd`, cannot.
+ */
+export function prepareProjectMemory(projectPath, opts) {
+    const root = opts.root ?? defaultVerseRoot();
+    const canonical = canonicalProjectPath(projectPath);
+    const dir = projectMemoryDir(canonical, root);
+    ensureMemoryDir(dir, root);
+    const current = readMemoryFile(dir);
+    const block = renderMemoryBlock({
+        dir,
+        projectName: basename(canonical) || canonical,
+        content: current?.text ?? '',
+        writable: opts.writable,
+    });
+    return { dir, block, writable: opts.writable };
+}
+/**
+ * The project's memory as the UI shows it. Never creates anything; a project
+ * with no memory yet reads as empty with `updatedAt: null`.
+ *
+ * `enabled` is passed in (the API resolves it from preferences) so this stays
+ * a pure read of the directory.
+ */
+export function readProjectMemory(projectPath, enabled, root = defaultVerseRoot()) {
+    const canonical = canonicalProjectPath(projectPath);
+    const dir = projectMemoryDir(canonical, root);
+    let dirOk = false;
+    try {
+        const stat = lstatSync(dir);
+        dirOk = stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        dirOk = false;
+    }
+    if (!dirOk) {
+        return { projectPath: canonical, enabled, content: '', bytes: 0, updatedAt: null, files: [] };
+    }
+    const file = readMemoryFile(dir);
+    return {
+        projectPath: canonical,
+        enabled,
+        content: file?.text ?? '',
+        bytes: file?.bytes ?? 0,
+        updatedAt: file ? new Date(file.mtimeMs).toISOString() : null,
+        files: listOtherFiles(dir),
+    };
+}
+/**
+ * Replace MEMORY.md with the operator's text (atomic, 0600). An empty string
+ * clears it. Rejects content over VERSE_MEMORY_MAX_BYTES (VERSE_TOO_LARGE)
+ * rather than truncating what the operator wrote, and NUL bytes (VERSE_INVALID).
+ *
+ * Allowed whether or not memory is enabled for the project — it is the
+ * operator's own file — and `enabled` in the result reports the preference.
+ */
+export function writeProjectMemory(projectPath, content, root = defaultVerseRoot()) {
+    if (typeof content !== 'string') {
+        throw new VerseServiceError('VERSE_INVALID', 'content must be a string');
+    }
+    if (content.includes('\0')) {
+        throw new VerseServiceError('VERSE_INVALID', 'content must not contain NUL bytes');
+    }
+    const bytes = byteLength(content);
+    if (bytes > VERSE_MEMORY_MAX_BYTES) {
+        throw new VerseServiceError('VERSE_TOO_LARGE', `memory is ${bytes} bytes; the limit is ${VERSE_MEMORY_MAX_BYTES}`);
+    }
+    const canonical = canonicalProjectPath(projectPath);
+    const dir = projectMemoryDir(canonical, root);
+    ensureMemoryDir(dir, root);
+    writePrivateFileAtomic(join(dir, VERSE_MEMORY_FILE), content);
+    const enabled = memoryEnabledFor(loadVersePreferences(root), canonical);
+    return readProjectMemory(canonical, enabled, root);
+}
+//# sourceMappingURL=project-memory.js.map

package/dist/core/verse/project-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-memory.js","sourceRoot":"","sources":["../../../src/core/verse/project-memory.ts"],"names":[],"mappings":"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"}

package/dist/core/verse/seats.d.ts

@@ -30,9 +30,23 @@ import type { AshlrConfig } from '../types.js';
 import { type ClaudeUsageResult } from '../fabric/claude-usage.js';
 import type { VerseSeatLaunch } from './session-engine.js';
 import { type VerseAccountCollector, type VerseAccountRecord } from './accounts.js';
-import { type VerseOllamaModelDetail } from './local-models.js';
+import { contextWindowFromTagSuffix, type VerseLocalWindow, type VerseOllamaModelDetail, type VerseOllamaServerDefault } from './local-models.js';
 import { type VerseBootstrap, type VerseEngine, type VerseModelOption, type VerseSeat, type VerseLocalDispatch, type VerseSeatCapacity, type VerseSeatHealth, type VerseSeatUsability } from './types.js';
 type NativeEngine = Exclude<VerseEngine, 'local'>;
+/**
+ * The BUILT-IN lists: what a native seat offers when nothing better is known
+ * (a Claude seat whose CLI version could not be read, a codex/grok seat that
+ * has not fetched its own catalog yet). Real seats are built per account by
+ * {@link nativeSeatModels} from the seat's own catalog and pinned binary —
+ * see core/verse/model-windows.ts, which holds every window and the evidence
+ * for it. Exported for tests and for callers that need the documented
+ * defaults without a discovery pass.
+ *
+ * Never hard-code a model list here again. Two past failures this replaced:
+ * Claude models all inherited the CLI's 200k "unknown model" window while the
+ * CLI ran six of them at 1M, and `claude-opus-5.5` (dotted) was offered even
+ * though every Claude Code binary resolves that spelling to Opus 5.
+ */
 export declare const VERSE_NATIVE_MODELS: Readonly<Record<NativeEngine, readonly VerseModelOption[]>>;
 /**
  * LEGACY FALLBACK ONLY. Local seat visibility is now decided by the model's
@@ -65,6 +79,23 @@ export interface VerseSeatDiscoveryOptions {
      * Tests pass it explicitly; the server never does.
      */
     collector?: VerseAccountCollector | null;
+    /**
+     * Where Claude Code keeps one file per installed version (default
+     * `~/.local/share/claude/versions`). Read only to tell an operator that a
+     * newer binary than their seat's pin is already installed.
+     */
+    claudeVersionsRoot?: string;
+    /**
+     * llama-server's origin for the per-slot window probe on the llama-server
+     * lane. Default: `resolveLlamaServerOrigin(cfg)`. Tests pass it so a real
+     * llama-server on this machine can never leak into a hermetic run.
+     */
+    llamaServerOrigin?: string;
+    /**
+     * Ollama's unpinned-request default context. `undefined` reads it from the
+     * environment / server log ({@link readOllamaServerDefault}).
+     */
+    ollamaServerDefault?: VerseOllamaServerDefault | null;
 }
 export interface VerseSeatDiscovery {
     /** Public, JSON-safe seats. */
@@ -99,6 +130,56 @@ export declare function resolveOllamaBaseUrl(cfg: AshlrConfig, explicit?: string
  * everywhere lands back on the working default.
  */
 export declare function resolveVerseLocalDispatch(cfg: AshlrConfig, explicit?: VerseLocalDispatch): VerseLocalDispatch;
+/**
+ * What a native seat's profile says about the CLI it is pinned to. PRIVATE:
+ * `nativeStatePath` and `executable` are machine paths and never reach a seat
+ * as-is; only the derived version, catalog-derived models and home-relative
+ * remediation text do.
+ */
+export interface VerseSeatProfile {
+    /** The profile directory (`<…>/native-profiles/<account>`). */
+    directory: string;
+    /** The provider CLI's pinned home: CODEX_HOME / GROK_HOME / CLAUDE_CONFIG_DIR. */
+    nativeStatePath: string | null;
+    /** The one binary the launcher execs. */
+    executable: string | null;
+}
+/**
+ * Locate and read `<profile>/profile.json` from an account's launcher argv —
+ * the same derivation `mcp-seat-view.resolveAccountStateRoots` uses
+ * (`…/launcher.mjs` ⇒ its directory's `profile.json`), but lifting the
+ * executable too, which the seat needs to know which CLI version it runs.
+ *
+ * A profile whose `provider` disagrees with the account is IGNORED rather
+ * than half-trusted: reading a grok catalog for a codex seat would be worse
+ * than reading none. Returns null whenever anything is missing.
+ */
+export declare function readSeatProfile(command: readonly string[], provider: NativeEngine): VerseSeatProfile | null;
+/**
+ * The operator command that points a prepared native profile at another CLI
+ * binary (src/cli/resources.ts routes `resources` → `profile` → `repin`). It is
+ * a constant because the seat note is copy-paste remediation: a spelling that
+ * does not route (`ashlr resource-profile …` never existed) is worse than no
+ * hint, and tests pin the exact text through this one name.
+ */
+export declare const VERSE_REPIN_COMMAND = "ashlr resources profile repin";
+export declare const VERSE_CATALOG_PENDING_NOTE = "Model list is Verse's built-in list until this seat's first turn fetches its own catalog.";
+/**
+ * One native seat's models, pinned CLI version and notes.
+ *
+ * Every source is the SEAT's: its own catalog file under its profile's
+ * `nativeStatePath` and the binary its launcher execs. The unpinned global
+ * homes (`~/.codex`, `~/.grok`, `~/.claude`) belong to a different account or
+ * binary and are never read — codex-a and codex-b run different CLI versions
+ * with different catalogs on this very machine.
+ */
+export declare function nativeSeatModels(provider: NativeEngine, profile: VerseSeatProfile | null, opts?: {
+    claudeVersionsRoot?: string;
+}): {
+    models: VerseModelOption[];
+    cliVersion: string | null;
+    notes: string[];
+};
 /**
  * THE V2.1 BUG THIS SECTION EXISTS TO FIX.
  *
@@ -204,10 +285,32 @@ export declare function preferredLocalTags(cfg: AshlrConfig): string[];
  * without tool support stays hidden no matter how preferred its tag is.
  */
 export declare function localSeatPreferenceRank(tag: string, preferred: readonly string[]): number;
-/** `qwen3-coder-next:ctx64k` → 65536; null when no such suffix. */
-export declare function contextWindowFromTagSuffix(tag: string): number | null;
+/**
+ * Re-exported: the tag-suffix parser now lives beside the one local window
+ * resolver in local-models.ts (and accepts `-ctx64k`, which it used to miss).
+ */
+export { contextWindowFromTagSuffix };
 /** `qwen3-coder-next:ctx64k` → "Qwen3-Coder-Next (local)". */
 export declare function localSeatLabel(tag: string): string;
+/**
+ * Plain-language caveats for one local seat's window, or none. Only the cases
+ * where the number on screen is weaker than it looks get a note: a figure
+ * Ollama actually allocates (pinned num_ctx, resident instance, its own
+ * default, llama-server's slot) needs no apology.
+ */
+export declare function localWindowNotes(resolved: VerseLocalWindow, lane: VerseLocalDispatch, slotReported: boolean): string[];
+/**
+ * Why a local window cannot host a Claude Code session, or null when it can.
+ *
+ * Local turns run Claude Code with `CLAUDE_CODE_MAX_CONTEXT_TOKENS=<window>`
+ * (the window must be stated: the CLI otherwise assumes 200k and overflows
+ * the runner). The CLI then reserves up to 20k for the reply and compacts
+ * 13k below that, so a 32,768 window compacts at 0 — below its own ~15k fixed
+ * prompt — and every turn is blocked or loops through compaction. Such a seat
+ * is LISTED with this reason (the operator learns why, and which tag would
+ * work) rather than offered as runnable or silently hidden.
+ */
+export declare function localWindowUnusableReason(window: number): string | null;
 /**
  * Discover every seat available to this server. Never throws; native seats
  * and local seats degrade independently.
@@ -229,4 +332,3 @@ export declare function discoverSeats(cfg: AshlrConfig, opts?: VerseSeatDiscover
  * Ollama tag has no subscription window.
  */
 export declare function refreshSeatTelemetry(cfg: AshlrConfig, discovery: VerseSeatDiscovery, opts?: VerseSeatDiscoveryOptions): VerseSeatDiscovery;
-export {};