@illuminis/comprism 0.1.0

package/out/lib/gateway.d.ts

@@ -0,0 +1,239 @@
+export interface Decision {
+    /** The model that finishes the work for least. Null when we could not decide. */
+    model: string | null;
+    /** What the caller would have run without us. */
+    would_have_used: string;
+    tier: string;
+    signals: string[];
+    /**
+     * True only when the figure rests on a close match in the corpus. False means
+     * a coarser lookup answered, and every surface must show it as an estimate.
+     */
+    confident: boolean;
+    rung: string | null;
+    rationale: string | null;
+}
+/** One model, as a person choosing between them needs to see it. */
+export interface CatalogModel {
+    key: string;
+    id: string;
+    label: string;
+    provider: string;
+    tier: string;
+    /** True when this workspace can call it with no further setup. */
+    reachable: boolean;
+    /** Why it cannot be reached, in words a person can act on. */
+    why_not: string | null;
+}
+/** One vendor and its models. */
+export interface CatalogProvider {
+    provider: string;
+    label: string;
+    has_key: boolean;
+    permitted: boolean;
+    models: CatalogModel[];
+}
+export interface GatewayReply {
+    intent: 'decide' | 'answer' | 'catalog' | 'store_key' | 'session' | 'job_start' | 'resolve_workspace' | 'sign_in' | 'sign_out' | 'attach' | 'transcribe' | 'graph';
+    client: string;
+    decision: Decision;
+    answer: string | null;
+    /** The receipt, already worded by the server. Clients never compose one. */
+    receipt: string | null;
+    /** The model that actually answered. */
+    ran_on: string | null;
+    /** What this job cost to finish, on the model we ran. */
+    cost_usd: number | null;
+    /** What it would have cost on the model the caller named. */
+    would_have_cost_usd: number | null;
+    /** The difference. Negative means we spent more, and it is shown either way. */
+    saved_usd: number | null;
+    /** True when any figure rests on a coarse lookup rather than a close match. */
+    estimated: boolean;
+    /** Where the job opens in full, every figure traceable to its records. */
+    details_url: string | null;
+    /** Every vendor and model. Present only for a catalog request. */
+    providers: CatalogProvider[];
+    /** Whether this machine's credential was actually revoked. Present only
+     *  when signing out. */
+    signed_out: boolean;
+    /** Whether a key was kept. Present only when storing one. */
+    stored: boolean;
+    /** What happened, in words a person can act on. */
+    message: string | null;
+    /**
+     * Did this workspace's build serve the intent that was asked for.
+     *
+     * False is a COMPLETE answer meaning "your workspace is behind", never an
+     * error and never an absence. A caller that reads it as an absence repeats
+     * the 17 September fault: a tool asked a workspace for its vendor list, the
+     * build did not carry that question, and the refusal was reported to the
+     * person as "you have no keys".
+     *
+     * Optional, because a workspace older than this field does not send it, and
+     * absent must read as "it answered", not as "it refused".
+     */
+    served?: boolean;
+    /**
+     * False when some part of this reply could not be established.
+     *
+     * An empty list in a reply with `complete: false` is NOT a list of nothing,
+     * it is a list we failed to obtain. Reading the two the same way is the whole
+     * of the 17 September fault, and it was present on both sides of the wire.
+     * Optional, because a workspace older than this field does not send it, and
+     * absent must read as "established".
+     */
+    complete?: boolean;
+    /** Every intent this workspace's build does serve. Empty on an older build. */
+    intents?: string[];
+    /** Present only for a graph request: what the map holds, what it still needs,
+     *  or the answer to one of the five questions. */
+    graph?: Record<string, unknown>;
+    /** Who this machine is signed in as. Present only for a session request. */
+    session?: SessionOut | null;
+    /** Permission for one coding job. Present only for a job_start request. */
+    job?: JobOut | null;
+    /** Present only for a sign_in request. */
+    sign_in?: SignInOut | null;
+    /** Present only for an attach or transcribe request. */
+    upload?: UploadOut | null;
+    /**
+     * True when the request was understood, allowed and acted on.
+     *
+     * False with `served: true` is a REFUSAL carrying its reason in `message`,
+     * and it is a complete answer. Without this a caller cannot tell "your plan
+     * does not include this" from "this workspace has never heard of it", and
+     * those have opposite fixes: one is a purchase, the other is a deploy.
+     */
+    granted?: boolean;
+    /**
+     * Did the workspace actually answer.
+     *
+     * False means we never heard from it, so EVERY other field here is this
+     * client's own placeholder rather than anything the workspace said. Without
+     * this a caller could not tell "the workspace says you have no provider key"
+     * from "the workspace did not answer", and it read the second as the first:
+     * somebody whose keys were all present and correct was told none was stored
+     * and walked into a form asking them to paste one.
+     */
+    ok: boolean;
+}
+/** Permission to send one file, and the address to send it to. */
+export interface UploadOut {
+    /** Presented at the upload address in place of the workspace credential. */
+    ticket: string;
+    expires_in: number;
+    /** Named by the SERVER. A client composes no addresses of its own. */
+    upload_path: string;
+}
+/** Permission to run one coding job, and the pass that opens its stream. */
+export interface JobOut {
+    job_id: string;
+    /**
+     * Presented by the stream in place of the workspace credential.
+     *
+     * One job, one use, two minutes. The job was already authorized by the one
+     * service before this was issued, so the stream decides nothing.
+     */
+    ticket: string;
+    expires_in: number;
+    /**
+     * What is left of this month's included coding spend, read ONCE by the
+     * service. The stream announces this same figure rather than reading it
+     * again, because two readings are how a job is authorized against one number
+     * and then tells the person watching it another.
+     */
+    allowance_remaining_usd: number | null;
+    stream_path: string;
+}
+/** Everything a client's header prints, answered by the workspace in one call. */
+/** What signing in returns. The credential appears here once and never again. */
+export interface SignInOut {
+    token: string;
+    /**
+     * This machine's own credential, returned ONCE.
+     *
+     * Nothing in the product ever returns it again, which is what makes revoking
+     * it in the portal a meaningful act rather than a gesture.
+     */
+    machine_credential: string;
+    tenant: string;
+    /** Computed by the SERVER, never guessed by this tool. */
+    workspace_url: string;
+    /** True when a second factor is needed. An answer, not a failure. */
+    needs_second_factor: boolean;
+    challenge: string;
+}
+export interface SessionOut {
+    signed_in: boolean;
+    user_email: string;
+    /** The company as a person says it, not the schema name. */
+    company: string;
+    tenant: string;
+    /**
+     * The address the workspace says it answers on, computed by the SERVER.
+     *
+     * Printed in preference to the address this machine happens to hold, because
+     * a client echoing its own stored address can never tell a person that the
+     * address is the thing that is wrong.
+     */
+    workspace_url: string;
+    comparing: string;
+    plan: string;
+    requests_per_minute: number;
+    requests_per_month: number;
+    vendors_with_key: number;
+    vendor_names: string[];
+    /** False when the vendor lookup could not answer. The count is then meaningless. */
+    vendors_known?: boolean;
+    machine: string;
+    can_write: boolean;
+}
+export interface Ask {
+    intent: 'decide' | 'answer' | 'catalog' | 'store_key' | 'session' | 'job_start' | 'resolve_workspace' | 'sign_in' | 'sign_out' | 'attach' | 'transcribe' | 'graph';
+    prompt: string;
+    callingModel?: string;
+    contextTokens?: number;
+    freshContext?: boolean;
+    tokensIn?: number;
+    tokensOut?: number;
+    /** The customer's own provider key, forwarded and never stored by us. */
+    providerKey?: string;
+    /** For store_key: which vendor the key belongs to. */
+    provider?: string;
+    /** For store_key: the key. Sent once, over TLS, and never written to disk. */
+    key?: string;
+    /** For job_start: rejoin this job rather than creating one. */
+    resumeJobId?: string;
+    /** For sign_in only. Sent once, over TLS, and written nowhere. */
+    password?: string;
+    /** For sign_in, when a second factor is required. */
+    challenge?: string;
+    code?: string;
+    /** For sign_in: how this machine appears where a person goes to revoke it. */
+    machineLabel?: string;
+    /** For graph: which of the map's operations this is. */
+    graphOp?: 'status' | 'stamps' | 'update' | 'finish' | 'ask' | 'forget' | 'policy';
+    /** For graph: the project on this machine the map belongs to. */
+    workspace?: string;
+    /**
+     * For graph: the facts read from this machine's own files, or the question
+     * being asked of the map.
+     *
+     * **Structure only, never source.** What travels is "a function called
+     * price_of exists at line 40 of this file, and these things call it". What
+     * that function SAYS never leaves the machine, and there is no field here
+     * that could carry it.
+     */
+    graphPayload?: Record<string, unknown>;
+}
+/**
+ * The same door, at an address this machine is not signed in to yet.
+ *
+ * Signing in is the one thing that cannot present a credential, because it is
+ * what mints one. So it needs a way to reach the door before a connection file
+ * exists. Everything else about the call is identical, which is the point: one
+ * door, and the credential is a header on it rather than a different address.
+ */
+export declare function askAt(url: string, input: Ask, tenant?: string): Promise<GatewayReply>;
+export declare function ask(input: Ask): Promise<GatewayReply>;

