predictable-ai 0.1.0

package/README.md

@@ -0,0 +1,265 @@
+# predictable-ai
+
+The Predictable agent surface, on the command line. One command per verb in the
+manifest, line-oriented output by default and `--json` for piping.
+
+## Install
+
+```bash
+npm install -g predictable-ai
+npx predictable-ai --version
+```
+
+The package ships one binary, `predictable`. `npx` runs it without installing it
+globally first. Either way `--version` prints this client's version and the
+agent-surface hash compiled into it — and, once a token is configured, the hash
+the deployment serves, so a client that disagrees with its deployment says so
+rather than failing later on a verb that moved.
+
+To work from a checkout instead:
+
+```bash
+cd cli
+npm ci
+npm run build
+node dist/bin.js --version
+```
+
+## Quickstart
+
+1. **Mint a token.** In the web app, open **Settings → Agent token**
+   (`/settings/agent-token`) and mint one. It is shown once.
+
+2. **Export it.** The environment variable is the channel:
+
+   ```bash
+   export PREDICTABLE_TOKEN='paste-the-minted-value-here'
+   ```
+
+   Typing it into an interactive shell leaves it in your history file. The
+   config-file channel described below avoids that, and a secret store beats
+   both.
+
+3. **Say who you are.** The token smoke-test verb:
+
+   ```bash
+   predictable whoami
+   ```
+
+4. **See what the token reaches.** `predictable lists list` in its default text
+   mode prints one line per **client** — id and name — and no lists at all, so
+   it will not hand you the list id step 5 needs. Ask for the JSON instead,
+   where each client carries its `lists`:
+
+   ```bash
+   predictable lists list --json
+   ```
+
+   That is the server's body verbatim, so it arrives on one line, with every
+   list's `id`, `name` and `discovery_source` in it. If you have `jq` — a
+   separate tool, not something this package installs — the same output reads
+   as a table:
+
+   ```bash
+   predictable lists list --json | jq -r '.clients[].lists[] | [.id, .name, .discovery_source] | @tsv'
+   ```
+
+   Either way, copy one of those list ids for the next step.
+
+5. **Preview a search.** The preview prices the run and mints a quote — it
+   spends nothing. Only the second step, the one carrying `--quote`, spends:
+
+   ```bash
+   predictable search run --preview --list <list-id>
+   ```
+
+   Not every list is eligible: base search runs only on a list whose
+   `discovery_source` is `exa_agent` (step 4 shows it), that is not
+   alumni-seeded, and that already has a search query from the describe step —
+   any other list is refused with a 400 rather than quoted.
+
+`predictable --help` lists every verb and `predictable <command> --help`
+explains one. `--json` prints the server's response body verbatim, so it pipes:
+
+```bash
+predictable lists list --json | jq '.clients[].lists[].name'
+```
+
+## Authenticate
+
+The CLI reads your token from one of two places, in this order:
+
+1. The `PREDICTABLE_TOKEN` environment variable.
+2. `~/.predictable/config.json`, a file holding `{"token": "..."}`.
+
+It never reads a token from the command line. A token typed as an argument is
+saved in your shell history and is visible in `ps` output to every other user on
+the machine, so no command here accepts one. Pass one as a flag and the CLI
+refuses by name and exits 1 — before printing help, before printing a version,
+and before sending anything — rather than ignoring the flag and making an
+anonymous request. Diagnostics never repeat back a value you typed, so a
+credential in the wrong place does not end up in a CI log.
+
+To get a token, open **Settings → Agent token** in the web app and mint
+one. It's shown once. Then store it:
+
+```bash
+mkdir -p ~/.predictable
+chmod 700 ~/.predictable
+# Paste the token when the editor opens, as {"token": "<the token>"}
+$EDITOR ~/.predictable/config.json
+chmod 600 ~/.predictable/config.json
+```
+
+Setting `PREDICTABLE_TOKEN` in your environment works too, and is the right
+channel in CI. Prefer a secret store over typing it into an interactive shell,
+where it lands in your history file.
+
+By default the CLI talks to the production deployment. Set
+`PREDICTABLE_BASE_URL` to point it at a preview.
+
+## Claude Code and other agents
+
+This CLI is the client-facing contract, and Claude Code is meant to drive it the
+way it drives `git`: install the package, put `PREDICTABLE_TOKEN` in the
+environment of the shell it runs in, and ask for the verb you want. Output is
+line-oriented by default and `--json` for structured reads, so an agent can
+parse what comes back. The two-step rule on paid verbs holds under an agent
+exactly as it does under a person: the preview mints a quote, the acting call
+needs `--quote`, and a paid command without one refuses locally and sends
+nothing.
+
+For clients that will install nothing, the same manifest is also served as MCP
+tools by a hosted head on the same deployment:
+
+- `POST https://www.predictable.ai/api/agent/mcp` — streamable HTTP, stateless,
+  a fresh server per request.
+- It authenticates with the same minted agent token, presented as a bearer
+  credential by the MCP client's own configuration. The rule this CLI enforces
+  holds there too: the credential travels in a header, never in an argument.
+- Both heads register the same verbs, generated from the one manifest, so the
+  two cannot drift apart.
+
+The criteria coaching is served both ways: `predictable guide criteria` on the
+CLI, and the `agent://guide` resource over MCP.
+
+## Spending credits
+
+Paid verbs are two steps. The first prices the work and mints a quote; the
+second spends against that quote:
+
+```bash
+predictable contacts source --preview --list <list-id>   # prints a quote id, credits, expiry
+predictable contacts source --quote <quote-id> --list <list-id>
+```
+
+Run the acting command without `--quote` and it refuses before sending
+anything, and tells you the preview command to run.
+
+## Exporting a campaign bundle
+
+`export campaign` is the one verb that writes FILES rather than printing
+records. It produces the seven-file bundle for a list:
+
+```bash
+predictable export campaign --list <list-id> --out ./acme-bundle
+```
+
+| File | What it holds |
+| ---- | ------------- |
+| `accounts.csv` | The approved-accounts export, byte for byte as the server sent it. |
+| `contacts.csv` | Every contact on the list. |
+| `sequence.json` | One sequence's detail. |
+| `events.csv` | Per-send rows, paged to exhaustion. |
+| `replies.json` | The list's replies. |
+| `stats.json` | Three reads: the sequences list with its per-sequence stats, billing usage, and the pipeline. Each is recorded as `ok` with its data or `unavailable` with the reason, so a source you were refused never looks like a source that returned nothing. |
+| `manifest.json` | What was exported, the server's exclusion counts, the row counts, the byte size of every other file, and which stats sources it actually carries. Anything a count does not cover is named in `completeness_scope` with the reason. |
+
+Add `--sequence <id>` to pick which sequence `sequence.json` describes and to
+narrow `events.csv` to that sequence.
+
+**The directory is replaced, and only on success.** The bundle is assembled in
+full before anything is written, then moved into place as the last act. If a
+read fails, a size cap is breached, or the write itself fails partway, `--out`
+is left exactly as it was — there is no partial bundle to mistake for a whole
+one. A bundle over 250,000 rows in any file, or 100 MB in total, exits with
+`bundle_envelope_exceeded` naming the file that broke the cap.
+
+The one bound on that guarantee, stated rather than glossed: replacing an
+existing bundle is two moves, and a process **killed** between them leaves
+`--out` absent for an instant. Nothing is lost — the previous bundle is beside
+it under a `.replaced-…` name and a later run puts it back — but a run
+interrupted by `kill -9` can leave you one bundle behind rather than exactly
+where you were. Closing that instant needs an atomic directory swap the
+platform does not portably offer.
+
+**The put-back needs a run that reaches the write.** It is the first act of the
+write phase, and the write phase begins only after every read has succeeded. A
+following run that fails earlier — a 500, an offline host — exits with `--out`
+still absent and the previous bundle still under its `.replaced-…` name.
+Nothing is lost on that path either, but it is the next run that reads
+cleanly, not simply the next run, that restores it.
+
+**`contacts.csv` is checked against the server's own total** for the list before
+anything is written. A short read is an error, not a smaller file.
+
+### Suppression and `--purpose`
+
+By default the accounts export is suppression-filtered. `--purpose
+reporting_history` **skips that filter on purpose** — it is for reporting on
+what you already did, not for choosing who to contact next:
+
+```bash
+predictable export campaign --list <list-id> --out ./acme-bundle --purpose reporting_history
+```
+
+The bundle says so in two places: a note on stderr when it runs, and
+`manifest.json`'s `purpose`. Do not send outreach to a list built from a
+`reporting_history` export.
+
+### A note on spreadsheets
+
+Cells that a spreadsheet would treat as a formula are written with a leading
+apostrophe so they open as text. That includes values that only look like
+formulas — a phone number starting `+`, an address starting `-` — so those
+gain an apostrophe too. `manifest.json` counts how many cells were affected.
+The stored data is unchanged; this applies to the exported file only.
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | Success. |
+| 1 | Bad flags, or the server rejected the request as given. |
+| 2 | The credential was refused (401 or 403). |
+| 3 | Rate limited (429). The server's `Retry-After` is echoed on stderr. |
+| 4 | Server error, or a verb this deployment does not serve yet. |
+| 5 | A paid command needs `--quote`. Nothing was sent. |
+
+Records go to stdout. Warnings, errors and hints go to stderr, so a pipeline
+never eats a diagnostic as data.
+
+## Versions
+
+`predictable --version` prints this package's version, the agent-surface hash
+compiled into it, and — when a token is configured — the hash the deployment
+serves. When those two hashes differ, this client and that deployment disagree
+about which verbs exist; update the client.
+
+## Development
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+`src/generated/commands.json` is generated from
+`dashboard/src/lib/agent/manifest.ts` and must never be hand-edited. The parity
+test in `test/parity.test.ts` fails if the command set here and the verb set
+there ever disagree.
+
+The end-to-end walk in `scripts/e2e-walk.mjs` runs the five read commands
+against whatever `PREDICTABLE_BASE_URL` names: a local stub in CI, or a
+deployment when you have a token for one.

