toolroll 0.9.104 → 0.9.105

package/dist/claude-print.js

@@ -1,28 +1,18 @@
-/**
- * The parts every bare `claude -p` call shares: a throwaway working folder, the flags that leave it with no tools,
- * no MCP servers and no saved session, and reading its one JSON reply. Each caller still builds its own argv around
- * these, in its own order.
- */
 import { Buffer } from "node:buffer";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { strictJsonParse } from "./converse.js";
-/** No tools, no permission prompts, no MCP servers, nothing kept: a `claude -p` call that can only answer. */
 export const CLAUDE_NO_TOOLS_ARGS = [
     "--safe-mode", "--no-session-persistence", "--tools", "", "--permission-mode", "dontAsk",
     "--permission-prompts", "none", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}',
 ];
-/** `--model <model>`, or nothing for the CLI's own default. */
 export const claudeModelArgs = (model) => (model === "default" ? [] : ["--model", model]);
-/** What a failed call's output says when this computer's Claude isn't signed in. */
 export const CLAUDE_SIGNED_OUT = /not logged in|login|authenticat/i;
-/** `claude -p --output-format json` stdout as its one object, or null. */
 export function claudeJsonBody(stdout, cap) {
     const parsed = strictJsonParse(Buffer.from(stdout, "utf8"), cap, 12);
     return parsed.ok && typeof parsed.value === "object" && parsed.value !== null && !Array.isArray(parsed.value) ? parsed.value : null;
 }
