@agentprojectcontext/apx 1.31.1 → 1.32.0

package/README.md

@@ -64,7 +64,6 @@ Runtime state — local machine only, never committed:
 
 ```text
 ~/.apx/projects/<project-id>/
-├── project.db             ← regenerable SQLite cache
 ├── messages/              ← local message history
 └── agents/
     ├── <slug>/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.31.1",
+  "version": "1.32.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/skills/apc-context/SKILL.md

@@ -81,7 +81,6 @@ Do not store:
 .apc/sessions/
 .apc/conversations/
 .apc/messages/
-.apc/project.db
 .apc/cache/
 .apc/tmp/
 .apc/private/

package/src/core/agent/constants.js

@@ -1,3 +1,8 @@
 export const MAX_TOOL_ITERS = 6;
 export const ACK_ONLY_TOOLS = new Set(["send_telegram"]);
 export const MAX_CONSECUTIVE_ACKS = 2;
+// Tools whose semantics REQUIRE handing control back to the user. After the
+// tool runs we break the loop — even under completionContract — because the
+// task literally cannot advance without a human reply. Without this, models
+// under forced toolChoice spam the same question across iterations.
+export const TURN_ENDING_TOOLS = new Set(["ask_questions"]);

package/src/core/agent/run-agent.js

@@ -4,7 +4,7 @@ import {
   cleanTextOfPseudoToolCalls,
 } from "./tool-call-parser.js";
 import { resolveActiveModel, fallbackModels } from "./model-router.js";
-import { MAX_TOOL_ITERS, ACK_ONLY_TOOLS, MAX_CONSECUTIVE_ACKS } from "./constants.js";
+import { MAX_TOOL_ITERS, ACK_ONLY_TOOLS, MAX_CONSECUTIVE_ACKS, TURN_ENDING_TOOLS } from "./constants.js";
 import {
   isShortConfirmation,
   lastAssistantAskedForConfirmation,
@@ -347,6 +347,7 @@ export async function runAgent({
     });
 
     let finishSummary = null;
+    let turnEndingQuestions = null;
     for (const tc of toolCalls) {
       const fn = tc.function || tc;
       const name = fn.name;
@@ -409,6 +410,20 @@ export async function runAgent({
         tool_name: name,
         content: JSON.stringify(toolResult),
       });
+
+      // Capture turn-ending intents (e.g. ask_questions). The loop cannot
+      // legitimately advance without a user reply; under completionContract
+      // forcing another tool call just produces ask_questions spam.
+      if (TURN_ENDING_TOOLS.has(name) && !turnEndingQuestions) {
+        // Questions may be plain strings (legacy) or {question, options, ...}.
+        // For the assistant_text fallback we only need the prompt strings.
+        const qs = Array.isArray(args.questions)
+          ? args.questions
+              .map((q) => (typeof q === "string" ? q : q && typeof q.question === "string" ? q.question : null))
+              .filter(Boolean)
+          : [];
+        turnEndingQuestions = qs;
+      }
     }
 
     // Task declared complete via the contract — emit the summary as the final
@@ -421,6 +436,19 @@ export async function runAgent({
       break;
     }
 
+    // ask_questions (or future turn-ending tools): the task is genuinely
+    // blocked on user input. Exit the loop — completionContract or not,
+    // asking again gets us nowhere. We deliberately do NOT emit a synthetic
+    // assistant_text and we leave lastText empty so persistence and one-shot
+    // API callers don't end up with a duplicate bullet list next to the
+    // rendering surfaces' own UI (web AskQuestionsCard, terminal renderer,
+    // telegram inline keyboard). The structured questions live on the tool
+    // trace — that's the canonical source.
+    if (turnEndingQuestions) {
+      if (!lastText) lastText = "";
+      break;
+    }
+
     const allAckOnly = toolCalls.every((tc) => {
       const n = (tc.function?.name) || tc.name;
       return ACK_ONLY_TOOLS.has(n);

package/src/core/confirmation/adapters/code.js

@@ -0,0 +1,41 @@
+// Code-surface confirmation adapter.
+//
+// Same stdin readline pattern as terminal, but formatted for the code TUI:
+// more structured output so it's visually distinct from agent output in the
+// split-pane Build mode. Uses stderr to avoid polluting the code output stream.
+
+import readline from "node:readline";
+
+const SEPARATOR = "─".repeat(60);
+
+/**
+ * Creates a requestConfirmation function for the code channel.
+ *
+ * @returns {(tool: string, args: object, description: string) => Promise<boolean>}
+ */
+export function createCodeConfirmAdapter() {
+  return async function requestConfirmation(_tool, _args, description) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+      terminal: false,
+    });
+
+    return new Promise((resolve) => {
+      process.stderr.write(
+        `\n${SEPARATOR}\n` +
+        `[apx] CONFIRM ACTION\n` +
+        `  ${description}\n` +
+        `  Answer [y = yes / N = no]: `
+      );
+      rl.once("line", (answer) => {
+        rl.close();
+        const confirmed = /^(y|yes|ok)$/i.test(answer.trim());
+        process.stderr.write(confirmed ? "✓ Confirmed\n" : "✗ Cancelled\n");
+        process.stderr.write(`${SEPARATOR}\n`);
+        resolve(confirmed);
+      });
+      rl.once("close", () => resolve(false));
+    });
+  };
+}

package/src/core/confirmation/adapters/telegram.js

@@ -0,0 +1,134 @@
+// Telegram confirmation adapter — async inline keyboard.
+//
+// Flow (why a Promise survives across two independent HTTP calls):
+//
+//   1. requestConfirmation() is called by the agent loop mid-tool-execution.
+//      It creates a pending entry in the shared store, embeds the correlationId
+//      in the button callback_data, sends the keyboard to Telegram, and returns
+//      a Promise that is NOT yet resolved.
+//
+//   2. The agent loop is now suspended at `await requestConfirmation(...)`.
+//      The Telegram bot's polling loop keeps running independently.
+//
+//   3. When the user taps a button, Telegram sends a callback_query update.
+//      The plugin's _handleUpdate() routes it to handleCallbackQuery() here.
+//
+//   4. handleCallbackQuery() calls pendingStore.resolve(correlationId, value),
+//      which finds the Promise's resolve function in the in-memory map and
+//      calls it. The agent loop resumes with true or false.
+//
+// Idempotency: once the promise resolves the entry is removed from the store.
+// Any subsequent tap on the same button won't find an entry and is a no-op.
+//
+// Post-restart stale buttons: if the process restarted after sending the
+// keyboard but before the user tapped, pendingStore.wasKnown() detects the
+// SQLite row with no memory entry and we show "Expirado" instead of an error.
+
+const API_BASE = "https://api.telegram.org";
+const TIMEOUT_MS = 60_000; // 60 s — long enough for a human, short enough to not block forever
+
+/**
+ * @param {{ token: string, chatId: string|number, pendingStore: ConfirmationPendingStore }} opts
+ * @returns {{ requestConfirmation, handleCallbackQuery }}
+ */
+export function createTelegramConfirmAdapter({ token, chatId, pendingStore }) {
+  async function requestConfirmation(tool, _args, description) {
+    const { correlationId, promise } = pendingStore.create({ timeoutMs: TIMEOUT_MS });
+
+    await sendConfirmKeyboard(token, chatId, description, correlationId, TIMEOUT_MS);
+
+    return promise;
+  }
+
+  // Called by ChannelPoller._handleUpdate() when a callback_query arrives.
+  // Returns true if the callback matched our pattern (consumed it), false otherwise.
+  async function handleCallbackQuery(callbackQuery) {
+    const data = callbackQuery.data || "";
+    const match = data.match(/^apx:confirm:([a-f0-9]{16}):(yes|no)$/);
+    if (!match) return false;
+
+    const [, correlationId, answer] = match;
+    const confirmed = answer === "yes";
+
+    // ACK the callback immediately to clear the loading spinner on the button.
+    // Fire-and-forget — a slow ACK is annoying but not fatal.
+    await answerCallbackQuery(token, callbackQuery.id, confirmed ? "✅ Confirmed" : "❌ Cancelled");
+
+    const resolved = pendingStore.resolve(correlationId, confirmed);
+
+    // If not resolved, the entry timed out or the process restarted — show "Expired"
+    // so the user knows the button is no longer actionable.
+    const inlineKeyboard = resolved
+      ? [[{ text: confirmed ? "✅ Confirmed" : "❌ Cancelled", callback_data: "apx:noop" }]]
+      : [[{ text: "⏱ Expired", callback_data: "apx:noop" }]];
+
+    if (callbackQuery.message?.chat?.id && callbackQuery.message?.message_id) {
+      await editMessageButtons(
+        token,
+        callbackQuery.message.chat.id,
+        callbackQuery.message.message_id,
+        inlineKeyboard
+      );
+    }
+
+    return true;
+  }
+
+  return { requestConfirmation, handleCallbackQuery };
+}
+
+// ---------- Telegram API helpers --------------------------------------------
+
+async function sendConfirmKeyboard(token, chatId, description, correlationId, timeoutMs) {
+  const timeoutSec = Math.round(timeoutMs / 1000);
+  await fetch(`${API_BASE}/bot${token}/sendMessage`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      chat_id: chatId,
+      text:
+        `⚠️ *Confirm action*\n\n${escapeMarkdown(description)}\n\n` +
+        `_Expires in ${timeoutSec}s. No response → cancelled._`,
+      parse_mode: "Markdown",
+      reply_markup: {
+        inline_keyboard: [[
+          { text: "✅ Yes", callback_data: `apx:confirm:${correlationId}:yes` },
+          { text: "❌ No",  callback_data: `apx:confirm:${correlationId}:no` },
+        ]],
+      },
+    }),
+  });
+}
+
+async function answerCallbackQuery(token, callbackQueryId, text) {
+  try {
+    await fetch(`${API_BASE}/bot${token}/answerCallbackQuery`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ callback_query_id: callbackQueryId, text }),
+    });
+  } catch {
+    // best-effort — Telegram gives only 30s to answer; after that it's already cleared
+  }
+}
+
+async function editMessageButtons(token, chatId, messageId, inlineKeyboard) {
+  try {
+    await fetch(`${API_BASE}/bot${token}/editMessageReplyMarkup`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        chat_id: chatId,
+        message_id: messageId,
+        reply_markup: { inline_keyboard: inlineKeyboard },
+      }),
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+// Escape Markdown special chars so description text doesn't break Telegram markup.
+function escapeMarkdown(text) {
+  return String(text || "").replace(/[_*[\]()~`>#+\-=|{}.!]/g, "\\$&");
+}

