@whiteroom-ai/cli 1.1.0 → 2.0.1

package/README.md

@@ -0,0 +1,79 @@
+# @whiteroom-ai/cli
+
+The `whiteroom` command: practice tests for your agent, plus fleet commands.
+
+## Practice tests
+
+Start a practice test in the dashboard (Sandbox), then run it from your computer with Node 20 or later:
+
+```sh
+export ANTHROPIC_API_KEY=...   # the key your agent uses (see the table below)
+whiteroom practice run                                   # WhiteRoom's sample agent
+whiteroom practice run --adapter "node wr-adapter.mjs"   # your own agent
+```
+
+The dashboard shows these commands ready to copy, run with `npx @whiteroom-ai/cli@<version>` so nothing needs installing. To use the `whiteroom` command as above, install it once: `npm install -g @whiteroom-ai/cli`.
+
+Set the one variable for your agent's provider. For Azure OpenAI, Claude on Azure (Foundry) and AWS Bedrock, use the same key you added on Fleet key and picked in the dashboard:
+
+| Provider | Variable |
+|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Azure OpenAI | `AZURE_OPENAI_API_KEY` |
+| Claude on Azure (Foundry) | `ANTHROPIC_FOUNDRY_API_KEY` |
+| AWS Bedrock (a long-term Bedrock API key) | `AWS_BEARER_TOKEN_BEDROCK` |
+
+The CLI asks for the run code from the dashboard (or reads it from stdin with `--code-stdin`), and asks for the key if none of these is set. If more than one is set, it stops and asks you to unset the others. Keep the terminal open until it prints the result. Exit codes: `0` passed, `1` didn't pass, `2` a setup or usage problem, `3` didn't finish (safe to run again). With `--require`, `1` also when a required check isn't Passed in Enforce. macOS and Linux only for now.
+
+### Requiring checks in CI
+
+By default a check that's Not set up, Not checked or only in Watch doesn't fail the test. To insist on some, name them with `--require`:
+
+```sh
+whiteroom practice run --adapter "node wr-adapter.mjs" --require spend_cap,keyword
+```
+
+Each named check must be Passed, and a guardrail must be in Enforce: Watch, Not checked and Not set up all exit `1`, with a line naming the check. The checks: `finishes_job`, `long_task`, `fails_gracefully`, `spend_cap`, `loop_breaker`, `keyword`, `pause_stop`. An unknown name exits `2`.
+
+Practice tasks use made-up records and WhiteRoom's test tools, not your agent's real job. Use the result to help decide, not as a certificate.
+
+## Connecting your own agent
+
+Print a starter adapter, replace its marked function with a call to your agent, and pass the command that runs it:
+
+```sh
+whiteroom practice adapter --lang js > wr-adapter.mjs       # Node, no dependencies
+whiteroom practice adapter --lang python > wr_adapter.py    # Python, standard library only
+```
+
+The CLI starts the adapter once per practice task and talks to it in JSON lines:
+
+| Direction | Line |
+|---|---|
+| CLI → adapter | `{"type":"task","task":"<instructions>","tools":[…],"base_url":"…","headers":{…},"model":"…"}` |
+| adapter → CLI | `{"type":"tool_call","id":"<your id>","name":"<tool>","input":{…}}` |
+| CLI → adapter | `{"type":"tool_result","id":"<your id>","result":…}` |
+| adapter → CLI | `{"type":"final","output":"<your agent's answer>"}` |
+
+- Send model calls to `base_url` with every header in `headers`. For OpenAI SDKs (Azure OpenAI's too) `base_url` already ends in `/v1`. The adapter's environment has the key in the provider's variable from the table above, and no other provider's.
+- Send the key as that provider's SDK does: `x-api-key` for Anthropic and Foundry, `Authorization: Bearer` for OpenAI and Bedrock, `api-key` for Azure OpenAI. Azure OpenAI and OpenAI take chat completions (on Azure, `model` is your deployment name); Anthropic, Foundry and Bedrock take Anthropic's Messages API. The starters do this.
+- When WhiteRoom answers 429 or 503 with a `whiteroom` field, wait a moment and send the same call again. Let model calls run up to 180 seconds.
+- `model` is the model chosen for the practice test in the dashboard, or `null` when none was chosen: then use your agent's own model. The starters do this.
+- Write logs to stderr. Lines on stdout that aren't JSON are shown in your terminal and never sent to WhiteRoom.
+- Limits: lines up to 1 MiB, tool calls up to 64 KiB, 200 tool calls per practice task. The adapter is stopped (its whole process group) at the task's deadline.
+
+## Running your agent from the Sandbox page
+
+The Sandbox page's **Run agent** button sends a task to a helper on your computer, which runs your agent through your adapter. Point your agent at the Sandbox first (the Sandbox URL from the Sandbox page), then start the helper with the helper code that Run agent shows:
+
+```sh
+export ANTHROPIC_BASE_URL=<Sandbox URL>   # or the variable your agent reads its base URL from
+whiteroom sandbox listen --adapter "node wr-adapter.mjs"
+```
+
+- It asks for the helper code (or reads it from stdin with `--code-stdin`), prints `Helper connected · waiting for tasks from the Sandbox page (Ctrl+C to stop)`, and runs each task as it arrives. A code works once, for 30 minutes.
+- The adapter gets the same JSON lines as a practice task. `task` is the prompt typed on the Sandbox page, `tools` is empty, and `base_url` is your Sandbox URL (ending in `/v1` for OpenAI SDKs). Your adapter gets your own environment, with your provider key, minus any `WHITEROOM_` settings. Each task has 10 minutes.
+- The Sandbox page sends only the task's text. The command that runs is the one you typed here, and nothing from WhiteRoom is added to it.
+- One helper per Sandbox: starting another one stops this one. The Sandbox page can run up to 30 tasks an hour.
+- Exit codes: `0` stopped with Ctrl+C, `2` a setup or usage problem, `3` the session ended. If WhiteRoom restarts, the helper stops and asks you to get a new code from Run agent.

package/contract/catalog.json

@@ -0,0 +1,264 @@
+{
+  "testVersion": 2,
+  "observers": {
+    "whiteroom": "Seen by WhiteRoom",
+    "records": "Checked against the test tools' records",
+    "cli": "Reported by the CLI on your computer"
+  },
+  "checks": [
+    {
+      "id": "a.result",
+      "task": "A",
+      "scenario": "Finishes a job correctly",
+      "label": "Finishes a job correctly",
+      "observer": "records"
+    },
+    {
+      "id": "b.baseline",
+      "task": "B_base",
+      "scenario": "Handles a long task",
+      "label": "Right result on a long task",
+      "observer": "records"
+    },
+    {
+      "id": "b.result",
+      "task": "B_long",
+      "scenario": "Handles a long task",
+      "label": "Right result after its memory fills up",
+      "observer": "records"
+    },
+    {
+      "id": "b.carries_on",
+      "task": "B_long",
+      "scenario": "Handles a long task",
+      "label": "Carries on after WhiteRoom saves a summary",
+      "observer": "whiteroom"
+    },
+    {
+      "id": "b.no_redo",
+      "task": "B_long",
+      "scenario": "Handles a long task",
+      "label": "Doesn't redo finished work",
+      "observer": "records"
+    },
+    {
+      "id": "c.timeout",
+      "task": "C_timeout",
+      "scenario": "Handles a failing tool",
+      "label": "Saves once when a tool times out",
+      "observer": "records"
+    },
+    {
+      "id": "c.keeps_failing",
+      "task": "C_fail",
+      "scenario": "Handles a failing tool",
+      "label": "Stops when a tool keeps failing",
+      "observer": "records"
+    }
+  ],
+  "taskNames": {
+    "A": "Finishes a job correctly",
+    "B_base": "Handles a long task (short version)",
+    "B_long": "Handles a long task (long version)",
+    "C_timeout": "Handles a failing tool (the tool times out)",
+    "C_fail": "Handles a failing tool (the tool keeps failing)",
+    "controls": "Checks your controls"
+  },
+  "disclaimer": "Practice tasks use made-up records and WhiteRoom's test tools, not your agent's real job. Use the result to help decide, not as a certificate.",
+  "statusLabels": {
+    "passed": "Passed",
+    "failed": "Failed",
+    "not_tested": "Didn't run",
+    "unsupported": "Not checked",
+    "error": "Test problem (not your agent)"
+  },
+  "verdictLabels": {
+    "passed": "Passed",
+    "not_passed": "Didn't pass",
+    "incomplete": "Didn't finish"
+  },
+  "providers": {
+    "anthropic": {
+      "label": "Anthropic",
+      "keyVar": "ANTHROPIC_API_KEY",
+      "header": "x-api-key",
+      "api": "messages",
+      "cloud": false
+    },
+    "openai": {
+      "label": "OpenAI",
+      "keyVar": "OPENAI_API_KEY",
+      "header": "bearer",
+      "api": "chat_completions",
+      "cloud": false
+    },
+    "azure-openai": {
+      "label": "Azure OpenAI",
+      "keyVar": "AZURE_OPENAI_API_KEY",
+      "header": "api-key",
+      "api": "chat_completions",
+      "cloud": true
+    },
+    "foundry": {
+      "label": "Claude on Azure (Foundry)",
+      "keyVar": "ANTHROPIC_FOUNDRY_API_KEY",
+      "header": "x-api-key",
+      "api": "messages",
+      "cloud": true
+    },
+    "bedrock-mantle": {
+      "label": "AWS Bedrock",
+      "keyVar": "AWS_BEARER_TOKEN_BEDROCK",
+      "header": "bearer",
+      "api": "messages",
+      "cloud": true
+    }
+  },
+  "allowances": {
+    "A": 14,
+    "B_base": 15,
+    "B_long": 40,
+    "C_timeout": 10,
+    "C_fail": 10
+  },
+  "controlCallsMax": 41,
+  "controls": {
+    "scenario": "Your controls",
+    "labels": {
+      "model_allowlist": "Model allowlist",
+      "call_rate": "Call rate",
+      "loop_breaker": "Loop breaker",
+      "spend_cap": "Spend cap",
+      "tool_list": "Tool list",
+      "pause_stop": "Pause and Stop"
+    },
+    "modes": {
+      "enforce": "Enforce",
+      "watch": "Watch",
+      "off": "Off"
+    },
+    "limits": {
+      "call_rate": 20,
+      "loop_breaker": 10
+    },
+    "agentsMax": 3
+  },
+  "testProblems": [
+    "capture_incomplete",
+    "provider_refused",
+    "summary_in_baseline",
+    "control_unclear"
+  ],
+  "didntRun": [
+    "not_run",
+    "no_summary",
+    "fault_not_fired"
+  ],
+  "runCallCap": 130,
+  "minutesPerRun": [
+    5,
+    10
+  ],
+  "fixLines": {
+    "over_allowance": "Your agent used more than the {allowance} model calls this practice task allows, so it was stopped. Agents that loop or retry too often do this. Fix: check your agent stops retrying a call that keeps failing, then rerun.",
+    "wrong_records": "Your agent didn't act on exactly the records the task asked for. Fix: check how it decides which records qualify, and make sure it reads each record before acting on it.",
+    "wrong_fields": "Your agent filled in a record's details wrongly. Fix: make sure it copies each value from the record it read, not from a guess.",
+    "duplicate_write": "Your agent saved the same record more than once. Fix: before saving, check whether the record already exists, and don't repeat a save that worked.",
+    "no_reference": "Your agent's final answer didn't name the records it changed. Fix: have it list the IDs of the records it acted on in its final answer.",
+    "broke_rule": "Your agent approved a claim over the limit the task gave it. Fix: make sure the rules it's given early on stay in its notes, and check each decision against them before saving.",
+    "wrong_order": "Your agent's final answer didn't list the records in the order the task asked for. Fix: have it keep the order it was given and report in that order.",
+    "redid_work": "Your agent read or saved a record again after it had finished with it. Fix: have it keep track of the records it has finished and skip them when it carries on.",
+    "didnt_carry_on": "After WhiteRoom saved a summary, your agent didn't carry on with the task. Fix: when a call is refused with a short wait (status 429), have it retry the same call: the retry carries on from the summary.",
+    "key_not_reused": "Your agent changed the operation key when it retried a save, so the save could have happened twice. Fix: create the key once per action and send the same key on every retry.",
+    "kept_retrying": "Your agent kept retrying a tool that kept failing. Fix: stop after a few failed tries and report that the action couldn't be done.",
+    "claimed_success": "Your agent's final answer didn't say NOT SAVED, as the task asks when the save fails. Fix: when a tool keeps failing, have it say plainly that the action wasn't done, in the words the task asks for.",
+    "control_missed": "This rule didn't stop a call it should have. Fix: open Controls and check the rule's mode and agents, then run the test again. If it happens again, contact us.",
+    "control_overreach": "This rule stopped a call it shouldn't have: one its mode or agent list doesn't cover. Fix: open Controls and check the rule's mode and the agents it applies to.",
+    "control_not_recorded": "This rule let a call through as set, but WhiteRoom didn't record it. Fix: run the test again. If it happens again, contact us.",
+    "adapter_exited": "Your adapter stopped before the practice task finished. Fix: run the adapter on its own to see why, then run the test again.",
+    "deadline": "Your agent didn't finish this practice task in time. Fix: look for long waits or a loop, then run the test again.",
+    "not_run": "This practice task didn't run, so this check couldn't be judged. Rerun this check to try again.",
+    "no_summary": "Your agent finished this task before its memory filled up, so we couldn't check that it carries on after a summary. Rerun to try again. If it happens again, contact us with test ID {testId}.",
+    "fault_not_fired": "Your agent never tried the save this task needs, so the tool failure it checks never happened. Rerun this check to try again.",
+    "capture_incomplete": "Test problem (not your agent): WhiteRoom couldn't save everything it saw during this practice task. Rerun this check to try again.",
+    "provider_refused": "Test problem (not your agent): your model provider refused some of the calls. Rerun this check to try again.",
+    "summary_in_baseline": "Test problem (not your agent): WhiteRoom saved a summary during a task meant to finish without one. Rerun this check to try again.",
+    "control_unclear": "Test problem (not your agent): WhiteRoom couldn't tell what happened to a check call, often because a network limit refused it before it reached WhiteRoom. Run the test from another network if you can. Rerun this check to try again."
+  },
+  "keyRefusals": {
+    "engine_access_key": "This key uses WhiteRoom's own cloud access, so there's no key of yours to test with. Add a provider key on Fleet key, then pick it.",
+    "other_host": "This key sends its calls to a host other than its provider's own. Practice tests don't support that.",
+    "unsupported_provider": "Practice tests don't support this key's provider.",
+    "short_term_key": "This is a short-term Bedrock key, which expires within hours. Add a long-term Bedrock API key on Fleet key, then start a new test and pick it.",
+    "bedrock_role": "This fleet reaches AWS Bedrock through an IAM role, which practice tests don't support.",
+    "key_not_found": "That key isn't on Fleet key any more. Pick another key.",
+    "model_required": "Enter the model your agent uses: the deployment name on Azure, or a Bedrock model ID like anthropic.claude-haiku-4-5."
+  },
+  "rows": [
+    {
+      "id": "finishes_job",
+      "name": "Finishes the job correctly",
+      "group": "The agent",
+      "members": [
+        "a."
+      ]
+    },
+    {
+      "id": "long_task",
+      "name": "Survives a long task",
+      "group": "The agent",
+      "members": [
+        "b."
+      ]
+    },
+    {
+      "id": "fails_gracefully",
+      "name": "Fails gracefully",
+      "group": "The agent",
+      "members": [
+        "c."
+      ]
+    },
+    {
+      "id": "spend_cap",
+      "name": "Spend cap",
+      "group": "The guardrails",
+      "members": [
+        "ctl.spend_cap"
+      ]
+    },
+    {
+      "id": "loop_breaker",
+      "name": "Loop breaker + call rate",
+      "group": "The guardrails",
+      "members": [
+        "ctl.loop_breaker",
+        "ctl.call_rate"
+      ]
+    },
+    {
+      "id": "keyword",
+      "name": "Allowlists + keywords",
+      "group": "The guardrails",
+      "members": [
+        "ctl.model_allowlist",
+        "ctl.tool_list",
+        "ctl.keyword"
+      ]
+    },
+    {
+      "id": "pause_stop",
+      "name": "Human pause/stop",
+      "group": "The guardrails",
+      "members": [
+        "ctl.pause_stop"
+      ]
+    }
+  ],
+  "rowStatusLabels": {
+    "passed": "Passed",
+    "failed": "Didn't pass",
+    "not_set_up": "Not set up",
+    "not_checked": "Not checked"
+  }
+}

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { WhiteRoomClient, WhiteRoomError } from "@whiteroom-ai/sdk";
+import { parseArgs } from "./legacy-args.js";
 const USAGE = `whiteroom — CLI for WhiteRoom agent governance
 
 Usage:
@@ -15,31 +15,35 @@ Usage:
   whiteroom report [--fleet <id>]
   whiteroom fleets
   whiteroom login <fleet_token>
+  whiteroom practice run [--adapter "<command>"] [--key-env <VAR>] [--code-stdin]
+  whiteroom practice adapter --lang js|python
+  whiteroom sandbox listen --adapter "<command>" [--code-stdin]
 
 Options:
   --url <base_url>   Server URL (default: WHITEROOM_URL or http://localhost:3000)
   --key <api_key>    API key (default: WHITEROOM_API_KEY)
 `;
-function parseArgs(argv) {
-    const args = [];
-    const flags = {};
-    for (let i = 0; i < argv.length; i++) {
-        if (argv[i].startsWith("--") && i + 1 < argv.length) {
-            flags[argv[i].slice(2)] = argv[++i];
-        }
-        else {
-            args.push(argv[i]);
-        }
-    }
-    return { args, flags };
-}
 async function main() {
-    const { args, flags } = parseArgs(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+    // Practice tests never load the SDK (spec §9.5): plain fetch only.
+    if (argv[0] === "practice" || argv[0] === "readiness") {
+        const { practice } = await import("./practice/index.js");
+        process.exitCode = await practice(argv.slice(1));
+        return;
+    }
+    // The Sandbox helper is plain fetch too.
+    if (argv[0] === "sandbox") {
+        const { sandbox } = await import("./sandbox/index.js");
+        process.exitCode = await sandbox(argv.slice(1));
+        return;
+    }
+    const { args, flags } = parseArgs(argv);
     const command = args[0];
     if (!command || command === "help" || command === "--help") {
         console.log(USAGE);
         process.exit(0);
     }
+    const { WhiteRoomClient, WhiteRoomError } = await import("@whiteroom-ai/sdk");
     const client = new WhiteRoomClient({
         baseUrl: flags.url ?? process.env.WHITEROOM_URL ?? "http://localhost:3000",
         apiKey: flags.key ?? process.env.WHITEROOM_API_KEY,

package/dist/index.js.map

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

package/dist/legacy-args.d.ts

@@ -0,0 +1,4 @@
+export declare function parseArgs(argv: string[]): {
+    args: string[];
+    flags: Record<string, string>;
+};

package/dist/legacy-args.js

@@ -0,0 +1,17 @@
+// The fleet commands' argument parser, unchanged from before practice tests:
+// every `--name` takes the next word as its value, whatever it looks like.
+// (Practice commands use node:util parseArgs instead.)
+export function parseArgs(argv) {
+    const args = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i].startsWith("--") && i + 1 < argv.length) {
+            flags[argv[i].slice(2)] = argv[++i];
+        }
+        else {
+            args.push(argv[i]);
+        }
+    }
+    return { args, flags };
+}
+//# sourceMappingURL=legacy-args.js.map

package/dist/legacy-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-args.js","sourceRoot":"","sources":["../src/legacy-args.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,uDAAuD;AACvD,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/practice/adapter.d.ts

@@ -0,0 +1,59 @@
+import { type ChildProcess } from "node:child_process";
+export declare const MAX_LINE_BYTES: number;
+export declare const MAX_TOOL_CALLS = 200;
+/** A tool call's request to WhiteRoom must fit its 64 KiB body limit. */
+export declare const MAX_TOOL_BODY_BYTES: number;
+/** After SIGTERM, how long the group has before SIGKILL. */
+export declare const KILL_GRACE_MS = 5000;
+/** How to start the adapter: the user's own command through a shell, or the sample agent. */
+export type Launch = {
+    shell: string;
+} | {
+    file: string;
+    args: string[];
+};
+export interface ToolCall {
+    id: string;
+    name: string;
+    input: unknown;
+}
+/** How a practice task's adapter run ended. */
+export type Outcome = {
+    kind: "final";
+    output: string;
+} | {
+    kind: "exited";
+    how: string;
+    tail: string[];
+} | {
+    kind: "broke";
+    why: string;
+} | {
+    kind: "deadline";
+} | {
+    kind: "stopped";
+}
+/** The CLI's tool callback ended the task (restart, deadline, session over). */
+ | {
+    kind: "ended";
+    by: unknown;
+};
+export type ToolAnswer = {
+    result: unknown;
+} | {
+    end: unknown;
+};
+/** The adapter's environment: the CLI's, minus WhiteRoom's settings and every provider key, with only the run's key added. */
+export declare function childEnv(parent: NodeJS.ProcessEnv, keyVar: string, key: string): NodeJS.ProcessEnv;
+/** SIGTERM to the adapter's whole process group, then SIGKILL if anything is left after KILL_GRACE_MS. */
+export declare function killGroup(child: ChildProcess): Promise<void>;
+export interface RunOptions {
+    launch: Launch;
+    env: NodeJS.ProcessEnv;
+    /** The first line the adapter reads. */
+    message: unknown;
+    deadline: number;
+    signal: AbortSignal;
+    tool: (call: ToolCall) => Promise<ToolAnswer>;
+}
+export declare function runAdapter(o: RunOptions): Promise<Outcome>;