@illuminis/comprism 0.1.0

package/out/lib/ui.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * Terminal presentation.
+ *
+ * This is a developer product, so the terminal IS the interface, and it gets the
+ * same care a screen would. Three rules hold it together:
+ *
+ *   1. **The brand shows up here.** The prism spectrum and the illuminis palette
+ *      are the same ones the portal and the documents use, rendered in 24-bit
+ *      color where the terminal supports it.
+ *   2. **Color is never the only signal.** Every state that matters also has a
+ *      glyph and a word, so the output survives `NO_COLOR`, a pipe, a CI log and
+ *      a color-blind reader unchanged.
+ *   3. **Nothing here is decoration for its own sake.** Every panel answers a
+ *      question the person actually has: what did that cost, what was wasted,
+ *      and how sure are we of the number.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveIndicator = exports.c = void 0;
+exports.width = width;
+exports.spectrumAt = spectrumAt;
+exports.prismRule = prismRule;
+exports.banner = banner;
+exports.money = money;
+exports.clip = clip;
+exports.pad = pad;
+exports.padLeft = padLeft;
+exports.stripAnsi = stripAnsi;
+exports.kpiCards = kpiCards;
+exports.paretoBars = paretoBars;
+exports.table = table;
+exports.receipt = receipt;
+exports.ok = ok;
+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;
+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;
+exports.c = {
+    blue: rgb(59, 111, 181), // primary_blue  #3B6FB5
+    deep: rgb(31, 77, 120), // heading_blue  #1F4D78
+    purple: rgb(107, 91, 167), // purple_accent #6B5BA7
+    green: rgb(22, 163, 74), // success       #16A34A
+    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),
+};
+/** The prism: white light entering, a spectrum leaving. The brand in one line. */
+const SPECTRUM = [
+    [59, 111, 181],
+    [79, 105, 186],
+    [99, 98, 184],
+    [123, 92, 175],
+    [150, 90, 160],
+    [176, 92, 138],
+    [201, 101, 112],
+    [217, 119, 6],
+];
+/**
+ * Any glyph, in one of the eight spectrum colors.
+ *
+ * Exported so the logo and the rule under it are drawn from the SAME eight
+ * values. Two hand-picked palettes in one product drift apart within a release,
+ * and the brand is the one thing a customer notices before the engine.
+ */
+function spectrumAt(index, glyph) {
+    if (!useColor)
+        return glyph;
+    const [r, g, b] = SPECTRUM[Math.abs(index) % SPECTRUM.length];
+    return `\x1b[38;2;${r};${g};${b}m${glyph}\x1b[0m`;
+}
+function prismRule(w = width()) {
+    if (!useColor)
+        return '-'.repeat(w);
+    const seg = Math.max(1, Math.floor(w / SPECTRUM.length));
+    let out = '';
+    for (let i = 0; i < SPECTRUM.length; i++) {
+        const [r, g, b] = SPECTRUM[i];
+        const len = i === SPECTRUM.length - 1 ? w - seg * (SPECTRUM.length - 1) : seg;
+        out += `\x1b[38;2;${r};${g};${b}m${'━'.repeat(Math.max(0, len))}`;
+    }
+    return `${out}\x1b[0m`;
+}
+function banner(subtitle) {
+    const lines = [
+        '',
+        `  ${exports.c.bold(exports.c.blue('◣'))}${exports.c.bold(exports.c.purple('◥'))}  ${exports.c.bold('CompletionPrism')} ${exports.c.dim('comprism')}`,
+        subtitle ? `  ${exports.c.muted(subtitle)}` : '',
+        prismRule(),
+    ].filter(Boolean);
+    return lines.join('\n');
+}
+// ── primitives ──────────────────────────────────────────────────────────────
+function money(v) {
+    if (v === null)
+        return 'unpriced';
+    if (v === 0)
+        return '$0.00';
+    if (v < 0.01)
+        return `$${v.toFixed(5)}`;
+    if (v < 1)
+        return `$${v.toFixed(4)}`;
+    return `$${v.toFixed(2)}`;
+}
+/** Clip to a visible width, with an ellipsis, so a card never bleeds. */
+function clip(s, n) {
+    const visible = stripAnsi(s);
+    if (visible.length <= n)
+        return s;
+    return `${visible.slice(0, Math.max(0, n - 1))}\u2026`;
+}
+function pad(s, n) {
+    const visible = stripAnsi(s);
+    return visible.length >= n ? s : s + ' '.repeat(n - visible.length);
+}
+function padLeft(s, n) {
+    const visible = stripAnsi(s);
+    return visible.length >= n ? s : ' '.repeat(n - visible.length) + s;
+}
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+/**
+ * A row of KPI cards - the same shape the portal's summary tab uses, so the two
+ * surfaces read as one product rather than two tools that happen to share a name.
+ */
+function kpiCards(cards) {
+    const w = width();
+    const cardW = Math.max(18, Math.floor((w - (cards.length - 1) * 2) / cards.length));
+    const tone = (t) => t === 'good' ? exports.c.green : t === 'warn' ? exports.c.amber : exports.c.text;
+    const top = cards.map(() => `┌${'─'.repeat(cardW - 2)}┐`).join('  ');
+    const inner = cardW - 4;
+    const label = cards
+        .map((k) => `│ ${pad(exports.c.muted(clip(k.label.toUpperCase(), inner)), inner)} │`)
+        .join('  ');
+    const value = cards
+        .map((k) => `│ ${pad(exports.c.bold(tone(k.tone)(clip(k.value, inner))), inner)} │`)
+        .join('  ');
+    const note = cards
+        .map((k) => `│ ${pad(exports.c.dim(clip(k.note || '', inner)), inner)} │`)
+        .join('  ');
+    const bottom = cards.map(() => `└${'─'.repeat(cardW - 2)}┘`).join('  ');
+    return [top, label, value, note, bottom].join('\n');
+}
+/**
+ * A Pareto bar: sorted descending with a running cumulative share.
+ *
+ * Pareto rather than a plain bar chart because the question a spend screen has
+ * to answer is not "how much did each cost" but "how few of these carry most of
+ * the bill" - the answer is usually two or three, and that is the whole insight.
+ */
+function paretoBars(rows, opts = {}) {
+    const unit = opts.unit || ((v) => v.toFixed(2));
+    const sorted = [...rows].sort((a, b) => b.value - a.value);
+    const total = sorted.reduce((s, r) => s + r.value, 0) || 1;
+    const labelW = Math.max(...sorted.map((r) => r.label.length), 8);
+    const barW = opts.barWidth || Math.max(12, Math.min(34, width() - labelW - 30));
+    const max = sorted[0]?.value || 1;
+    let cumulative = 0;
+    const out = [];
+    for (const r of sorted) {
+        cumulative += r.value;
+        const share = (cumulative / total) * 100;
+        const filled = Math.max(r.value > 0 ? 1 : 0, Math.round((r.value / max) * barW));
+        const bar = exports.c.blue('█'.repeat(filled)) + exports.c.dim('·'.repeat(Math.max(0, barW - filled)));
+        out.push(`  ${pad(exports.c.text(r.label), labelW)}  ${bar}  ${padLeft(unit(r.value), 10)}  ${exports.c.dim(`${padLeft(share.toFixed(0), 3)}% cum`)}${r.sub ? `  ${exports.c.dim(r.sub)}` : ''}`);
+    }
+    return out.join('\n');
+}
+function table(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(stripAnsi(h).length, ...rows.map((r) => stripAnsi(r[i] || '').length)));
+    const head = `  ${headers.map((h, i) => pad(exports.c.muted(h.toUpperCase()), widths[i])).join('   ')}`;
+    const sep = `  ${widths.map((w) => exports.c.dim('─'.repeat(w))).join('   ')}`;
+    const body = rows.map((r) => `  ${r.map((cell, i) => pad(cell, widths[i])).join('   ')}`);
+    return [head, sep, ...body].join('\n');
+}
+// ── the live indicator ──────────────────────────────────────────────────────
+/**
+ * The thing that makes it visible that something is between the person and the
+ * provider.
+ *
+ * Without this, an instrumented session looks exactly like an uninstrumented
+ * one, and a product nobody can see is a product nobody renews. It shows the
+ * work as it happens - characterising, dispatching, recording - and then gets
+ * out of the way, leaving the answer and a one-line receipt.
+ */
+class LiveIndicator {
+    timer = null;
+    frame = 0;
+    label = '';
+    frames = ['◜', '◠', '◝', '◞', '◡', '◟'];
+    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);
+    }
+    update(label) {
+        this.label = label;
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        if (isTty)
+            process.stdout.write(`\r${' '.repeat(width())}\r`);
+    }
+}
+exports.LiveIndicator = LiveIndicator;
+/**
+ * The receipt, rendered by the client and never injected into the conversation.
+ *
+ * Injected text is re-sent on every later turn, so a receipt in the message
+ * array is a line item the customer pays for again on every turn for the rest of
+ * the session. It belongs on the screen, not in the context window.
+ */
+function receipt(r) {
+    const parts = [];
+    parts.push(`${exports.c.purple('◈')} ${exports.c.bold(r.model)}`);
+    parts.push(exports.c.dim('·'));
+    parts.push(`${r.inputTokens ?? '?'}${exports.c.dim(' in')} ${r.outputTokens ?? '?'}${exports.c.dim(' out')}`);
+    parts.push(exports.c.dim('·'));
+    parts.push(exports.c.bold(money(r.costUsd)));
+    parts.push(exports.c.dim('·'));
+    parts.push(exports.c.dim(`${(r.latencyMs / 1000).toFixed(1)}s`));
+    parts.push(exports.c.dim('·'));
+    parts.push(exports.c.dim(`${r.tier}`));
+    const lines = [`  ${parts.join(' ')}`];
+    if (r.remediated) {
+        lines.push(`  ${exports.c.amber('↑')} ${exports.c.amber('weak answer repaired')} ${exports.c.dim(`- ${r.attempts} attempts, ${money(r.wastedUsd)} spent on the attempt that failed`)}`);
+    }
+    lines.push(`  ${exports.c.green('✓')} ${exports.c.dim('recorded:')} ${exports.c.dim('ledger row, decision record, fingerprint only - no request text stored')}`);
+    if (r.withheld) {
+        lines.push(`  ${exports.c.muted('○')} ${exports.c.dim(`no recommendation (${r.withheld.replace(/_/g, ' ')}) - request ran untouched`)}`);
+    }
+    return lines.join('\n');
+}
+function ok(msg) {
+    return `  ${exports.c.green('✓')} ${msg}`;
+}
+function warn(msg) {
+    return `  ${exports.c.amber('!')} ${msg}`;
+}
+function fail(msg) {
+    return `  ${exports.c.red('✗')} ${msg}`;
+}
+function info(msg) {
+    return `  ${exports.c.blue('▸')} ${msg}`;
+}

