mockpit 1.0.0 → 1.2.0

package/dist/server/handoff.js

@@ -0,0 +1,38 @@
+// Orphaned replies: a Send lands on the session that owns the mock, and when
+// that agent restarts into a new session (a new conversation, /clear, a crash)
+// nobody would ever read it. The rule below decides when a newer session may
+// take such a reply instead. Runtime-agnostic (no node imports).
+//
+// The danger is the other way round: two agents can work in one repo at once,
+// and an agent waiting on the user looks exactly like a dead one — both are
+// silent. So each clause narrows who counts as "the same agent, restarted":
+//
+// - Same project, same cwd, same agent name. A restart reopens the same harness
+//   in the same checkout; a different worktree or tool is a parallel worker.
+// - The owner was created first and has made no call since the taker appeared
+//   (agentActiveAt, which the user's own Sends don't bump). An owner that kept
+//   working after the taker started is running alongside it, not gone.
+// - The owner has no feedback long-poll open right now (`mockpit watch`).
+//
+// A reply also waits HANDOFF_GRACE_MS after the Send, so the owner — the agent
+// the user is most likely about to tell — gets first claim. The one exception:
+// a keyless owner (no harness conversation id) can never come back, so a reply
+// it got before the taker existed goes at once — the user answered, then
+// restarted. A keyed owner always gets the grace: its conversation may resume.
+export const HANDOFF_GRACE_MS = 2 * 60_000;
+export const HANDOFF_NOTE = "Sent to an earlier agent session in this project that has gone quiet; it is yours now. Read the mock before acting.";
+export const ownerActiveAt = (s) => s.agentActiveAt ?? s.lastActiveAt;
+export function supersedes(taker, owner, listening) {
+    return (owner.id !== taker.id &&
+        owner.project !== null &&
+        owner.project === taker.project &&
+        owner.cwd === taker.cwd &&
+        owner.agent === taker.agent &&
+        owner.createdAt < taker.createdAt &&
+        ownerActiveAt(owner) < taker.createdAt &&
+        !listening);
+}
+export function handoffReady(comment, owner, taker, now) {
+    return ((!owner.keyed && comment.createdAt < taker.createdAt) ||
+        now - Date.parse(comment.createdAt) >= HANDOFF_GRACE_MS);
+}

package/dist/server/index.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { createApp } from "./app.js";
 import { createNodeExecutor } from "./codeRunner.js";
 import { GUIDE_TOPICS } from "./designGuide.js";
+import { createFileLog } from "./logFile.js";
 import { SqlStore } from "./sqlStore.js";
 import { createSqliteStorage } from "./sqliteStorage.js";
 // Source layout puts this file at server/index.ts; the published package runs
@@ -33,6 +34,16 @@ const publicRead = pr === "session" || pr === "full" ? pr : undefined;
 const dbPath = process.env.MOCKPIT_DB ?? join(homedir(), ".mockpit", "mockpit.db");
 const store = new SqlStore(createSqliteStorage(dbPath));
 console.log(`mockpit store: SQLite at ${dbPath}`);
