product-console-companion 0.3.0 → 0.5.0

package/README.md

@@ -9,12 +9,12 @@ your own machine, so:
   `MAX_FILE_CHARS`/`MAX_TREE_PATHS` don't apply here at all);
 - AI spend bills against your own key/subscription, not the workspace's shared/BYOK credential.
 
-Covers every AI call the hosted Console makes that reads your code — six task kinds as of this
-release (`verify_module` — "Check against code" on a module card; `generate_spec_batch` —
-writing full specs during setup; `propose_skeleton` and `propose_new_capabilities` — the two
-shallow whole-repo scans; `design_prompt` — the free-text export; `analyse_shipment` — the
-passive per-commit drift check behind the GitHub webhook and the "Check GitHub" button), two
-backends, chosen per connection at `connect` time:
+Runs every AI task the hosted Console dispatches. That includes the repo-aware setup and code
+checks as well as graph reasoning such as impact analysis, reviews, coupling maps, graph Q&A,
+edge descriptions, and exports. Graph-reasoning tasks receive all of their context from the
+Console and run connectionless with zero filesystem access. New server-side graph-reasoning task
+kinds use the same safe fallback without requiring another companion release. Two backends are
+available, chosen per connection at `connect` time:
 
 - **`api-key`** (default) — no CLI dependency. Calls Anthropic directly with your own API key
   (`api-key-caller.ts`), running its own two-pass file-select-then-judge, mirroring
@@ -63,6 +63,10 @@ npx product-console-companion connect --url https://console.fynchconsulting.com
 
 This runs your workspace's PRD-only setup AI calls when there is no repo yet. `run` then polls
 for workspace-level tasks in addition to any per-repo connections configured on this machine.