package/out/lib/version.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Every version string the Companion stamps onto a record.
+ *
+ * Ground rule 3: a derived record without the version of the code that produced
+ * it cannot be restated and cannot serve as evidence. These are bumped when the
+ * behavior behind them changes, never on a whim, because consumers select by
+ * version and old records keep meaning what they meant.
+ */
+/** The package version. Stamped on every row the Companion writes. */
+export declare const COMPRISM_VERSION = "0.1.0";
+/** The structural classifier. Bump when a signal is added, removed or retuned. */
+export declare const CLASSIFIER_VERSION = "structural-v1";
+/**
+ * The dispatch policy.
+ *
+ * `naive` is the honest name for what this release does: the first eligible
+ * candidate for the structural band, with no estimate consulted. When the model
+ * program delivers tables, decisions made under this version stay permanently
+ * distinguishable from decisions made under a learned one - which is exactly
+ * why the version is on the record rather than in a changelog.
+ */
+export declare const POLICY_VERSION = "naive-v1";
+/** The estimator interface. Inert in this release: no tables, no recommendation. */
+export declare const ESTIMATOR_VERSION = "inert-v1";

package/out/lib/version.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Every version string the Companion stamps onto a record.
+ *
+ * Ground rule 3: a derived record without the version of the code that produced
+ * it cannot be restated and cannot serve as evidence. These are bumped when the
+ * behavior behind them changes, never on a whim, because consumers select by
+ * version and old records keep meaning what they meant.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ESTIMATOR_VERSION = exports.POLICY_VERSION = exports.CLASSIFIER_VERSION = exports.COMPRISM_VERSION = void 0;
+/** The package version. Stamped on every row the Companion writes. */
+exports.COMPRISM_VERSION = '0.1.0';
+/** The structural classifier. Bump when a signal is added, removed or retuned. */
+exports.CLASSIFIER_VERSION = 'structural-v1';
+/**
+ * The dispatch policy.
+ *
+ * `naive` is the honest name for what this release does: the first eligible
+ * candidate for the structural band, with no estimate consulted. When the model
+ * program delivers tables, decisions made under this version stay permanently
+ * distinguishable from decisions made under a learned one - which is exactly
+ * why the version is on the record rather than in a changelog.
+ */
+exports.POLICY_VERSION = 'naive-v1';
+/** The estimator interface. Inert in this release: no tables, no recommendation. */
+exports.ESTIMATOR_VERSION = 'inert-v1';

