agent-canvas 0.1.39 → 0.1.41

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/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
 
@@ -167,14 +184,14 @@ 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`.

package/daemon/client/App.tsx

@@ -21,6 +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";
 
 export type ActiveView = { type: "overview" } | { type: "canvas"; filename: string } | { type: "file"; path: string };
 
@@ -312,9 +313,11 @@ function App() {
     fetchMeta()
       .then((data: any) => {
         if (data.currentRevision) {
+          const nextRevisions: RevisionInfo[] = data.revisions || [];
+          carryUnsubmittedDraft(localStorage, sessionId, data.currentRevision, nextRevisions);
           setCurrentRevision(data.currentRevision);
           setSelectedRevision(data.currentRevision);
-          setRevisions(data.revisions || []);
+          setRevisions(nextRevisions);
         }
         if (data.canvasFiles) {
           const files = (data.canvasFiles as string[]).sort();
@@ -378,11 +381,12 @@ function App() {
         try {
           const data = JSON.parse(event.data);
           if (data.type === "plan-updated") {
+            const allRevisions: RevisionInfo[] = Array.isArray(data.revisions) ? data.revisions : [];
+            carryUnsubmittedDraft(localStorage, sessionId, data.currentRevision, allRevisions);
             setCurrentRevision(data.currentRevision);
             setSelectedRevision(data.currentRevision);
             setCompareRevision(null);
-            if (data.revisions) {
-              const allRevisions = data.revisions as RevisionInfo[];
+            if (allRevisions.length > 0) {
               setRevisions(allRevisions);
               const latest = allRevisions.find((r: RevisionInfo) => r.revision === data.currentRevision);
               if (latest?.canvasFiles) {

package/daemon/client/annotationDraft.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import { carryUnsubmittedDraft } from "./annotationDraft";
+
+class MemoryStorage {
+  private readonly values = new Map<string, string>();
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null;
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value);
+  }
+}
+
+const sessionId = "session";
+const key = (revision: number) => `canvas:${sessionId}:rev:${revision}`;
+
+describe("carryUnsubmittedDraft", () => {
+  test("carries the latest unsent draft into a new revision", () => {
+    const storage = new MemoryStorage();
+    storage.setItem(key(2), JSON.stringify({
+      annotations: [{ id: "annotation-1" }],
+      generalNote: "Review in progress",
+      responses: [["choice", { value: "keep" }]],
+      feedbackEntries: [["old", { markdown: "stale generated content" }]],
+    }));
+    storage.setItem(key(3), JSON.stringify({
+      annotations: [],
+      generalNote: "",
+      responses: [["new-choice", { value: null }]],
+      feedbackEntries: [["new", { markdown: "generated content" }]],
+    }));
+
+    const sourceRevision = carryUnsubmittedDraft(storage, sessionId, 3, [
+      { revision: 1, hasFeedback: true },
+      { revision: 2, hasFeedback: false },
+      { revision: 3, hasFeedback: false },
+    ]);
+
+    expect(sourceRevision).toBe(2);
+    expect(JSON.parse(storage.getItem(key(3)) ?? "")).toEqual({
+      annotations: [{ id: "annotation-1" }],
+      generalNote: "Review in progress",
+      responses: [["choice", { value: "keep" }]],
+      feedbackEntries: [],
+    });
+  });
+
+  test("does not cross a submitted revision", () => {
+    const storage = new MemoryStorage();
+    storage.setItem(key(1), JSON.stringify({
+      annotations: [{ id: "stale-annotation" }],
+      generalNote: "",
+      responses: [],
+    }));
+
+    expect(carryUnsubmittedDraft(storage, sessionId, 3, [
+      { revision: 1, hasFeedback: false },
+      { revision: 2, hasFeedback: true },
+      { revision: 3, hasFeedback: false },
+    ])).toBeNull();
+    expect(storage.getItem(key(3))).toBeNull();
+  });
+
+  test("does not overwrite meaningful target data", () => {
+    const storage = new MemoryStorage();
+    storage.setItem(key(2), JSON.stringify({
+      annotations: [{ id: "old-annotation" }],
+      generalNote: "",
+      responses: [],
+    }));
+    const current = JSON.stringify({
+      annotations: [{ id: "current-annotation" }],
+      generalNote: "",
+      responses: [],
+    });
+    storage.setItem(key(3), current);
+
+    expect(carryUnsubmittedDraft(storage, sessionId, 3, [
+      { revision: 2, hasFeedback: false },
+      { revision: 3, hasFeedback: false },
+    ])).toBeNull();
+    expect(storage.getItem(key(3))).toBe(current);
+  });
+
+  test("skips empty intermediate revision state", () => {
+    const storage = new MemoryStorage();
+    storage.setItem(key(2), JSON.stringify({
+      annotations: [],
+      generalNote: "Still drafting",
+      responses: [],
+    }));
+    storage.setItem(key(3), JSON.stringify({
+      annotations: [],
+      generalNote: "",
+      responses: [["choice", { value: [] }]],
+      feedbackEntries: [["generated", { markdown: "not user input" }]],
+    }));
+
+    expect(carryUnsubmittedDraft(storage, sessionId, 4, [
+      { revision: 1, hasFeedback: true },
+      { revision: 2, hasFeedback: false },
+      { revision: 3, hasFeedback: false },
+      { revision: 4, hasFeedback: false },
+    ])).toBe(2);
+  });
+
+  test("does not resurrect a carried draft after it is cleared", () => {
+    const storage = new MemoryStorage();
+    storage.setItem(key(2), JSON.stringify({
+      annotations: [{ id: "annotation-1" }],
+      generalNote: "",
+      responses: [],
+    }));
+    const revisions = [
+      { revision: 1, hasFeedback: true },
+      { revision: 2, hasFeedback: false },
+      { revision: 3, hasFeedback: false },
+    ];
+
+    expect(carryUnsubmittedDraft(storage, sessionId, 3, revisions)).toBe(2);
+    const cleared = JSON.stringify({ annotations: [], generalNote: "", responses: [] });
+    storage.setItem(key(3), cleared);
+
+    expect(carryUnsubmittedDraft(storage, sessionId, 3, revisions)).toBeNull();
+    expect(storage.getItem(key(3))).toBe(cleared);
+    expect(carryUnsubmittedDraft(storage, sessionId, 4, [
+      ...revisions,
+      { revision: 4, hasFeedback: false },
+    ])).toBeNull();
+    expect(storage.getItem(key(4))).toBeNull();
+  });
+});

package/daemon/client/annotationDraft.ts

@@ -0,0 +1,95 @@
+interface RevisionState {
+  revision: number;
+  hasFeedback: boolean;
+}
+
+interface AnnotationStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+function storageKey(sessionId: string, revision: number): string {
+  return `canvas:${sessionId}:rev:${revision}`;
+}
+
+function handledKey(sessionId: string, revision: number): string {
+  return `${storageKey(sessionId, revision)}:draft-handled`;
+}
+
+function parseState(raw: string | null): object | null {
+  if (!raw) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? value
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function hasResponseValue(entry: unknown): boolean {
+  if (!Array.isArray(entry) || entry.length < 2) return false;
+  const response: unknown = entry[1];
+  if (typeof response !== "object" || response === null || Array.isArray(response)) return false;
+
+  const note = Reflect.get(response, "note");
+  if (typeof note === "string" && note.trim().length > 0) return true;
+
+  const value = Reflect.get(response, "value");
+  if (typeof value === "string") return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return value !== null && value !== undefined;
+}
+
+function hasDraftContent(state: object | null): boolean {
+  if (!state) return false;
+  const annotations = Reflect.get(state, "annotations");
+  if (Array.isArray(annotations) && annotations.length > 0) return true;
+
+  const generalNote = Reflect.get(state, "generalNote");
+  if (typeof generalNote === "string" && generalNote.trim().length > 0) return true;
+
+  const responses = Reflect.get(state, "responses");
+  return Array.isArray(responses) && responses.some(hasResponseValue);
+}
+
+/** Carry an unsent draft forward without crossing submitted revisions. */
+export function carryUnsubmittedDraft(
+  storage: AnnotationStorage,
+  sessionId: string,
+  targetRevision: number,
+  revisions: RevisionState[],
+): number | null {
+  try {
+    const targetKey = storageKey(sessionId, targetRevision);
+    if (hasDraftContent(parseState(storage.getItem(targetKey)))) {
+      storage.setItem(handledKey(sessionId, targetRevision), "1");
+      return null;
+    }
+    if (storage.getItem(handledKey(sessionId, targetRevision)) !== null) return null;
+
+    const previous = revisions
+      .filter((revision) => revision.revision < targetRevision)
+      .sort((left, right) => right.revision - left.revision);
+
+    for (const revision of previous) {
+      if (revision.hasFeedback) return null;
+
+      const source = parseState(storage.getItem(storageKey(sessionId, revision.revision)));
+      if (!hasDraftContent(source)) {
+        if (storage.getItem(handledKey(sessionId, revision.revision)) !== null) return null;
+        continue;
+      }
+
+      storage.setItem(targetKey, JSON.stringify({
+        ...source,
+        feedbackEntries: [],
+      }));
+      storage.setItem(handledKey(sessionId, targetRevision), "1");
+      return revision.revision;
+    }
+  } catch {}
+
+  return null;
+}