agent-yes 1.228.0 → 1.229.0

package/ts/serve.ts

@@ -37,11 +37,13 @@ import {
   writeToIpc,
   type CommonOpts,
 } from "./subcommands.ts";
+import { answerAsk, listAsks } from "./askApi.ts";
 import { TYPING_BADGE } from "./badges.ts";
 import { isCallbackRevoked, loadCallbackSecretReadOnly } from "./callback.ts";
 import { CLAUDE_SESSION_PIN_ENV } from "./sessionEnv.ts";
 import { MAX_CALLBACK_MSG_BYTES, frameVisitorMessage, verifyCapability } from "./callbackCore.ts";
 import { isTerminalReply } from "./terminalReply.ts";
+import { removeControlCharacters } from "./removeControlCharacters.ts";
 import { parseStatusText } from "./statusText.ts";
 import { ensureNodeRuntime, liveEnv } from "./nodeRuntime.ts";
 import { acquireWebrtcHostLock, type ServeLockOwner } from "./serveLock.ts";
@@ -2053,6 +2055,135 @@ export async function cmdServe(rest: string[]): Promise<number> {
       }
     }
 
+    // Both /api/asks routes below share this: "every project" is derived the
+    // same way `ay ls` aggregates across projects — the distinct `cwd`s in
+    // the live-agent registry — since there is no separate "registered
+    // projects" list to read; a project this host has never run an agent in
+    // has nothing to aggregate anyway.
+    const liveProjectRoots = async (): Promise<string[]> => {
+      const records = await listRecords(undefined, defaultOpts({ all: true }));
+      return [...new Set(records.map((r) => r.cwd).filter(Boolean))];
+    };
+
+    // GET /api/asks — the `/ask` decision panel (A7): every `blocked-by-human`
+    // task across every project this host's agents have registered, one
+    // human-facing list.
+    if (req.method === "GET" && p === "/api/asks") {
+      try {
+        const asks = await listAsks(await liveProjectRoots());
+        return Response.json(asks);
+      } catch (e) {
+        return new Response((e as Error).message, { status: 500 });
+      }
+    }
+
+    // POST /api/asks/answer  body {projectRoot, taskId, choice?, acknowledged?}
+    // — the closed loop's single request: `answerAsk()` clears the block and
+    // (for human/decision-kind tasks) advances the transition atomically, so
+    // there is no intermediate state visible to a second request. As a
+    // best-effort follow-up (never blocks the response on it), if the task's
+    // owner resolves to a currently-live agent IN THIS SAME PROJECT, the
+    // answer is written straight into that agent's terminal via the exact
+    // same FIFO mechanism `/api/send` already uses — the real-time half of
+    // the closed loop, for whichever agent happens to be alive and watching
+    // right now.
+    if (req.method === "POST" && p === "/api/asks/answer") {
+      let raw: unknown;
+      try {
+        raw = await req.json();
+      } catch {
+        return new Response("invalid JSON body", { status: 400 });
+      }
+      // Type-validate every field explicitly — an untyped JS client (or a
+      // bug) can send a non-string projectRoot/taskId or a truthy
+      // non-boolean `acknowledged`, which would otherwise surface as an
+      // opaque 500 deep inside answerAsk() instead of a clean 400
+      // (codex-review nitpick).
+      if (typeof raw !== "object" || raw === null) {
+        return new Response("body must be a JSON object", { status: 400 });
+      }
+      const body = raw as Record<string, unknown>;
+      const { projectRoot, taskId, choice, acknowledged, expectedBlockRev } = body;
+      if (typeof projectRoot !== "string" || !projectRoot) {
+        return new Response("projectRoot must be a non-empty string", { status: 400 });
+      }
+      if (typeof taskId !== "string" || !taskId) {
+        return new Response("taskId must be a non-empty string", { status: 400 });
+      }
+      if (choice !== undefined && typeof choice !== "string") {
+        return new Response("choice must be a string", { status: 400 });
+      }
+      if (acknowledged !== undefined && typeof acknowledged !== "boolean") {
+        return new Response("acknowledged must be a boolean", { status: 400 });
+      }
+      if (expectedBlockRev !== undefined && !Number.isSafeInteger(expectedBlockRev)) {
+        // A boundary route must never forward NaN/Infinity/fractional values
+        // into the store's blockRev comparison — those can never legitimately
+        // equal a real blockRev (always a safe, non-negative integer), so
+        // letting them through just produces a confusing rejection deep
+        // inside answerAsk() instead of a clean 400 here (codex-review
+        // Important).
+        return new Response("expectedBlockRev must be a safe integer", { status: 400 });
+      }
+      // Scoped to the SAME live-agent-derived project set GET/api/asks
+      // aggregates over — not merely "a store happens to exist here"
+      // (codex-review Important: hasTodoStore() alone still let a caller
+      // target any readable/writable ay todo store path on the host, not
+      // just ones actually surfaced by this API).
+      const registeredRoots = await liveProjectRoots();
+      if (!registeredRoots.includes(projectRoot)) {
+        return new Response(`no registered project at ${projectRoot}`, { status: 404 });
+      }
+      let result: Awaited<ReturnType<typeof answerAsk>>;
+      try {
+        result = await answerAsk(projectRoot, taskId, { choice, acknowledged, expectedBlockRev });
+      } catch (e) {
+        return new Response((e as Error).message, { status: 400 });
+      }
+      const { record: rec, answerText } = result;
+      // Best-effort, fire-and-forget: the task is already correctly updated
+      // above regardless of whether this succeeds. Deliberately NOT awaited —
+      // a stalled FIFO write must never hang the response, which is the
+      // whole point of "best-effort" (codex-review Important: an earlier
+      // version awaited this, so a stuck agent could hang answerAsk's caller
+      // even though the todo state had already been updated). This is a real,
+      // accepted limitation, not a bug: if owner resolution or the FIFO
+      // write fails, there is no retry queue here — the durable, correct
+      // outcome is that the task's stored state already reflects the
+      // answer (see answerAsk's own doc comment), and the owning agent will
+      // pick it up on its own next normal check (`ay todo get`, a reconcile
+      // pass, etc.) rather than through a guaranteed real-time push. A
+      // persistent notification-retry mechanism would be new scope well
+      // beyond this route.
+      if (rec.owner) {
+        // Scoped to THIS project's cwd — an unscoped search could match a
+        // same-named owner in a DIFFERENT project and write the answer into
+        // the wrong agent's terminal (codex-review Important).
+        resolveOne(rec.owner, defaultOpts({ all: true, cwdScope: projectRoot }))
+          .then((owner) => {
+            if (!owner.fifo_file) return;
+            // `answerText` comes from answerAsk()'s own validated result, NOT
+            // re-derived from the raw request body here — the earlier
+            // version recomputed `choice ?? "acknowledged"` independently,
+            // which had the SAME unvalidated-choice gap answerAsk() itself
+            // just fixed (codex-review Important). Also strip terminal
+            // control sequences AND collapse newlines: even a genuinely
+            // validated choice option is free text set at ask-creation time
+            // and could still contain control bytes or embedded newlines
+            // that inject extra "typed" lines/escape sequences into the
+            // live agent's terminal via this raw IPC write (codex-review
+            // Important).
+            const safeAnswerText = removeControlCharacters(answerText).replace(/[\r\n]+/g, " ");
+            return writeToIpc(owner.fifo_file, `[/ask] ${taskId} answered: ${safeAnswerText}\n`);
+          })
+          .catch(() => {
+            // owner not currently live / not resolvable / FIFO write failed —
+            // best-effort only, nothing to report back to this request.
+          });
+      }
+      return Response.json(rec);
+    }
+
     // GET /api/search?q= — chat-history search across every agent's log.
     // v1 ("simple" scope, by design): no sidecar index yet — each agent's raw
     // log TAIL (SEARCH_TAIL_BYTES) is rendered through the same headless-xterm