package/src/core/confirmation/adapters/terminal.js

@@ -0,0 +1,35 @@
+// Terminal confirmation adapter — synchronous stdin readline.
+//
+// The agent loop blocks here while waiting for user input. This is fine on
+// the terminal surface because the whole process is interactive and
+// single-threaded from the user's perspective.
+
+import readline from "node:readline";
+
+/**
+ * Creates a requestConfirmation function for the terminal channel.
+ * Uses stderr so stdout remains clean (useful when output is piped).
+ *
+ * @returns {(tool: string, args: object, description: string) => Promise<boolean>}
+ */
+export function createTerminalConfirmAdapter() {
+  return async function requestConfirmation(_tool, _args, description) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+      terminal: false,
+    });
+
+    return new Promise((resolve) => {
+      process.stderr.write(
+        `\n⚠  Confirmation required\n   ${description}\n   Continue? [y/N] `
+      );
+      rl.once("line", (answer) => {
+        rl.close();
+        resolve(/^(y|yes|ok)$/i.test(answer.trim()));
+      });
+      // Covers Ctrl+C / EOF while waiting.
+      rl.once("close", () => resolve(false));
+    });
+  };
+}

package/src/core/confirmation/adapters/web.js

@@ -0,0 +1,53 @@
+// Web / TUI confirmation adapter — async SSE + HTTP confirm endpoint.
+//
+// How the Promise resolves across two separate HTTP calls:
+//
+//   1. The agent loop (running inside an SSE request handler) calls
+//      requestConfirmation(). This emits a "confirmation_required" SSE event
+//      containing the correlationId and description, then suspends by awaiting
+//      the pending store's Promise.
+//
+//   2. The browser / TUI receives the SSE event and renders a confirm/cancel
+//      dialog. The dialog is keyed by correlationId.
+//
+//   3. The user responds → frontend POSTs to
+//      POST /super-agent/confirm/:correlationId  { confirmed: boolean }
+//
+//   4. The API handler (api/confirm.js) calls pendingStore.resolve(correlationId,
+//      value). This finds the in-memory resolve callback and calls it, unblocking
+//      the agent loop. The SSE stream receives the next event and continues.
+//
+// `onEvent` is the SSE emitter for the current turn. It's injected at adapter
+// creation time (each turn gets its own adapter instance) so the "please show
+// a dialog" event reaches the right open SSE connection.
+
+import { getConfirmationStore } from "../pending-store.js";
+
+const TIMEOUT_MS = 120_000; // 2 min — humans on screens are slower than keyboard
+
+/**
+ * Factory — call once per SSE turn, passing the turn's `onEvent` emitter.
+ *
+ * @param {{ onEvent: (event: object) => Promise<void>|void }} opts
+ * @returns {(tool: string, args: object, description: string) => Promise<boolean>}
+ */
+export function createWebConfirmAdapter({ onEvent }) {
+  return async function requestConfirmation(tool, _args, description) {
+    const store = getConfirmationStore();
+
+    const { correlationId, promise } = store.create({ timeoutMs: TIMEOUT_MS });
+
+    // Push a structured event to the open SSE stream so the frontend knows
+    // to render a confirmation dialog. The correlationId is the shared key
+    // between this pending promise and the POST /confirm/:correlationId call.
+    await onEvent({
+      type: "confirmation_required",
+      correlationId,
+      tool,
+      description,
+      timeout_ms: TIMEOUT_MS,
+    });
+
+    return promise;
+  };
+}