package/out/lib/gateway.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askAt = askAt;
+exports.ask = ask;
+/**
+ * The one door, from this side of it.
+ *
+ * ── Why this file replaced four others ────────────────────────────────────
+ *
+ * This tool used to decide for itself. It carried the whole decision, the
+ * retry behavior of every model, the cost of a wrong answer and the price
+ * list, and it worked out the winner on the customer's own laptop.
+ *
+ * That is our method, and a package on a public registry is readable by anyone
+ * who installs it, forever. So none of it lives here any more. The tool sends
+ * what it is about to do and receives a decision. Everything that makes the
+ * decision stays on our servers.
+ *
+ * The rule, from the owner: anything a client installs is thin; anything
+ * model-related runs on our server. What is left here is the network call and
+ * the shape of the reply, which is not a secret and cannot be one.
+ */
+const connection_1 = require("./connection");
+/**
+ * A decision that decides nothing, for when the door cannot be reached.
+ *
+ * Fail open, rule 10. The tool must never cost somebody their work because our
+ * server is slow or down: no model means the caller runs what it was going to
+ * run, and the reason is recorded rather than hidden.
+ */
+function openFailure(intent, callingModel, why) {
+    return {
+        // The intent the caller ASKED for, echoed back. Returning 'decide' for a
+        // failed catalog call made a caller switching on the intent read the
+        // placeholder as a real answer to a different question.
+        intent,
+        client: 'cli',
+        decision: {
+            model: null,
+            would_have_used: callingModel || '',
+            tier: 'standard',
+            signals: [],
+            confident: false,
+            rung: null,
+            rationale: why,
+        },
+        answer: null,
+        receipt: null,
+        ran_on: null,
+        cost_usd: null,
+        would_have_cost_usd: null,
+        saved_usd: null,
+        estimated: false,
+        details_url: null,
+        providers: [],
+        stored: false,
+        signed_out: false,
+        message: why,
+        // We never heard back, so we know nothing about what this workspace serves.
+        // `served` stays true: the failure is `ok: false`, and conflating the two
+        // would tell a person their workspace is out of date when it is simply
+        // unreachable.
+        served: true,
+        // Nothing in this placeholder was established, because nobody answered.
+        complete: false,
+        // Nothing was granted either, and a caller that reads `granted` must not
+        // see the default of true on a reply that never came from anywhere.
+        granted: false,
+        intents: [],
+        session: null,
+        job: null,
+        // The whole reason this field exists. We never heard from the workspace,
+        // so every field above is this client's placeholder and not something the
+        // workspace said. A caller that reads an empty `providers` as "you have no
+        // keys" is the fault that sent somebody with four working keys into a form
+        // asking them to paste one.
+        ok: false,
+    };
+}
+/**
+ * The same door, at an address this machine is not signed in to yet.
+ *
+ * Signing in is the one thing that cannot present a credential, because it is
+ * what mints one. So it needs a way to reach the door before a connection file
+ * exists. Everything else about the call is identical, which is the point: one
+ * door, and the credential is a header on it rather than a different address.
+ */
+async function askAt(url, input, tenant) {
+    return post(url, input, undefined, tenant);
+}
+async function ask(input) {
+    const conn = (0, connection_1.readConnection)();
+    if (!conn?.url || !conn.workspaceKey) {
+        return openFailure(input.intent, input.callingModel, 'this machine is not signed in');
+    }
+    return post(conn.url, input, conn.workspaceKey, conn.tenant);
+}
+async function post(url, input, credential, tenant) {
+    const conn = { url, workspaceKey: credential, tenant };
+    const headers = { 'content-type': 'application/json' };
+    // No credential on a sign in, because signing in is what mints one. Sending
+    // `Bearer undefined` made the door reject the request before it could reach
+    // the handler that does not need one.
+    if (conn.workspaceKey)
+        headers.authorization = `Bearer ${conn.workspaceKey}`;
+    if (conn.tenant)
+        headers['X-Tenant-ID'] = conn.tenant;
+    // Forwarded, never written to disk: the customer's money stays the
+    // customer's, and we hold no secret of theirs on their behalf.
+    if (input.providerKey)
+        headers['X-Anthropic-Key'] = input.providerKey;
+    try {
+        const res = await fetch(`${conn.url.replace(/\/+$/, '')}/api/v1/dev/gateway`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                intent: input.intent,
+                client: 'cli',
+                prompt: input.prompt,
+                calling_model: input.callingModel ?? null,
+                context_tokens: input.contextTokens ?? 0,
+                fresh_context: input.freshContext ?? true,
+                tokens_in: input.tokensIn ?? null,
+                tokens_out: input.tokensOut ?? null,
+                ...(input.provider ? { provider: input.provider } : {}),
+                ...(input.key ? { key: input.key } : {}),
+                ...(input.resumeJobId ? { resume_job_id: input.resumeJobId } : {}),
+                ...(input.password ? { password: input.password } : {}),
+                ...(input.challenge ? { challenge: input.challenge } : {}),
+                ...(input.code ? { code: input.code } : {}),
+                ...(input.machineLabel ? { machine_label: input.machineLabel } : {}),
+                ...(input.graphOp ? { graph_op: input.graphOp } : {}),
+                ...(input.workspace ? { workspace: input.workspace } : {}),
+                ...(input.graphPayload ? { graph_payload: input.graphPayload } : {}),
+            }),
+        });
+        if (!res.ok) {
+            // The workspace's OWN words, when it gave any. A bare status number told
+            // a person nothing: "403" was really "this product is for organization
+            // workspaces and yours is an individual account", which is actionable,
+            // and the number was not. An auth failure carries no body here, so
+            // nothing echoes a credential back.
+            let why = `the service answered ${res.status}`;
+            try {
+                const body = (await res.json());
+                if (body.detail?.message)
+                    why = body.detail.message;
+            }
+            catch { /* no body, so the status stays the reason */ }
+            const failed = openFailure(input.intent, input.callingModel, why);
+            // 422 IS AN OLD WORKSPACE, NOT A BROKEN ONE.
+            //
+            // A build that predates the intent list rejects an unknown intent with a
+            // validation error before its handler runs. Reported as an ordinary
+            // failure, that stopped a coding job against a workspace whose own
+            // credential path was alive and would have worked. Newer builds answer
+            // 200 with `served: false` and never reach this line.
+            if (res.status === 422)
+                return { ...failed, served: false };
+            return failed;
+        }
+        // `ok` is this client's own marker and the server never sends it: it
+        // records that the workspace answered at all. Set here, on the one path
+        // where that is true, so no caller has to infer it from an empty field.
+        const reply = (await res.json());
+        return { ...reply, ok: true };
+    }
+    catch {
+        return openFailure(input.intent, input.callingModel, 'the service could not be reached');
+    }
+}

