@agentprojectcontext/apx 1.31.2 → 1.32.0

package/package.json

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

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/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

@@ -68,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(" ");
 }
 

package/src/host/daemon/plugins/desktop.js

@@ -146,6 +146,15 @@ async function _handleMessage({ ws, text, previousMessages }, { projects, config
           _send(ws, { type: "tool_start", name: t.tool, args: t.args });
         } else if (event.type === "tool_result") {
           _send(ws, { type: "tool_done", name: event.trace.tool });
+          // ask_questions on desktop is voice-first: there's no inline-keyboard
+          // UI to render, so we turn the structured questions into a spoken
+          // segment. The user voice-replies on the next turn and the super-agent
+          // sees that reply in its history. Each option is announced inline so
+          // TTS reads them aloud naturally.
+          if (event.trace?.tool === "ask_questions") {
+            const segments = formatAskQuestionsForVoice(event.trace.args?.questions);
+            if (segments) emitSegment(segments);
+          }
         } else if (event.type === "assistant_text" && event.text) {
           // A complete assistant text segment (e.g. the "I'll check…" intro
           // emitted right before a tool runs). Ship it as its own message.
@@ -193,6 +202,31 @@ async function _handleMessage({ ws, text, previousMessages }, { projects, config
   }
 }
 
+// Build a voice-friendly transcript of an ask_questions tool call so the
+// desktop's TTS reads the prompt aloud and the bubble shows what was asked.
+// Single question + options reads as "<question> Opciones: A; B; C."
+// Multiple questions are numbered. Free-text questions just speak the prompt.
+function formatAskQuestionsForVoice(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  const lines = [];
+  raw.forEach((rawQ, idx) => {
+    const q = typeof rawQ === "string" ? { question: rawQ } : (rawQ || {});
+    const text = typeof q.question === "string" ? q.question.trim() : "";
+    if (!text) return;
+    const prefix = raw.length > 1 ? `${idx + 1}. ` : "";
+    const opts = Array.isArray(q.options) ? q.options : [];
+    const optLabels = opts
+      .map((o) => (typeof o === "string" ? o : (o && typeof o.label === "string" ? o.label : "")))
+      .filter(Boolean);
+    let line = `${prefix}${text}`;
+    if (optLabels.length > 0) {
+      line += ` Opciones: ${optLabels.join("; ")}.`;
+    }
+    lines.push(line);
+  });
+  return lines.length > 0 ? lines.join("\n") : null;
+}
+
 function _send(ws, msg) {
   if (ws) {
     sendToClient(ws, msg);

package/src/host/daemon/plugins/telegram-ask.js

@@ -0,0 +1,309 @@
+// Telegram ask_questions integration.
+//
+// When the super-agent ends a turn with an `ask_questions` tool call, the
+// telegram plugin calls into this module instead of sending the bare reply
+// text. We render each question as a Telegram message with an inline keyboard
+// (one button per option, plus skip/cancel), keep the in-flight state in
+// memory keyed by chat_id, and resume by feeding the compiled answers back
+// to the super-agent as a synthetic user prompt.
+//
+// State is intentionally process-local: an ask flow that started before a
+// daemon restart simply dies; the user can re-issue the original prompt.
+
+import { performance } from "node:perf_hooks";
+
+const ASK_TTL_MS = 30 * 60_000; // 30 min — abandoned flows GC'd after this
+
+const STORE = new Map(); // chat_id (string) → AskState
+
+// AskState shape:
+// {
+//   chatId, projectId, authorId,
+//   correlationId,         // short id used in callback_data to dedupe restarts
+//   questions: AskQuestion[],
+//   answers: { picked: Set<number>, text: string, skipped: boolean }[],
+//   index: number,
+//   messageId: number|null, // last sent question message (for edit/disable)
+//   createdAt, lastTouchedAt,
+//   resume: (compiled: string) => Promise<void>, // called when flow completes
+// }
+
+function emptyAnswer() {
+  return { picked: new Set(), text: "", skipped: false };
+}
+
+function genCorrelationId() {
+  // Time-derived monotonically-ish id, kept short for Telegram's 64-byte
+  // callback_data limit. No Date.now() in workflows but we're in normal Node.
+  return Math.floor(performance.now() * 1000).toString(36) + Math.floor(Math.random() * 36 ** 4).toString(36);
+}
+
+// Normalize whatever shape the model passed (strings or {question,...} objs)
+// into the canonical question record. Identical contract to the web side
+// (InlineAskPanel.tsx normalizeQuestionClient).
+export function normalizeQuestion(q) {
+  if (typeof q === "string") {
+    return { question: q, options: [], multiSelect: false, allowText: true };
+  }
+  if (!q || typeof q !== "object") return null;
+  const text = typeof q.question === "string" ? q.question : "";
+  if (!text) return null;
+  const rawOptions = Array.isArray(q.options) ? q.options : [];
+  const options = rawOptions
+    .map((o) => {
+      if (typeof o === "string") return { label: o };
+      if (o && typeof o === "object" && typeof o.label === "string") {
+        return {
+          label: o.label,
+          description: typeof o.description === "string" ? o.description : undefined,
+        };
+      }
+      return null;
+    })
+    .filter(Boolean);
+  return {
+    question: text,
+    header: typeof q.header === "string" ? q.header : undefined,
+    options,
+    multiSelect: q.multiSelect === true,
+    allowText: q.allowText === false ? false : true,
+  };
+}
+
+// Pull the most recent ask_questions tool call out of a super-agent trace.
+// Returns the normalized question list, or null when the turn didn't ask.
+export function extractAskQuestionsFromTrace(trace) {
+  if (!Array.isArray(trace)) return null;
+  for (let i = trace.length - 1; i >= 0; i--) {
+    const t = trace[i];
+    if (t && t.tool === "ask_questions") {
+      const raw = (t.args && Array.isArray(t.args.questions)) ? t.args.questions : [];
+      const normalized = raw.map(normalizeQuestion).filter(Boolean);
+      return normalized.length > 0 ? normalized : null;
+    }
+  }
+  return null;
+}
+
+// Compile collected answers into a single user-message string. Mirrors the
+// shape produced by the web InlineAskPanel.compileAnswers so the super-agent
+// sees consistent input across surfaces.
+export function compileAnswers(state) {
+  const lines = [];
+  state.questions.forEach((q, i) => {
+    const a = state.answers[i] || emptyAnswer();
+    if (a.skipped) {
+      lines.push(`- ${q.question}\n  → (omitido)`);
+      return;
+    }
+    const parts = [];
+    if (q.options && q.options.length > 0) {
+      const labels = [...a.picked]
+        .sort((x, y) => x - y)
+        .map((idx) => q.options[idx]?.label)
+        .filter(Boolean);
+      if (labels.length > 0) parts.push(labels.join(", "));
+    }
+    const text = (a.text || "").trim();
+    if (text) {
+      parts.push(q.options && q.options.length > 0 ? `(Otro: ${text})` : text);
+    }
+    const answerText = parts.length > 0 ? parts.join(" ") : "(sin respuesta)";
+    lines.push(`- ${q.question}\n  → ${answerText}`);
+  });
+  return lines.join("\n");
+}
+
+// Build the Telegram InlineKeyboardMarkup for one question. Single-select:
+// pressing an option commits immediately; the keyboard disappears via
+// editMessageReplyMarkup. Multi-select: each press toggles a check on the
+// label; a "✓ Confirmar" row commits. No options: keyboard has only a Saltar
+// row, and the user is expected to reply with text.
+export function buildKeyboard(state) {
+  const cid = state.correlationId;
+  const q = state.questions[state.index];
+  const a = state.answers[state.index] || emptyAnswer();
+  const rows = [];
+
+  if (Array.isArray(q.options) && q.options.length > 0) {
+    q.options.forEach((opt, i) => {
+      const picked = a.picked.has(i);
+      const label = q.multiSelect
+        ? `${picked ? "☑" : "☐"} ${opt.label}`
+        : opt.label;
+      rows.push([
+        { text: label, callback_data: `apx:ask:${cid}:opt:${i}` },
+      ]);
+    });
+    if (q.multiSelect) {
+      rows.push([{ text: "✓ Confirmar", callback_data: `apx:ask:${cid}:next` }]);
+    }
+  }
+
+  // Control row: skip + cancel. Plus a back arrow when we're past Q1.
+  const controls = [];
+  if (state.index > 0) controls.push({ text: "◀︎ Atrás", callback_data: `apx:ask:${cid}:back` });
+  controls.push({ text: "Omitir", callback_data: `apx:ask:${cid}:skip` });
+  controls.push({ text: "Cerrar", callback_data: `apx:ask:${cid}:cancel` });
+  rows.push(controls);
+
+  return { inline_keyboard: rows };
+}
+
+// Plain-text body of the question message: header (N/M) + question + a hint
+// for free-text questions.
+export function formatQuestionText(state) {
+  const q = state.questions[state.index];
+  const total = state.questions.length;
+  const head = total > 1 ? `[${state.index + 1}/${total}] ` : "";
+  const hasOptions = Array.isArray(q.options) && q.options.length > 0;
+  const hint = hasOptions
+    ? (q.multiSelect
+        ? "\n\n_Multi-selección: tocá las opciones que quieras y después Confirmar._"
+        : "\n\n_Tocá una opción para responder._")
+    : "\n\n_Respondé con un mensaje de texto._";
+  return `❓ ${head}${q.question}${hint}`;
+}
+
+// ---- Store API ------------------------------------------------------------
+
+export function saveState(chatId, state) {
+  STORE.set(String(chatId), { ...state, lastTouchedAt: Date.now() });
+}
+
+export function getState(chatId) {
+  const s = STORE.get(String(chatId));
+  if (!s) return null;
+  if (Date.now() - s.lastTouchedAt > ASK_TTL_MS) {
+    STORE.delete(String(chatId));
+    return null;
+  }
+  return s;
+}
+
+export function clearState(chatId) {
+  STORE.delete(String(chatId));
+}
+
+export function hasPendingFreeText(chatId) {
+  const s = getState(chatId);
+  if (!s) return false;
+  const q = s.questions[s.index];
+  if (!q) return false;
+  return !(Array.isArray(q.options) && q.options.length > 0);
+}
+
+// Apply a user text reply to the currently-pending free-text question.
+// Returns the updated state (caller decides whether to advance) or null if
+// there was no pending free-text question.
+export function applyTextAnswer(chatId, text) {
+  const s = getState(chatId);
+  if (!s) return null;
+  const q = s.questions[s.index];
+  const hasOptions = Array.isArray(q.options) && q.options.length > 0;
+  if (hasOptions) return null; // multi/single-select questions are answered via callback only
+  const ans = s.answers[s.index] || emptyAnswer();
+  ans.text = (text || "").trim();
+  ans.skipped = false;
+  s.answers[s.index] = ans;
+  saveState(chatId, s);
+  return s;
+}
+
+// Apply a callback_query button press. Returns one of:
+//   { action: "advance", state }   — render the next question
+//   { action: "redraw",  state }   — same question, refresh the keyboard (toggle)
+//   { action: "done",    state, compiled } — last question answered
+//   { action: "cancel",  state }   — user closed the panel
+//   null — callback wasn't ours
+//
+// callback_data scheme: apx:ask:<correlationId>:<verb>[:<arg>]
+//   verbs: opt:<i>, next, back, skip, cancel
+export function applyCallback(chatId, data) {
+  const s = getState(chatId);
+  if (!s) return null;
+  if (typeof data !== "string" || !data.startsWith("apx:ask:")) return null;
+  const rest = data.slice("apx:ask:".length); // <corr>:<verb>[:<arg>]
+  const [corr, verb, arg] = rest.split(":");
+  if (corr !== s.correlationId) {
+    // Stale button from a previous flow.
+    return null;
+  }
+  const q = s.questions[s.index];
+  const ans = s.answers[s.index] || emptyAnswer();
+
+  if (verb === "opt") {
+    const optIdx = Number.parseInt(arg, 10);
+    if (!Number.isFinite(optIdx) || optIdx < 0 || optIdx >= (q.options?.length || 0)) {
+      return null;
+    }
+    if (q.multiSelect) {
+      // Toggle and stay on the same question.
+      if (ans.picked.has(optIdx)) ans.picked.delete(optIdx);
+      else ans.picked.add(optIdx);
+      ans.skipped = false;
+      s.answers[s.index] = ans;
+      saveState(chatId, s);
+      return { action: "redraw", state: s };
+    }
+    // Single-select: commit + advance.
+    ans.picked = new Set([optIdx]);
+    ans.skipped = false;
+    s.answers[s.index] = ans;
+    return advance(s);
+  }
+
+  if (verb === "next") return advance(s);
+  if (verb === "back") {
+    if (s.index > 0) {
+      s.index -= 1;
+      saveState(chatId, s);
+    }
+    return { action: "advance", state: s };
+  }
+  if (verb === "skip") {
+    s.answers[s.index] = { picked: new Set(), text: "", skipped: true };
+    return advance(s);
+  }
+  if (verb === "cancel") {
+    clearState(chatId);
+    return { action: "cancel", state: s };
+  }
+  return null;
+}
+
+function advance(s) {
+  if (s.index >= s.questions.length - 1) {
+    const compiled = compileAnswers(s);
+    clearState(s.chatId);
+    return { action: "done", state: s, compiled };
+  }
+  s.index += 1;
+  saveState(s.chatId, s);
+  return { action: "advance", state: s };
+}
+
+// Build the initial state and persist it. Caller must follow up with the
+// first sendMessage (use formatQuestionText + buildKeyboard).
+export function startFlow({ chatId, projectId, authorId, questions, resume }) {
+  const state = {
+    chatId: String(chatId),
+    projectId: projectId != null ? String(projectId) : null,
+    authorId: authorId != null ? String(authorId) : null,
+    correlationId: genCorrelationId(),
+    questions,
+    answers: questions.map(() => emptyAnswer()),
+    index: 0,
+    messageId: null,
+    createdAt: Date.now(),
+    lastTouchedAt: Date.now(),
+    resume,
+  };
+  saveState(chatId, state);
+  return state;
+}
+
+// Test-only: clear the global store between unit tests.
+export function _reset() {
+  STORE.clear();
+}