@illuminis/comprism 0.1.2 → 0.1.4

package/README.md

@@ -4,26 +4,91 @@ The half of CompletionPrism that runs on your machine. It sits between the tool
 you already use and the AI provider, records what finishing your work actually
 cost, and changes nothing about what your tool does.
 
+## Install
+
+Three ways, one tool. Pick the one that suits the machine; each gives you the
+same `comprism` command, sign in and settings.
+
+| Option | Pick it when | Install |
+| --- | --- | --- |
+| 1. Install script (recommended) | Nothing needs to be on the machine first: no Node, no Python | `curl -fsSL https://yourco.completionprism.com/install.sh \| sh` |
+| 2. npm | You already use Node 22 or newer | `npm install -g @illuminis/comprism` |
+| 3. Python | You have Python 3.9 or newer and no Node | `pip install comprism-cli` (or `pipx install comprism-cli`) |
+
+On Windows, the install script is one line in PowerShell:
+`irm https://yourco.completionprism.com/install.ps1 | iex`. The address is your
+own workspace, the one you sign in to. A company that allows only its own
+package sources installs the Python option from the workspace:
+`pip install --index-url https://yourco.completionprism.com/pypi/simple/ comprism-cli`.
+
+Then sign in:
+
 ```bash
-npm install && npm run build
+comprism login
+```
 
-export ANTHROPIC_API_KEY=...      # or OPENAI_API_KEY
-node out/cli.js setup
-node out/cli.js session
-node out/cli.js report
+That is the whole install. It configures itself, including the one line it adds
+to your shell profile, and it says what it touched. npm hides that message by
+default, so add `--foreground-scripts` to the install if you want to read it.
+A Python install finishes its setup on the first `comprism login`.
+
+No API key to export. The keys live in your workspace, and every decision is
+made on our servers.
+
+Sign in from an interactive terminal. `comprism login` and its `connect` alias
+exit with status 1 when input is piped or redirected, before asking for credentials
+or contacting the service. Sign in first, then run commands from your script.
+
+```bash
+comprism status         # which account and company this machine is signed in to
+comprism check          # what this machine still needs, and how to add it
+comprism install        # redo the shell setup, if the install could not
+comprism cost           # what a session cost, and which factors drove it
+comprism uninstall      # takes the line back out
 ```
 
+`comprism check` exits with status 1 while setup is unfinished, so a script can
+test for it. `comprism --version` prints the installed version. `comprism
+update` installs a newer version the same way this one was installed; your sign
+in and the single profile line are kept.
+
+`comprism uninstall` removes the profile line, the generated shell script and
+any old Claude Desktop entry of ours; for an install script install it also
+removes the program. It leaves your sign in and settings in `~/.comprism` and
+says so. Run `comprism logout` first to revoke this machine's key. Then remove
+the tool the way it was installed: nothing more for the install script,
+`npm uninstall -g @illuminis/comprism` for npm, `pip uninstall comprism-cli`
+for Python. Delete `~/.comprism` to remove every trace.
+
+Automatic shell setup covers zsh and bash on macOS and Linux, and PowerShell on
+Windows. The Windows install script also puts the tool on your user PATH, so
+Command Prompt finds it too.
+
+## Where the money went
+
+`comprism cost` breaks down a session without leaving the terminal: what it
+cost, what it would have cost, and the five factors behind the difference, then
+every provider call with its tokens, its price and the decision that chose that
+model.
+
+```bash
+comprism cost                       # the newest session this workspace recorded
+comprism cost srv_69e322469de33b90  # a particular one
+cost                                # inside a session, meaning this one
+```
+
+The figures come from the same service the portal reads, so the two can never
+quote different numbers for one piece of work. A factor nothing measured prints
+blank, never zero: a zero in a cost column reads as a measurement.
+
 ## The coding agent
 
-`comprism agent` is a coding agent in your terminal. It reads your project,
-changes files, runs commands, runs your tests, and shows you every change before
-it makes it.
+`comprism work` reads your project, changes files, runs commands, runs your
+tests, and shows you every change before it makes it.
 
 ```bash
-npm install -g @illuminis/comprism
-comprism login                    # once, per machine
 cd ~/your-project
-comprism agent "the tests are failing, work out why and fix it"
+comprism work "the tests are failing, work out why and fix it"
 ```
 
 **What makes it different from the others.** Every step is routed to whichever
@@ -63,7 +128,7 @@ production. Those are yours to do.
 ### Before you let it change anything
 
 ```bash
-comprism agent --plan "rename the parser module and update every caller"
+comprism work --plan "rename the parser module and update every caller"
 ```
 
 It reads what it needs, tells you what it would do, and changes nothing. The