package/out/lib/prompt.d.ts

@@ -0,0 +1,34 @@
+/** Close it on every path, or the command holds the terminal and looks hung. */
+export declare function closePrompt(): void;
+/** Ask a question and wait for the answer. */
+export declare function ask(prompt: string): Promise<string>;
+/**
+ * Ask for a secret, and do not put it on the screen.
+ *
+ * ── Why the first two attempts failed, and what is different ──────────────
+ *
+ * Both earlier tries SUPPRESSED what readline wanted to print. Readline does
+ * not print characters one at a time; on every keystroke it redraws the whole
+ * line, prompt included. Swallowing that output therefore swallowed the
+ * question and the cursor with it, and left a person on a blank line unable to
+ * tell whether the program was even listening.
+ *
+ * So this does not suppress the redraw, it PERFORMS it: the prompt is written
+ * back out followed by one dot per character actually held in the line. Paste
+ * and backspace come out right for free, because the dots are counted from the
+ * line itself rather than tallied from keystrokes.
+ *
+ * With no terminal attached there is nothing to redraw and nothing to hide
+ * from, so the plain question is used. That is the piped case, where the only
+ * reader is a script.
+ */
+export declare function askHidden(prompt: string): Promise<string>;
+/**
+ * Everything on the line that is not a flag or a flag's value.
+ *
+ * A person types `comprism ask fix the failing test`, not
+ * `comprism ask --request "fix the failing test"`.
+ */
+export declare function freeText(args: string[], flagsTakingValue: string[]): string;
+/** The subject of a command: taken from the line, or asked for. */
+export declare function subject(args: string[], prompt: string, flagsTakingValue?: string[]): Promise<string>;