package/ts/todoBlock.spec.ts

@@ -30,4 +30,14 @@ describe("todoBlock", () => {
     expect(rendered[3]).toContain("xyz789");
     expect(new Set(rendered).size).toBe(4); // all distinct
   });
+
+  it("describeBlock includes the actionLink when a blocked-by-human ask is action-shaped (A7)", () => {
+    const rendered = describeBlock({
+      type: "blocked-by-human",
+      who: "taku",
+      actionLink: "https://example/oauth",
+    });
+    expect(rendered).toContain("taku");
+    expect(rendered).toContain("https://example/oauth");
+  });
 });

package/ts/todoBlock.ts

@@ -23,7 +23,19 @@
 
 export type TodoBlock =
   | { type: "blocked-by-task"; taskId: string }
-  | { type: "blocked-by-human"; who: string; question?: string; options?: string[] }
+  // `options` (choice-shape, A7): the human picks one via /ask's buttons.
+  // `actionLink` (action-shape, A7): the human must personally complete
+  // something at that URL (e.g. an OAuth/CAPTCHA flow) — /ask renders an
+  // "open link, then confirm" button instead of a choice list. At most one
+  // of the two is expected to be set; neither is required (a bare question
+  // with no options/actionLink just needs an acknowledgement).
+  | {
+      type: "blocked-by-human";
+      who: string;
+      question?: string;
+      options?: string[];
+      actionLink?: string;
+    }
   | { type: "blocked-by-external"; signal: string; checkFn?: string }
   | { type: "waiting-on-agent"; agentId: string };
 