package/src/core/confirmation/index.js

@@ -0,0 +1,44 @@
+// Human-in-the-loop confirmation system.
+//
+// Public surface:
+//   getConfirmationStore()          shared SQLite-backed pending store
+//   buildConfirmDescription(t, a)   human-readable action summary
+//   isConfirmationRequired(err)     true when a tool threw requires_confirmation:
+//
+// Adapters (one per channel type) live under ./adapters/.
+
+export { getConfirmationStore, ConfirmationPendingStore } from "./pending-store.js";
+
+/**
+ * Returns true when `error` was thrown by createPermissionGuard() to signal
+ * that this tool call needs explicit user approval before proceeding.
+ */
+export function isConfirmationRequired(error) {
+  return (
+    error != null &&
+    typeof error.message === "string" &&
+    error.message.startsWith("requires_confirmation:")
+  );
+}
+
+/**
+ * Build a short, human-readable description of the action being confirmed.
+ * Shown in all confirmation channels (terminal prompt, Telegram message, web dialog).
+ */
+export function buildConfirmDescription(tool, args) {
+  const text = (s, max = 150) => String(s || "").slice(0, max);
+
+  const builders = {
+    send_telegram: (a) => `Send Telegram message: "${text(a.text)}"`,
+    run_shell:     (a) => `Run shell command: \`${text(a.command)}\``,
+    write_file:    (a) => `Write file: ${a.path || a.file || "(no path)"}`,
+    edit_file:     (a) => `Edit file: ${a.path || a.file || "(no path)"}`,
+    create_task:   (a) => `Create task: "${a.title || a.name || "?"}"`,
+    add_project:   (a) => `Add project: ${a.path || a.name || "?"}`,
+    set_identity:  (a) => `Change agent identity to: "${a.name || "?"}"`,
+    call_runtime:  (a) => `Call runtime: ${a.runtime || a.name || "?"}`,
+  };
+
+  const fn = builders[tool];
+  return fn ? fn(args) : `Run tool: \`${tool}\``;
+}

