agent-canvas 0.1.40 → 0.1.42

package/README.md

@@ -16,6 +16,7 @@ When Claude needs to present a plan, review, explanation, or decision — instea
 - **Browse files** referenced in the canvas
 - **Review revisions** as Claude iterates
 - **Send structured feedback** back to Claude in one click
+- **Hand off secrets locally** without placing values in model context or feedback
 
 ## Install
 
@@ -54,6 +55,22 @@ Claude uses different canvas flows depending on the task:
 | **Explain** | "How does X work?" | Single canvas |
 | **Review** | Code/architecture review | Findings → Fix Plan → Summary |
 | **Decision** | Choosing between options | Single canvas with comparison |
+| **Runbook** | User must complete manual setup or provide a secret | Instructions → secure handoff → command → result |
+
+### Local secret handoff
+
+Runbooks can use `SecretInput` when a command needs a token that must stay out of feedback and model context. The browser stores the value only in the local daemon's memory. Feedback contains the field ID and environment variable name, not the value.
+
+The agent then runs the target command through the local wrapper:
+
+```bash
+bunx agent-canvas exec \
+  --session <session-id> \
+  --secret SERVICE_TOKEN=service-token \
+  -- service-cli deploy
+```
+
+Secret resolution requires a daemon capability available to the CLI but not to canvas JavaScript. A new canvas revision, daemon shutdown, or session cleanup clears the value. The target command must not print its environment or credentials.
 
 ## Theming
 
@@ -72,7 +89,7 @@ bun daemon/build.ts --watch    # watch mode
 
 # Test with demo canvas
 bun bin/agent-canvas.ts daemon start