@@ -52,7 +64,7 @@ export function describeBlock(block: TodoBlock): string {
     case "blocked-by-task":
       return `blocked by task ${block.taskId}`;
     case "blocked-by-human":
-      return `waiting on ${block.who}${block.question ? `: ${block.question}` : ""}`;
+      return `waiting on ${block.who}${block.question ? `: ${block.question}` : ""}${block.actionLink ? ` (action: ${block.actionLink})` : ""}`;
     case "blocked-by-external":
       return `waiting on external signal: ${block.signal}`;
     case "waiting-on-agent":

package/ts/todoCli.spec.ts

@@ -221,6 +221,107 @@ describe("ay todo CLI", () => {
     await expect(run("block", "T1")).rejects.toThrow(/usage: ay todo block/);
   });
 
+  it("block --type blocked-by-human --action-link produces an action-shaped ask (A7)", async () => {
+    await run("new", "e", "--kind", "code");
+    const action = await run(
+      "block",
+      "T1",
+      "--type",
+      "blocked-by-human",
+      "--who",
+      "taku",
+      "--action-link",
+      "https://example/oauth",
+    );
+    expect(action.out).toContain("taku");
+    expect(action.out).toContain("https://example/oauth");
+    const got = await run("get", "T1", "--format", "json");
+    expect(JSON.parse(got.out).block).toEqual({
+      type: "blocked-by-human",
+      who: "taku",
+      actionLink: "https://example/oauth",
+    });
+  });
+
+  it("block --type blocked-by-human refuses --options together with --action-link (mutually exclusive ask shapes, codex-review round-9 Important)", async () => {
+    await run("new", "f", "--kind", "code");
+    await expect(
+      run(
+        "block",
+        "T1",
+        "--type",
+        "blocked-by-human",
+        "--who",
+        "taku",
+        "--options",
+        "a",
+        "b",
+        "--action-link",
+        "https://example/oauth",
+      ),
+    ).rejects.toThrow(/mutually exclusive/);
+  });
+
+  it("block --action-link refuses a non-http(s) URL scheme (javascript:/data: would be an XSS vector when /ask renders it into an <a href>, codex-review round-10 Important)", async () => {
+    await run("new", "g", "--kind", "code");
+    await expect(
+      run(
+        "block",
+        "T1",
+        "--type",
+        "blocked-by-human",
+        "--who",
+        "taku",
+        "--action-link",
+        "javascript:alert(1)",
+      ),
+    ).rejects.toThrow(/must be a valid http/);
+    await expect(
+      run(
+        "block",
+        "T1",
+        "--type",
+        "blocked-by-human",
+        "--who",
+        "taku",
+        "--action-link",
+        "data:text/html,x",
+      ),
+    ).rejects.toThrow(/must be a valid http/);
+    const ok = await run(
+      "block",
+      "T1",
+      "--type",
+      "blocked-by-human",
+      "--who",
+      "taku",
+      "--action-link",
+      "https://example/oauth",
+    );
+    expect(ok.out).toContain("https://example/oauth");
+  });
+
+  it("block --action-link stores the URL PARSER's normalized href, not the raw input — a value with embedded control characters that WHATWG URL parsing tolerates/strips must never persist those bytes verbatim, since describeBlock() later renders this as terminal/log text (codex-review round-16 Important)", async () => {
+    await run("new", "h", "--kind", "code");
+    const withTab = await run(
+      "block",
+      "T1",
+      "--type",
+      "blocked-by-human",
+      "--who",
+      "taku",
+      "--action-link",
+      "https://example/oauth\tinjected",
+    );
+    const got = JSON.parse((await run("get", "T1", "--format", "json")).out);
+    // whatever the parser accepted, it must be exactly what's stored — never
+    // the raw argv string re-used after validation passed on a DIFFERENT
+    // (parser-normalized) value
+    expect(got.block.actionLink).toBe(new URL("https://example/oauth\tinjected").href);
+    expect(got.block.actionLink).not.toContain("\t");
+    expect(withTab.out).not.toContain("\t");
+  });
+
   it("dep add/rm, tree, and digest render real output and surface cycles as a clean error", async () => {
     await run("new", "a", "--kind", "code");
     await run("new", "b", "--kind", "code");

package/ts/todoCli.ts

@@ -45,11 +45,33 @@ import { describeBlock, type TodoBlock } from "./todoBlock.ts";
 import { renderDigest, renderTree, buildTreeJSON, unblockedTasks } from "./todoDigest.ts";
 import { reconcileTodos, type LiveAgent } from "./todoAutomation.ts";
 import { readGlobalPids } from "./globalPidIndex.ts";
+import { removeControlCharacters } from "./removeControlCharacters.ts";
 
 function fail(message: string): never {
   throw new Error(message);
 }
 
+/**
+ * Same check ask.html's own render-time guard uses — a real URL parse, not
+ * just a scheme-prefix regex, which could still let a malformed string
+ * through. Returns the parser's own normalized `.href` (not the raw input)
+ * on success, `null` otherwise: WHATWG URL parsing tolerates/strips some
+ * control characters (e.g. embedded tabs/newlines) from the input while
+ * still returning a valid http(s) URL, so validating against `s` but then
+ * STORING `s` verbatim could still persist those raw control characters
+ * into the store — later rendered as terminal/log text by `describeBlock()`
+ * (codex-review Important). Storing `.href` instead guarantees the store
+ * only ever holds what the parser actually validated.
+ */
+function normalizeHttpUrl(s: string): string | null {
+  try {
+    const u = new URL(s);
+    return u.protocol === "http:" || u.protocol === "https:" ? u.href : null;
+  } catch {
+    return null;
+  }
+}
+
 function parseKind(raw: string | undefined): LifecycleKind {
   if (!raw) fail(`--kind is required (one of: ${Object.keys(LIFECYCLES).join(", ")})`);
   if (!isKnownKind(raw))
@@ -286,6 +308,7 @@ const blockCmd: CommandModule<
     who: string | undefined;
     question: string | undefined;
     options: string[] | undefined;
+    "action-link": string | undefined;
     signal: string | undefined;
     agent: string | undefined;
   }
@@ -300,7 +323,16 @@ const blockCmd: CommandModule<
       .option("task", { type: "string", describe: "required for --type blocked-by-task" })
       .option("who", { type: "string", describe: "required for --type blocked-by-human" })
       .option("question", { type: "string" })
-      .option("options", { type: "string", array: true })
+      .option("options", {
+        type: "string",
+        array: true,
+        describe: "choice-shape ask (/ask renders buttons)",
+      })
+      .option("action-link", {
+        type: "string",
+        describe:
+          "action-shape ask (/ask renders an 'open link, then confirm' button) — e.g. an OAuth/CAPTCHA URL",
+      })
       .option("signal", { type: "string", describe: "required for --type blocked-by-external" })
       .option("agent", { type: "string", describe: "required for --type waiting-on-agent" }),
   handler: async (argv) => {
@@ -317,11 +349,47 @@ const blockCmd: CommandModule<
         break;
       case "blocked-by-human":
         if (!argv.who) fail("--who <name> is required for --type blocked-by-human");
+        // choice-shape (--options) and action-shape (--action-link) are
+        // mutually exclusive — reject the combination outright here rather
+        // than let it depend on askApi.ts's own tie-breaking precedence
+        // (which, as of codex-review round-9, checks actionLink first in
+        // BOTH listAsksForProject() and answerAsk(), so the two now agree
+        // with each other even if this guard were bypassed by a direct
+        // library caller — but a block should simply never be created with
+        // both set in the first place).
+        if (argv.options?.length && argv["action-link"]) {
+          fail(
+            "--options and --action-link are mutually exclusive (choice-shape vs action-shape ask)",
+          );
+        }
+        let normalizedActionLink: string | undefined;
+        if (argv["action-link"]) {
+          const normalized = normalizeHttpUrl(argv["action-link"]);
+          if (!normalized) {
+            // The /ask page renders this straight into an <a href>. HTML-
+            // escaping the text does NOT block dangerous URL schemes
+            // (`javascript:`, `data:`) — only the scheme itself does. Reject
+            // at write time so a non-http(s) link can never reach the store
+            // at all (codex-review Important). Uses the same `URL` parser
+            // ask.html's own render-time check uses (codex-review nitpick: a
+            // regex prefix match alone would still store a malformed string
+            // like "https:/notreallyaurl" that happens to match the prefix).
+            // The rejected input is echoed for the operator's benefit, but
+            // never verbatim — an invalid value can still contain control
+            // characters/newlines, and this string reaches a terminal
+            // (codex-review round-18 nitpick).
+            fail(
+              `--action-link must be a valid http:// or https:// URL (got "${removeControlCharacters(argv["action-link"]).replace(/[\r\n]+/g, " ")}")`,
+            );
+          }
+          normalizedActionLink = normalized;
+        }
         block = {
           type: "blocked-by-human",
           who: argv.who,
           question: argv.question,
           options: argv.options,
+          actionLink: normalizedActionLink,
         };
         break;
       case "blocked-by-external":

package/ts/todoStore.spec.ts

@@ -573,4 +573,130 @@ describe("TodoStore", () => {
     // refused, not erased: the newer block is still exactly what it was
     expect(s.get(t._id)?.block).toEqual({ type: "blocked-by-human", who: "taku" });
   });
+
+  it("clearBlockIfMatches() — the generalized guard — clears only when the FRESH record's blockRev still equals the snapshot, and refuses (without erasing) a block that changed since decided (codex-review round-15 Important)", async () => {
+    const s = await openStore(TEST_ROOT);
+    const t = await s.create({ summary: "x", kind: "code" });
+    const original = {
+      type: "blocked-by-human",
+      who: "taku",
+      question: "canary or beta?",
+    } as const;
+    const afterSet = await s.setBlock(t._id, original);
+    const cleared = await s.clearBlockIfMatches(t._id, afterSet.blockRev ?? 0);
+    expect(cleared.block).toBeNull();
+
+    const afterReplace = await s.setBlock(t._id, {
+      type: "blocked-by-human",
+      who: "taku",
+      question: "a NEW question",
+    });
+    await expect(s.clearBlockIfMatches(t._id, (afterReplace.blockRev ?? 0) - 1)).rejects.toThrow(
+      /block changed since this was decided/,
+    );
+    // refused, not erased: the newer block survives untouched
+    expect(s.get(t._id)?.block).toEqual({
+      type: "blocked-by-human",
+      who: "taku",
+      question: "a NEW question",
+    });
+  });
+
+  it("clearBlockIfMatches() catches an ABA race — a block replaced with BYTE-FOR-BYTE IDENTICAL content still gets a fresh blockRev, so a stale caller is refused rather than erasing that distinct, newer block instance (codex-review round-17 Important)", async () => {
+    const s = await openStore(TEST_ROOT);
+    const t = await s.create({ summary: "x", kind: "code" });
+    const identicalBlock = {
+      type: "blocked-by-human",
+      who: "taku",
+      question: "canary or beta?",
+    } as const;
+    const firstSet = await s.setBlock(t._id, identicalBlock);
+    const capturedRev = firstSet.blockRev ?? 0;
+    // Someone re-sets the EXACT same block content — a content-only
+    // comparison would see no difference at all.
+    await s.setBlock(t._id, identicalBlock);
+    await expect(s.clearBlockIfMatches(t._id, capturedRev)).rejects.toThrow(
+      /block changed since this was decided/,
+    );
+    // refused, not erased: the (identical-looking but distinct, newer)
+    // block instance survives
+    expect(s.get(t._id)?.block).toEqual(identicalBlock);
+  });
+
+  it("answerHumanBlock() applies a gate's evidence, its transition, AND the block clear in ONE atomic write — never a partial application (codex-review round-18 Important, replacing the old approve()+transition()+clearBlockIfMatches() composition)", async () => {
+    const s = await openStore(TEST_ROOT);
+    const t = await s.create({ summary: "pick a channel", kind: "decision" });
+    const afterSet = await s.setBlock(t._id, {
+      type: "blocked-by-human",
+      who: "taku",
+      options: ["canary", "beta"],
+    });
+    const answered = await s.answerHumanBlock(t._id, afterSet.blockRev ?? 0, {
+      name: "human-decided",
+      toState: "decided",
+      validator: "taku",
+      note: "canary",
+    });
+    expect(answered.block).toBeNull();
+    expect(answered.state).toBe("decided");
+    expect(answered.verifyEvidence).toEqual([
+      expect.objectContaining({ gate: "human-decided", validator: "taku", note: "canary" }),
+    ]);
+  });
+
+  it("answerHumanBlock() refuses (without applying anything) a stale expectedBlockRev, and separately refuses independent-verification violations (validator === owner) — matching approve()'s own unconditional rule (codex-review round-18 Important)", async () => {
+    const s = await openStore(TEST_ROOT);
+    const t = await s.create({ summary: "x", kind: "decision" });
+    const afterSet = await s.setBlock(t._id, { type: "blocked-by-human", who: "taku" });
+    await s.setBlock(t._id, { type: "blocked-by-human", who: "taku" }); // bumps blockRev again
+    await expect(
+      s.answerHumanBlock(t._id, afterSet.blockRev ?? 0, {
+        name: "human-decided",
+        toState: "decided",
+        validator: "taku",
+        note: "acknowledged",
+      }),
+    ).rejects.toThrow(/this ask has changed since it was loaded/);
+    expect(s.get(t._id)?.state).toBe("deciding"); // unchanged — refused before any write
+
+    const owned = await s.create({ summary: "y", kind: "decision", owner: "taku" });
+    const ownedBlock = await s.setBlock(owned._id, { type: "blocked-by-human", who: "taku" });
+    await expect(
+      s.answerHumanBlock(owned._id, ownedBlock.blockRev ?? 0, {
+        name: "human-decided",
+        toState: "decided",
+        validator: "taku", // same identity as owner
+        note: "acknowledged",
+      }),
+    ).rejects.toThrow(/independent verification required/);
+    expect(s.get(owned._id)?.state).toBe("deciding"); // unchanged
+    expect(s.get(owned._id)?.block).not.toBeNull(); // NOT cleared either — refused, not partially applied
+  });
+
+  it("answerHumanBlock() re-validates canTransition against the FRESH state, not a value captured before the call — a state change UNRELATED to block (so invisible to the blockRev check alone) must still be caught, matching transition()'s own concurrent-state-drift defense (codex-review round-18 Important)", async () => {
+    const s = await openStore(TEST_ROOT);
+    const t = await s.create({ summary: "x", kind: "decision" });
+    const afterSet = await s.setBlock(t._id, { type: "blocked-by-human", who: "taku" });
+    // Simulate a concurrent writer moving the task's STATE (not its block)
+    // to "done" — the same append-only-merge-line technique the
+    // markOrphaned() test above uses. blockRev is untouched, so the
+    // blockRev check alone would see nothing wrong; only re-validating
+    // canTransition against the fresh state catches this.
+    await appendFile(
+      path.join(TEST_ROOT, ".agent-yes", "todos.jsonl"),
+      JSON.stringify({ _id: t._id, state: "done" }) + "\n",
+    );
+    await expect(
+      s.answerHumanBlock(t._id, afterSet.blockRev ?? 0, {
+        name: "human-decided",
+        toState: "decided",
+        validator: "taku",
+        note: "acknowledged",
+      }),
+    ).rejects.toThrow(/no transition done -> decided.*state changed concurrently/);
+    // refused, not partially applied: block survives untouched, state
+    // stays exactly what the concurrent writer set it to
+    expect(s.get(t._id)?.block).not.toBeNull();
+    expect(s.get(t._id)?.state).toBe("done");
+  });
 });