@@ -85,7 +150,7 @@ ran a command, the undo says so plainly rather than claiming to have reversed it
 ### Carrying on tomorrow
 
 ```bash
-comprism agent --resume <job-id> "also add a test for the empty case"
+comprism work --resume <job-id> "also add a test for the empty case"
 ```
 
 It continues the conversation rather than starting a new one, so it already knows
@@ -94,7 +159,7 @@ what it read and decided.
 ### In a script, or in continuous integration
 
 ```bash
-comprism agent --yes --mode auto_edit "run the linter and fix what it reports"
+comprism work --yes --mode auto_edit "run the linter and fix what it reports"
 echo $?     # 0 if it finished, non-zero if it did not
 ```
 
@@ -108,8 +173,8 @@ By default, whichever finishes each step for least. Pin one when you want to
 decide yourself:
 
 ```bash
-comprism agent --model gpt-5 "..."          # or any model your account can reach
-comprism agent --max-spend 2.00 "..."       # stop here rather than running on
+comprism work --model gpt-5 "..."          # or any model your account can reach
+comprism work --max-spend 2.00 "..."       # stop here rather than running on
 ```
 
 Four providers are wired: Anthropic, OpenAI, Google and xAI. Which ones you can
@@ -117,19 +182,20 @@ reach depends on the keys on your account.
 
 ### Requirements
 
-Node 22 or newer, and a workspace you have signed in to with `comprism login`.
+A workspace you have signed in to with `comprism login`. Node 22 or newer for
+the npm option only; the install script and Python options carry their own.
 
 ---
 
 ## Instrument a tool you already use
 
-```bash
-node out/cli.js proxy
-export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
-```
+Nothing to do. The install configured this, by adding one fenced line to your
+shell profile that points your existing tools at the recorder. Open a new
+terminal and `claude` is already measured.
 
 Requests are forwarded to the provider byte for byte. Your key is forwarded,
-never read or stored. Unset the variable and we are gone, with nothing to undo.
+never read or stored. `comprism uninstall` takes the line back out and every
+tool goes straight to its provider again.
 
 ## Whose Anthropic account pays
 
@@ -138,7 +204,7 @@ surface can carry a credential.
 
 | How you work | Where the key comes from | Stored anywhere? |
 |---|---|---|
-| `comprism session`, `comprism proxy`, or an IDE pointed at your workspace | this machine, per request | no |
+| `comprism`, the interception the install configured, or an IDE pointed at your workspace | this machine, per request | no |
 | The developer API and the SDKs | the `X-Anthropic-Key` header, per request | no |
 | Claude Desktop and claude.ai | your workspace's own stored key | yes, encrypted, and only this one |
 
@@ -148,16 +214,14 @@ answering those prompts at all means the workspace holding a key. A workspace
 that holds none gets its connector answers refused - never billed to illuminis.
 
 ```bash
-node out/cli.js key            # whose account pays, here and in your workspace
-node out/cli.js key push       # send this machine's key, for the connector surface
-node out/cli.js key clear      # take it back out
+comprism keys           # whose account pays, here and in your workspace
 ```
 
-`push` is the one command that deliberately sends a provider key anywhere. It
-sends the key this machine already resolves, over TLS, to the workspace you are
-signed in to; Anthropic validates it before it is stored; nothing is written to
-disk here either way. An administrator can do the same in the app, under Policy
-and Data Controls.
+Sending a key to your workspace, for the connector row above, is deliberate and
+it is the one action that puts a provider key anywhere. It goes over TLS to the
+workspace you are signed in to, the provider validates it before it is stored,
+and nothing is written to disk here either way. An administrator can do the same
+in the app, under Policy and Data Controls.
 
 ## The stats footer
 
@@ -192,11 +256,9 @@ failure is logged rather than shown. Nothing is added at all when the turn ends
 in a tool call, a refusal, a truncation, an error event, an empty response, or a
 model with no published price.
 
-```bash
-node out/cli.js footer            # what it is doing now
-node out/cli.js footer off        # byte-faithful in both directions
-node out/cli.js footer on
-```
+Switch it off with `"enabled": false` under `footer` in
+`~/.comprism/config.json`, which makes the proxy byte faithful in both
+directions.
 
 ### Configuring pricing, the baseline and the template
 

package/out/agent/command.d.ts

@@ -1,6 +1,21 @@
 import { type JobResult } from "./session";