-CANVAS_SESSION_ID=demo bun bin/agent-canvas.ts push example/plan.jsx --label "Demo"
+CANVAS_SESSION_ID=demo bun bin/agent-canvas.ts push example --label "Demo"
 # Open http://localhost:19400/s/demo
 ```
 

package/bin/agent-canvas.ts

@@ -6,6 +6,7 @@ import { handleWatch } from "./lib/commands/watch.ts";
 import { handleDaemon } from "./lib/commands/daemon.ts";
 import { handleInstall } from "./lib/commands/install.ts";
 import { handleInstructions } from "./lib/commands/instructions.ts";
+import { handleExec } from "./lib/commands/exec.ts";
 import { VERSION } from "./lib/config.ts";
 
 function printUsage() {
@@ -14,9 +15,11 @@ function printUsage() {
 Commands:
   agent-canvas install [local|global]  Install skill for Claude Code
   agent-canvas instructions [topic]    Show usage instructions (for AI agents)
-  agent-canvas push <file.jsx>         Push a canvas, open browser
+  agent-canvas push <directory>        Push canvases, open browser
   agent-canvas fetch [--session <id>]  Check for feedback (returns immediately)
   agent-canvas watch [--session <id>]  Wait for user feedback (blocks until submitted)
+  agent-canvas exec --secret ENV=id -- <command>
+                                      Run a command with an in-memory secret
   agent-canvas daemon status           Show daemon status
   agent-canvas daemon stop             Stop the daemon
   agent-canvas daemon start            Start the daemon
@@ -46,6 +49,7 @@ async function main() {
     case "push": return handlePush(rest);
     case "fetch": return handleFetch(rest);
     case "watch": return handleWatch(rest);
+    case "exec": return handleExec(rest);
     case "instructions": return handleInstructions(rest);
     case "install": return handleInstall(rest);
     case "daemon": return handleDaemon(rest);

package/bin/lib/commands/exec.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { parseSecretAssignments, spawnWithSecretEnvironment } from "./exec";
+
+describe("secret-aware exec", () => {
+  test("parses explicit environment mappings", () => {
+    expect(parseSecretAssignments(["SERVICE_TOKEN=service-token", "API_KEY=api.key"])).toEqual([
+      { envName: "SERVICE_TOKEN", fieldId: "service-token" },
+      { envName: "API_KEY", fieldId: "api.key" },
+    ]);
+  });
+
+  test("rejects invalid and duplicate environment names", () => {
+    expect(() => parseSecretAssignments(["bad-name=token"])).toThrow("Invalid environment variable name");
+    expect(() => parseSecretAssignments(["TOKEN=first", "TOKEN=second"])).toThrow("Duplicate environment variable mapping");
+  });
+
+  test("injects the secret into the child environment", async () => {
+    const assignments = parseSecretAssignments(["RUNBOOK_TEST_TOKEN=service-token"]);
+    const exitCode = await spawnWithSecretEnvironment(
+      [process.execPath, "-e", "process.exit(process.env.RUNBOOK_TEST_TOKEN === 'test-value' ? 0 : 1)"],
+      assignments,
+      new Map([["service-token", "test-value"]]),
+    );
+
+    expect(exitCode).toBe(0);
+  });
+});

package/bin/lib/commands/exec.ts

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { parseArgs } from "util";
+import { BASE_URL, CLI_AUTH_FILE } from "../config.ts";
+import { ensureDaemon } from "../daemon-lifecycle.ts";
+import { getSessionId } from "../helpers.ts";
+
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const FIELD_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export interface SecretAssignment {
+  envName: string;
+  fieldId: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function parseSecretAssignments(rawAssignments: string[]): SecretAssignment[] {
+  if (rawAssignments.length === 0) {
+    throw new Error("At least one --secret ENV_NAME=field-id mapping is required");
+  }
+
+  const assignments: SecretAssignment[] = [];
+  const environmentNames = new Set<string>();
+  for (const raw of rawAssignments) {
+    const separator = raw.indexOf("=");
+    const envName = separator === -1 ? "" : raw.slice(0, separator);
+    const fieldId = separator === -1 ? "" : raw.slice(separator + 1);
+    if (!ENV_NAME_RE.test(envName)) {
+      throw new Error(`Invalid environment variable name in --secret mapping: ${raw}`);
+    }
+    if (!FIELD_ID_RE.test(fieldId)) {
+      throw new Error(`Invalid secret field ID in --secret mapping: ${raw}`);
+    }
+    if (environmentNames.has(envName)) {
+      throw new Error(`Duplicate environment variable mapping: ${envName}`);
+    }
+    environmentNames.add(envName);
+    assignments.push({ envName, fieldId });
+  }
+  return assignments;
+}
+
+async function resolveSecretValues(sessionId: string, fieldIds: string[]): Promise<Map<string, string>> {
+  if (!existsSync(CLI_AUTH_FILE)) throw new Error("Canvas daemon CLI capability is unavailable");
+  const cliAuthToken = readFileSync(CLI_AUTH_FILE, "utf-8").trim();
+  const response = await fetch(`${BASE_URL}/api/session/${encodeURIComponent(sessionId)}/secrets/resolve`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Agent-Canvas-CLI-Token": cliAuthToken,
+    },
+    body: JSON.stringify({ fields: fieldIds }),
+  });
+  const raw: unknown = await response.json().catch(() => null);
+  if (!response.ok) {
+    const message = isRecord(raw) && typeof raw.error === "string"
+      ? raw.error
+      : `Secret API request failed with status ${response.status}`;
+    const missing = isRecord(raw) && Array.isArray(raw.missing)
+      ? raw.missing.filter((field): field is string => typeof field === "string")
+      : [];
+    throw new Error(missing.length > 0 ? `${message}: ${missing.join(", ")}` : message);
+  }
+  if (!isRecord(raw) || !Array.isArray(raw.values)) {
+    throw new Error("Secret API returned an invalid response");
+  }
+
+  const values = new Map<string, string>();
+  for (const entry of raw.values) {
+    if (!isRecord(entry) || typeof entry.id !== "string" || typeof entry.value !== "string") {
+      throw new Error("Secret API returned an invalid value entry");
+    }
+    values.set(entry.id, entry.value);
+  }
+  return values;
+}
+
+function executableExists(command: string): boolean {
+  if (command.includes("/")) return existsSync(resolve(command));
+  return Bun.spawnSync(["which", command], { stdout: "ignore", stderr: "ignore" }).exitCode === 0;
+}
+
+export async function spawnWithSecretEnvironment(
+  commandArgs: string[],
+  assignments: SecretAssignment[],
+  values: Map<string, string>,
+): Promise<number> {
+  const command = commandArgs[0];
+  if (!command) throw new Error("No command specified after --");
+  if (!executableExists(command)) throw new Error(`Executable not found: ${command}`);
+
+  const environment = { ...process.env };
+  for (const assignment of assignments) {
+    const value = values.get(assignment.fieldId);
+    if (value === undefined) throw new Error(`Secret is not ready: ${assignment.fieldId}`);
+    environment[assignment.envName] = value;
+  }
+
+  const child = Bun.spawn(commandArgs, {
+    env: environment,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  return child.exited;
+}
+
+export async function handleExec(args: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      session: { type: "string" },
+      secret: { type: "string", multiple: true },
+    },
+    allowPositionals: true,
+  });
+
+  const assignments = parseSecretAssignments(values.secret ?? []);
+  if (positionals.length === 0) throw new Error("No command specified. Put the command after --");
+
+  const sessionId = getSessionId(values.session);
+  await ensureDaemon();
+  const secretValues = await resolveSecretValues(sessionId, assignments.map((assignment) => assignment.fieldId));
+  const exitCode = await spawnWithSecretEnvironment(positionals, assignments, secretValues);
+  process.exit(exitCode);
+}

package/bin/lib/commands/watch.ts

@@ -19,5 +19,12 @@ export async function handleWatch(args: string[]) {
     process.exit(0);
   }
 
-  await waitForFeedback(sessionId);
+  try {
+    const submittedFeedback = await waitForFeedback(sessionId);
+    process.stdout.write(submittedFeedback);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
 }

package/bin/lib/config.ts

@@ -10,3 +10,4 @@ export const BASE_URL = `http://localhost:${DAEMON_PORT}`;
 export const WS_URL = `ws://localhost:${DAEMON_PORT}`;
 export const TIMEOUT_MS = parseInt(process.env.CANVAS_TIMEOUT || String(60 * 60 * 1000), 10);
 export const PID_FILE = join(TEMP_DIR, "daemon.pid");