package/out/lib/voice.d.ts

@@ -0,0 +1,50 @@
+/** One recording tool, as this file needs to drive it. */
+interface Recorder {
+    /** What to tell somebody who wants to know what is listening. */
+    name: string;
+    command: string;
+    args: (out: string) => string[];
+}
+/** The first recording tool this machine has, or null. */
+export declare function recorder(): Recorder | null;
+/**
+ * What to tell somebody who has no recording tool, or null when they do.
+ *
+ * One sentence and one command. Not a list of three options with trade-offs:
+ * somebody who just wanted to say a sentence out loud is not shopping for audio
+ * software.
+ */
+export declare function missing(): string | null;
+/** A recording in progress. */
+export interface Recording {
+    /** Where the audio is being written. */
+    file: string;
+    /** What is doing the listening, for the line on screen. */
+    by: string;
+    /** Stop, wait for the file to be finished properly, and hand it back. */
+    stop: () => Promise<{
+        file: string;
+        bytes: number;
+    }>;
+}
+/**
+ * Start listening.
+ *
+ * Throws when there is nothing to listen with, which the caller should have
+ * headed off with `missing` so the person gets a sentence rather than an error.
+ */
+export declare function start(): Recording;
+/** Delete the recording and the folder holding it. Always, and immediately. */
+export declare function discard(file: string): void;
+/**
+ * The words in a recording, according to our server.
+ *
+ * Every refusal comes back as a sentence somebody can act on, because the
+ * commonest one by far is a tenant holding only an Anthropic key, and
+ * "transcription failed" would send that person looking at their microphone.
+ */
+export declare function transcribe(baseUrl: string, credential: string, file: string): Promise<{
+    text: string;
+    provider: string;
+}>;
+export {};