-/** Runs `work` in a fresh temporary folder named `<prefix>…`, removed afterwards whatever happens. */
 export async function inScratchDir(prefix, work) {
     const dir = mkdtempSync(join(tmpdir(), prefix));
     try {

package/dist/cli-fast.js

@@ -1,14 +1,6 @@
-/**
- * The answers that need nothing but this file: `--version` and the top-level
- * usage. The bin asks here before importing the CLI, so neither loads the
- * store, the contracts or a single command family. main() asks here too, so
- * both roads print the same bytes.
- */
 import { HELP } from "./cli-help.js";
 import { PACKAGE_VERSION } from "./version.js";
-/** Exactly the invocations whose whole answer is top-level usage — anything more goes through the CLI. */
 const HELP_INVOCATIONS = new Set(["--help", "-h", "help"]);
-/** The line to print and exit 0 with, or null when the CLI has to run. */
 export function quickAnswer(argv) {
     if (argv[0] === "--version" || argv[0] === "-v")
         return PACKAGE_VERSION;

package/dist/cli-help.js

@@ -1,68 +1,21 @@
-/**
- * The top-level usage text, on its own so `toolroll --help` can print it
- * without loading every command family (see cli-fast.ts).
- */
 import { DEFAULT_MAX_DEPTH } from "./scan.js";
-export const HELP = `toolroll — hand coding work to agents, walk away, come back to pull requests
+export const HELP = `toolroll — hand coding work to agents, approve each plan, accept what comes back Ready
 
-Usage
-  toolroll                  at your terminal: start Toolroll here (or attach) and open it in the terminal
-                                   (--web: the browser; --project-root <dir>: where projects live)
-                                   in a repository without a terminal, under an agent or with --json: only says what it would do
-  toolroll open [--web]     open this computer's Toolroll again, signed in
-  toolroll welcome          the three steps to a first result (--json: the model)
-  toolroll password set     add a password (typed twice, at your terminal)
-  toolroll scan [path...]   report what is in flight (also bare \`toolroll\` outside a repository)
-  toolroll [path...]        the same report for the paths given
-  toolroll pulls            report what is waiting on a person
-  toolroll graph            report which work graph is already here
-  toolroll repos            list connected repositories, and how to adjust
-  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)
-  toolroll repos remove <path>
-                                   take it out of the console; its tasks and results stay
-  toolroll repos add-from-github <owner/name> --root <dir>
-                                   preview, then clone and connect (--yes)
-  toolroll link             put \`toolroll\` on your PATH
-  toolroll unlink           take it off again
-  toolroll update           update to the latest release: verified, drained, undoable
-                                   (preview first; --yes, --now, --at HH:MM, --rollback)
-  toolroll release <branch> release Toolroll itself: checks, your approval, deploy, merge, tag, publish
-                                   (rerun the same command to continue; --help)
-  toolroll skills install --claude-code [--dir <path>]
-                                   install this binary's guides for Claude Code (preview first)
-  toolroll skills install   teach a repo's agents this queue exists (preview first)
-  toolroll demo             a seeded throwaway sandbox — see it working in 90 seconds
-  toolroll up               app + builder for every saved project — the normal start
-  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)
-  toolroll status           running, queued, ready results, release check and plan windows
-  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)
-  toolroll lead token       mint your lead agent's sign-in: its own work pings nobody
-  toolroll lead say "<text>"  (the lead) one short message in its person's chat
+  toolroll                      start Toolroll here and open it in this terminal (--web: in the browser)
+                                In it: n new task · a approve its plan · c accept a Ready result
+                                       b send it back · Enter open a task · ? every key
+  toolroll repos add <folder>   add a project (in a repository, \`toolroll\` adds that one)
+  toolroll demo                 try it first: sample tasks, no model calls, no cost
+  toolroll update               update to the latest release (shows what changes first)
 
-Tasks — \`toolroll task\` prints the whole list,
-and any task command + --help prints it too
-  toolroll approver add <name>
-                               add a person who can approve work
-  toolroll task add <title> queue work
-  toolroll task show <id>   one task: its plan, builds and what it waits for
-  toolroll task approve <id>
-                               the yes — nothing builds without one
-  toolroll task accept <id> --finish
-                               accept the result you read (--despite "<why>": accept it with a reason, without finishing)
-  toolroll task send-back <id> --feedback "<what to change>"
-                               send the result back for changes
-  toolroll task retry <id>  build it again
-  toolroll task ready <id>  can I merge it? each check, and what clears a blocker
-  toolroll chat --as <you> --token <t>
-                               talk to your lead: one conversation across every
-                               project; it proposes, you confirm (--say "…" for one turn)
-  toolroll card <source>    the data chat shows as a card: tasks, results, flows, spend,
-                               projects, builders, mode, integrations, providers, findings, handover
-  toolroll flows list | show <id> | create | edit | trigger | script | card | archive
-                               set up and inspect flows (writes preview until --yes)
+  toolroll task add "<what should change>"   add a task from a shell; approve its plan in Toolroll
+  toolroll task show <id>                    where a task is, and its result once it's Ready
 
-Machine and agent commands (the builder, agent tools, recovery):
-  toolroll internals        lists them; each keeps working as before
+More: toolroll task --help (every task command) · toolroll internals (everything else)`;
+export const SCAN_HELP = `toolroll scan [path...] — report what is in flight below a folder
+
+  toolroll scan [path...]   report what is in flight (also bare \`toolroll\` outside a repository)
+  toolroll [path...]        the same report for the paths given
 
 With nothing connected it reports everything it can find below the working
 directory. Once you connect repositories it reports those instead.
@@ -83,26 +36,88 @@ index lock with an editor you have open.
 
 --dirty is off by default because reading a working tree is unbounded
 work: on a large or cloud-synced repo \`git status\` can take minutes,
-where listing branches takes milliseconds.
+where listing branches takes milliseconds.`;
+export const INTERNALS_HELP = `toolroll internals — every other command (each keeps working as before)
 
-link shows what it would do and changes nothing; add --yes to apply it,
-or --to <dir> to choose where. It never uses sudo, never leaves your
-home directory, and never touches a file it did not create.`;
-/** The commands people rarely type: the builder's own loop, the machine contract and recovery. They all keep working;
- * `toolroll internals` (or `toolroll internals --help`) lists them so top-level help stays about the work. */
-export const INTERNALS_HELP = `toolroll internals — machine and agent commands
+Starting and running
+  toolroll up               app + builder for every saved project, for a server or a phone (--laptop: what bare \`toolroll\` runs)
+  toolroll open [--web]     open this computer's Toolroll again, signed in (bare \`toolroll\` does the same)
+  toolroll welcome          the three steps to a first result (--json: the model)
+  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)
+  toolroll background on|off|show
+                               keep this computer's Toolroll running when you log in
+  toolroll stop             stop this computer's Toolroll once its running work is saved
+  toolroll password set     add a password (typed twice, at your terminal)
+  toolroll link             put \`toolroll\` on your PATH
+  toolroll unlink           take it off again
+                               (link shows what it would do and changes nothing; add --yes to apply it,
+                               or --to <dir> to choose where. It never uses sudo, never leaves your
+                               home directory, and never touches a file it did not create.)
 
-  toolroll contract         the machine contract: envelope version + capabilities
-                                   (--commands dumps the declared command guide)
+Reports
+  toolroll scan [path...]   report what is in flight (\`toolroll scan --help\`: its options)
+  toolroll status           running, queued, ready results, release check and plan windows
+  toolroll pulls            report what is waiting on a person
+  toolroll graph            report which work graph is already here
+  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)
+
+Projects
+  toolroll repos            list connected repositories, and how to adjust
+  toolroll repos remove <path>
+                               take it out of the console; its tasks and results stay
+  toolroll repos add-from-github <owner/name> --root <dir>
+                               preview, then clone and connect (--yes)
+
+Chat and the lead
+  toolroll chat --as <you> --token <t>
+                               talk to your lead: one conversation across every
+                               project; it proposes, you confirm (--say "…" for one turn)
+  toolroll lead token       mint your lead agent's sign-in: its own work pings nobody
+  toolroll lead say "<text>"  (the lead) one short message in its person's chat
+  toolroll card <source>    the data chat shows as a card: tasks, results, flows, spend,
+                               projects, builders, mode, integrations, providers, findings, handover
+  toolroll flows list | show <id> | create | edit | trigger | script | card | archive
+                               set up and inspect flows (writes preview until --yes)
+
+People
+  toolroll approver add <name>
+                               add a person who can approve work
+
+Tasks (\`toolroll task --help\` lists every task command)
+  toolroll task approve <id>
+                               the yes — nothing builds without one
+  toolroll task accept <id> --finish
+                               accept the result you read (--despite "<why>": accept it with a reason, without finishing)
+  toolroll task send-back <id> --feedback "<what to change>"
+                               send the result back for changes
+  toolroll task retry <id>  build it again
+  toolroll task ready <id>  can I merge it? each check, and what clears a blocker
+  toolroll task wait <id> [--timeout <seconds>]
+                               wait for this attempt to finish or need a person
+  toolroll task scope <id> --goal <text>
+                               write a task's plan from the command line
+
+Agent guides
+  toolroll skills install --claude-code [--dir <path>]
+                               install this binary's guides for Claude Code (preview first)
+  toolroll skills install   teach a repo's agents this queue exists (preview first)
   toolroll skills list      the guides this exact binary serves
   toolroll skills get <name>  print one guide (version-matched, never stale)
+  toolroll contract         the machine contract: envelope version + capabilities
+                               (--commands dumps the declared command guide)
+
+Releasing Toolroll
+  toolroll release <branch> release Toolroll itself: checks, your approval, deploy, merge, tag, publish
+                               (rerun the same command to continue; --help)
+  toolroll release approve  a person's approval for a release
+  toolroll release --recover-deploy [--stage <dir>] [--yes]
+  toolroll release --release-gate <id> [--yes]
+                               the release tool's recovery steps (toolroll release <branch> runs them for you)
+
+Machine
   toolroll health           recent server latency, write waits and live streams
   toolroll ready            what could be started right now
   toolroll check-progress <run>  current or final approved check progress
-  toolroll task wait <id> [--timeout <seconds>]
-                               wait for this attempt to finish or need a person
-  toolroll task scope <id> --goal <text>
-                               write a task's plan from the command line
   toolroll claim <id> --runner <name>
   toolroll heartbeat <lease> / worker release <lease> / reap
   toolroll tick --runner <name> --token <t> --repo <path>
@@ -112,7 +127,4 @@ export const INTERNALS_HELP = `toolroll internals — machine and agent commands
                                open in VS Code on the device you browse from)
   toolroll watch / daemon install   run only the builder
   toolroll doctor           check that Toolroll's service holds no key a build could read
-  toolroll reconcile        recover what the last stretch left behind
-  toolroll release --recover-deploy [--stage <dir>] [--yes]
-  toolroll release --release-gate <id> [--yes]
-                               the release tool's recovery steps (toolroll release <branch> runs them for you)`;
+  toolroll reconcile        recover what the last stretch left behind`;

package/dist/cli-http.js

@@ -2,19 +2,15 @@ import { adapterPolicy } from "./server/route-policy.js";
 import { contractRow, fileArguments, STEP_UP_MESSAGE } from './remote-command.js';
 import { limitWords } from './request-budget.js';
 import { TOKEN_REPLACEMENT } from './password-bearer.js';
-/** Inlined file contents, summed as UTF-8 bytes. */
 export const CLI_FILES_BYTES = 256 * 1024;
-/** The whole JSON body: the files plus argv and JSON escaping headroom. */
 export const CLI_REQUEST_BYTES = 2 * CLI_FILES_BYTES;
 const ARGV_MAX = 256;
 const ARG_BYTES = 16 * 1024;
 const FILES_MAX = 16;
-/** What a missing or unusable token hears: how to get one, and how to save it. */
 const SIGN_IN = `Sign in with an API token: ${TOKEN_REPLACEMENT.charAt(0).toLowerCase()}${TOKEN_REPLACEMENT.slice(1)}, then toolroll connect <origin> --token-stdin.`;
 function send(response, status, value, headers = {}) {
     if (response.destroyed || response.writableEnded)
         return;
-    // A declared length: the client can tell a complete answer from a cut-off one.
     const text = JSON.stringify(value);
     response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': String(Buffer.byteLength(text)), 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', ...headers });
     response.end(text);
@@ -31,7 +27,6 @@ async function body(request) {
     }
     return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
 }
-/** Decode the request's shape and byte limits. The endpoint checks file references against its command policy. */
 export function cliRequest(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return { problem: 'Send {argv, files}.' };
@@ -59,7 +54,6 @@ export function cliRequest(value) {
     }
     return { argv: argv, files: kept };
 }
-/** The longest one request may hold the server: the client polls again for longer waits. */
 export const CLI_WAIT_SECONDS = 25;
 function longPollBounded(argv) {
     const words = argv.filter(one => !one.startsWith('-'));
@@ -68,7 +62,6 @@ function longPollBounded(argv) {
     const at = argv.indexOf('--timeout'), given = at < 0 ? NaN : Number(argv[at + 1]);
     return argv.filter(one => one === '--timeout').length === 1 && Number.isFinite(given) && given >= 0 && given <= CLI_WAIT_SECONDS;
 }
-/** Handles exactly `/api/cli`; false for any other path. */
 export async function handleCliHttp(request, response, options) {
     const url = new URL(request.url ?? '/', 'http://standing-orders.local');
     if (url.pathname !== '/api/cli')
@@ -78,7 +71,6 @@ export async function handleCliHttp(request, response, options) {
         return reject(400, 'credentials-in-url', 'Send the command in the request body; nothing travels in the URL.');
     if (request.method !== 'POST')
         return reject(405, 'method-not-allowed', 'Use POST.');
-    // A browser always names its page. The remote CLI never does, so a page can never drive this endpoint.
     if (request.headers.origin !== undefined)
         return reject(403, 'browser-origin', 'Remote commands come from the CLI, not a browser.');
     const names = request.rawHeaders.filter((_value, index) => index % 2 === 0).map(name => name.toLowerCase());
@@ -102,7 +94,6 @@ export async function handleCliHttp(request, response, options) {
     }
     if (!principal)
         return reject(401, 'unauthenticated', `This API token is not valid (expired, revoked or its person removed). ${TOKEN_REPLACEMENT}.`);
-    // Counted once here, however long the command then holds the request (a task wait is one request).
     const admitted = options.admit === undefined ? { ok: true } : options.admit(principal);
     if (!admitted.ok && admitted.status === 503)
         return reject(503, 'limits-unavailable', 'Request limits could not be checked; nothing ran. Try again shortly.');
@@ -147,7 +138,6 @@ export async function handleCliHttp(request, response, options) {
     }
     if (run === null)
         return reject(501, 'remote-unavailable', 'This server cannot run remote commands yet. Update it, or use --local.');
-    // Files stay in memory: runOperateAs reads them by their argument, so nothing is written to disk here.
     const out = [];
     let exitCode;
     try {