+export const CLI_AUTH_FILE = join(TEMP_DIR, "daemon-auth-token");

package/bin/lib/daemon-lifecycle.ts

@@ -1,7 +1,7 @@
 import { spawn } from "child_process";
 import { openSync, closeSync, readFileSync, existsSync, mkdirSync, unlinkSync } from "fs";
 import { join } from "path";
-import { PACKAGE_ROOT, TEMP_DIR, BASE_URL, PID_FILE, VERSION } from "./config.ts";
+import { PACKAGE_ROOT, TEMP_DIR, BASE_URL, PID_FILE, CLI_AUTH_FILE, VERSION } from "./config.ts";
 
 export async function isDaemonRunning(): Promise<boolean> {
   try {
@@ -79,10 +79,12 @@ export function stopDaemon(): boolean {
       process.kill(pid, "SIGTERM");
       console.log("Daemon stopped.");
       try { unlinkSync(PID_FILE); } catch {}
+      try { unlinkSync(CLI_AUTH_FILE); } catch {}
       return true;
     } catch {
       console.log("Daemon was not running (stale PID file).");
       try { unlinkSync(PID_FILE); } catch {}
+      try { unlinkSync(CLI_AUTH_FILE); } catch {}
       return false;
     }
   } else {

package/bin/lib/helpers.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import { waitForFeedback } from "./helpers";
+
+class FakeSocket {
+  onmessage: ((event: MessageEvent) => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+  onclose: ((event: CloseEvent) => void) | null = null;
+
+  close(): void {}
+}
+
+describe("waitForFeedback", () => {
+  test("reconnects after an unexpected close", async () => {
+    const sockets: FakeSocket[] = [];
+    const result = waitForFeedback("session", {
+      createSocket: () => {
+        const socket = new FakeSocket();
+        sockets.push(socket);
+        queueMicrotask(() => {
+          if (sockets.length === 1) socket.onclose?.(new CloseEvent("close"));
+          else socket.onmessage?.(new MessageEvent("message", { data: JSON.stringify({ type: "submit", feedback: "Done" }) }));
+        });
+        return socket;
+      },
+      timeoutMs: 1_000,
+      reconnectAttempts: 1,
+      reconnectDelayMs: 0,
+    });
+
+    await expect(result).resolves.toBe("Done");
+    expect(sockets).toHaveLength(2);
+  });
+
+  test("rejects when the connection keeps closing", async () => {
+    const result = waitForFeedback("session", {
+      createSocket: () => {
+        const socket = new FakeSocket();
+        queueMicrotask(() => socket.onclose?.(new CloseEvent("close")));
+        return socket;
+      },
+      timeoutMs: 1_000,
+      reconnectAttempts: 2,
+      reconnectDelayMs: 0,
+    });
+
+    await expect(result).rejects.toThrow("WebSocket closed before feedback was submitted.");
+  });
+});

package/bin/lib/helpers.ts

@@ -33,39 +33,89 @@ export function openBrowser(url: string) {
   console.error(`Open this URL in your browser: ${url}`);
 }
 
-export async function waitForFeedback(sessionId: string): Promise<void> {
-  return new Promise((resolveP, rejectP) => {
-    const ws = new WebSocket(`${WS_URL}/ws/wait/${sessionId}`);
-    const timeout = setTimeout(() => {
+interface FeedbackSocket {
+  close(): void;
+  onmessage: ((event: MessageEvent) => void) | null;
+  onerror: ((event: Event) => void) | null;
+  onclose: ((event: CloseEvent) => void) | null;
+}
+
+interface FeedbackWaitOptions {
+  createSocket?: (url: string) => FeedbackSocket;
+  timeoutMs?: number;
+  reconnectAttempts?: number;
+  reconnectDelayMs?: number;
+}
+
+class FeedbackWaitError extends Error {
+  constructor(message: string, readonly retryable: boolean) {
+    super(message);
+  }
+}
+
+function waitForFeedbackConnection(
+  sessionId: string,
+  timeoutMs: number,
+  createSocket: (url: string) => FeedbackSocket,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const ws = createSocket(`${WS_URL}/ws/wait/${sessionId}`);
+    let settled = false;
+
+    const finish = (result: string | FeedbackWaitError) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
       ws.close();
-      console.error("Error: Timeout waiting for feedback.");
-      process.exit(1);
-    }, TIMEOUT_MS);
+      if (result instanceof FeedbackWaitError) reject(result);
+      else resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      finish(new FeedbackWaitError("Timeout waiting for feedback.", false));
+    }, timeoutMs);
 
     ws.onmessage = (event) => {
       try {
         const data = JSON.parse(typeof event.data === "string" ? event.data : "");
         if (data.type === "submit") {
-          clearTimeout(timeout);
-          process.stdout.write(data.feedback);
-          ws.close();
-          process.exit(0);
+          finish(data.feedback);
         }
       } catch {}
     };
 
     ws.onerror = () => {
-      clearTimeout(timeout);
-      console.error("Error: WebSocket connection failed.");
-      process.exit(1);
+      finish(new FeedbackWaitError("WebSocket connection failed.", true));
     };
 
     ws.onclose = () => {
-      clearTimeout(timeout);
+      finish(new FeedbackWaitError("WebSocket closed before feedback was submitted.", true));
     };
   });
 }
 
+export async function waitForFeedback(sessionId: string, options: FeedbackWaitOptions = {}): Promise<string> {
+  const createSocket = options.createSocket ?? ((url: string) => new WebSocket(url));
+  const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+  const reconnectAttempts = options.reconnectAttempts ?? 3;
+  const reconnectDelayMs = options.reconnectDelayMs ?? 1_000;
+  const deadline = Date.now() + timeoutMs;
+
+  for (let attempt = 0; ; attempt++) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) throw new FeedbackWaitError("Timeout waiting for feedback.", false);
+
+    try {
+      return await waitForFeedbackConnection(sessionId, remainingMs, createSocket);
+    } catch (error) {
+      if (!(error instanceof FeedbackWaitError) || !error.retryable || attempt >= reconnectAttempts) {
+        throw error;
+      }
+      await Bun.sleep(Math.min(reconnectDelayMs, Math.max(0, deadline - Date.now())));
+    }
+  }
+}
+
 export async function readLine(): Promise<string> {
   const buf: number[] = [];
   for await (const chunk of Bun.stdin.stream()) {

package/bin/lib/instructions/component-secretinput.md

@@ -0,0 +1,61 @@
+# Component: SecretInput
+
+Local-only secret handoff for runbooks. Use it when the user must create or retrieve a token, password, private key, or other value that a command needs but the agent must not receive in its context.
+
+The value stays outside normal canvas response state. It is not written to `localStorage`, annotations, feedback markdown, canvas revisions, or session metadata. The browser deposits it in the local daemon's in-memory vault. Feedback contains only the field ID and environment variable name.
+
+## Props
+
+- `id` (string, required) — unique field ID. Use letters, numbers, dots, underscores, and hyphens.
+- `label` (string, required) — user-facing description.
+- `env` (string, required) — environment variable used by the target command.
+- `placeholder` (string) — input hint. Never put an example real secret here.
+- `required` (boolean) — prevents feedback submission until the secret is stored.
+
+## Usage
+
+```jsx
+<Section title="Create an API token">
+  <Item id="open-settings" label="1. Open token settings">
+    Open the service's token settings. Create a token with the minimum scopes needed for this task.
+  </Item>
+
+  <SecretInput
+    id="service-token"
+    label="2. Paste the new token"
+    env="SERVICE_TOKEN"
+    placeholder="Paste token"
+    required
+  />
+</Section>
+```
+
+After feedback says the field is ready, run the target command through the wrapper:
+
+```bash
+bunx agent-canvas exec \
+  --session <session-id> \
+  --secret SERVICE_TOKEN=service-token \
+  -- service-cli deploy
+```
+
+Repeat `--secret` for multiple values:
+
+```bash
+bunx agent-canvas exec \
+  --session <session-id> \
+  --secret CLIENT_ID=client-id \
+  --secret CLIENT_SECRET=client-secret \
+  -- service-cli login
+```
+
+## Security contract
+
+- Use `SecretInput`, never `UserInput`, for secrets.
+- Secret inputs work only on the local `localhost` canvas. They are unavailable in shared canvases.
+- The CLI starts the command directly without a shell. The secret does not appear in the generated command or its arguments.
+- Secret resolution requires a daemon capability that is available to the CLI but not to canvas JavaScript.
+- The target program can still reveal its environment or print the secret. Use commands that do not echo credentials and do not enable verbose shell tracing.
+- A new canvas revision clears all secrets for the session. Run the required commands before pushing the next revision.
+- The same secret can be used by more than one wrapped command in the current revision. The user can replace or clear it in the browser.
+- Daemon shutdown, session deletion, and stale-session cleanup clear the in-memory value.

package/bin/lib/instructions/flow-feature.md

@@ -151,7 +151,7 @@ Goal: detailed implementation plan with file-level changes. The user approves be
 
 ## Phase 4: Summary (`summary.jsx`)
 
-Push AFTER implementation is complete. Always do this, even briefly. **After pushing the summary, start a background watch** — the user may want to provide feedback (follow-up requests, corrections, questions about what was done).
+Push AFTER implementation is complete. Always do this, even briefly. **After pushing the summary, start the host-specific watch described in the overview** — the user may want to provide feedback (follow-up requests, corrections, questions about what was done).
 
 ```jsx
 <Section title="Implementation Summary: [Feature Name]">

package/bin/lib/instructions/flow-plan.md

@@ -58,7 +58,7 @@ Goal: detailed implementation plan with file-level changes. The user approves be
 
 ## Phase 2: Summary (`summary.jsx`)
 
-Push AFTER implementation is complete. Always do this, even briefly. **After pushing the summary, start a background watch** — the user may want to provide feedback (follow-up requests, corrections, questions about what was done).
+Push AFTER implementation is complete. Always do this, even briefly. **After pushing the summary, start the host-specific watch described in the overview** — the user may want to provide feedback (follow-up requests, corrections, questions about what was done).
 
 ```jsx
 <Section title="Implementation Summary: [Feature Name]">

package/bin/lib/instructions/flow-runbook.md

@@ -0,0 +1,77 @@
+# RUNBOOK Flow
+
+**When**: The agent needs the user to complete manual browser or account steps before automated work can continue. Examples: create an API token, approve an OAuth application, configure a webhook, or retrieve a credential.
+
+**Phases**: Instructions → user action and secure handoff → agent command → result or next runbook revision
+
+Runbooks are local-only when they include secrets. Read `component-secretinput` before authoring one.
+
+## Phase 1: Instructions (`runbook.jsx`)
+
+Give the user ordered, concrete steps. Include the exact destination, required permissions, expected result, and a safe secret field. Do not ask the user to paste a secret into annotations, general notes, `UserInput`, chat, or a terminal command.
+
+```jsx
+<Section title="Connect the service">
+  <Callout type="info">
+    Complete these steps in order. The token value will stay outside agent feedback and model context.
+  </Callout>
+
+  <Item id="open-token-page" label="1. Open token settings" status="todo">
+    Open https://service.example/settings/tokens while signed in to the target account.
+  </Item>
+
+  <Item id="create-token" label="2. Create a scoped token" status="todo">
+    Name it for this task. Grant only read:projects and write:deployments. Set the shortest practical expiry.
+  </Item>
+
+  <SecretInput
+    id="service-token"
+    label="3. Paste the token"
+    env="SERVICE_TOKEN"
+    required
+  />
+
+  <Choice
+    id="target-confirmation"
+    label="Which environment did you configure?"
+    options={["Staging", "Production"]}
+    required
+  />
+</Section>
+```
+
+Push and immediately watch as usual. The user first stores the secret, then submits feedback. The watcher receives a safe marker such as:
+
+```text
+Service token
+Secret is ready. Field: service-token. Environment variable: SERVICE_TOKEN.
+```
+
+It never receives the value.
+
+The raw-value resolver requires a daemon capability stored outside the browser. Canvas JSX can deposit, replace, clear, and check readiness, but it cannot read the value back.
+
+## Phase 2: Run the command
+
+Use the exact session ID and field-to-environment mapping from the runbook:
+
+```bash
+bunx agent-canvas exec \
+  --session <session-id> \
+  --secret SERVICE_TOKEN=service-token \
+  -- service-cli configure --environment staging
+```
+
+Rules:
+
+1. Put the target command after `--`.
+2. Never interpolate the secret into the shell command, arguments, generated files, or logs.
+3. Do not use commands that print their complete environment or enable debug output that includes credentials.
+4. Preserve the wrapped command's output and exit code when reporting the result.
+5. Run every command that needs the secret before pushing another revision. A new revision clears the vault.
+
+## Phase 3: Continue or finish
+
+If another manual action is needed, update the existing runbook with the next steps, push a new revision, and watch again. The user must deposit any required secrets again because revision changes clear them.
+
+When the operation is complete, push the standard implementation summary. Report what succeeded, what remains, and whether the user should revoke the temporary token. Never include the token value.