agent-canvas 0.1.40 → 0.1.42

package/bin/lib/instructions/overview.md

@@ -4,16 +4,17 @@ Canvas opens a rich, annotatable document in the user's browser. You write JSX,
 
 Use it whenever structured visual communication beats inline chat: plans, reviews, decisions, explanations, discovery interviews.
 
-**Note**: Replace all `<session-id>` references below with your actual canvas session ID (provided in the skill header).
+**Note**: Replace all `<session-id>` references below with the stable canvas
+session ID resolved by the skill.
 
 ## Core Workflow
 
 ### 1. Write JSX
 
-Use the **Write** tool to create `.jsx` files in `$TMPDIR/agent-canvas/<session-id>/`:
+Use the **Write** tool to create `.jsx` files in `${TMPDIR:-/tmp}/agent-canvas/<session-id>/`:
 
 ```jsx
-// $TMPDIR/agent-canvas/<session-id>/plan.jsx
+// ${TMPDIR:-/tmp}/agent-canvas/<session-id>/plan.jsx
 
 <Section title="Authentication Redesign">
   A proposal to replace session-based auth with JWT tokens.
@@ -41,7 +42,7 @@ Components are auto-available — no imports needed. The file can be a JSX fragm
 Push the directory to open all canvases in the browser:
 
 ```bash
-bunx agent-canvas push $TMPDIR/agent-canvas/<session-id>/ --session <session-id> --label "Implementation Plan"
+bunx agent-canvas push ${TMPDIR:-/tmp}/agent-canvas/<session-id>/ --session <session-id> --label "Implementation Plan"
 ```
 
 All `*.jsx` files in the directory are pushed as a snapshot. Each file appears as a separate tab. **Always show the `browserUrl` from the output to the user.**
@@ -52,16 +53,32 @@ Options:
 
 ### 3. Watch for feedback
 
-Run the watch command **in the background** using the Bash tool's `run_in_background` parameter:
+Start watching immediately after every push:
 
 ```bash
-# Use Bash tool with run_in_background: true
 bunx agent-canvas watch --session <session-id>
 ```
 
-You will be **automatically notified** when the user submits feedback. Do NOT poll, sleep, or proactively check. Just stop and wait.
+How to run the watcher depends on the host:
 
-**Important**: The push → watch sequence is atomic. Never push without watching. After starting the background watch, do not continue with other work unless instructed.
+- **Codex**: Keep the watcher attached to the current agent turn. Run it without
+  detaching or backgrounding it. If the shell tool yields a process/session
+  handle, call `write_stdin` on that same handle until the command returns the
+  feedback. Do not end the agent turn while the watcher is still running.
+- **Claude Code**: Run the watcher in the background using the Bash tool's
+  `run_in_background` parameter. You will be **automatically notified** when the
+  user submits feedback. Do NOT poll, sleep, or proactively check. Just stop and
+  wait.
+- **Other hosts**: Keep the watcher in the foreground unless the host explicitly
+  guarantees that background-process completion wakes the agent.
+
+In Codex, a wait may yield before feedback arrives. Continue waiting on the same
+process handle; do not start another watcher. Keep user-facing progress updates
+brief and no more than 60 seconds apart while waiting.
+
+**Important**: The push → watch sequence is atomic. Never push without starting
+the host-specific watcher immediately afterward. Do not continue with unrelated
+work while waiting for feedback.
 
 ### 4. Iterate
 
@@ -82,7 +99,7 @@ Returns immediately — prints feedback if available, otherwise no output.
 Use different files for different phases or concerns:
 
 ```
-$TMPDIR/agent-canvas/<session-id>/
+${TMPDIR:-/tmp}/agent-canvas/<session-id>/
   discovery.jsx    # Discovery interview
   requirements.jsx # Requirements spec
   plan.jsx         # Implementation plan
@@ -92,7 +109,7 @@ Write new files as phases progress, then push the directory. Previous files rema
 
 ## File Location
 
-All canvas files go in `$TMPDIR/agent-canvas/<session-id>/`. This is a system temp directory — no `.gitignore` needed.
+All canvas files go in `${TMPDIR:-/tmp}/agent-canvas/<session-id>/`. This is a system temp directory — no `.gitignore` needed.
 
 ## Components
 
