@illuminis/comprism 0.1.3 → 0.1.5

package/out/lib/sync.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectBatch = collectBatch;
+exports.sync = sync;
+/**
+ * Sync: the one thin contract between the Companion and the tenant.
+ *
+ * The Companion works standalone with no service to call - that is the wedge,
+ * and nothing here changes it. Sync is opt-in, additive, and one direction: the
+ * local stores are read, posted, and left exactly as they were. Nothing is
+ * deleted locally on success, because the local record is the primary evidence
+ * and a server round trip is not a reason to destroy it.
+ *
+ * Two properties make it safe to run on a cron:
+ *
+ *   **Idempotent.** Every record is keyed by the id the Companion assigned it,
+ *   and the server refuses a duplicate rather than inserting a second copy. A
+ *   retry after a dropped connection cannot double-count anyone's spend.
+ *
+ *   **Reconciled.** The response carries what the batch claimed and what the
+ *   tenant now holds. If the two disagree, that is visible here, in the command
+ *   the person just ran - not three weeks later in a figure someone is trying to
+ *   defend to a CFO.
+ */
+const chains_1 = require("../internal/chains");
+const config_1 = require("./config");
+const evidence_1 = require("../internal/evidence");
+const links_1 = require("../internal/links");
+const scan_1 = require("../internal/scan");
+const sessions_1 = require("../commands/sessions");
+const snapshot_1 = require("../internal/snapshot");
+const store_1 = require("./store");
+const version_1 = require("./version");
+/** Everything the local stores hold, in the shape the tenant expects. */
+function collectBatch() {
+    const sessions = (0, sessions_1.listSessions)();
+    const chains = (0, chains_1.buildChainsFromStore)(sessions);
+    return {
+        companion_version: version_1.COMPRISM_VERSION,
+        sessions,
+        ledger: (0, store_1.readRows)(store_1.LEDGER_FILE),
+        decisions: (0, snapshot_1.readSnapshots)(),
+        chains,
+        links: (0, links_1.readLinks)(),
+        executed_pairs: (0, evidence_1.readExecutedPairs)(),
+        policy_rejections: (0, evidence_1.readRejections)(),
+        exploration: (0, evidence_1.readExploration)(),
+        imported_ledger: (0, scan_1.readImportedLedger)(),
+        scan_findings: (0, scan_1.readFindings)(),
+    };
+}
+async function sync(target) {
+    const batch = collectBatch();
+    const cfg = (0, config_1.loadConfig)();
+    const headers = {
+        'content-type': 'application/json',
+        authorization: `Bearer ${target.token}`,
+    };
+    // On localhost there is no subdomain, so the tenant travels in a header.
+    // Hyphenated in the header, underscored in the schema: the single most common
+    // cause of "it cannot find the tenant".
+    if (target.tenant)
+        headers['X-Tenant-ID'] = target.tenant;
+    const res = await fetch(`${target.url.replace(/\/+$/, '')}/api/v1/completion/sync`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(batch),
+    });
+    if (!res.ok) {
+        // The status line, never the body: a server error body can echo the payload,
+        // and the payload is the customer's record.
+        throw new Error(`sync failed: ${res.status} ${res.statusText}`);
+    }
+    const result = (await res.json());
+    const sent = {};
+    for (const [key, value] of Object.entries(batch)) {
+        if (Array.isArray(value))
+            sent[key] = value.length;
+    }
+    return { ...result, sent, ...(cfg.mode ? {} : {}) };
+}

package/out/lib/ui.d.ts