package/src/core/confirmation/pending-store.js

@@ -0,0 +1,68 @@
+// Pending confirmation store: in-memory map of unresolved confirmations.
+//
+// Each entry holds a Promise's resolve callback and a timeout timer.
+// When the user responds (any channel), resolve() is called and the agent
+// loop that was suspended at `await requestConfirmation(...)` resumes.
+//
+// No persistence needed: confirmations are ephemeral (30–120s window).
+// If the daemon restarts, the agent runs that created them are also dead,
+// so there is nothing to resume. Stale Telegram buttons simply won't find
+// an entry and the handleCallbackQuery path shows "Expired" gracefully.
+
+import { randomBytes } from "node:crypto";
+
+function generateId() {
+  return randomBytes(8).toString("hex"); // 16 hex chars, URL-safe
+}
+
+export class ConfirmationPendingStore {
+  constructor() {
+    // correlationId -> { resolve: (boolean) => void, timer: NodeJS.Timeout }
+    this._pending = new Map();
+  }
+
+  /**
+   * Register a new pending confirmation.
+   *
+   * Returns { correlationId, promise } where:
+   *   - correlationId: embed in the reply (button callback_data, SSE event…)
+   *   - promise: resolves to true (confirmed) or false (denied / timeout)
+   *
+   * After timeoutMs with no response the promise auto-resolves to false.
+   */
+  create({ timeoutMs = 30_000 } = {}) {
+    const correlationId = generateId();
+
+    const promise = new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(correlationId);
+        resolve(false);
+      }, timeoutMs);
+      this._pending.set(correlationId, { resolve, timer });
+    });
+
+    return { correlationId, promise };
+  }
+
+  /**
+   * Resolve a pending confirmation.
+   * Returns true if found and resolved, false if not found (timed out, already
+   * resolved, or stale button after a process restart).
+   */
+  resolve(correlationId, value) {
+    const entry = this._pending.get(correlationId);
+    if (!entry) return false;
+    clearTimeout(entry.timer);
+    this._pending.delete(correlationId);
+    entry.resolve(value);
+    return true;
+  }
+}
+
+// Singleton — one store per daemon process, shared by all adapters.
+let _store = null;
+
+export function getConfirmationStore() {
+  if (!_store) _store = new ConfirmationPendingStore();
+  return _store;
+}