package/out/lib/prompt.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.closePrompt = closePrompt;
+exports.ask = ask;
+exports.askHidden = askHidden;
+exports.freeText = freeText;
+exports.subject = subject;
+/**
+ * Asking a person for something, in a terminal.
+ *
+ * One reader, opened on demand and closed at the end of the command. Readline
+ * reads ahead, so a fresh reader per question throws away whatever was already
+ * typed, which silently lost the second answer of two.
+ */
+const node_readline_1 = __importDefault(require("node:readline"));
+let reader = null;
+function open() {
+    if (!reader) {
+        reader = node_readline_1.default.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: process.stdin.isTTY === true,
+        });
+    }
+    return reader;
+}
+/** Close it on every path, or the command holds the terminal and looks hung. */
+function closePrompt() {
+    reader?.close();
+    reader = null;
+}
+/** Ask a question and wait for the answer. */
+function ask(prompt) {
+    return new Promise((resolve) => {
+        open().question(prompt, (answer) => resolve(answer.trim()));
+    });
+}
+/**
+ * Ask for a secret, and do not put it on the screen.
+ *
+ * ── Why the first two attempts failed, and what is different ──────────────
+ *
+ * Both earlier tries SUPPRESSED what readline wanted to print. Readline does
+ * not print characters one at a time; on every keystroke it redraws the whole
+ * line, prompt included. Swallowing that output therefore swallowed the
+ * question and the cursor with it, and left a person on a blank line unable to
+ * tell whether the program was even listening.
+ *
+ * So this does not suppress the redraw, it PERFORMS it: the prompt is written
+ * back out followed by one dot per character actually held in the line. Paste
+ * and backspace come out right for free, because the dots are counted from the
+ * line itself rather than tallied from keystrokes.
+ *
+ * With no terminal attached there is nothing to redraw and nothing to hide
+ * from, so the plain question is used. That is the piped case, where the only
+ * reader is a script.
+ */
+function askHidden(prompt) {
+    const reader = open();
+    if (process.stdin.isTTY !== true)
+        return ask(prompt);
+    const inner = reader;
+    const asItWas = inner._writeToOutput.bind(reader);
+    inner._writeToOutput = (chunk) => {
+        // A newline is the answer being accepted, and it still has to happen.
+        if (chunk.includes("\n") || chunk.includes("\r")) {
+            asItWas(chunk);
+            return;
+        }
+        process.stdout.write(`\r${prompt}${"\u2022".repeat(inner.line.length)}`);
+    };
+    return new Promise((resolve) => {
+        reader.question(prompt, (answer) => {
+            // Put readline back the way it was, whatever happened, or every later
+            // question on this reader would come out as dots.
+            inner._writeToOutput = asItWas;
+            process.stdout.write("\n");
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Everything on the line that is not a flag or a flag's value.
+ *
+ * A person types `comprism ask fix the failing test`, not
+ * `comprism ask --request "fix the failing test"`.
+ */
+function freeText(args, flagsTakingValue) {
+    return args
+        .filter((a, i) => {
+        if (a.startsWith('--'))
+            return false;
+        const prev = args[i - 1];
+        return !(prev && flagsTakingValue.includes(prev));
+    })
+        .join(' ')
+        .trim();
+}
+/** The subject of a command: taken from the line, or asked for. */
+async function subject(args, prompt, flagsTakingValue = []) {
+    const onTheLine = freeText(args, flagsTakingValue);
+    if (onTheLine)
+        return onTheLine;
+    return ask(prompt);
+}