+import { type OutputChoice } from "../lib/output";
 export interface AgentArgs {
     request: string[];
+    /** Inside a session: background processes outlive this job and are stopped
+     *  when the session ends (manual 5.13). */
+    keepProcesses?: boolean;
+    /** Seconds each command may run before it is stopped (manual 5.12). */
+    timeout?: number;
+    /** Start from this GitHub issue (manual 5.20). */
+    issue?: number;
+    /** Lead the team defined under this name (manual 5.27). */
+    team?: string;
+    /** A review, not a request: the instruction is the service's (manual 5.19). */
+    review?: {
+        pr?: number;
+        post?: boolean;
+    };
     /** Start it and hand the terminal back. See `runDetached` for what this can
      *  and cannot do. */
     background?: boolean;
@@ -14,6 +29,14 @@ export interface AgentArgs {
     /** Run `model` and nothing else, whatever the router would prefer. */
     pin?: boolean;
     maxSpend?: number;
+    /** Stop after this many steps (manual 4.13). */
+    maxSteps?: number;
+    /** No new step after this many minutes (manual 10.7). */
+    maxMinutes?: number;
+    /** Reasoning effort: low, medium or high (manual 4.18). */
+    effort?: string;
+    /** Run commands in the operating system's sandbox (manual 4.12). */
+    sandbox?: boolean;
     /** `--allow "python3 grade.py"`, repeatable. Exact commands, pre approved. */
     allow?: string[];
     yes?: boolean;
@@ -31,7 +54,13 @@ export interface AgentArgs {
      *  already said. Not the same as `resume`, which re-enters a job that stopped
      *  part way; this is the ordinary next question in a conversation. */
     continuesJob?: string;
+    /** Which conversation this job belongs to, so the server files it under the
+     *  session the person is actually in rather than under their whole day. */
+    conversationId?: string;
     cwd?: string;
+    /** Other folders the person named with `--add-folder` or `folders add`
+     *  (manual 2.3). Nothing else ever becomes an allowed folder. */
+    addFolders?: string[];
     /**
      * Ask the person a yes or no question.
      *
@@ -44,6 +73,9 @@ export interface AgentArgs {
      * what the standalone command wants.
      */
     confirm?: (question: string) => Promise<boolean>;
+    /** A line of text from the same lent keyboard, for the plan question and the
+     *  agent's questions. Null means Ctrl+C. */
+    prompt?: (question: string) => Promise<string | null>;
     /**
      * Files already uploaded, to be put in front of this question.
      *
@@ -52,6 +84,12 @@ export interface AgentArgs {
      * here would be sending them twice and storing them nowhere useful.
      */
     attachments?: string[];
+    /** Names of files the person named that could not be attached, so the
+     *  agent is told rather than left to guess (manual 3.10). */
+    leftOut?: string[];
+    /** The terminal to ask approval questions at when standard input is a
+     *  pipe (manual 3.9). Never the pipe itself. */
+    keyboard?: NodeJS.ReadableStream | null;
     /**
      * Handed a way to stop the job, as soon as there is one to stop.
      *
@@ -65,10 +103,21 @@ export interface AgentArgs {
      *  to it while it runs. A caller that owns the keyboard needs both, because
      *  a person watching a job go the wrong way at step three should be able to
      *  correct it rather than stop it and start again. */
-    onStarted?: (controls: {
-        cancel: () => void;
-        steer: (text: string) => void;
-    }) => void;
+    onStarted?: (controls: JobControls) => void;
+    /** `--output` and `--quiet`, and whether standard output is a terminal
+     *  (manual 10.2, 10.3). Absent inside a session, which always draws. */
+    output?: OutputChoice;
+    /** `--schema`: the answer must be JSON of this shape (manual 10.5). */
+    answerSchema?: Record<string, unknown>;
+    /** A queued job this runner claimed (10.17 to 10.19); the service holds
+     *  its request, mode and limits. */
+    queuedJob?: string;
+    /** `--config`: settings read as if they were the project file (10.8). */
+    settingsConfig?: Record<string, unknown>;
+    /** `--no-personal`: leave out personal settings and instructions (10.8). */
+    noPersonal?: boolean;
+    /** Start in the full view (manual 6.9), because Ctrl+O was pressed earlier. */
+    fullView?: boolean;
     /**
      * Told what the job cost, once it has finished.
      *
@@ -81,6 +130,28 @@ export interface AgentArgs {
      */
     onFinished?: (result: JobResult) => void;
 }
+export declare const MODES: string[];
+/** What a caller holding the keyboard can do to a running job (manual 6.7 to
+ *  6.9). Every one of them is a message to the service, which decides. */
+export interface JobControls {
+    cancel: () => void;
+    steer: (text: string) => void;
+    pause: () => void;
+    carryOn: (text: string) => void;
+    isPaused: () => boolean;
+    queue: (clear: boolean) => void;
+    setFull: (on: boolean) => void;
+    /** Helpers running now, as the service reported them (manual 5.25). */
+    helpers: () => Array<{
+        id: string;
+        question: string;
+        agent?: string | null;
+    }>;
+    /** `stop h2`: the service stops that helper, the rest carry on. */
+    stopHelper: (id: string) => void;
+    /** The job's id, once the service has issued it. */
+    jobId: () => string | undefined;
+}
 export declare function runAgent(args: AgentArgs): Promise<number>;
 /** The help text. Written to be read by somebody who has not read anything else. */
 export declare const AGENT_HELP: string;