+Pass `--backend cli` to use your Claude subscription for these repo-less tasks too. This mode
+runs with zero filesystem access (stricter than the repo-scoped `cli` backend, because there is
+nothing to read). PDF-format PRDs cannot be delivered to the `cli` backend yet; use `api-key`,
+or re-upload the PRD as `.md`, `.txt`, or `.docx`.
 
 **`--backend api-key`** (default) needs an Anthropic API key (get one free at
 console.anthropic.com) — either pass it inline with `--api-key sk-ant-...` (saved to this

package/dist/api-key-caller.js

@@ -300,7 +300,16 @@ ${repoCtx.packageJson ?? '(none found)'}
     const text = message.content.find((b) => b.type === 'text');
     if (!text || text.type !== 'text')
         throw new Error('No result returned.');
-    return { result: JSON.parse(text.text), filesRead: [] };
+    return { result: spec.schema ? JSON.parse(text.text) : text.text, filesRead: [] };
+}
+/** Forward-compatible fallback for server-created graph/spec reasoning tasks. The server sends
+ *  the complete self-describing spec, so these calls never need or receive filesystem context. */
+export async function runGenericTask(client, task, repoPath) {
+    const spec = task.payload?.spec;
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+        throw new Error(`Cannot run task kind "${task.kind}": payload.spec is missing or not an object.`);
+    }
+    return runShallowRepoTask(client, spec, repoPath, true);
 }
 export async function runProposeSkeletonTask(client, task, repoPath) {
     const payload = task.payload;

package/dist/claude-cli-caller.js

@@ -11,6 +11,7 @@
  * during development, not guessed from --help text alone — see the Phase 2 PR description.
  */
 import spawn from 'cross-spawn';
+import { tmpdir } from 'node:os';
 import { createInterface } from 'node:readline';
 import { createSandbox } from './sandbox.js';
 import { appendDiffToVolatile, prepareShipmentAnalysis } from './shipment.js';
@@ -26,13 +27,18 @@ function normalizeToRepoRelative(filePath, root) {
     const r = root.replace(/\\/g, '/');
     return (p.startsWith(r) ? p.slice(r.length) : p).replace(/^\/+/, '');
 }
-/** The actual invocation — task-kind-agnostic. Runs `spec` against a disposable sandbox
- *  worktree of `repoPath`, returns whatever structured_output the model produced plus every
- *  file it actually read via the Read tool. Every exported per-kind function below is a thin
- *  wrapper over this: extract a ModelTaskSpec from that kind's own payload shape, call this,
- *  return what it returns. */
-async function runViaCli(spec, maxBudgetUsd, repoPath) {
-    const sandbox = await createSandbox(repoPath);
+/** The actual invocation — task-kind-agnostic. Repo-scoped calls run against a disposable
+ *  sandbox worktree of `repoPath`; connection-less calls grant no tools and need no sandbox.
+ *  Returns whatever structured_output the model produced plus every file it actually read via
+ *  the Read tool. Every exported per-kind function below is a thin wrapper over this. */
+async function runViaCli(spec, maxBudgetUsd, repoPath, connectionless = false) {
+    if (spec.stableDocumentBase64) {
+        throw new Error("This task includes a PDF PRD, which the cli backend can't read yet. Pair with " +
+            '--backend api-key instead, or re-upload the PRD as .md/.txt/.docx.');
+    }
+    const sandbox = connectionless
+        ? { path: tmpdir(), cleanup: async () => { } }
+        : await createSandbox(repoPath);
     try {
         const args = [
             '-p',
@@ -43,10 +49,7 @@ async function runViaCli(spec, maxBudgetUsd, repoPath) {
             '--verbose',
             ...(spec.schema ? ['--json-schema', JSON.stringify(spec.schema)] : []),
             '--restricted',
-            '--tools',
-            'Read,Grep,Glob',
-            '--add-dir',
-            sandbox.path,
+            ...(connectionless ? ['--tools', ''] : ['--tools', 'Read,Grep,Glob', '--add-dir', sandbox.path]),
             '--model',
             spec.model,
             '--effort',
@@ -66,6 +69,8 @@ async function runViaCli(spec, maxBudgetUsd, repoPath) {
         let stderrTail = '';
         let timedOut = false;
         const child = spawn('claude', args, { cwd: sandbox.path });
+        if (spec.stableText)
+            child.stdin.write(spec.stableText + '\n\n');
         child.stdin.write(spec.volatileText);
         child.stdin.end();
         // stdout/stderr are only null when stdio is explicitly configured away from 'pipe' — the
@@ -130,24 +135,31 @@ async function runViaCli(spec, maxBudgetUsd, repoPath) {
         await sandbox.cleanup();
     }
 }
+/** Forward-compatible fallback for server-created graph/spec reasoning tasks. The server sends
+ *  the complete self-describing spec, so these calls run connectionless with zero tools. */
+export async function runGenericTaskViaCli(task, repoPath) {
+    const spec = task.payload?.spec;
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+        throw new Error(`Cannot run task kind "${task.kind}": payload.spec is missing or not an object.`);
+    }
+    return runViaCli(spec, task.maxBudgetUsd, repoPath, true);
+}
 export async function runVerifyModuleTaskViaCli(task, repoPath) {
     const payload = task.payload;
     return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
 }
 /** moduleIds isn't needed here the way api-key-caller.ts's batch path needs it (to structure its
- *  own file-select pass) — the CLI does its own exploring in one shot off spec.volatileText
- *  alone, which already names every module in the batch. */
+ *  own file-select pass) — spec.volatileText already names every module in the batch. */
 export async function runGenerateSpecBatchTaskViaCli(task, repoPath) {
     const payload = task.payload;
-    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath, payload.connectionless);
 }
 /** propose_skeleton and propose_new_capabilities are "shallow whole-repo" tasks (see
- *  api-key-caller.ts's own comment on the pair) — for the CLI backend this needs no special
- *  handling at all: --add-dir plus Read/Grep/Glob already lets the model explore the repo
- *  itself, same as verify_module/generate_spec_batch, so these are exactly as thin as those. */
+ *  api-key-caller.ts's own comment on the pair). Repo-scoped calls let the model explore via
+ *  --add-dir plus Read/Grep/Glob; a connection-less skeleton call has no repo to explore. */
 export async function runProposeSkeletonTaskViaCli(task, repoPath) {
     const payload = task.payload;
-    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath, payload.connectionless);
 }
 export async function runProposeNewCapabilitiesTaskViaCli(task, repoPath) {
     const payload = task.payload;

package/dist/cli.js

@@ -5,8 +5,8 @@ import { resolve } from 'node:path';
 import { addConnection, configPath, enableWorkspacePolling, loadConfig } from './config.js';
 import { CompanionClient, CompanionHttpError } from './http-client.js';
 import { assertIsRepo, currentCommit } from './local-scan.js';
-import { runAnalyseShipmentTask, runDesignPromptTask, runGenerateSpecBatchTask, runProposeNewCapabilitiesTask, runProposeSkeletonTask, runVerifyModuleTask } from './api-key-caller.js';
-import { runAnalyseShipmentTaskViaCli, runDesignPromptTaskViaCli, runGenerateSpecBatchTaskViaCli, runProposeNewCapabilitiesTaskViaCli, runProposeSkeletonTaskViaCli, runVerifyModuleTaskViaCli } from './claude-cli-caller.js';
+import { runAnalyseShipmentTask, runDesignPromptTask, runGenerateSpecBatchTask, runGenericTask, runProposeNewCapabilitiesTask, runProposeSkeletonTask, runVerifyModuleTask } from './api-key-caller.js';
+import { runAnalyseShipmentTaskViaCli, runDesignPromptTaskViaCli, runGenerateSpecBatchTaskViaCli, runGenericTaskViaCli, runProposeNewCapabilitiesTaskViaCli, runProposeSkeletonTaskViaCli, runVerifyModuleTaskViaCli } from './claude-cli-caller.js';
 /** A flag with nothing after it (end of argv, or the next token is itself another "--flag") is
  *  treated as a bare boolean ("true") rather than swallowing the following flag as its value —
  *  needed for --no-run below. Every existing "--flag value" pair still parses exactly as before. */
@@ -42,6 +42,7 @@ async function cmdConnect(argv) {
     const token = f.token;
     const connectionId = f.connection;
     const apiKey = f['api-key'];
+    const backend = (f.backend || 'api-key');
     // Pairing on its own does nothing useful — see cmdRun below — so this defaults to starting
     // right away, which is what someone following the app's own copy-pasted command wants: one
     // paste, and it's working. --no-run is the escape hatch for pairing a second/third project
@@ -50,11 +51,25 @@ async function cmdConnect(argv) {
     if (!url || !token) {
         console.error('Usage: product-console-companion connect --url <your Console link> --token <publicId.secret> --connection <connectionId> ' +
             '[--path <folder — defaults to the folder you\'re in right now>] [--backend api-key|cli] [--api-key <your Anthropic key>] [--no-run]\n' +
-            '   or: product-console-companion connect --url <your Console link> --token <publicId.secret> [--api-key <your Anthropic key>] [--no-run]');
+            '   or: product-console-companion connect --url <your Console link> --token <publicId.secret> [--backend api-key|cli] [--api-key <your Anthropic key>] [--no-run]');
+        process.exitCode = 1;
+        return;
+    }
+    if (backend !== 'api-key' && backend !== 'cli') {
+        console.error(`--backend must be "api-key" or "cli", got "${backend}"`);
         process.exitCode = 1;
         return;
     }
     if (!connectionId) {
+        if (backend === 'cli') {
+            const version = await checkClaudeCliAvailable();
+            if (!version) {
+                console.error('This needs Claude Code installed and you logged into it first: npm install -g @anthropic-ai/claude-code, then run `claude` and follow the login prompt.');
+                process.exitCode = 1;
+                return;
+            }
+            console.log(`Found Claude Code: ${version}`);
+        }
         const client = new CompanionClient(url, token);
         try {
             await client.whoami();
@@ -65,7 +80,7 @@ async function cmdConnect(argv) {
             process.exitCode = 1;
             return;
         }
-        enableWorkspacePolling({ url, token, apiKey });
+        enableWorkspacePolling({ url, token, apiKey, backend });
         console.log(`Connected! This computer will now run AI calls for this workspace's setup (PRD-only) tasks. (Saved to ${configPath}.)`);
         if (!shouldRunAfter) {
             console.log('Run "product-console-companion run" whenever you\'re ready to start.');
@@ -78,12 +93,6 @@ async function cmdConnect(argv) {
     // --path is optional — defaults to wherever this command is actually run from, so "open a
     // terminal in your project's folder, paste this" just works without typing a path at all.
     const repoPath = resolve(f.path || '.');
-    const backend = (f.backend || 'api-key');
-    if (backend !== 'api-key' && backend !== 'cli') {
-        console.error(`--backend must be "api-key" or "cli", got "${backend}"`);
-        process.exitCode = 1;
-        return;
-    }
     try {
         await assertIsRepo(repoPath);
     }
@@ -127,35 +136,31 @@ const IDLE_POLL_MS = 5000;
 /** How often to extend a claimed task's lease while it's in flight — comfortably inside the
  *  server's ~2-minute lease window (server/store.ts's LOCAL_TASK_LEASE_MS). */
 const HEARTBEAT_MS = 30_000;
-/** The task-kind registry, companion-side — one entry per kind this companion knows how to run,
- *  each backed by both backends. Grows by one entry per phase, same as the server's own registry
- *  (server/companion.ts's TASK_RESULT_SCHEMAS) — the two lists should always name the same kinds. */
+/** The explicitly repo-aware task kinds, companion-side. Everything else falls through to a
+ *  connectionless runner: only our server creates tasks, their ModelTaskSpec is self-describing
+ *  (model, effort, maxTokens, system, stable/volatile text, optional schema), and graph reasoning
+ *  has nothing legitimate to read from disk. That also makes future server kinds work without a
+ *  companion release. */
 async function runTask(task, backend, anthropic, repoPath) {
-    const connectionless = task.payload.connectionless === true;
-    const effectiveBackend = connectionless ? 'api-key' : backend;
-    if (connectionless && !anthropic) {
-        throw new Error('This is a connection-less (PRD-only) task, which needs an Anthropic API key. Re-run ' +
-            '`connect` with --api-key <key>, or set ANTHROPIC_API_KEY.');
-    }
     if (task.kind === 'verify_module') {
-        return effectiveBackend === 'cli' ? runVerifyModuleTaskViaCli(task, repoPath) : runVerifyModuleTask(anthropic, task, repoPath); // anthropic is always set for backend 'api-key' — see cmdRun
+        return backend === 'cli' ? runVerifyModuleTaskViaCli(task, repoPath) : runVerifyModuleTask(anthropic, task, repoPath); // anthropic is always set for backend 'api-key' — see cmdRun
     }
     if (task.kind === 'generate_spec_batch') {
-        return effectiveBackend === 'cli' ? runGenerateSpecBatchTaskViaCli(task, repoPath) : runGenerateSpecBatchTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runGenerateSpecBatchTaskViaCli(task, repoPath) : runGenerateSpecBatchTask(anthropic, task, repoPath);
     }
     if (task.kind === 'propose_skeleton') {
-        return effectiveBackend === 'cli' ? runProposeSkeletonTaskViaCli(task, repoPath) : runProposeSkeletonTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runProposeSkeletonTaskViaCli(task, repoPath) : runProposeSkeletonTask(anthropic, task, repoPath);
     }
     if (task.kind === 'propose_new_capabilities') {
-        return effectiveBackend === 'cli' ? runProposeNewCapabilitiesTaskViaCli(task, repoPath) : runProposeNewCapabilitiesTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runProposeNewCapabilitiesTaskViaCli(task, repoPath) : runProposeNewCapabilitiesTask(anthropic, task, repoPath);
     }
     if (task.kind === 'design_prompt') {
-        return effectiveBackend === 'cli' ? runDesignPromptTaskViaCli(task, repoPath) : runDesignPromptTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runDesignPromptTaskViaCli(task, repoPath) : runDesignPromptTask(anthropic, task, repoPath);
     }
     if (task.kind === 'analyse_shipment') {
-        return effectiveBackend === 'cli' ? runAnalyseShipmentTaskViaCli(task, repoPath) : runAnalyseShipmentTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runAnalyseShipmentTaskViaCli(task, repoPath) : runAnalyseShipmentTask(anthropic, task, repoPath);
     }
-    throw new Error(`This companion doesn't know how to run task kind "${task.kind}" yet.`);
+    return backend === 'cli' ? runGenericTaskViaCli(task, repoPath) : runGenericTask(anthropic, task, repoPath);
 }
 async function runOneTask(anthropic, backend, client, repoPath, task) {
     console.log(`[${new Date().toISOString()}] claimed ${task.kind} task ${task.id} via ${backend} (budget $${task.maxBudgetUsd.toFixed(2)} — not yet enforced client-side, see README)`);
@@ -188,10 +193,11 @@ async function cmdRun() {
         process.exitCode = 1;
         return;
     }
-    // Repo backends are chosen per connection; workspace-level tasks always use api-key. Only
+    // Repo backends are chosen per connection; workspace-level tasks have their own choice. Only
     // require what's actually configured to run, not every prerequisite either backend could need.
-    const needsApiKey = config.pollWorkspaceTasks || config.connections.some((c) => c.backend !== 'cli');
-    const needsCli = config.connections.some((c) => c.backend === 'cli');
+    const workspaceBackend = config.workspaceBackend ?? 'api-key';
+    const needsApiKey = (config.pollWorkspaceTasks && workspaceBackend !== 'cli') || config.connections.some((c) => c.backend !== 'cli');
+    const needsCli = (config.pollWorkspaceTasks && workspaceBackend === 'cli') || config.connections.some((c) => c.backend === 'cli');
     // config.apiKey (set via `connect --api-key ...`) takes priority over the environment variable
     // — the easier path for someone who'd rather paste their key once into a command than learn
     // what an environment variable is and how to set one on their OS. Both are supported; neither
@@ -230,7 +236,7 @@ async function cmdRun() {
         console.log(`  - ${c.connectionId} → ${c.repoPath} @ ${sha.slice(0, 7)} (${c.backend})`);
     }
     if (config.pollWorkspaceTasks) {
-        console.log('  - workspace-level (connection-less / PRD-only) tasks');
+        console.log(`  - workspace-level (connection-less / PRD-only) tasks (${workspaceBackend})`);
     }
     console.log('Waiting for work — leave this running. Ctrl+C any time to stop.');
     let stopping = false;
@@ -278,7 +284,7 @@ async function cmdRun() {
             if (claim.task) {
                 claimedAny = true;
                 // Connection-less task kinds do not read a repo; cwd is a harmless placeholder.
-                await runOneTask(anthropic, 'api-key', client, process.cwd(), claim.task);
+                await runOneTask(anthropic, workspaceBackend, client, process.cwd(), claim.task);
             }
         }
         if (!claimedAny && !stopping)

package/dist/config.js

@@ -33,6 +33,7 @@ export function addConnection(args) {
         connections,
         apiKey: args.apiKey || existing?.apiKey,
         pollWorkspaceTasks: existing?.pollWorkspaceTasks,
+        workspaceBackend: existing?.workspaceBackend,
     };
     save(config);
     return config;
@@ -48,6 +49,7 @@ export function enableWorkspacePolling(args) {
         connections: existing?.connections ?? [],
         apiKey: args.apiKey || existing?.apiKey,
         pollWorkspaceTasks: true,
+        workspaceBackend: args.backend || existing?.workspaceBackend,
     };
     save(config);
     return config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "product-console-companion",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Local-first BYOS companion for the Fynch Product Console — reads code and runs AI calls from your own machine instead of the hosted server.",
   "type": "module",
   "license": "MIT",