package/out/lib/voice.js

@@ -0,0 +1,218 @@
+"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.recorder = recorder;
+exports.missing = missing;
+exports.start = start;
+exports.discard = discard;
+exports.transcribe = transcribe;
+/**
+ * Saying a request instead of typing it.
+ *
+ * ── The split, and why it is where it is ──────────────────────────────────
+ *
+ * This file records. It does not transcribe, and it never will: the published
+ * package holds no model logic, no vendor address and no provider key, and a
+ * ship check enforces that. The recording goes to our server, the server asks a
+ * vendor, and the words come back. See `services/transcription.py`.
+ *
+ * ── Recording without adding a dependency ─────────────────────────────────
+ *
+ * This package has no dependencies at all, deliberately, and a microphone
+ * library would be the first - a compiled one, on every customer's laptop, for
+ * a feature most of them will use occasionally. So it drives a recording tool
+ * the machine already has.
+ *
+ * That is an honest trade and it has a cost worth stating: macOS ships no
+ * command line recorder, so on a Mac with neither ffmpeg nor sox this does not
+ * work. The answer to that is to say so in one sentence naming the one command
+ * that fixes it, which is what `missing` returns. What it must never do is fail
+ * quietly and leave somebody holding a key wondering whether we heard them.
+ *
+ * ── Stopping ──────────────────────────────────────────────────────────────
+ *
+ * Every one of these tools writes a WAV header that is only correct once the
+ * recording ends properly, so stopping means an interrupt and then WAITING for
+ * the tool to finish writing. Killing it outright leaves a file whose header
+ * claims a length it does not have, which every transcriber reads as silence.
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const gateway_1 = require("./gateway");
+/** Is this on the PATH at all. */
+function present(command) {
+    try {
+        return (0, node_child_process_1.spawnSync)('which', [command], { stdio: 'ignore' }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sixteen kilohertz, one channel, everywhere.
+ *
+ * What every speech model wants and nothing more. Recording in studio quality
+ * would make a file several times the size, take longer to upload, and be
+ * downsampled by the vendor on arrival anyway.
+ */
+const RATE = '16000';
+const RECORDERS = [
+    // sox first. It is the one built for this, it needs no device name, and it
+    // stops cleanly.
+    { name: 'sox', command: 'rec', args: (out) => ['-q', '-c', '1', '-r', RATE, out] },
+    {
+        name: 'ffmpeg',
+        command: 'ffmpeg',
+        args: (out) => [
+            '-loglevel', 'quiet', '-nostdin',
+            ...(process.platform === 'darwin'
+                ? ['-f', 'avfoundation', '-i', ':default']
+                : ['-f', 'alsa', '-i', 'default']),
+            '-ac', '1', '-ar', RATE, '-y', out,
+        ],
+    },
+    // Linux's own, present on most desktop installs.
+    { name: 'arecord', command: 'arecord', args: (out) => ['-q', '-f', 'S16_LE', '-c', '1', '-r', RATE, out] },
+];
+/** The first recording tool this machine has, or null. */
+function recorder() {
+    return RECORDERS.find((r) => present(r.command)) ?? null;
+}
+/**
+ * What to tell somebody who has no recording tool, or null when they do.
+ *
+ * One sentence and one command. Not a list of three options with trade-offs:
+ * somebody who just wanted to say a sentence out loud is not shopping for audio
+ * software.
+ */
+function missing() {
+    if (recorder())
+        return null;
+    return process.platform === 'darwin'
+        ? 'Speaking needs a recording tool, and macOS does not come with one. '
+            + 'Install it once with:  brew install sox'
+        : 'Speaking needs a recording tool. Install it once with:  '
+            + 'sudo apt install sox   (or your system\'s package manager)';
+}
+/**
+ * Start listening.
+ *
+ * Throws when there is nothing to listen with, which the caller should have
+ * headed off with `missing` so the person gets a sentence rather than an error.
+ */
+function start() {
+    const tool = recorder();
+    if (!tool)
+        throw new Error(missing() ?? 'No recording tool.');
+    const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'comprism-voice-')), 'said.wav');
+    const child = (0, node_child_process_1.spawn)(tool.command, tool.args(file), {
+        stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    let stopped = null;
+    const stop = () => {
+        if (stopped)
+            return stopped;
+        stopped = new Promise((resolve) => {
+            const done = () => {
+                let bytes = 0;
+                try {
+                    bytes = fs.statSync(file).size;
+                }
+                catch {
+                    bytes = 0;
+                }
+                resolve({ file, bytes });
+            };
+            // Interrupt, not kill. Every one of these tools finishes writing the WAV
+            // header on an interrupt and none of them does on a kill, and a header
+            // that was never finished reads as silence to whoever transcribes it.
+            child.once('close', done);
+            try {
+                child.kill('SIGINT');
+            }
+            catch {
+                done();
+            }
+            // A tool that has not closed in two seconds is not going to. Taking the
+            // file as it stands beats leaving somebody at a prompt that has stopped
+            // answering them.
+            setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* already gone */ }
+                done();
+            }, 2000).unref();
+        });
+        return stopped;
+    };
+    return { file, by: tool.name, stop };
+}
+/** Delete the recording and the folder holding it. Always, and immediately. */
+function discard(file) {
+    try {
+        fs.rmSync(path.dirname(file), { recursive: true, force: true });
+    }
+    catch { /* a temp file we could not remove is not worth a word to anybody */ }
+}
+/**
+ * The words in a recording, according to our server.
+ *
+ * Every refusal comes back as a sentence somebody can act on, because the
+ * commonest one by far is a tenant holding only an Anthropic key, and
+ * "transcription failed" would send that person looking at their microphone.
+ */
+async function transcribe(baseUrl, credential, file) {
+    const form = new FormData();
+    form.append('audio', new Blob([fs.readFileSync(file)], { type: 'audio/wav' }), 'said.wav');
+    // Permission first, from the one service, which also names the address. The
+    // recording itself does not travel through that door: a JSON request is the
+    // wrong shape for audio. The decision is made there and nowhere else.
+    const granted = await (0, gateway_1.ask)({ intent: 'transcribe', prompt: '' });
+    const pass = granted.ok && granted.served !== false ? granted.upload : null;
+    if (granted.ok && granted.served !== false && !pass) {
+        throw new Error(granted.message || 'your workspace would not allow that recording');
+    }
+    const where = pass?.upload_path || '/api/v1/agent/transcribe';
+    const res = await fetch(`${baseUrl.replace(/\/+$/, '')}${where}${pass?.ticket ? `?ticket=${encodeURIComponent(pass.ticket)}` : ''}`, { method: 'POST', headers: { Authorization: `Bearer ${credential}` }, body: form });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(body.detail || `The server said ${res.status}.`);
+    }
+    const row = await res.json();
+    return { text: row.text, provider: row.provider };
+}

