@north-light/crouter 0.3.318 → 0.3.319

package/dist/core/__tests__/inline-memory-refs.test.js

@@ -1,225 +0,0 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/inline-memory-refs.test.ts
-//
-// Load-bearing corpus regression for `buildRefInventory` — the authoritative
-// inventory the broker and terminal attach viewer both resolve inline memory
-// references against. Covers scope precedence dedup, referenceability
-// (both kinds, gated and slash docs), directory browse names, malformed-doc omission,
-// metadata-only rows, and stable ordering, all over real on-disk fixtures.
-import { test, describe, before, beforeEach, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { ensureScopeInitialized } from '../config.js';
-import { closeScopedStores } from '../scoped-state/db.js';
-import { resetScopeCache } from '../scope.js';
-import { clearSessionCache } from '../substrate/session-cache.js';
-import { memoryDir as nodeMemoryDir } from '../runtime/memory.js';
-import { buildRefInventory } from '../memory/inline-ref-inventory.js';
-import { gatewayMemoryRows } from '../runtime/chat-inventory-rows.js';
-// Wave C4 — buildRefInventory: the authoritative corpus builder. Fixture-
-// backed (node/project/user scope docs on disk), since precedence dedup,
-// referenceability-ignores-gate/slash, and directory browse names are all corpus-shape
-// facts that a pure in-memory test can't exercise. Fixture names are prefixed
-// to avoid any collision with the real shipped builtin/user corpus that
-// listAllMemoryDocs() also picks up in this environment.
-describe('buildRefInventory (fixture-backed corpus)', () => {
-    const NODE_ID = 'crtr-inline-ref-fixture-node';
-    const PROJECT_NAMESPACE = 'crtr-inline-ref-fixture-project';
-    const projectName = (local) => `${PROJECT_NAMESPACE}/root/${local}`;
-    let canvasHome;
-    let userHome;
-    let projectBase;
-    let projectRoot;
-    let prevCwd;
-    let prevCanvasHome;
-    let prevUserHome;
-    let prevNodeId;
-    function writeDoc(dir, file, frontmatter, body = 'Body.') {
-        mkdirSync(dir, { recursive: true });
-        const path = join(dir, file);
-        writeFileSync(path, `---\n${frontmatter}\n---\n${body}\n`, 'utf8');
-        return path;
-    }
-    function projectMemoryDir() {
-        return join(projectRoot, '.crouter', 'memory');
-    }
-    function userMemoryDir() {
-        return join(userHome, '.crouter', 'memory');
-    }
-    function nodeScopeMemoryDir() {
-        return nodeMemoryDir(NODE_ID);
-    }
-    function plantNorthlightVisibilityExtension() {
-        const manifestDir = join(userHome, '.crouter', 'plugins', 'northlight', '.crouter-plugin');
-        mkdirSync(manifestDir, { recursive: true });
-        writeFileSync(join(manifestDir, 'plugin.json'), JSON.stringify({
-            name: 'northlight',
-            memory_extensions: {
-                visibility: {
-                    type: 'boolean',
-                    default: true,
-                    write_help: 'Control chat visibility.',
-                    edit_help: 'Control chat visibility.',
-                },
-            },
-        }));
-    }
-    before(() => {
-        prevCanvasHome = process.env['CRTR_HOME'];
-        prevUserHome = process.env['HOME'];
-        prevNodeId = process.env['CRTR_NODE_ID'];
-        prevCwd = process.cwd();
-    });
-    beforeEach(() => {
-        closeScopedStores();
-        canvasHome = mkdtempSync(join(tmpdir(), 'crtr-inline-ref-canvas-'));
-        userHome = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-inline-ref-user-')));
-        projectBase = mkdtempSync(join(tmpdir(), 'crtr-inline-ref-project-'));
-        projectRoot = join(projectBase, 'root');
-        mkdirSync(projectRoot, { recursive: true });
-        const repositoryMemory = join(projectBase, '.crouter', 'memory');
-        mkdirSync(repositoryMemory, { recursive: true });
-        mkdirSync(projectMemoryDir(), { recursive: true });
-        writeFileSync(join(repositoryMemory, 'INDEX.md'), `---\nnamespace: ${PROJECT_NAMESPACE}\n---\nProject front door.\n`, 'utf8');
-        process.env['CRTR_HOME'] = canvasHome;
-        process.env['HOME'] = userHome;
-        process.env['CRTR_NODE_ID'] = NODE_ID;
-        process.chdir(projectRoot);
-        resetScopeCache();
-        ensureScopeInitialized('user', join(userHome, '.crouter'));
-        clearSessionCache();
-    });
-    after(() => {
-        closeScopedStores();
-        process.chdir(prevCwd);
-        resetScopeCache();
-        clearSessionCache();
-        rmSync(canvasHome, { recursive: true, force: true });
-        rmSync(userHome, { recursive: true, force: true });
-        rmSync(projectBase, { recursive: true, force: true });
-        if (prevCanvasHome === undefined)
-            delete process.env['CRTR_HOME'];
-        else
-            process.env['CRTR_HOME'] = prevCanvasHome;
-        if (prevUserHome === undefined)
-            delete process.env['HOME'];
-        else
-            process.env['HOME'] = prevUserHome;
-        if (prevNodeId === undefined)
-            delete process.env['CRTR_NODE_ID'];
-        else
-            process.env['CRTR_NODE_ID'] = prevNodeId;
-    });
-    test('canonical qualification removes project shadowing while equal identities keep precedence', () => {
-        const local = 'crtr-inline-ref-fixture-shared';
-        const qualified = projectName(local);
-        writeDoc(userMemoryDir(), `${local}.md`, "kind: knowledge\nshort-form: 'user copy'");
-        writeDoc(projectMemoryDir(), `${local}.md`, "kind: knowledge\nshort-form: 'project copy'");
-        writeDoc(nodeScopeMemoryDir(), `${local}.md`, "kind: knowledge\nshort-form: 'node copy'");
-        let { refs, names } = buildRefInventory();
-        assert.ok(names.has(local));
-        assert.ok(names.has(qualified));
-        let winner = refs.find((r) => r.name === local);
-        assert.equal(winner?.scope, 'node');
-        assert.equal(winner?.shortForm, 'node copy');
-        winner = refs.find((r) => r.name === qualified);
-        assert.equal(winner?.scope, 'project');
-        assert.equal(winner?.shortForm, 'project copy');
-        rmSync(join(nodeScopeMemoryDir(), `${local}.md`));
-        clearSessionCache();
-        ({ refs, names } = buildRefInventory());
-        winner = refs.find((r) => r.name === local);
-        assert.equal(winner?.scope, 'user');
-        assert.equal(winner?.shortForm, 'user copy');
-    });
-    test('both kinds, a gated doc, and a slash:true doc are all referenceable — no gate/rung/slash filtering', () => {
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-knowledge.md', 'kind: knowledge');
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-preference.md', 'kind: preference');
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-gated.md', 'kind: knowledge\ngate:\n  never-matches: true');
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-slash.md', 'kind: knowledge\nslash: true');
-        const { refs, names } = buildRefInventory();
-        for (const local of [
-            'crtr-inline-ref-fixture-knowledge',
-            'crtr-inline-ref-fixture-preference',
-            'crtr-inline-ref-fixture-gated',
-            'crtr-inline-ref-fixture-slash',
-        ]) {
-            const name = projectName(local);
-            assert.ok(names.has(name), `expected ${name} to be referenceable`);
-        }
-        assert.equal(refs.find((r) => r.name === projectName('crtr-inline-ref-fixture-knowledge'))?.kind, 'knowledge');
-        assert.equal(refs.find((r) => r.name === projectName('crtr-inline-ref-fixture-preference'))?.kind, 'preference');
-    });
-    test('a collapsed directory document keeps one canonical name and registers its browse node', () => {
-        const local = 'crtr-inline-ref-fixture-taste';
-        const name = projectName(local);
-        writeDoc(join(projectMemoryDir(), local), 'INDEX.md', "kind: knowledge\nshort-form: 'taste index'");
-        const { refs, names } = buildRefInventory();
-        assert.ok(!names.has(`${name}/INDEX`));
-        assert.ok(names.has(name));
-        assert.ok(refs.some((r) => r.name === name));
-        assert.equal(refs.find((r) => r.name === name)?.shortForm, 'taste index');
-    });
-    test('a project root INDEX document is omitted from refs but its namespace remains usable', () => {
-        writeDoc(join(projectBase, '.crouter', 'memory'), 'INDEX.md', `namespace: ${PROJECT_NAMESPACE}\nkind: knowledge\nshort-form: 'project root index'`);
-        const local = 'crtr-inline-ref-fixture-sibling';
-        writeDoc(projectMemoryDir(), `${local}.md`, 'kind: knowledge');
-        const { refs, names } = buildRefInventory();
-        assert.ok(!names.has(''));
-        assert.ok(!refs.some((r) => r.name === ''));
-        assert.ok(names.has(projectName(local)));
-    });
-    test('refs are metadata-only: exactly {name, kind, scope, shortForm, gatewayVisible}, no body/path', () => {
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-meta.md', "kind: knowledge\nshort-form: 'hook'");
-        const { refs } = buildRefInventory();
-        const ref = refs.find((r) => r.name === projectName('crtr-inline-ref-fixture-meta'));
-        assert.ok(ref);
-        assert.deepEqual(Object.keys(ref).sort(), ['gatewayVisible', 'kind', 'name', 'scope', 'shortForm']);
-    });
-    test('Gateway eligibility excludes builtins and effective Northlight-hidden refs without changing resolution', () => {
-        plantNorthlightVisibilityExtension();
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-hidden.md', 'kind: knowledge\nextensions:\n  northlight:\n    visibility: false');
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-visible.md', 'kind: knowledge');
-        const { refs, names } = buildRefInventory();
-        const hidden = refs.find((ref) => ref.name === projectName('crtr-inline-ref-fixture-hidden'));
-        const visible = refs.find((ref) => ref.name === projectName('crtr-inline-ref-fixture-visible'));
-        assert.equal(hidden?.gatewayVisible, false);
-        assert.equal(visible?.gatewayVisible, true);
-        assert.ok(names.has(projectName('crtr-inline-ref-fixture-hidden')));
-        assert.ok(names.has(projectName('crtr-inline-ref-fixture-visible')));
-        assert.ok(refs.some((ref) => ref.scope === 'builtin'));
-        assert.ok(refs.filter((ref) => ref.scope === 'builtin').every((ref) => !ref.gatewayVisible));
-        const chatRows = gatewayMemoryRows(refs);
-        assert.ok(!chatRows.some((ref) => ref.name === projectName('crtr-inline-ref-fixture-hidden')));
-        assert.ok(chatRows.some((ref) => ref.name === projectName('crtr-inline-ref-fixture-visible')));
-        assert.ok(!chatRows.some((ref) => ref.scope === 'builtin'));
-    });
-    test('a malformed doc (no valid kind) is omitted from the inventory', () => {
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-malformed.md', "short-form: 'no kind here'");
-        const { names } = buildRefInventory();
-        assert.ok(!names.has(projectName('crtr-inline-ref-fixture-malformed')));
-    });
-    test('project qualification keeps distinct scope identities separate', () => {
-        const local = 'crtr-inline-ref-fixture-dedup';
-        writeDoc(userMemoryDir(), `${local}.md`, 'kind: knowledge');
-        writeDoc(projectMemoryDir(), `${local}.md`, 'kind: knowledge');
-        const { refs } = buildRefInventory();
-        assert.equal(refs.filter((r) => r.name === local).length, 1);
-        assert.equal(refs.filter((r) => r.name === projectName(local)).length, 1);
-    });
-    test('refs are stably sorted by winning scope precedence then name', () => {
-        writeDoc(nodeScopeMemoryDir(), 'crtr-inline-ref-fixture-b-node.md', 'kind: knowledge');
-        writeDoc(nodeScopeMemoryDir(), 'crtr-inline-ref-fixture-a-node.md', 'kind: knowledge');
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-c-project.md', 'kind: knowledge');
-        const { refs } = buildRefInventory();
-        const fixtureRefs = refs.filter((r) => r.name.startsWith('crtr-inline-ref-fixture-'));
-        const idxA = fixtureRefs.findIndex((r) => r.name === 'crtr-inline-ref-fixture-a-node');
-        const idxB = fixtureRefs.findIndex((r) => r.name === 'crtr-inline-ref-fixture-b-node');
-        const idxC = fixtureRefs.findIndex((r) => r.name === projectName('crtr-inline-ref-fixture-c-project'));
-        // Node-scope docs (a, b) sort before the project-scope doc (c); within the
-        // same scope, alphabetically by name.
-        assert.ok(idxA < idxB, 'a-node before b-node (alphabetical within node scope)');
-        assert.ok(idxB < idxC, 'node scope before project scope');
-    });
-});

package/dist/core/__tests__/integration/broker-fork-seam.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/core/__tests__/integration/broker-fork-seam.test.js

@@ -1,193 +0,0 @@
-// Run with: npm run test:integration
-//
-// BUG-REGRESSION (broker-universal-host cut, design §B.broker; U1 report
-// mq8ftenr-5d55313d). Before the cut, the headless broker had NO fork path — its
-// session selection THREW `--fork is not supported by the headless broker`. After
-// the cut EVERY node is a broker, so `node new --fork-from <id>` would always hit
-// that throw. The fix routes the broker's fork through pi's REAL fork seam,
-// SessionManager.forkFrom (broker.ts buildBrokerSession, the `forking` branch) —
-// the same method pi's own `--fork` CLI flag uses.
-//
-// This test drives the BROKER's OWN fork branch (broker.ts buildBrokerSession,
-// the `forking` branch ~1106) end to end: it calls `buildBrokerSession` with
-// `cfg.forkFrom` set to a real source session .jsonl — the EXACT path a
-// `node new --fork-from <id>` boot takes through the broker — and asserts the
-// resulting live session is a genuine fork: a NEW session id (not a colliding
-// copy) and a `parentSession` header pointing at the source, with the source's
-// history copied in. Because it invokes `buildBrokerSession` (not
-// `SessionManager.forkFrom` directly), it goes RED if broker.ts's fork branch
-// reverts to `throw "--fork is not supported by the headless broker"` — it
-// guards its own stated regression.
-//
-// Like the C3/C4 real-SDK wiring tests, it drives the REAL engine (broker-sdk's
-// static SDK re-exports) — NOT the CRTR_BROKER_ENGINE fake the lifecycle suite
-// uses, whose fixture omits forkFrom and so could never exercise this branch. It
-// runs offline (fork + session/services assembly are all local: no network/auth).
-//
-// The tail of this file covers the pre-launch resolve layer that feeds the
-// broker branch: `resolveForkSource` refusing a reference that resolves to no
-// forkable session file.
-import { test, before, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createNode } from '../../canvas/canvas.js';
-import { closeDb, migrate, openDb } from '../../canvas/db.js';
-import { closeScopedStores } from '../../scoped-state/db.js';
-import { initializeFreshScopedStore } from '../../scoped-state/migrate.js';
-import { resolveForkSource } from '../../runtime/spawn.js';
-import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../../runtime/broker-sdk.js';
-import { buildBrokerSession } from '../../runtime/broker.js';
-// M-9 (broker.ts fault-and-die model gate): buildBrokerSession with no cfg.model
-// now calls the REAL SDK's modelRegistry.getAvailable() and faults if it's empty
-// — which it always is on a host/CI runner with no authenticated provider. This
-// test drives the fork branch only, so it registers the SAME hermetic
-// fake-but-authenticated model the C3 wiring tests use, rather than depending on
-// ambient host credentials (which don't exist in CI — see broker-sdk-wiring's
-// c3-custom-provider-ext.ts fixture).
-const HERE = join(dirname(fileURLToPath(import.meta.url)), '..');
-const C3_EXT = join(HERE, 'fixtures', 'c3-custom-provider-ext.ts');
-// The REAL engine — bypasses the CRTR_BROKER_ENGINE fake entirely (the whole
-// point: the fake omits forkFrom, so only the real SDK can prove the branch).
-const realEngine = {
-    createAgentSessionServices,
-    createAgentSessionFromServices,
-    SessionManager,
-    VERSION,
-};
-let dir;
-let home;
-let agentDir;
-const previousHome = process.env['HOME'];
-const previousCanvasHome = process.env['CRTR_HOME'];
-const previousAgentDir = process.env['PI_CODING_AGENT_DIR'];
-before(() => {
-    dir = mkdtempSync(join(tmpdir(), 'crtr-fork-seam-'));
-    home = mkdtempSync(join(tmpdir(), 'crtr-fork-home-'));
-    closeDb();
-    closeScopedStores();
-    process.env['HOME'] = home;
-    process.env['CRTR_HOME'] = join(home, '.crouter', 'canvas');
-    agentDir = join(home, '.pi', 'agent');
-    process.env['PI_CODING_AGENT_DIR'] = agentDir;
-    migrate(openDb());
-    initializeFreshScopedStore({ kind: 'user', root: join(home, '.crouter') });
-    initializeFreshScopedStore({ kind: 'provider', root: agentDir });
-});
-after(() => {
-    closeDb();
-    closeScopedStores();
-    if (previousHome === undefined)
-        delete process.env['HOME'];
-    else
-        process.env['HOME'] = previousHome;
-    if (previousCanvasHome === undefined)
-        delete process.env['CRTR_HOME'];
-    else
-        process.env['CRTR_HOME'] = previousCanvasHome;
-    if (previousAgentDir === undefined)
-        delete process.env['PI_CODING_AGENT_DIR'];
-    else
-        process.env['PI_CODING_AGENT_DIR'] = previousAgentDir;
-    rmSync(dir, { recursive: true, force: true });
-    rmSync(home, { recursive: true, force: true });
-});
-/** A minimal but VALID pi session .jsonl (the exact on-disk shape v3 emits): a
- *  `session` header line + two `message` entries. This is what a node that has
- *  run a turn or two carries on disk — the source the broker forks from. */
-function writeSourceSession(path, srcId) {
-    const lines = [
-        JSON.stringify({ type: 'session', version: 3, id: srcId, timestamp: '2026-06-10T20:27:32.891Z', cwd: dir }),
-        JSON.stringify({ type: 'message', id: 'a42170e1', parentId: null, timestamp: '2026-06-10T20:27:32.893Z', message: { role: 'user', content: 'source turn one' } }),
-        JSON.stringify({ type: 'message', id: 'f309b932', parentId: 'a42170e1', timestamp: '2026-06-10T20:27:32.893Z', message: { role: 'assistant', content: 'source reply one' } }),
-    ];
-    writeFileSync(path, lines.join('\n') + '\n');
-    return 2; // entry count (the two message lines)
-}
-test('D2 broker fork branch: buildBrokerSession(cfg.forkFrom) yields a NEW id + parentSession header, copying history (never throws "fork not supported")', async () => {
-    // 1. A real source session on disk.
-    const srcFile = join(dir, 'src.jsonl');
-    const srcId = '019eb338-029b-7536-b3eb-d33bd6f641a8';
-    const srcEntryCount = writeSourceSession(srcFile, srcId);
-    // 2. Drive the BROKER's fork branch: buildBrokerSession with cfg.forkFrom set —
-    //    the same recipe a `node new --fork-from <id>` boot produces. The OLD broker
-    //    THREW in this branch ("--fork is not supported by the headless broker"), so
-    //    if broker.ts:~1106 reverts to that throw, this rejects and the test goes RED.
-    const cfg = {
-        cwd: dir,
-        extensionPaths: [C3_EXT],
-        forkFrom: srcFile,
-        model: 'c3prov/c3model',
-    };
-    let session;
-    let resuming;
-    await assert.doesNotReject(async () => {
-        const built = await buildBrokerSession(realEngine, cfg);
-        session = built.session;
-        resuming = built.resuming;
-    }, 'the broker fork branch must NOT throw "fork is not supported by the headless broker"');
-    assert.ok(session !== undefined, 'buildBrokerSession returned a live session for the fork');
-    try {
-        // 3. A fork boots as a FRESH spawn (resuming=false) so the kickoff firstPrompt
-        //    fires — the new node gets the source history AND a new task to start on.
-        assert.equal(resuming, false, 'a fork is a fresh spawn (resuming=false) so the kickoff fires');
-        // 4. Real fork metadata on the broker's selected SessionManager, not a
-        //    colliding .jsonl copy.
-        const sm = session.sessionManager;
-        assert.notEqual(sm.getSessionId(), srcId, 'the fork is a NEW session id (not a copy that would collide on resume)');
-        const header = sm.getHeader();
-        assert.equal(header?.parentSession, srcFile, 'the fork header records parentSession pointing at the source .jsonl');
-        // 5. The source history is carried into the fork (fork copies, not empty
-        //    start). The broker boot may append its own session-start entry, so the
-        //    fork holds AT LEAST the source's messages — a naïve empty session would
-        //    have zero.
-        assert.ok(sm.getEntries().length >= srcEntryCount, `the fork carries the source conversation history forward ` +
-            `(>= ${srcEntryCount} source entries; got ${sm.getEntries().length})`);
-    }
-    finally {
-        session.dispose();
-    }
-});
-// resolveForkSource — a reference that resolves to no forkable session file
-// must fail loudly BEFORE launch, rather than hand the broker a source it
-// cannot fork.
-function nodeRow(id, over = {}) {
-    return {
-        node_id: id,
-        name: id,
-        created: new Date().toISOString(),
-        cwd: '/tmp/work',
-        kind: 'developer',
-        mode: 'base',
-        lifecycle: 'terminal',
-        status: 'active',
-        ...over,
-    };
-}
-test('resolveForkSource refuses every reference that resolves to no forkable session file', () => {
-    const sessions = mkdtempSync(join(tmpdir(), 'crtr-pi-agent-'));
-    const previousSessions = process.env['PI_CODING_AGENT_DIR'];
-    process.env['PI_CODING_AGENT_DIR'] = sessions;
-    try {
-        // Broker-cut contract (U6/§B.broker): the broker forks an absolute .jsonl
-        // PATH, never a bare session id, so a node row carrying only pi_session_id
-        // is unforkable.
-        createNode(nodeRow('id-only', { pi_session_id: 'uuid-1' }));
-        assert.throws(() => resolveForkSource('id-only'), /no pi session yet|session FILE/);
-        createNode(nodeRow('fresh'));
-        assert.throws(() => resolveForkSource('fresh'), /no pi session yet/);
-        // An unknown bare/partial uuid is scanned against pi's sessions store and
-        // fails when it matches nothing — never passed through verbatim.
-        assert.throws(() => resolveForkSource('019e8ce3-322e'), /no pi session/);
-        assert.throws(() => resolveForkSource('   '), /requires a node id/);
-    }
-    finally {
-        if (previousSessions === undefined)
-            delete process.env['PI_CODING_AGENT_DIR'];
-        else
-            process.env['PI_CODING_AGENT_DIR'] = previousSessions;
-        rmSync(sessions, { recursive: true, force: true });
-    }
-});

package/dist/core/__tests__/integration/broker-sdk-wiring.test.d.ts

@@ -1 +0,0 @@
-export {};