package/src/host/daemon/api/artifacts.js

@@ -2,14 +2,93 @@
 //   GET    /projects/:pid/artifacts
 //   POST   /projects/:pid/artifacts
 //   GET    /projects/:pid/artifacts/:name
+//   POST   /projects/:pid/artifacts/:name/run        body: { args?: string[] }
 //   DELETE /projects/:pid/artifacts/:name
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import path from "node:path";
 import {
+  artifactPath,
   createArtifact,
   listArtifacts,
   readArtifact,
   removeArtifact,
 } from "../../../core/artifacts-store.js";
 
+// Same heuristic as `apx artifact run` (cli/commands/artifact.js): exec bit
+// OR shebang counts as runnable. We auto-chmod when shebang-only so the
+// web Run button "just works" the way it would from the terminal.
+function detectRunnable(absPath) {
+  let stat;
+  try {
+    stat = fs.statSync(absPath);
+  } catch {
+    return { runnable: false, reason: "not_found" };
+  }
+  if (!stat.isFile()) return { runnable: false, reason: "not_a_file" };
+  const execBit = (stat.mode & 0o111) !== 0;
+  let hasShebang = false;
+  try {
+    const fd = fs.openSync(absPath, "r");
+    const buf = Buffer.alloc(2);
+    fs.readSync(fd, buf, 0, 2, 0);
+    fs.closeSync(fd);
+    hasShebang = buf.toString("utf8") === "#!";
+  } catch { /* leave hasShebang = false */ }
+  if (execBit) return { runnable: true, autoChmod: false };
+  if (hasShebang) return { runnable: true, autoChmod: true };
+  return { runnable: false, reason: "no_exec_no_shebang" };
+}
+
+// Cap stdout/stderr captured per run so a runaway script can't blow up the
+// daemon. 256 KiB each — enough for typical script output, small enough to
+// fit in one HTTP response without streaming.
+const MAX_CAPTURE_BYTES = 256 * 1024;
+// Hard timeout for synchronous web execution. Long-running scripts should
+// be invoked from the terminal where the user has direct stdio.
+const RUN_TIMEOUT_MS = 30_000;
+
+function runArtifact({ absPath, cwd, args, timeoutMs = RUN_TIMEOUT_MS }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawn(absPath, Array.isArray(args) ? args : [], { cwd });
+    let stdout = "";
+    let stderr = "";
+    let truncated = false;
+    let timedOut = false;
+    const cap = (s, chunk) => {
+      if (s.length >= MAX_CAPTURE_BYTES) { truncated = true; return s; }
+      const next = s + chunk.toString("utf8");
+      if (next.length > MAX_CAPTURE_BYTES) { truncated = true; return next.slice(0, MAX_CAPTURE_BYTES); }
+      return next;
+    };
+    child.stdout.on("data", (c) => { stdout = cap(stdout, c); });
+    child.stderr.on("data", (c) => { stderr = cap(stderr, c); });
+    const killer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill("SIGTERM"); } catch { /* ignore */ }
+      setTimeout(() => { try { child.kill("SIGKILL"); } catch { /* ignore */ } }, 1500);
+    }, timeoutMs);
+    child.on("error", (err) => {
+      clearTimeout(killer);
+      resolve({ ok: false, error: err.message, durationMs: Date.now() - started });
+    });
+    child.on("exit", (code, signal) => {
+      clearTimeout(killer);
+      resolve({
+        ok: !timedOut && code === 0,
+        exitCode: code,
+        signal,
+        timedOut,
+        truncated,
+        stdout,
+        stderr,
+        durationMs: Date.now() - started,
+      });
+    });
+  });
+}
+
 export function register(app, { project }) {
   app.get("/projects/:pid/artifacts", (req, res) => {
     const p = project(req, res);
@@ -49,4 +128,42 @@ export function register(app, { project }) {
     );
     res.status(ok ? 204 : 404).end();
   });
+
+  // Synchronous execute. Web's "Run" button hits this; the terminal CLI uses
+  // its own local spawn (stdio inherited) so it can run interactively. Output
+  // is captured up to MAX_CAPTURE_BYTES and the call is bounded by
+  // RUN_TIMEOUT_MS — anything longer should go through the terminal.
+  app.post("/projects/:pid/artifacts/:name/run", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const name = decodeURIComponent(req.params.name);
+    const absPath = artifactPath(p.storagePath, name);
+    if (!fs.existsSync(absPath)) {
+      return res.status(404).json({ error: `artifact "${name}" not found` });
+    }
+    const detection = detectRunnable(absPath);
+    if (!detection.runnable) {
+      return res.status(400).json({
+        error: `artifact "${name}" is not runnable`,
+        reason: detection.reason,
+      });
+    }
+    if (detection.autoChmod) {
+      try {
+        const st = fs.statSync(absPath);
+        fs.chmodSync(absPath, st.mode | 0o111);
+      } catch (e) {
+        return res.status(500).json({ error: `chmod failed: ${e.message}` });
+      }
+    }
+    const args = Array.isArray(req.body?.args)
+      ? req.body.args.filter((a) => typeof a === "string")
+      : [];
+    const result = await runArtifact({
+      absPath,
+      cwd: path.dirname(absPath),
+      args,
+    });
+    res.json(result);
+  });
 }