package/dist/args.js

@@ -0,0 +1,76 @@
+import { CliError, EXIT } from './errors.js';
+/** Flags every command understands. */
+export const GLOBAL_BOOLEANS = ['json', 'help'];
+/**
+ * Split argv into a command name and its flags.
+ *
+ * `known` is the registered command list, longest match first, so `lists status`
+ * wins over a hypothetical `lists`.
+ */
+export function parseArgs(argv, known) {
+    const words = [];
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (token === undefined || token.startsWith('-'))
+            break;
+        words.push(token);
+        i += 1;
+    }
+    const byLength = [...known].sort((a, b) => b.split(' ').length - a.split(' ').length);
+    let command = '';
+    let consumed = 0;
+    for (const candidate of byLength) {
+        const parts = candidate.split(' ');
+        if (parts.length <= words.length && parts.every((p, n) => words[n] === p)) {
+            command = candidate;
+            consumed = parts.length;
+            break;
+        }
+    }
+    const flags = new Map();
+    const booleans = new Set();
+    const rest = words.slice(consumed);
+    while (i < argv.length) {
+        const token = argv[i];
+        if (!token.startsWith('--')) {
+            if (token === '-h') {
+                booleans.add('help');
+                i += 1;
+                continue;
+            }
+            rest.push(token);
+            i += 1;
+            continue;
+        }
+        const body = token.slice(2);
+        if (body.length === 0) {
+            i += 1;
+            continue;
+        }
+        const eq = body.indexOf('=');
+        if (eq > 0) {
+            flags.set(body.slice(0, eq), body.slice(eq + 1));
+            i += 1;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            booleans.add(body);
+            i += 1;
+            continue;
+        }
+        flags.set(body, next);
+        i += 2;
+    }
+    return { command, flags, booleans, rest };
+}
+/** Read a required flag, or fail with a usage error naming it. */
+export function requireFlag(args, name, placeholder) {
+    const value = args.flags.get(name);
+    if (value === undefined || value.length === 0) {
+        throw new CliError(EXIT.USAGE, `--${name} ${placeholder} is required.`);
+    }
+    return value;
+}
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/bin.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { run } from './run.js';
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+const code = await run({
+    argv: process.argv.slice(2),
+    env: process.env,
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    readStdin,
+});
+process.exitCode = code;
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAE9B,KAAK,UAAU,SAAS;IACtB,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IACxE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC;AAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3B,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAC5C,SAAS;CACV,CAAC,CAAA;AAEF,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAA"}