@@ -35,6 +35,14 @@ export declare const c: {
  * and the brand is the one thing a customer notices before the engine.
  */
 export declare function spectrumAt(index: number, glyph: string): string;
+/**
+ * A small picture, drawn two pixels to a character with the half block glyph:
+ * the top pixel is the glyph's color and the bottom one its background, which
+ * makes each pixel square in an ordinary terminal font. Each row of `pixels`
+ * is six hex digits per pixel, `......` for a clear one, and two rows make one
+ * line. Returns nothing without color, because the picture is only color.
+ */
+export declare function pixelArt(pixels: string[]): string[];
 export declare function prismRule(w?: number): string;
 export declare function banner(subtitle?: string): string;
 export declare function money(v: number | null): string;
@@ -79,12 +87,10 @@ export declare function table(headers: string[], rows: string[][]): string;
  * out of the way, leaving the answer and a one-line receipt.
  */
 export declare class LiveIndicator {
-    private timer;
-    private frame;
-    private label;
-    private readonly frames;
+    private shown;
     start(label: string): void;
     update(label: string): void;
+    private draw;
     stop(): void;
 }
 export interface ReceiptData {

package/out/lib/ui.js

@@ -19,6 +19,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LiveIndicator = exports.c = void 0;
 exports.width = width;
 exports.spectrumAt = spectrumAt;
+exports.pixelArt = pixelArt;
 exports.prismRule = prismRule;
 exports.banner = banner;
 exports.money = money;
@@ -35,15 +36,20 @@ exports.warn = warn;
 exports.fail = fail;
 exports.info = info;
 const isTty = process.stdout.isTTY === true;
-const noColor = !!process.env.NO_COLOR || process.env.TERM === 'dumb';
-const useColor = isTty && !noColor;
+/** Decided when drawn, not when loaded, so `--plain`, `plain true` and
+ *  `theme plain` applied at start up take effect (manual 6.10, 6.12). */
+const noColor = () => !!process.env.NO_COLOR || process.env.TERM === 'dumb';
+const useColorNow = () => isTty && !noColor();
+/** Plain mode: no color and nothing redrawn; every update is a new line. */
+const plainNow = () => process.env.COMPRISM_PLAIN === '1' || !isTty;
+const light = () => process.env.COMPRISM_THEME === 'light';
 function width() {
     return Math.min(process.stdout.columns || 88, 100);
 }
 // ── palette ─────────────────────────────────────────────────────────────────
 // illuminis brand, from branding/brand.toml. Deep navy is unreadable on a dark
 // terminal, so the terminal palette leans on the two blues and the purple.
-const rgb = (r, g, b) => (s) => useColor ? `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m` : s;
+const rgb = (r, g, b) => (s) => useColorNow() ? `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m` : s;
 exports.c = {
     blue: rgb(59, 111, 181), // primary_blue  #3B6FB5
     deep: rgb(31, 77, 120), // heading_blue  #1F4D78
@@ -52,9 +58,10 @@ exports.c = {
     amber: rgb(217, 119, 6), // warning       #D97706
     red: rgb(220, 38, 38), // error         #DC2626
     muted: rgb(158, 158, 158), // muted_text    #9E9E9E
-    text: rgb(214, 219, 228),
-    bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
-    dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+    // Light on a dark terminal, dark on a light one (manual 6.10).
+    text: (s) => (light() ? rgb(40, 44, 52)(s) : rgb(214, 219, 228)(s)),
+    bold: (s) => (useColorNow() ? `\x1b[1m${s}\x1b[0m` : s),
+    dim: (s) => (useColorNow() ? `\x1b[2m${s}\x1b[0m` : s),
 };
 /** The prism: white light entering, a spectrum leaving. The brand in one line. */
 const SPECTRUM = [
@@ -75,13 +82,46 @@ const SPECTRUM = [
  * and the brand is the one thing a customer notices before the engine.
  */
 function spectrumAt(index, glyph) {
-    if (!useColor)
+    if (!useColorNow())
         return glyph;
     const [r, g, b] = SPECTRUM[Math.abs(index) % SPECTRUM.length];
     return `\x1b[38;2;${r};${g};${b}m${glyph}\x1b[0m`;
 }
+/**
+ * A small picture, drawn two pixels to a character with the half block glyph:
+ * the top pixel is the glyph's color and the bottom one its background, which
+ * makes each pixel square in an ordinary terminal font. Each row of `pixels`
+ * is six hex digits per pixel, `......` for a clear one, and two rows make one
+ * line. Returns nothing without color, because the picture is only color.
+ */
+function pixelArt(pixels) {
+    if (!useColorNow())
+        return [];
+    const at = (row, x) => {
+        const hex = row?.slice(x * 6, x * 6 + 6);
+        return !hex || hex === '......' ? null
+            : [0, 2, 4].map((k) => parseInt(hex.slice(k, k + 2), 16)).join(';');
+    };
+    const lines = [];
+    for (let y = 0; y < pixels.length; y += 2) {
+        let line = '';
+        for (let x = 0; x < (pixels[y]?.length ?? 0) / 6; x++) {
+            const top = at(pixels[y], x), bottom = at(pixels[y + 1], x);
+            if (top && bottom)
+                line += `\x1b[38;2;${top}m\x1b[48;2;${bottom}m▀\x1b[0m`;
+            else if (top)
+                line += `\x1b[38;2;${top}m▀\x1b[0m`;
+            else if (bottom)
+                line += `\x1b[38;2;${bottom}m▄\x1b[0m`;
+            else
+                line += ' ';
+        }
+        lines.push(line);
+    }
+    return lines;
+}
 function prismRule(w = width()) {
-    if (!useColor)
+    if (!useColorNow())
         return '-'.repeat(w);
     const seg = Math.max(1, Math.floor(w / SPECTRUM.length));
     let out = '';
@@ -197,29 +237,29 @@ function table(headers, rows) {
  * out of the way, leaving the answer and a one-line receipt.
  */
 class LiveIndicator {
-    timer = null;
-    frame = 0;
-    label = '';
-    frames = ['◜', '◠', '◝', '◞', '◡', '◟'];
+    shown = false;
+    // No animation of its own. A glyph turning on a timer looks like work
+    // whether or not anything is happening; the line changes only when the
+    // caller has something new to say, and in plain mode each change is a new
+    // line rather than a redraw (manual 6.12).
     start(label) {
-        if (!isTty)
-            return;
-        this.label = label;
-        this.timer = setInterval(() => {
-            const glyph = this.frames[this.frame % this.frames.length];
-            this.frame += 1;
-            process.stdout.write(`\r  ${exports.c.purple(glyph)} ${exports.c.dim(this.label)}   `);
-        }, 90);
+        this.draw(label);
     }
     update(label) {
-        this.label = label;
+        this.draw(label);
+    }
+    draw(label) {
+        if (plainNow()) {
+            process.stdout.write(`  ${label}\n`);
+            return;
+        }
+        process.stdout.write(`\r  ${exports.c.purple('◠')} ${exports.c.dim(label)}   `);
+        this.shown = true;
     }
     stop() {
-        if (this.timer)
-            clearInterval(this.timer);
-        this.timer = null;
-        if (isTty)
+        if (this.shown && !plainNow())
             process.stdout.write(`\r${' '.repeat(width())}\r`);
+        this.shown = false;
     }
 }
 exports.LiveIndicator = LiveIndicator;

package/out/lib/voice.d.ts

@@ -34,6 +34,42 @@ export interface Recording {
  * headed off with `missing` so the person gets a sentence rather than an error.
  */
 export declare function start(): Recording;
+/** Live dictation in progress, on the Mac's own recogniser. */
+export interface LiveDictation {
+    /** The loudness now, 0 to 1. */
+    level: () => number;
+    /** The words so far. */
+    words: () => string;
+    /** Stop listening and get the final words, or null when it could not listen. */
+    stop: () => Promise<string | null>;
+    /** Why it could not listen, when it could not. */
+    problem: () => string;
+}
+/**
+ * Words as they are spoken, the way the web app shows them.
+ *
+ * Nothing is recorded to a file and nothing leaves the machine: the Mac's own
+ * recogniser listens and reports what it hears, several times a second.
+ * Returns null where there is no helper, and the caller records and has the
+ * server write it down instead, as before.
+ */
+export declare function listenLive(language?: string): LiveDictation | null;
+/**
+ * How loud the last tenth of a second was, from 0 to 1.
+ *
+ * Read off the file as it is written, so somebody speaking sees the meter move
+ * and knows they are being heard, before a single word has come back. Sixteen
+ * bit mono at 16 kHz is 3,200 bytes a tenth of a second.
+ */
+export declare function level(file: string): number;
+/**
+ * What has been said so far, as a WAV file a transcriber can read.
+ *
+ * The recorder writes the header's lengths only when it stops, so a copy taken
+ * mid recording claims no audio at all. The copy gets the lengths of what is
+ * actually there. Returns null until there is at least half a second to send.
+ */
+export declare function soFar(file: string): string | null;
 /** Delete the recording and the folder holding it. Always, and immediately. */
 export declare function discard(file: string): void;
 /**

package/out/lib/voice.js

@@ -36,6 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.recorder = recorder;
 exports.missing = missing;
 exports.start = start;
+exports.listenLive = listenLive;
+exports.level = level;
+exports.soFar = soFar;
 exports.discard = discard;
 exports.transcribe = transcribe;
 /**
@@ -102,7 +105,9 @@ const RECORDERS = [
             ...(process.platform === 'darwin'
                 ? ['-f', 'avfoundation', '-i', ':default']
                 : ['-f', 'alsa', '-i', 'default']),
-            '-ac', '1', '-ar', RATE, '-y', out,
+            // Written as it is heard, not held until the end, so the meter and the
+            // words so far have something to read while the person is speaking.
+            '-ac', '1', '-ar', RATE, '-flush_packets', '1', '-y', out,
         ],
     },
     // Linux's own, present on most desktop installs.
@@ -143,6 +148,30 @@ function start() {
         stdio: ['ignore', 'ignore', 'ignore'],
     });
     let stopped = null;
+    // The recorder never outlives the session. Closing the window or ending the
+    // process while it listens would otherwise leave a microphone recording to a
+    // file nobody knows about, the worst thing this tool could do.
+    const abandon = () => {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch { /* already gone */ }
+        discard(file);
+    };
+    const onSignal = (signal) => {
+        abandon();
+        release();
+        process.kill(process.pid, signal);
+    };
+    const release = () => {
+        process.off('exit', abandon);
+        process.off('SIGHUP', onSignal);
+        process.off('SIGTERM', onSignal);
+    };
+    process.once('exit', abandon);
+    process.once('SIGHUP', onSignal);
+    process.once('SIGTERM', onSignal);
+    child.once('close', release);
     const stop = () => {
         if (stopped)
             return stopped;
@@ -182,6 +211,136 @@ function start() {
     };
     return { file, by: tool.name, stop };
 }
+/** The helper built beside this file on a Mac, when there is one. */
+function helper() {
+    if (process.platform !== 'darwin')
+        return null;
+    const p = path.join(__dirname, '..', 'native', 'dictate');
+    return fs.existsSync(p) ? p : null;
+}
+/**
+ * Words as they are spoken, the way the web app shows them.
+ *
+ * Nothing is recorded to a file and nothing leaves the machine: the Mac's own
+ * recogniser listens and reports what it hears, several times a second.
+ * Returns null where there is no helper, and the caller records and has the
+ * server write it down instead, as before.
+ */
+function listenLive(language = 'en-US') {
+    const bin = helper();
+    if (!bin)
+        return null;
+    const child = (0, node_child_process_1.spawn)(bin, [language], { stdio: ['pipe', 'pipe', 'ignore'] });
+    let loud = 0;
+    let heard = '';
+    let final = null;
+    let why = '';
+    let rest = '';
+    const ended = new Promise((resolve) => child.once('close', () => resolve()));
+    child.stdout?.on('data', (chunk) => {
+        rest += chunk.toString('utf8');
+        const lines = rest.split('\n');
+        rest = lines.pop() ?? '';
+        for (const line of lines) {
+            const kind = line.slice(0, 1);
+            const text = line.slice(2);
+            if (kind === 'L')
+                loud = Number(text) || 0;
+            else if (kind === 'P')
+                heard = text;
+            else if (kind === 'F')
+                final = text;
+            else if (kind === 'E')
+                why = text;
+        }
+    });
+    // The helper never outlives the session.
+    const abandon = () => { try {
+        child.kill('SIGKILL');
+    }
+    catch { /* gone */ } };
+    process.once('exit', abandon);
+    return {
+        level: () => loud,
+        words: () => heard,
+        problem: () => why,
+        stop: async () => {
+            // Closing its input is "Enter was pressed": it says its final words and ends.
+            try {
+                child.stdin?.end();
+            }
+            catch { /* gone */ }
+            const timeout = new Promise((resolve) => setTimeout(resolve, 4000).unref());
+            await Promise.race([ended, timeout]);
+            abandon();
+            process.off('exit', abandon);
+            if (why && !final && !heard)
+                return null;
+            return (final ?? heard).trim();
+        },
+    };
+}
+/** Where the samples start in a WAV file this recorder wrote, or -1. */
+function dataStart(buf) {
+    const at = buf.indexOf('data', 12, 'ascii');
+    return at < 0 ? -1 : at + 8;
+}
+/**
+ * How loud the last tenth of a second was, from 0 to 1.
+ *
+ * Read off the file as it is written, so somebody speaking sees the meter move
+ * and knows they are being heard, before a single word has come back. Sixteen
+ * bit mono at 16 kHz is 3,200 bytes a tenth of a second.
+ */
+function level(file) {
+    try {
+        const size = fs.statSync(file).size;
+        const n = 3200;
+        if (size < 44 + n)
+            return 0;
+        const fd = fs.openSync(file, 'r');
+        const buf = Buffer.alloc(n);
+        fs.readSync(fd, buf, 0, n, size - n - (size - 44) % 2);
+        fs.closeSync(fd);
+        let sum = 0;
+        for (let i = 0; i + 1 < n; i += 2) {
+            const s = buf.readInt16LE(i) / 32768;
+            sum += s * s;
+        }
+        const rms = Math.sqrt(sum / (n / 2));
+        // Speech sits roughly between -50 dB (quiet room) and -10 dB (close and loud).
+        const db = 20 * Math.log10(rms || 1e-9);
+        return Math.max(0, Math.min(1, (db + 50) / 40));
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * What has been said so far, as a WAV file a transcriber can read.
+ *
+ * The recorder writes the header's lengths only when it stops, so a copy taken
+ * mid recording claims no audio at all. The copy gets the lengths of what is
+ * actually there. Returns null until there is at least half a second to send.
+ */
+function soFar(file) {
+    try {
+        const buf = fs.readFileSync(file);
+        const start = dataStart(buf);
+        if (start < 0 || buf.length - start < 16000)
+            return null;
+        const usable = buf.length - ((buf.length - start) % 2);
+        const copy = Buffer.from(buf.subarray(0, usable));
+        copy.writeUInt32LE(usable - 8, 4);
+        copy.writeUInt32LE(usable - start, start - 4);
+        const out = path.join(path.dirname(file), 'so-far.wav');
+        fs.writeFileSync(out, copy);
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
 /** Delete the recording and the folder holding it. Always, and immediately. */
 function discard(file) {
     try {

package/out/postinstall.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Runs on `npm install -g @illuminis/comprism`. Rule R1.
@@ -20,8 +23,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * swallowing its own errors. A package that fails to install because its
  * telemetry could not configure itself deserves to be uninstalled.
  */
+const node_fs_1 = __importDefault(require("node:fs"));
 const install_1 = require("./commands/install");
 const readiness_1 = require("./lib/readiness");
+/**
+ * Written to the terminal itself, not to npm. npm hides everything an install
+ * script prints unless the install fails, so the next steps a person needs
+ * right now never reached the screen (owner, 27 September 2026). Falls back to
+ * standard output where there is no terminal, such as a build server's log.
+ */
+function say(text) {
+    const tty = process.platform === 'win32' ? 'CONOUT$' : '/dev/tty';
+    try {
+        const fd = node_fs_1.default.openSync(tty, 'w');
+        node_fs_1.default.writeSync(fd, text);
+        node_fs_1.default.closeSync(fd);
+    }
+    catch {
+        process.stdout.write(text);
+    }
+}
 async function main() {
     // Local development installs (`npm install` inside the repo) should not touch
     // the developer's shell profile. Only a global install means "set me up".
@@ -44,29 +65,33 @@ async function main() {
         if (report.desktop.staleRemoved) {
             desktopLines.push('    · removed an old CompletionPrism entry from Claude Desktop (it could not answer)');
         }
-        if (report.desktop.note) {
+        // Only when Claude Desktop is on this machine: a line about an app somebody
+        // does not have is noise in a list of next steps.
+        if (report.desktop.note && report.desktop.present) {
             desktopLines.push(`    · ${report.desktop.note}`);
         }
         else if (report.desktop.present && report.baseUrl) {
             desktopLines.push(`    · Claude Desktop: add ${report.baseUrl}/mcp under Settings > Connectors`);
         }
-        process.stdout.write([
+        // A short numbered list of what to do next, and nothing a person has to
+        // decode. The setup detail (which profile got a line) is one quiet line.
+        const signIn = !(report.enrolled && report.baseUrl);
+        const steps = [
+            'Open a new terminal window.',
+            ...(signIn ? ['Sign in:              comprism login'] : []),
+            'Start working:        comprism      (or claude, already measured)',
+            ...(report.baseUrl ? [`See what it saved:    ${report.baseUrl}`] : []),
+        ];
+        say([
             '',
-            '  CompletionPrism is set up.',
-            `    · interception configured against ${report.baseUrl || 'no tenant yet - run `comprism connect`'}`,
-            ...report.profilesTouched.map((p) => `    · added one line to ${p}`),
-            ...report.profilesAlreadyHad.map((p) => `    · already configured in ${p}`),
-            ...desktopLines,
+            '  CompletionPrism is installed.',
             '',
-            '  Open a new terminal and just work:',
-            '    claude            your tools, instrumented, unchanged',
-            '    comprism          our own session',
-            '    comprism check    what this machine still needs',
+            '  Next steps',
+            ...steps.map((line, i) => `    ${i + 1}. ${line}`),
+            ...desktopLines,
             '',
-            ...(report.baseUrl
-                ? [`  What your work cost: ${report.baseUrl}`, '']
-                : []),
-            '  If our recorder is ever down your tools are unaffected. Undo with `comprism uninstall`.',
+            ...report.profilesTouched.map((p) => `  Set up in ${p}.`),
+            '  To remove it later, one command: comprism uninstall',
             '',
         ].join('\n'));
         // What this machine still needs, said at the only moment somebody is
@@ -76,7 +101,7 @@ async function main() {
         // already fine is noise on a screen somebody is about to close.
         const machine = (0, readiness_1.check)();
         if (!machine.ready) {
-            process.stdout.write([
+            say([
                 '  Two things the work itself may need on this machine:',
                 ...machine.lines,
                 '',
@@ -89,7 +114,7 @@ async function main() {
     }
     catch {
         // Never fail an install over setup. The user can run `comprism install`.
-        process.stdout.write('\n  CompletionPrism installed. Run `comprism install` to finish setup.\n\n');
+        say('\n  CompletionPrism is installed. Next step: open a new terminal and run `comprism install`.\n\n');
     }
 }
 void main();

package/out/providers/anthropic.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Anthropic adapter.
+ *
+ * Deliberately dependency-free: the Messages API over `fetch`, nothing else.
+ * The Companion has to install into someone else's tool without dragging a
+ * dependency tree behind it, and a proxy that sits in front of a provider is a
+ * poor place to inherit somebody's transitive supply chain.
+ */
+import type { Message, ProviderResult } from '../lib/types';
+export interface AnthropicCall {
+    model: string;
+    messages: Message[];
+    maxTokens: number;
+    apiKey: string;
+}
+export declare function callAnthropic(call: AnthropicCall): Promise<ProviderResult>;
+/** Carries the status code so the shared retry policy can read it. */
+export declare class ProviderHttpError extends Error {
+    status: number;
+    latencyMs: number;
+    constructor(status: number, message: string);
+}