package/out/postinstall.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/out/postinstall.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Runs on `npm install -g @illuminis/comprism`. Rule R1.
+ *
+ * The whole point is that the user types one command and is finished. So the
+ * install configures interception itself rather than printing instructions.
+ *
+ * Three things make that safe to do to somebody's machine automatically:
+ *
+ *   - It is fenced and reversible. One marked block in the shell profile, and
+ *     `comprism uninstall` removes exactly it.
+ *   - It says out loud what it touched. No silent edits.
+ *   - It cannot break anything. The script it installs exports nothing unless a
+ *     recorder is actually answering, so a broken or missing proxy leaves every
+ *     AI tool on the machine talking straight to its provider, as before.
+ *
+ * And it never fails the install: `|| true` in the npm script, plus this file
+ * swallowing its own errors. A package that fails to install because its
+ * telemetry could not configure itself deserves to be uninstalled.
+ */
+const install_1 = require("./commands/install");
+const readiness_1 = require("./lib/readiness");
+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".
+    const isGlobal = process.env.npm_config_global === 'true';
+    if (!isGlobal)
+        return;
+    try {
+        const report = (0, install_1.install)();
+        // Claude Desktop is not something this script can finish. A remote
+        // connector is authorized by a consent screen, so the honest output is the
+        // address to paste - never a claim that it is live.
+        //
+        // This path is the one that used to get it wrong twice over: npm runs this
+        // script, so anything derived from the running file is derived from
+        // POSTINSTALL rather than the CLI, and the entry it wrote looked perfectly
+        // reasonable in the config file while being a server that could only
+        // observe. It reported "registered and answering" and the user then saw no
+        // receipt and an empty Sessions screen, with nothing anywhere saying why.
+        const desktopLines = [];
+        if (report.desktop.staleRemoved) {
+            desktopLines.push('    · removed an old CompletionPrism entry from Claude Desktop (it could not answer)');
+        }
+        if (report.desktop.note) {
+            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([
+            '',
+            '  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,
+            '',
+            '  Open a new terminal and just work:',
+            '    claude            your tools, instrumented, unchanged',
+            '    comprism          our own session',
+            '    comprism report   what finishing your work cost',
+            '',
+            '  If our recorder is ever down your tools are unaffected. Undo with `comprism uninstall`.',
+            '',
+        ].join('\n'));
+        // What this machine still needs, said at the only moment somebody is
+        // thinking about setup. Finding out three days later, mid job, that a PDF
+        // cannot be read is the same information delivered at the worst possible
+        // time. Said only when something IS missing: a list of things that are
+        // already fine is noise on a screen somebody is about to close.
+        const machine = (0, readiness_1.check)();
+        if (!machine.ready) {
+            process.stdout.write([
+                '  Two things the work itself may need on this machine:',
+                ...machine.lines,
+                '',
+                `  To add what is missing:  ${machine.fix}`,
+                '  Everything else, including Word, PowerPoint and PDF documents, is',
+                '  built on our servers and needs nothing installed here.',
+                '',
+            ].join('\n'));
+        }
+    }
+    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');
+    }
+}
+void main();