+// The event log is on by default, next to the database, so a session can be
+// diagnosed after the fact without having planned to (`scripts/inspect.ts`).
+// MOCKPIT_LOG names another file; "off" disables it. An in-memory database
+// gets none unless asked: it is a throwaway run.
+const logSetting = process.env.MOCKPIT_LOG;
+const logPath = logSetting === "off"
+    ? undefined
+    : logSetting || (dbPath === ":memory:" ? undefined : join(dirname(dbPath), "events.jsonl"));
+if (logPath)
+    console.log(`mockpit event log: ${logPath}`);
 const app = createApp({
     store,
     viewerHtml,
@@ -46,6 +57,7 @@ const app = createApp({
     upgradeCommand: "npm install -g mockpit",
     // `run` scripts execute in QuickJS inside a worker thread per run.
     executor: createNodeExecutor(),
+    log: logPath ? createFileLog(logPath) : undefined,
 });
 const port = Number(process.env.PORT ?? 8228);
 // MOCKPIT_HOST (or `serve --host`) restricts the listener to one address.

package/dist/server/knobs.js

@@ -320,11 +320,10 @@ export function checkKnobValues(raw, mock, posts, what) {
     return { ok: true, value: out };
 }
 // How many discrete choices a knob offers, or null when it is continuous. A knob
-// with only a handful is usually a decision dressed as a control (plan D12).
+// with only a handful is usually a decision dressed as a control (plan D12). A
+// toggle is null: on/off reads fine on one render.
 export function discreteChoices(config) {
     const knob = explicitKnob(config);
-    if (knob.type === "toggle")
-        return 2;
     if (knob.type === "select")
         return knob.options.length;
     if (knob.type === "image" && knob.options)

package/dist/server/logFile.d.ts

@@ -0,0 +1,2 @@
+import type { LogSink } from "./eventLog.ts";
+export declare function createFileLog(path: string, maxBytes?: number): LogSink;

package/dist/server/logFile.js

@@ -0,0 +1,27 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+// One file plus one rotated predecessor caps the log at twice this, so leaving
+// it on by default costs a bounded slice of disk.
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+// Appends JSONL to `path`, rolling it to `<path>.1` past `maxBytes`. Writes are
+// synchronous so lines never interleave and a crash loses nothing already
+// answered; the loop's call rate makes that cost negligible.
+export function createFileLog(path, maxBytes = DEFAULT_MAX_BYTES) {
+    mkdirSync(dirname(path), { recursive: true });
+    let size = 0;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        // No file yet.
+    }
+    return (entry) => {
+        const line = `${JSON.stringify(entry)}\n`;
+        if (size > 0 && size + line.length > maxBytes) {
+            renameSync(path, `${path}.1`);
+            size = 0;
+        }
+        appendFileSync(path, line);
+        size += Buffer.byteLength(line);
+    };
+}

package/dist/server/mcpHttp.d.ts

@@ -23,11 +23,11 @@ export interface McpFlows {
         },
         ctx: FlowContext
     ]>;
-    say: Flow<[ref: unknown, body: any]>;
+    say: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
     feedback: Flow<[query: {
         session?: unknown;
         project?: unknown;
-    }]>;
+    }, ctx: FlowContext]>;
 }
 export interface McpDeps {
     store: Store;

package/dist/server/mcpHttp.js

@@ -1,6 +1,6 @@
 import { decodeBase64 } from "./base64.js";
 import { isGuideTopic, unknownTopicMessage } from "./designGuide.js";
-import { HTTP_MCP_TOOLS, HTTP_RUN_TOOLS, MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, toolResult, } from "./mcpSpec.js";
+import { HTTP_MCP_TOOLS, HTTP_RUN_TOOLS, MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, toolResult, withFeedbackImages, } from "./mcpSpec.js";
 import { RUN_INSTRUCTIONS } from "./runApi.js";
 // A flow's error status becomes a tool error carrying the same JSON body the
 // REST tier returns, so the agent sees the hint (states, variants) either way.
@@ -24,6 +24,10 @@ export function registerMcp(app, deps) {
         const projects = await store.listProjects();
         return projects[0]?.name ?? "workspace";
     }
+    async function loadImage(ref) {
+        const asset = await store.getAsset(ref.id);
+        return asset ? { data: asset.data, mimeType: asset.contentType } : null;
+    }
     async function callTool(name, args, ctx) {
         switch (name) {
             case "publish":
@@ -39,9 +43,9 @@ export function registerMcp(app, deps) {
                     history: args.history === true,
                 }));
             case "feedback":
-                return unwrap(await flows.feedback({ session: args.session, project: args.project }));
+                return unwrap(await flows.feedback({ session: args.session, project: args.project }, ctx));
             case "say":
-                return unwrap(await flows.say(args.mock, args));
+                return unwrap(await flows.say(args.mock, args, ctx));
             case "export":
                 return unwrap(await flows.exportMock(args.mock, args, ctx));
             case "upload": {
@@ -124,9 +128,11 @@ export function registerMcp(app, deps) {
                 const name = msg.params?.name;
                 if (name === "run") {
                     const args = msg.params?.arguments ?? {};
-                    return rpc(msg.id, runToolResult(unwrap(await deps.run(args, ctx))));
+                    const envelope = unwrap(await deps.run(args, ctx));
+                    return rpc(msg.id, await withFeedbackImages(runToolResult(envelope), envelope, loadImage));
                 }
-                return rpc(msg.id, toolResult(name, await callTool(name, msg.params?.arguments ?? {}, ctx)));
+                const value = await callTool(name, msg.params?.arguments ?? {}, ctx);
+                return rpc(msg.id, await withFeedbackImages(toolResult(name, value), value, loadImage));
             }
             catch (err) {
                 return rpc(msg.id, {

package/dist/server/mcpSpec.d.ts

@@ -1,4 +1,5 @@
 import * as z from "zod/v4";
+import { type ImageRef } from "./feedbackBatch.ts";
 export declare const MCP_SERVER_INFO: {
     name: string;
     version: string;
@@ -180,6 +181,13 @@ export declare function toolResult(name: string, value: unknown): {
         text: string;
     }[];
 };
+export declare const MAX_RESULT_IMAGES = 8;
+export declare function withFeedbackImages<T extends {
+    content: unknown[];
+}>(result: T, value: unknown, load: (ref: ImageRef) => Promise<{
+    data: Uint8Array;
+    mimeType: string;
+} | null>): Promise<T>;
 export declare function runToolResult(envelope: unknown): {
     isError?: boolean | undefined;
     structuredContent?: Record<string, unknown> | undefined;

package/dist/server/mcpSpec.js

@@ -1,5 +1,7 @@
 import * as z from "zod/v4";
+import { encodeBase64 } from "./base64.js";
 import { GUIDE_TOPICS } from "./designGuide.js";
+import { feedbackImages } from "./feedbackBatch.js";
 import { KIT_IDS } from "./kits.js";
 import { RUN_DESCRIPTION } from "./runApi.js";
 import { SURFACE_KINDS } from "./types.js";
@@ -245,6 +247,7 @@ const feedbackSchema = o({
         mix: bag,
         tuned: bag,
         comments: z.array(o({ part: nullStr, text: str })),
+        reactions: strs.optional().describe('One-tap reactions, e.g. 👍 part "hero" (variant B)'),
     })
         .nullable()
         .describe("The user's Send; null if only comments"),
@@ -288,7 +291,13 @@ const OUTPUT_SCHEMAS = {
         session: nullStr,
     },
     publish: writeOutput,
-    ask: { asks: z.array(o({ id: str, text: str })), open: num, url: str, feedback: feedbackRide },
+    ask: {
+        asks: z.array(o({ id: str, text: str })),
+        open: num,
+        url: str,
+        nudges: strs.optional(),
+        feedback: feedbackRide,
+    },
     feedback: {
         feedback: z.array(feedbackSchema).describe("One batch per mock; empty when nothing is new"),
         pending: z.array(pendingSchema),
@@ -394,6 +403,22 @@ export function toolResult(name, value) {
         ...(structured ? { structuredContent: value } : {}),
     };
 }
+// The images a result's feedback carries, inlined as image content so the
+// model sees what the user attached instead of only its URL. Capped per result:
+// the rest stay reachable by URL in the JSON.
+export const MAX_RESULT_IMAGES = 8;
+export async function withFeedbackImages(result, value, load) {
+    const batches = value?.feedback;
+    if (!Array.isArray(batches))
+        return result;
+    const images = [];
+    for (const ref of feedbackImages(batches).slice(0, MAX_RESULT_IMAGES)) {
+        const bytes = await load(ref).catch(() => null);
+        if (bytes)
+            images.push({ type: "image", data: encodeBase64(bytes.data), mimeType: bytes.mimeType });
+    }
+    return images.length ? { ...result, content: [...result.content, ...images] } : result;
+}
 // A run that failed is still a full envelope (calls, feedback); isError tells
 // the client the script did not finish.
 export function runToolResult(envelope) {

package/dist/server/run.js

@@ -170,13 +170,13 @@ export function createRunFlow(deps) {
                 return [value, `${value.mock} ${value.asks.length} ask(s)`];
             },
             async feedback() {
-                const value = await take(flows.feedback(await mine({})));
+                const value = await take(flows.feedback(await mine({}), flowCtx));
                 const n = value.feedback.length;
                 return [value, n ? `${n} batch(es)` : "no feedback"];
             },
             async say([v, message]) {
                 const r = plain(v);
-                await take(flows.say(r.mock, { ...(await mine(r)), message }));
+                await take(flows.say(r.mock, { ...(await mine(r)), message }, flowCtx));
                 return [null, String(r.mock ?? "?")];
             },
             async upload([data, opts]) {

package/dist/server/runApi.d.ts

@@ -1,4 +1,4 @@
-export declare const RUN_API = "// The body of an async function, in plain JavaScript (no TypeScript syntax).\n// `await mockpit.*`, `return` a JSON value, print() adds an output line.\n// No network, timers, imports or process. Session, project and agent are fixed\n// for the run; pass the returned session to the next run.\ntype Ref = { mock: string; state?: string; variant?: string };\ntype Knobs = Record<string, unknown>; // path \u2192 [default,min,max,step] | boolean | {type:\"select\",options} | \"#hex\"\ntype Surface =\n  | { kind: \"html\"; html: string; kits?: string[] }\n  | { kind: \"markdown\"; markdown: string }\n  | { kind: \"diff\"; patch?: string; files?: { filename: string; before: string; after: string }[]; layout?: \"unified\" | \"split\" }\n  | { kind: \"image\"; assetId: string; alt?: string; caption?: string }\n  | { kind: \"terminal\"; text: string; cols?: number; title?: string }\n  | { kind: \"mermaid\"; mermaid: string }\n  | { kind: \"json\"; data: unknown; title?: string }\n  | { kind: \"code\"; code: string; language?: string; lineStart?: number };\ntype Ask = {\n  id?: string; text: string; scope?: \"mock\" | \"state\" | \"part\"; state?: string; part?: string; multi?: boolean;\n  options: { id?: string; label: string; variant?: string; set?: Knobs }[];\n};\ntype Written = {\n  post: { state: string | null; variant: string; version: number }; url: string;\n  parts: { state: string | null; parts: { name: string }[] }[];\n  partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };\n  nudges?: string[]; suggestedAsk?: Ask; // send it with ask when nudged\n};\ntype Feedback = {\n  mock: string | null;\n  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; mix: Knobs; tuned: Knobs; comments: { part: string | null; text: string }[] };\n  comments: { text: string; state: string | null; variant: string | null }[];\n  accepted: { state: string | null; variant: string }[]; archived: { state: string | null; variant: string }[];\n};\ntype Pending = { mock: string; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };\ndeclare const mockpit: {\n  guide(topic?: \"knobs\" | \"asks\" | \"surfaces\" | \"html\" | \"feedback\" | \"http\" | \"scripts\"): Promise<string>;\n  /** No mock: every mock plus pending. With one: its states, variants, asks, parts, knobs. */\n  read(mock?: string, opts?: { body?: boolean; history?: boolean }): Promise<unknown>;\n  /** Creates or versions (mock, state, variant). One of: html; surfaces, the full ordered list\n   * ({id} alone keeps that surface, a missing id is removed); parts {\"name\"|\"name#key\": outer html}. */\n  publish(v: Ref & { title?: string; kind?: \"component\" | \"page\"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number }): Promise<Written>;\n  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string }>;\n  /** Never waits: what the user sent since you last heard, and what they are doing now. */\n  feedback(): Promise<{ feedback: Feedback[]; pending: Pending[] }>;\n  say(v: Ref, message: string): Promise<void>;\n  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string }[]; reply: unknown }>;\n  /** data: base64 bytes. Use id as an image surface's assetId. */\n  upload(data: string, opts: { contentType: string; filename?: string; kind?: \"image\" | \"file\" }): Promise<{ id: string; url: string }>;\n};\ndeclare function print(...values: unknown[]): void;";
+export declare const RUN_API = "// The body of an async function, in plain JavaScript (no TypeScript syntax).\n// `await mockpit.*`, `return` a JSON value, print() adds an output line.\n// No network, timers, imports or process. Session, project and agent are fixed\n// for the run; pass the returned session to the next run.\ntype Ref = { mock: string; state?: string; variant?: string };\ntype Knobs = Record<string, unknown>; // path \u2192 [default,min,max,step] | boolean | {type:\"select\",options} | \"#hex\"\ntype Surface =\n  | { kind: \"html\"; html: string; kits?: string[] }\n  | { kind: \"markdown\"; markdown: string }\n  | { kind: \"diff\"; patch?: string; files?: { filename: string; before: string; after: string }[]; layout?: \"unified\" | \"split\" }\n  | { kind: \"image\"; assetId: string; alt?: string; caption?: string }\n  | { kind: \"terminal\"; text: string; cols?: number; title?: string }\n  | { kind: \"mermaid\"; mermaid: string }\n  | { kind: \"json\"; data: unknown; title?: string }\n  | { kind: \"code\"; code: string; language?: string; lineStart?: number };\ntype Ask = {\n  id?: string; text: string; scope?: \"mock\" | \"state\" | \"part\"; state?: string; part?: string; multi?: boolean;\n  options: { id?: string; label: string; variant?: string; set?: Knobs }[];\n};\ntype Written = {\n  post: { state: string | null; variant: string; version: number }; url: string;\n  parts: { state: string | null; parts: { name: string }[] }[];\n  partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };\n  nudges?: string[]; suggestedAsk?: Ask; // send it with ask when nudged\n};\ntype Feedback = {\n  mock: string | null;\n  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; mix: Knobs; tuned: Knobs; comments: { part: string | null; text: string }[] };\n  comments: { text: string; state: string | null; variant: string | null }[];\n  accepted: { state: string | null; variant: string }[]; archived: { state: string | null; variant: string }[];\n};\ntype Pending = { mock: string; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };\ndeclare const mockpit: {\n  guide(topic?: \"knobs\" | \"asks\" | \"surfaces\" | \"html\" | \"feedback\" | \"http\" | \"scripts\"): Promise<string>;\n  /** No mock: every mock plus pending. With one: its states, variants, asks, parts, knobs. */\n  read(mock?: string, opts?: { body?: boolean; history?: boolean }): Promise<unknown>;\n  /** Creates or versions (mock, state, variant). One of: html; surfaces, the full ordered list\n   * ({id} alone keeps that surface, a missing id is removed); parts {\"name\"|\"name#key\": outer html}. */\n  publish(v: Ref & { title?: string; kind?: \"component\" | \"page\"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number }): Promise<Written>;\n  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string; nudges?: string[] }>;\n  /** Never waits: what the user sent since you last heard, and what they are doing now. */\n  feedback(): Promise<{ feedback: Feedback[]; pending: Pending[] }>;\n  say(v: Ref, message: string): Promise<void>;\n  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string }[]; reply: unknown }>;\n  /** data: base64 bytes. Use id as an image surface's assetId. */\n  upload(data: string, opts: { contentType: string; filename?: string; kind?: \"image\" | \"file\" }): Promise<{ id: string; url: string }>;\n};\ndeclare function print(...values: unknown[]): void;";
 export declare const RUN_FUNCTIONS: readonly ["guide", "read", "publish", "ask", "feedback", "say", "export", "upload"];
 export type RunFunction = (typeof RUN_FUNCTIONS)[number];
 export declare const RUN_EXAMPLE = "const html = (tone) => `<section data-part=\"hero\" class=\"${tone}\"><h1>Writer</h1></section>`;\nawait mockpit.publish({ mock: \"writer\", variant: \"calm\", html: html(\"calm\") });\nawait mockpit.publish({ mock: \"writer\", variant: \"bold\", html: html(\"bold\") });\nconst { url } = await mockpit.ask(\"writer\", [{ id: \"look\", text: \"Which look?\",\n  options: [{ label: \"Calm\", variant: \"calm\" }, { label: \"Bold\", variant: \"bold\" }] }]);\n// Tell the user where to look and end the turn; a later run reads mockpit.feedback().\nreturn url;";

package/dist/server/runApi.js

@@ -43,7 +43,7 @@ declare const mockpit: {
   /** Creates or versions (mock, state, variant). One of: html; surfaces, the full ordered list
    * ({id} alone keeps that surface, a missing id is removed); parts {"name"|"name#key": outer html}. */
   publish(v: Ref & { title?: string; kind?: "component" | "page"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number }): Promise<Written>;
-  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string }>;
+  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string; nudges?: string[] }>;
   /** Never waits: what the user sent since you last heard, and what they are doing now. */
   feedback(): Promise<{ feedback: Feedback[]; pending: Pending[] }>;
   say(v: Ref, message: string): Promise<void>;

package/dist/server/sqlStore.d.ts

@@ -26,7 +26,7 @@ export declare class SqlStore implements Store {
     private rowToPost;
     private rowToAsset;
     private rowToComment;
-    listSessions(): Promise<Session[]>;
+    listSessions(project?: string): Promise<Session[]>;
     getSession(id: string): Promise<Session | null>;
     getSessionByKey(key: string): Promise<Session | null>;
     createSession(input: CreateSessionInput): Promise<Session>;
@@ -34,6 +34,8 @@ export declare class SqlStore implements Store {
     removeSession(id: string): Promise<boolean>;
     private touch;
     markAgentSeen(sessionId: string, seq: number): Promise<void>;
+    touchAgent(sessionId: string): Promise<void>;
+    handOff(sessionId: string, seen: Pick<Session, "agentSeq" | "agentActiveAt">, toSeq: number): Promise<boolean>;
     getSetting(key: string): Promise<string | null>;
     setSetting(key: string, value: string): Promise<void>;
     listProjects(): Promise<import("./types.ts").ProjectSummary[]>;

package/dist/server/sqlStore.js

@@ -1,4 +1,4 @@
-import { collectAssetIds, DEFAULT_PROJECT, DEFAULT_VARIANT, hashAssetId, HISTORY_LIMIT, htmlSurface, MAX_WORKSPACE_ASSET_BYTES, newId, normalizeSurfaceIds, projectFromCwd, reservedAgent, selectEvictions, slugify, stripNul, summarizeProjects, } from "./types.js";
+import { collectAssetIds, collectAttachedIds, DEFAULT_PROJECT, DEFAULT_VARIANT, hashAssetId, HISTORY_LIMIT, htmlSurface, MAX_WORKSPACE_ASSET_BYTES, newId, normalizeSurfaceIds, projectFromCwd, reservedAgent, selectEvictions, slugify, stripNul, summarizeProjects, } from "./types.js";
 function parseJson(raw, fallback) {
     if (typeof raw !== "string" || !raw)
         return fallback;
@@ -65,7 +65,7 @@ export class SqlStore {
       CREATE TABLE IF NOT EXISTS sessions (
         id TEXT PRIMARY KEY, agent TEXT NOT NULL, title TEXT, cwd TEXT,
         createdAt TEXT NOT NULL, lastActiveAt TEXT NOT NULL,
-        agentSeq INTEGER NOT NULL DEFAULT 0, project TEXT, key TEXT
+        agentSeq INTEGER NOT NULL DEFAULT 0, project TEXT, key TEXT, agentActiveAt TEXT
       );
       CREATE TABLE IF NOT EXISTS mocks (
         id TEXT PRIMARY KEY, project TEXT NOT NULL, slug TEXT NOT NULL, title TEXT NOT NULL,
@@ -100,6 +100,7 @@ export class SqlStore {
             agentSeq: "INTEGER NOT NULL DEFAULT 0",
             project: "TEXT",
             key: "TEXT",
+            agentActiveAt: "TEXT",
         });
         if (legacy)
             this.migrateLegacy();
@@ -381,6 +382,8 @@ export class SqlStore {
             lastActiveAt: r.lastActiveAt,
             agentSeq: r.agentSeq ?? 0,
             project: r.project ?? null,
+            agentActiveAt: r.agentActiveAt ?? null,
+            keyed: r.key != null,
         };
     }
     rowToMock(r) {
@@ -458,11 +461,13 @@ export class SqlStore {
         };
     }
     // --- sessions ---
-    async listSessions() {
-        return this.sql
-            .exec("SELECT * FROM sessions ORDER BY lastActiveAt DESC")
-            .toArray()
-            .map((r) => this.rowToSession(r));
+    async listSessions(project) {
+        const rows = project === undefined
+            ? this.sql.exec("SELECT * FROM sessions ORDER BY lastActiveAt DESC").toArray()
+            : this.sql
+                .exec("SELECT * FROM sessions WHERE project = ? ORDER BY lastActiveAt DESC", project)
+                .toArray();
+        return rows.map((r) => this.rowToSession(r));
     }
     async getSession(id) {
         const rows = this.sql.exec("SELECT * FROM sessions WHERE id = ?", id).toArray();
@@ -485,8 +490,10 @@ export class SqlStore {
             lastActiveAt: now,
             agentSeq: 0,
             project: stripNul(input.project)?.trim() || projectFromCwd(stripNul(input.cwd ?? null)) || null,
+            agentActiveAt: now,
+            keyed: !!stripNul(input.key)?.trim(),
         };
-        this.sql.exec("INSERT INTO sessions (id, agent, title, cwd, createdAt, lastActiveAt, agentSeq, project, key) VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?)", session.id, session.agent, session.title, session.cwd, session.createdAt, session.lastActiveAt, session.project, stripNul(input.key)?.trim() || null);
+        this.sql.exec("INSERT INTO sessions (id, agent, title, cwd, createdAt, lastActiveAt, agentSeq, project, key, agentActiveAt) VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?)", session.id, session.agent, session.title, session.cwd, session.createdAt, session.lastActiveAt, session.project, stripNul(input.key)?.trim() || null, session.agentActiveAt);
         return session;
     }
     async renameSession(id, title) {
@@ -528,6 +535,14 @@ export class SqlStore {
     async markAgentSeen(sessionId, seq) {
         this.sql.exec("UPDATE sessions SET agentSeq = ? WHERE id = ? AND agentSeq < ?", seq, sessionId, seq);
     }
+    async touchAgent(sessionId) {
+        this.sql.exec("UPDATE sessions SET agentActiveAt = ? WHERE id = ?", new Date().toISOString(), sessionId);
+    }
+    async handOff(sessionId, seen, toSeq) {
+        return (this.sql
+            .exec("UPDATE sessions SET agentSeq = ? WHERE id = ? AND agentSeq = ? AND agentActiveAt IS ? AND agentSeq < ? RETURNING id", toSeq, sessionId, seen.agentSeq, seen.agentActiveAt, toSeq)
+            .toArray().length > 0);
+    }
     // --- settings ---
     async getSetting(key) {
         return this.settingSync(key);
@@ -593,6 +608,8 @@ export class SqlStore {
             updatedAt: new Date().toISOString(),
         };
         this.sql.exec("UPDATE mocks SET title = ?, kind = ?, states = ?, asks = ?, knobs = ?, sessionId = ?, updatedAt = ? WHERE id = ?", next.title, next.kind, JSON.stringify(next.states), JSON.stringify(next.asks), JSON.stringify(next.knobs), next.sessionId, next.updatedAt, id);
+        if (patch.asks !== undefined)
+            this.invalidateAssetRefs();
         return next;
     }
     async removeMock(id) {
@@ -612,6 +629,7 @@ export class SqlStore {
         if (!mock)
             return null;
         this.sql.exec("UPDATE mocks SET draft = ? WHERE id = ?", draft ? JSON.stringify(draft) : null, mockId);
+        this.invalidateAssetRefs();
         return { ...mock, draft };
     }
     touchMock(mockId, at) {
@@ -826,6 +844,8 @@ export class SqlStore {
             return null;
         const comment = this.rowToComment(rows[0]);
         this.sql.exec("DELETE FROM comments WHERE id = ?", id);
+        if (comment.kind === "reply")
+            this.invalidateAssetRefs();
         this.touch(comment.sessionId);
         return comment;
     }
@@ -851,6 +871,7 @@ export class SqlStore {
             for (const id of input.archive) {
                 this.sql.exec("UPDATE posts SET status = 'archived' WHERE id = ? AND mockId = ?", id, input.mockId);
             }
+            this.invalidateAssetRefs();
             return comment;
         });
     }
@@ -865,6 +886,17 @@ export class SqlStore {
         for (const r of this.sql.exec("SELECT surfaces FROM post_versions").toArray()) {
             collectAssetIds(parseJson(r.surfaces, []), out);
         }
+        // The user's attachments: in a draft, in a sent reply, on an answered ask.
+        for (const r of this.sql.exec("SELECT asks, draft FROM mocks").toArray()) {
+            collectAttachedIds(parseJson(r.draft, null), out);
+            for (const ask of parseJson(r.asks, []))
+                collectAttachedIds(ask, out);
+        }
+        for (const r of this.sql
+            .exec("SELECT payload FROM comments WHERE kind = 'reply' AND payload IS NOT NULL")
+            .toArray()) {
+            collectAttachedIds(parseJson(r.payload, null), out);
+        }
         // An installed icon set is referenced by its project's design, not by a
         // surface; evicting it would blank that project's icons.
         for (const r of this.sql

package/dist/server/types.d.ts

@@ -8,6 +8,8 @@ export interface Session {
     lastActiveAt: string;
     agentSeq: number;
     project: string | null;
+    agentActiveAt: string | null;
+    keyed: boolean;
 }
 export declare const SURFACE_KINDS: readonly ["html", "diff", "image", "markdown", "terminal", "mermaid", "json", "code"];
 export type SurfaceKind = (typeof SURFACE_KINDS)[number];
@@ -214,6 +216,8 @@ export interface Ask {
     answer?: AskAnswer;
     other?: string;
     note?: string;
+    otherImages?: string[];
+    noteImages?: string[];
     at: string;
 }
 export declare const OTHER_ID = "other";
@@ -222,12 +226,17 @@ export interface PartCommentAnchor {
     quote?: string;
     selector?: string;
     box?: number[];
+    width?: number;
 }
+export declare const REACTIONS: readonly ["up", "down", "more"];
+export type Reaction = (typeof REACTIONS)[number];
 export interface PartComment {
     part: string | null;
     state: string | null;
     text: string;
     anchor?: PartCommentAnchor;
+    reaction?: Reaction;
+    variant?: string;
 }
 export interface ReplyDecision {
     kind: "accept" | "revise" | "drop";
@@ -242,6 +251,8 @@ export interface Draft {
     comments: PartComment[];
     others?: Record<string, string>;
     notes?: Record<string, string>;
+    otherImages?: Record<string, string[]>;
+    noteImages?: Record<string, string[]>;
     updatedAt: string;
 }
 export interface Reply {
@@ -253,6 +264,8 @@ export interface Reply {
     comments: PartComment[];
     others?: Record<string, string>;
     notes?: Record<string, string>;
+    otherImages?: Record<string, string[]>;
+    noteImages?: Record<string, string[]>;
     text?: string;
     decision?: ReplyDecision;
 }
@@ -523,13 +536,15 @@ export interface PostQuery {
     sessionId?: string;
 }
 export interface Store {
-    listSessions(): Promise<Session[]>;
+    listSessions(project?: string): Promise<Session[]>;
     getSession(id: string): Promise<Session | null>;
     getSessionByKey(key: string): Promise<Session | null>;
     createSession(input: CreateSessionInput): Promise<Session>;
     renameSession(id: string, title: string): Promise<Session | null>;
     removeSession(id: string): Promise<boolean>;
     markAgentSeen(sessionId: string, seq: number): Promise<void>;
+    touchAgent(sessionId: string): Promise<void>;
+    handOff(sessionId: string, seen: Pick<Session, "agentSeq" | "agentActiveAt">, toSeq: number): Promise<boolean>;
     getSetting(key: string): Promise<string | null>;
     setSetting(key: string, value: string): Promise<void>;
     listProjects(): Promise<ProjectSummary[]>;
@@ -572,6 +587,8 @@ export declare const HISTORY_LIMIT = 20;
 export declare function reservedAgent(name: string): string;
 export declare function stripNul<T extends string | null | undefined>(s: T): T;
 export declare const MAX_ASSET_BYTES: number;
+export declare const ATTACHABLE_IMAGE_TYPES: ReadonlySet<string>;
+export declare const MAX_ASK_IMAGES = 6;
 export declare const MAX_WORKSPACE_ASSET_BYTES: number;
 export declare const newId: () => string;
 export declare function hashAssetId(data: Uint8Array): Promise<string>;
@@ -583,13 +600,19 @@ export declare function projectFromCwd(cwd: string | null | undefined): string |
 export declare const htmlSurface: (html: string, kits?: unknown) => HtmlSurface;
 export declare const askAnswered: (a: Pick<Ask, "answer" | "other" | "note">) => boolean;
 export declare const openAsks: (mock: Pick<Mock, "asks">) => Ask[];
-export declare function builtinAskCount(mock: Pick<Mock, "asks" | "states">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[], mockId: string): number;
+export declare function builtinAskIds(mock: Pick<Mock, "asks" | "states">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[], mockId: string): string[];
+export declare const builtinAskCount: (mock: Pick<Mock, "asks" | "states">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[], mockId: string) => number;
 export declare const openCount: (mock: Pick<Mock, "id" | "asks" | "states">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[]) => number;
+export declare function draftedCount(mock: Pick<Mock, "id" | "asks" | "states" | "draft">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[]): number | null;
 export declare const BUILTIN_ASK_ID = "variant";
 export declare function builtinAsk(mock: Pick<Mock, "states">, posts: Pick<Post, "state" | "variant">[], id: string): Ask | undefined;
 export declare function summarizeProjects(mocks: Mock[], sessions: Session[], posts?: Post[]): ProjectSummary[];
 export declare function surfacesByteLength(surfaces: Surface[]): number;
 export declare function collectAssetIds(surfaces: Surface[], out: Set<string>): void;
+export declare function collectAttachedIds(holder: {
+    otherImages?: unknown;
+    noteImages?: unknown;
+} | null | undefined, out: Set<string>): void;
 export interface EvictionCandidate {
     id: string;
     byteLength: number;

package/dist/server/types.js

@@ -54,6 +54,10 @@ export function isSandboxedSurfaceKind(kind) {
 // The viewer's write-in option on every ask. Reserved, so a delivered
 // `{id: "other", other: true}` choice never shadows an option the agent declared.
 export const OTHER_ID = "other";
+// A one-tap verdict on a part (or, with part null, on the variant itself),
+// for a reviewer on a phone who would rather not type: like, dislike, or
+// "more like this". Rides as a part comment, so it travels in the one reply.
+export const REACTIONS = ["up", "down", "more"];
 export const HISTORY_LIMIT = 20;
 // "user" is the reserved trust label for genuine human comments. A session
 // agent with that name could otherwise have its programmatic comments delivered
@@ -73,6 +77,15 @@ export function stripNul(s) {
 // budget the store evicts down to. One Durable Object holds the whole workspace, so
 // the budget sits well under its ~10 GB SQLite ceiling.
 export const MAX_ASSET_BYTES = 5 * 1024 * 1024;
+// What the user may attach to a write-in or a note: raster formats a model can
+// read. SVG is active content, so it is never attachable.
+export const ATTACHABLE_IMAGE_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+]);
+export const MAX_ASK_IMAGES = 6;
 export const MAX_WORKSPACE_ASSET_BYTES = 2 * 1024 * 1024 * 1024;
 // Short, unguessable id: 8 random bytes (64 bits) as 11 url-safe base64 chars.
 // These double as bearer capabilities: in publicRead mode `/s/:id` and
@@ -145,7 +158,7 @@ export const openAsks = (mock) => mock.asks.filter((a) => !askAnswered(a));
 // rule as viewer/src/logic.ts builtinAsks, so Home, `read` and `pending` count
 // the question the user actually sees. Answering it archives the losers, which
 // is what makes it stop counting.
-export function builtinAskCount(mock, posts, mockId) {
+export function builtinAskIds(mock, posts, mockId) {
     const live = (state) => posts
         .filter((p) => p.mock === mockId && p.state === state && p.status !== "archived")
         .map((p) => p.variant);
@@ -159,14 +172,30 @@ export function builtinAskCount(mock, posts, mockId) {
     const states = mock.states.length ? mock.states : [null];
     const needing = states.filter(needs);
     if (!needing.length)
-        return 0;
+        return [];
     const key = (state) => [...live(state)].sort().join("\n");
     const first = key(needing[0]);
     return needing.length === states.length && states.every((st) => key(st) === first)
-        ? 1
-        : needing.length;
+        ? [BUILTIN_ASK_ID]
+        : needing.map((st) => (st === null ? BUILTIN_ASK_ID : `${BUILTIN_ASK_ID}:${st}`));
 }
+export const builtinAskCount = (mock, posts, mockId) => builtinAskIds(mock, posts, mockId).length;
 export const openCount = (mock, posts) => openAsks(mock).length + builtinAskCount(mock, posts, mock.id);
+// How many of the open asks the user's unsent draft already speaks for (a
+// pick, a write-in or a note), so Home can show a started mock as "draft 2/4";
+// null when there is no draft. A count only: the draft's content stays private.
+export function draftedCount(mock, posts) {
+    const d = mock.draft;
+    if (!d)
+        return null;
+    const open = [...openAsks(mock).map((a) => a.id), ...builtinAskIds(mock, posts, mock.id)];
+    const said = (id) => {
+        const a = d.answers[id];
+        const picked = Array.isArray(a) ? a.length > 0 : a !== undefined;
+        return picked || d.others?.[id] !== undefined || d.notes?.[id] !== undefined;
+    };
+    return open.filter(said).length;
+}
 // The viewer's built-in "Which one?" for variants no agent ask binds: `variant`
 // mock-wide, `variant:<state>` per state. Never stored; synthesized from the
 // variants so a reply answering it validates, flips and reads like any ask. An
@@ -275,6 +304,20 @@ export function collectAssetIds(surfaces, out) {
             out.add(p.assetId);
     }
 }
+// The images a draft, a reply or a sent ask carries (all keep the user's
+// attachments in otherImages / noteImages).
+export function collectAttachedIds(holder, out) {
+    for (const map of [holder?.otherImages, holder?.noteImages]) {
+        if (!map || typeof map !== "object")
+            continue;
+        for (const ids of Array.isArray(map) ? [map] : Object.values(map)) {
+            if (Array.isArray(ids))
+                for (const id of ids)
+                    if (typeof id === "string")
+                        out.add(id);
+        }
+    }
+}
 // Pick the assets to evict so `incomingBytes` fits under `budget`. Oldest
 // (lastAccessedAt) first, but unreferenced assets go before referenced ones —
 // a live embed is only evicted as a last resort, once unreferenced candidates