package/src/host/daemon/api/code.js

@@ -14,6 +14,7 @@
 // + per-mode tool gating), then persists the rich assistant turn.
 import { runSuperAgent } from "../super-agent.js";
 import { appendSuperAgentErrorTrace } from "./shared.js";
+import { createWebConfirmAdapter } from "../../../core/confirmation/adapters/web.js";
 import {
   listCodeSessions,
   getCodeSession,
@@ -67,6 +68,18 @@ function modeGuidanceFor(mode) {
     "confirmation and do not stop after one step — keep calling tools until the",
     "entire task is done, then briefly summarize what you changed and why.",
     "Prefer surgical edits over rewrites.",
+    "When the user asks for a reusable script, snippet, or 'artifact' (something",
+    "they want to keep and run later), put it under `artifacts/<name>` inside",
+    "the project — it then shows up in the Artifacts tab. Don't drop reusable",
+    "scripts at the project root.",
+    "If a parameter you need is missing (API key, app id, target URL, …), call",
+    "`ask_questions` ONCE with all your questions and stop — control returns",
+    "to the user. Do not call ask_questions again in the same turn; you'll just",
+    "get the same blank state back. Each question can be a string (free-text",
+    "answer) OR an object {question, options:[{label, description}], multiSelect}",
+    "for choices. Prefer 2–4 mutually-exclusive options when a question has a",
+    "natural shortlist (yes/no, which-of-these, …); leave options empty for",
+    "open-ended answers (API keys, names, free-form ideas).",
   ].join(" ");
 }
 
@@ -295,6 +308,7 @@ export function register(app, { projects, project, config, registries, plugins }
         // it keeps the normal "text ends the turn" behavior.
         completionContract: mode === "build",
         onEvent,
+        requestConfirmation: createWebConfirmAdapter({ onEvent }),
       });
       projects.rebuild(p.id);
 

package/src/host/daemon/api/confirm.js

@@ -0,0 +1,30 @@
+// Confirmation resolution endpoint for web and TUI channels.
+//
+//   POST /super-agent/confirm/:correlationId
+//   Body: { confirmed: boolean }
+//
+// Called by the frontend after the user responds to a "confirmation_required"
+// SSE event emitted by the web confirmation adapter. Resolves the pending
+// Promise in the agent loop, unblocking it to continue with confirmed: true
+// or to return a cancelled error.
+
+import { getConfirmationStore } from "../../../core/confirmation/pending-store.js";
+
+export function register(app) {
+  app.post("/super-agent/confirm/:correlationId", async (req, res) => {
+    const { correlationId } = req.params;
+    const { confirmed } = req.body;
+
+    if (typeof confirmed !== "boolean") {
+      return res.status(400).json({ error: "confirmed must be a boolean" });
+    }
+
+    const resolved = getConfirmationStore().resolve(correlationId, confirmed);
+
+    if (!resolved) {
+      return res.status(404).json({ error: "confirmation not found or already expired" });
+    }
+
+    return res.json({ ok: true, confirmed });
+  });
+}