@@ -121,6 +138,7 @@ All components are globally available in canvas JSX — no imports needed. For i
 - **Choice** — single-select radio group. Props: `id`, `label`, `options`, `required`
 - **MultiChoice** — multi-select checkboxes. Props: `id`, `label`, `options`, `required`
 - **UserInput** — free text input. Props: `id`, `label`, `placeholder`, `required`
+- **SecretInput** — local in-memory secret handoff. Props: `id`, `label`, `env`, `placeholder`, `required`
 - **RangeInput** — numeric slider. Props: `id`, `label`, `min`, `max`, `minLabel`, `maxLabel`, `required`
 
 ### Advanced
@@ -146,6 +164,7 @@ User wants something built/changed?
 User wants to understand something? → EXPLAIN flow
 User wants review/audit? → REVIEW flow
 User wants to make a decision? → DECISION flow
+Agent needs the user to complete manual steps? → RUNBOOK flow
 ```
 
 **Adapt dynamically**: flows are guidelines, not rigid pipelines. Skip or combine phases when appropriate:
@@ -167,17 +186,18 @@ User wants to make a decision? → DECISION flow
 2. **Announce** briefly: "I'll start with discovery, then create a detailed plan."
 3. **Write canvas JSX** with the Write tool
 4. **Push + show browserUrl** to the user
-5. **IMMEDIATELY watch in background** — the push → watch sequence is atomic
+5. **IMMEDIATELY watch using the host-specific strategy above** — the push → watch sequence is atomic
 6. **Read feedback** — check for annotations, answers, context files
 7. **Edit and re-push + watch**, or advance to next phase
 8. **After implementation**, push a summary canvas and **watch for feedback** — the user may want to respond
 
 ## Important Rules
 
-- **Never `cd`** before running `bunx agent-canvas` commands. The daemon uses the current working directory to resolve project file paths (`<FilePreview>`, file browser). Always run commands from the project root. Since canvas files are in `$TMPDIR`, use absolute paths to reference them — e.g. `bunx agent-canvas push $TMPDIR/agent-canvas/<session-id>/`.
+- **Never `cd`** before running `bunx agent-canvas` commands. The daemon uses the current working directory to resolve project file paths (`<FilePreview>`, file browser). Always run commands from the project root. Since canvas files are in `${TMPDIR:-/tmp}`, use absolute paths to reference them — e.g. `bunx agent-canvas push ${TMPDIR:-/tmp}/agent-canvas/<session-id>/`.
 - **Write** canvas files using the Write tool. Never use bash heredocs.
 - **Edit** canvas files using the Edit tool. Never rewrite entire files.
 - Every `<Item>` and interactive component needs a unique `id`.
+- Use `<SecretInput>`, never `<UserInput>`, for credentials. Read `component-secretinput` and `flow-runbook` first.
 - `<FilePreview path="...">` paths are relative to project root.
 - Read any files the user added to context (listed under "Added context" in feedback).
 - Always push a summary canvas after implementation, even if brief.

package/daemon/client/AnnotationProvider.tsx

@@ -1,6 +1,7 @@
 import React, { useState, useCallback, useEffect, useRef, useMemo } from "react";
 import { AnnotationCtx } from "#canvas/runtime";
 import type { Annotation, AnnotationContext, PlanResponse, FeedbackEntry, AnnotationContextValue } from "#canvas/runtime";
+import { clearPersistedDraft } from "./annotationDraft";
 import { generateAnnotationId } from "./utils";
 
 // Re-export types for convenience
@@ -44,12 +45,6 @@ function savePersisted(sessionId: string, revision: number, state: PersistedStat
   } catch {}
 }
 
-function clearPersisted(sessionId: string, revision: number) {
-  try {
-    localStorage.removeItem(storageKey(sessionId, revision));
-  } catch {}
-}
-
 export function AnnotationProvider({ sessionId, revision, isReadOnly, remoteAnnotations, children }: AnnotationProviderProps) {
   const [localAnnotations, setAnnotations] = useState<Annotation[]>(() => {
     const saved = loadPersisted(sessionId, revision);
@@ -164,7 +159,7 @@ export function AnnotationProvider({ sessionId, revision, isReadOnly, remoteAnno
     setActiveAnnotationId(null);
     setResponses(new Map());
     setFeedbackEntries(new Map());
-    clearPersisted(sessionId, revision);
+    clearPersistedDraft(localStorage, sessionId, revision);
   }, [sessionId, revision]);
 
   return (

package/daemon/client/App.tsx

@@ -21,7 +21,7 @@ import { ShareDialog, ShareButton, type ShareEntry } from "./ShareDialog";
 import { ReviewerIdentityDialog } from "./ReviewerIdentityDialog";
 import type { Annotation } from "#canvas/runtime";
 import { MODE, fetchMeta, FS_AVAILABLE, WS_AVAILABLE, submitSharedFeedback, getReviewerIdentity, setReviewerIdentity } from "./clientApi";
-import { carryUnsubmittedDraft } from "./annotationDraft";
+import { carryUnsubmittedDraft, clearPersistedDraft } from "./annotationDraft";
 
 export type ActiveView = { type: "overview" } | { type: "canvas"; filename: string } | { type: "file"; path: string };
 
@@ -314,6 +314,9 @@ function App() {
       .then((data: any) => {
         if (data.currentRevision) {
           const nextRevisions: RevisionInfo[] = data.revisions || [];
+          for (const revision of nextRevisions) {
+            if (revision.hasFeedback) clearPersistedDraft(localStorage, sessionId, revision.revision);
+          }
           carryUnsubmittedDraft(localStorage, sessionId, data.currentRevision, nextRevisions);
           setCurrentRevision(data.currentRevision);
           setSelectedRevision(data.currentRevision);
@@ -407,7 +410,13 @@ function App() {
             }
           }
           if (data.type === "revision-updated") {
-            if (data.revisions) setRevisions(data.revisions);
+            if (Array.isArray(data.revisions)) {
+              const nextRevisions: RevisionInfo[] = data.revisions;
+              for (const revision of nextRevisions) {
+                if (revision.hasFeedback) clearPersistedDraft(localStorage, sessionId, revision.revision);
+              }
+              setRevisions(nextRevisions);
+            }
           }
           if (data.type === "watcher-status") {
             setAgentWatching(!!data.watching);
@@ -448,6 +457,7 @@ function App() {
         annotations: structuredAnnotations,
         generalNote: feedback,
       });
+      clearPersistedDraft(localStorage, sessionId, selectedRevision);
       setSharedFeedbackSubmitted(true);
       setToast({ kind: "success", message: "Feedback submitted. The canvas author will see it shortly." });
     } catch (e: any) {

package/daemon/client/annotationDraft.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { carryUnsubmittedDraft } from "./annotationDraft";
+import { carryUnsubmittedDraft, clearPersistedDraft } from "./annotationDraft";
 
 class MemoryStorage {
   private readonly values = new Map<string, string>();
@@ -11,12 +11,27 @@ class MemoryStorage {
   setItem(key: string, value: string): void {
     this.values.set(key, value);
   }
+
+  removeItem(key: string): void {
+    this.values.delete(key);
+  }
 }
 
 const sessionId = "session";
 const key = (revision: number) => `canvas:${sessionId}:rev:${revision}`;
 
 describe("carryUnsubmittedDraft", () => {
+  test("clears a submitted draft and its carry marker", () => {
+    const storage = new MemoryStorage();
+    storage.setItem(key(2), JSON.stringify({ generalNote: "Submitted" }));
+    storage.setItem(`${key(2)}:draft-handled`, "1");
+
+    clearPersistedDraft(storage, sessionId, 2);
+
+    expect(storage.getItem(key(2))).toBeNull();
+    expect(storage.getItem(`${key(2)}:draft-handled`)).toBeNull();
+  });
+
   test("carries the latest unsent draft into a new revision", () => {
     const storage = new MemoryStorage();
     storage.setItem(key(2), JSON.stringify({

package/daemon/client/annotationDraft.ts

@@ -8,6 +8,10 @@ interface AnnotationStorage {
   setItem(key: string, value: string): void;
 }
 
+interface RemovableAnnotationStorage {
+  removeItem(key: string): void;
+}
+
 function storageKey(sessionId: string, revision: number): string {
   return `canvas:${sessionId}:rev:${revision}`;
 }
@@ -16,6 +20,17 @@ function handledKey(sessionId: string, revision: number): string {
   return `${storageKey(sessionId, revision)}:draft-handled`;
 }
 
+export function clearPersistedDraft(
+  storage: RemovableAnnotationStorage,
+  sessionId: string,
+  revision: number,
+): void {
+  try {
+    storage.removeItem(storageKey(sessionId, revision));
+    storage.removeItem(handledKey(sessionId, revision));
+  } catch {}
+}
+
 function parseState(raw: string | null): object | null {
   if (!raw) return null;
   try {

package/daemon/client/clientApi.ts

@@ -118,6 +118,47 @@ export function uploadUrl(): string {
   return `/api/session/${MODE.sessionId}/upload`;
 }
 
+function localSecretUrl(fieldId: string, suffix: "status" | "value"): string {
+  if (MODE.isShared) throw new Error("Secret inputs are available only on the local canvas daemon");
+  return `/api/session/${encodeURIComponent(MODE.sessionId)}/secrets/${encodeURIComponent(fieldId)}/${suffix}`;
+}
+
+async function secretApiError(response: Response): Promise<Error> {
+  const raw: unknown = await response.json().catch(() => null);
+  if (typeof raw === "object" && raw !== null && "error" in raw && typeof raw.error === "string") {
+    return new Error(raw.error);
+  }
+  return new Error(`Secret API request failed with status ${response.status}`);
+}
+
+/** Return only readiness metadata. The secret value is never sent back to the browser. */
+export async function getLocalSecretStatus(fieldId: string): Promise<boolean> {
+  const response = await fetch(localSecretUrl(fieldId, "status"), { cache: "no-store" });
+  if (!response.ok) throw await secretApiError(response);
+  const raw: unknown = await response.json();
+  return typeof raw === "object" && raw !== null && "ready" in raw && raw.ready === true;
+}
+
+/** Deposit a secret into the daemon's in-memory vault. */
+export async function storeLocalSecret(fieldId: string, value: string): Promise<void> {
+  const response = await fetch(localSecretUrl(fieldId, "value"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    cache: "no-store",
+    body: JSON.stringify({ value }),
+  });
+  if (!response.ok) throw await secretApiError(response);
+}
+
+/** Remove a deposited secret without retrieving its value. */
+export async function clearLocalSecret(fieldId: string): Promise<void> {
+  const response = await fetch(localSecretUrl(fieldId, "value"), {
+    method: "DELETE",
+    cache: "no-store",
+  });
+  if (!response.ok) throw await secretApiError(response);
+}
+
 // --- Meta fetch (with optional decryption) ---------------------------------
 
 interface RawMetaResponse {

package/daemon/client/components/SecretInput.tsx

@@ -0,0 +1,156 @@
+import React, { useEffect, useState } from "react";
+import { useFeedback } from "#canvas/runtime";
+import { MODE, clearLocalSecret, getLocalSecretStatus, storeLocalSecret } from "../clientApi";
+
+const FIELD_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+interface SecretInputProps {
+  id: string;
+  label: string;
+  env: string;
+  placeholder?: string;
+  required?: boolean;
+}
+
+/** Local-only secret handoff that never enters annotation or feedback state. */
+export function SecretInput({ id, label, env, placeholder, required }: SecretInputProps) {
+  const [value, setValue] = useState("");
+  const [ready, setReady] = useState(false);
+  const [busy, setBusy] = useState(!MODE.isShared);
+  const [error, setError] = useState<string | null>(null);
+  const validFieldId = FIELD_ID_RE.test(id);
+  const validEnvName = ENV_NAME_RE.test(env);
+  const locallyAvailable = !MODE.isShared;
+
+  useEffect(() => {
+    if (!locallyAvailable || !validFieldId) {
+      setBusy(false);
+      return;
+    }
+
+    let active = true;
+    getLocalSecretStatus(id)
+      .then((isReady) => {
+        if (active) setReady(isReady);
+      })
+      .catch((cause: unknown) => {
+        if (active) setError(cause instanceof Error ? cause.message : "Could not read secret status");
+      })
+      .finally(() => {
+        if (active) setBusy(false);
+      });
+    return () => { active = false; };
+  }, [id, locallyAvailable, validFieldId]);
+
+  const feedback = ready
+    ? `**${label}**\nSecret is ready. Field: \`${id}\`. Environment variable: \`${env}\`.\n`
+    : "";
+  useFeedback(`secret:${id}`, feedback, {
+    label,
+    required: required && locallyAvailable,
+  });
+
+  const store = async () => {
+    if (!value || !validFieldId || !validEnvName) return;
+    setBusy(true);
+    setError(null);
+    try {
+      await storeLocalSecret(id, value);
+      setValue("");
+      setReady(true);
+    } catch (cause: unknown) {
+      setError(cause instanceof Error ? cause.message : "Could not store secret");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const clear = async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      await clearLocalSecret(id);
+      setReady(false);
+    } catch (cause: unknown) {
+      setError(cause instanceof Error ? cause.message : "Could not clear secret");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  if (!locallyAvailable) {
+    return (
+      <div data-md="secretinput" data-md-label={label} className="-mx-4 px-4 py-3 my-1 rounded-lg bg-accent-amber-muted">
+        <div className="text-[13px] font-body font-medium text-text-primary">{label}</div>
+        <p className="text-[12px] font-body text-text-secondary mt-1">
+          Secret input is unavailable in shared canvases. Open this runbook on the author's local canvas daemon.
+        </p>
+      </div>
+    );
+  }
+
+  const configurationError = !validFieldId
+    ? "Secret field IDs may contain letters, numbers, dots, underscores, and hyphens."
+    : !validEnvName
+      ? "Environment variable names must use letters, numbers, and underscores and may not start with a number."
+      : null;
+
+  return (
+    <div data-md="secretinput" data-md-label={label} className="-mx-4 px-4 py-3 my-1 rounded-lg transition-colors duration-150 hover:bg-bg-input">
+      <div className="flex items-baseline justify-between gap-3 mb-2">
+        <div className="flex items-baseline gap-2">
+          <span className="text-[13px] font-body font-medium text-text-primary">{label}</span>
+          {required && <span className="text-[10px] text-accent-red font-body">*</span>}
+        </div>
+        <span className={`text-[11px] font-body ${ready ? "text-accent-green" : "text-text-tertiary"}`}>
+          {busy ? "Working…" : ready ? "Ready in memory" : "Not stored"}
+        </span>
+      </div>
+
+      <div className="flex gap-2">
+        <input
+          type="password"
+          value={value}
+          onChange={(event) => setValue(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") {
+              event.preventDefault();
+              void store();
+            }
+          }}
+          placeholder={placeholder || "Paste secret value"}
+          autoComplete="off"
+          spellCheck={false}
+          disabled={busy || !!configurationError}
+          className="min-w-0 flex-1 bg-bg-input text-[13px] font-mono text-text-primary rounded-lg px-3 py-2 focus:outline-none border border-border-subtle focus:border-border-hover placeholder:text-text-tertiary disabled:opacity-50 transition-colors"
+        />
+        <button
+          type="button"
+          onClick={() => void store()}
+          disabled={busy || !value || !!configurationError}
+          className="px-3 py-2 rounded-lg bg-btn-primary text-btn-primary-text text-[12px] font-body font-medium disabled:opacity-40 disabled:cursor-default"
+        >
+          {ready ? "Replace" : "Store"}
+        </button>
+        {ready && (
+          <button
+            type="button"
+            onClick={() => void clear()}
+            disabled={busy}
+            className="px-3 py-2 rounded-lg border border-border-subtle text-text-secondary text-[12px] font-body font-medium hover:border-border-hover disabled:opacity-40"
+          >
+            Clear
+          </button>
+        )}
+      </div>
+
+      <p className="text-[11px] font-body text-text-tertiary mt-1.5">
+        Stored only in daemon memory. The agent receives field {id} for {env}, not the value.
+      </p>
+      {(configurationError || error) && (
+        <p className="text-[11px] text-accent-red font-body mt-1">{configurationError || error}</p>
+      )}
+    </div>
+  );
+}

package/daemon/client/components/index.ts

@@ -11,6 +11,7 @@ export { Mermaid } from "./Mermaid";
 export { Diff } from "./Diff";
 export { Choice, MultiChoice } from "./Choice";
 export { UserInput, RangeInput } from "./UserInput";
+export { SecretInput } from "./SecretInput";
 export { ImageView } from "./Image";
 export { Markdown } from "./Markdown";
 export { useFeedback } from "#canvas/runtime";