@agentprojectcontext/apx 1.39.0 → 1.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -41,7 +41,6 @@
     "prepack": "node scripts/sync-apc-skill.js && node scripts/build-web.js",
     "postinstall": "node src/interfaces/cli/postinstall.js"
   },
-  "packageManager": "pnpm@10.25.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentui/core": "^0.2.16",

package/src/core/agent/constants.js

@@ -1,4 +1,10 @@
-export const MAX_TOOL_ITERS = 6;
+// Per-turn tool-loop budget for conversational surfaces (telegram/desktop/voice
+// /deck). The LAST of these iterations is reserved by run-agent.js for a
+// tool-free, model-authored wrap-up — so a multi-step task gets ~N-1 action
+// steps and always closes with a contextual message instead of going silent.
+// Coding surfaces (web Code / terminal Build) raise this via maxIters and use
+// the finish-tool completionContract instead.
+export const MAX_TOOL_ITERS = 10;
 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

package/src/core/agent/retry.js

@@ -60,6 +60,15 @@ export function isRetryableEngineError(err) {
     // → model couldn't pick a tool → retry on a different model.
     if (status === 400) {
       if (/failed to call a function|did not produce a (valid )?tool/i.test(msg)) return true;
+      // Ollama tool-call grammar failure: small / cloud models that can't emit
+      // structured tool JSON return a 400 with a parse error like
+      //   "Value looks like object, but can't find closing '}' symbol"
+      // That's the model failing to produce tools, not our payload being
+      // malformed — advance to a tool-capable model instead of dying here.
+      if (/ollama/i.test(msg) &&
+          /looks like (object|array)|can'?t find closing|unexpected end of json|invalid (json|grammar)/i.test(msg)) {
+        return true;
+      }
       // explicit schema / param errors are our bug, not transient
       return false;
     }

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

@@ -84,6 +84,21 @@ export const FINISH_TOOL_SCHEMA = {
   },
 };
 
+// Behavioral nudge appended to the system prompt for the ONE tool-free wrap-up
+// step at the end of a turn (see the loop's `isFinalWrapUp`). This shapes
+// BEHAVIOR only — it never dictates wording or supplies a canned/templated
+// sentence. The reply the user sees is 100% model-authored and varies with
+// what the model actually did this turn. We do NOT mention any "tool limit":
+// the model just speaks from where it is. Critically it must not claim work it
+// didn't do (weak models otherwise fabricate "all done").
+const WRAPUP_NUDGE =
+  "\n\n[Internal note — last step of this turn. No more tools will run now. " +
+  "Reply in plain prose, in the user's language, from your own context: briefly " +
+  "say what you actually accomplished so far (check the tool results above — do " +
+  "NOT claim anything you didn't do), and if work is still pending, name what's " +
+  "left and ask the user whether you should continue. Do not mention limits, " +
+  "steps, or iterations — just talk naturally.]";
+
 /**
  * Shared tool-calling agent loop used by super-agent and future surfaces.
  */
@@ -222,6 +237,12 @@ export async function runAgent({
   };
   let usePseudoTools = false;
   let ackOnlyStreak = 0;
+  // "Never end on silence": a model call that returns no tool calls AND no
+  // usable text is a dud (weak models do this). We re-prompt instead of ending
+  // the turn empty, and the retry does NOT consume an iteration of the tool
+  // budget. Bounded so a model that only ever returns empty can't spin forever.
+  let emptyRetries = 0;
+  const MAX_EMPTY_RETRIES = 2;
   // Side-effect dedupe. Weaker models (Gemini especially) sometimes
   // re-emit the SAME tool call across iterations — e.g. send_telegram
   // three times with identical args, spamming the user. For tools
@@ -276,25 +297,44 @@ export async function runAgent({
   for (let iter = 0; iter < maxIters; iter++) {
     // Merge any tools activated via discover_tools on the previous iteration.
     drainPendingTools();
-    await emitProgress(onEvent, { type: "model_start", iteration: iter + 1, model: activeModel });
+    // Final iteration of a non-contract turn: the model is out of action steps.
+    // Rather than cut off silently mid-tool-call, we run ONE tool-free step so
+    // the model writes a natural closing in its OWN words — what it did, what's
+    // left, and (if anything remains) whether to continue. We change only the
+    // STRUCTURE (no tools this step) + a behavioral nudge; the wording is
+    // entirely the model's. Coding surfaces keep their finish-tool flow, so
+    // this never applies under completionContract.
+    const isFinalWrapUp =
+      !useContract && effectiveSchemas.length > 0 && iter === maxIters - 1;
+    await emitProgress(onEvent, {
+      type: isFinalWrapUp ? "final_wrapup" : "model_start",
+      iteration: iter + 1,
+      model: activeModel,
+    });
     const forceTool =
+      !isFinalWrapUp &&
       effectiveSchemas.length > 0 &&
       (useContract ||
         (ackOnlyStreak > 0 && ackOnlyStreak <= MAX_CONSECUTIVE_ACKS));
+    const baseSystem = usePseudoTools
+      ? pseudoToolSystem(system, effectiveSchemas)
+      : system;
     let result;
     try {
       result = await tryCallEngine({
-        system: usePseudoTools ? pseudoToolSystem(system, effectiveSchemas) : system,
+        system: isFinalWrapUp ? baseSystem + WRAPUP_NUDGE : baseSystem,
         messages: conversation,
         config: globalConfig,
-        tools: usePseudoTools ? null : effectiveSchemas,
-        toolChoice: usePseudoTools ? null : (forceTool ? "required" : "auto"),
+        // On the wrap-up step we withhold tools entirely so the model must
+        // answer in prose — same as a real engine called with tools omitted.
+        tools: (usePseudoTools || isFinalWrapUp) ? null : effectiveSchemas,
+        toolChoice: (usePseudoTools || isFinalWrapUp) ? null : (forceTool ? "required" : "auto"),
         // Smaller cap by default: 1024 ate too much of the cheap-tier TPM
         // budget. The super-agent rarely emits long replies; tool args are
         // small. Summarization callers raise it via the maxTokens arg.
         maxTokens,
         signal,
-        onToken: (!forceTool && onToken) ? onToken : null,
+        onToken: ((!forceTool || isFinalWrapUp) && onToken) ? onToken : null,
       });
     } catch (e) {
       if (usePseudoTools && /^ollama:/i.test(String(activeModel || "")) && /ollama\s+500/i.test(String(e?.message || "")) && trace.length > 0) {
@@ -333,6 +373,17 @@ export async function runAgent({
 
     if (!toolCalls || toolCalls.length === 0) {
       lastText = cleanTextOfPseudoToolCalls(lastText) || lastText;
+      // Dud turn (no tools, no text): re-prompt instead of ending empty, and
+      // don't let it cost an iteration of the tool budget. `iter -= 1` cancels
+      // the loop's `iter++`; the emptyRetries cap stops an all-empty model from
+      // looping forever (after which we break and the surface's last-resort
+      // floor sends a non-silent reply).
+      if (!String(lastText).trim() && emptyRetries < MAX_EMPTY_RETRIES) {
+        emptyRetries += 1;
+        await emitProgress(onEvent, { type: "empty_retry", iteration: iter + 1, attempt: emptyRetries });
+        iter -= 1;
+        continue;
+      }
       break;
     }
 

package/src/core/agent/tools/pseudo-tools.js

@@ -35,6 +35,18 @@ export function pseudoToolSystem(system, toolSchemas) {
 
 export function shouldRetryWithPseudoTools(modelId, error, alreadyPseudo) {
   if (alreadyPseudo) return false;
+  if (!/^ollama:/i.test(String(modelId || ""))) return false;
   const message = String(error?.message || "");
-  return /^ollama:/i.test(String(modelId || "")) && /ollama\s+500/i.test(message);
+  // Ollama can't always do native/structured tool-calling. Two failure shapes,
+  // same fix — drop structured tools and re-run with text-based pseudo-tools
+  // (parsed from the prompt, no grammar required):
+  //   • 5xx mid-call (model timeout / server error)
+  //   • 400 with a JSON/grammar parse error, e.g.
+  //     "Value looks like object, but can't find closing '}' symbol"
+  if (/ollama\s+5\d\d/i.test(message)) return true;
+  if (/ollama\s+400/i.test(message) &&
+      /looks like (object|array)|can'?t find closing|unexpected end of json|invalid (json|grammar)/i.test(message)) {
+    return true;
+  }
+  return false;
 }

package/src/core/channels/telegram/dispatch.js

@@ -436,6 +436,17 @@ export async function handleUpdate(self, u) {
                 iteration: ev.iteration,
               },
             });
+          } else if (ev.type === "engine_failed") {
+            // A model in the fallback chain errored; the loop is rotating to
+            // the next one. Log it so a mid-turn provider failure (rate limit,
+            // tool-grammar 400, …) is diagnosable instead of invisible.
+            self.log(
+              `telegram[${self.channel.name}] engine_failed: ${ev.model || "?"} (${ev.reason || "?"}) → ${ev.retry_with || "end of chain"}`,
+            );
+          } else if (ev.type === "model_routed" || ev.type === "model_retry") {
+            self.log(
+              `telegram[${self.channel.name}] ${ev.type}: model=${ev.model || "?"}${ev.reason ? ` reason=${ev.reason}` : ""}${ev.from_fallback ? " (fallback)" : ""}`,
+            );
           }
         } catch (e) {
           // A failed intermediate send must not abort the whole run.
@@ -542,9 +553,18 @@ export async function handleUpdate(self, u) {
     // turn isn't silently empty.
     const finalClean = replyText ? stripThinking(replyText).trim() : "";
     let toSend = "";
-    if (finalClean && finalClean !== lastStreamedText) toSend = finalClean;
-    else if (!finalClean && streamedCount === 0) {
-      toSend = t("telegram.fallback_listo", { lang: resolveLang(self.globalConfig) });
+    if (finalClean && finalClean !== lastStreamedText) {
+      toSend = finalClean;
+    } else if (!finalClean) {
+      // Never end a turn on silence. The loop's tool-free wrap-up normally
+      // fills finalClean with a model-authored closing (handled above); this is
+      // the last-resort floor for the rare case it still came back empty. A
+      // pure chit-chat turn that did nothing gets the short ack; a turn that
+      // streamed/acted but produced no closing gets a neutral "continue?" that
+      // does NOT claim completion.
+      toSend = streamedCount === 0
+        ? t("telegram.fallback_listo", { lang: resolveLang(self.globalConfig) })
+        : t("telegram.fallback_continue", { lang: resolveLang(self.globalConfig) });
     }
 
     stopTyping();

package/src/core/engines/mock.js

@@ -10,19 +10,32 @@ export default {
     return { ok: true, soft: true };
   },
 
-  async chat({ system, messages, model = "mock" }) {
+  async chat({ system, messages, model = "mock", tools }) {
     const last = [...messages].reverse().find((m) => m.role === "user");
     const userText = last?.content || "";
+    // Mirror real engines: tool calls are only possible when the caller offers
+    // tools. The loop withholds them on its tool-free wrap-up step, and we must
+    // honor that here — otherwise the mock would keep "calling" tools the model
+    // can't actually reach.
+    const toolsAvailable = Array.isArray(tools) && tools.length > 0;
     const requestedTool = userText.match(/\[mock:tool:([a-z_]+)\]/)?.[1];
+    const loopTool = userText.match(/\[mock:loop:([a-z_]+)\]/)?.[1];
     const finishSummary = userText.match(/\[mock:finish:([^\]]*)\]/)?.[1];
     const hasToolResult = messages.some((m) => m.role === "tool");
-    // Completion-contract path: once a tool has run, emit a `finish` call with
-    // the requested summary so tests can exercise the loop's graceful exit.
-    if (finishSummary != null && hasToolResult) {
+    // `[mock:empty]` → a dud turn (no text, no tools) to exercise the loop's
+    // empty-retry / never-end-silent guard.
+    if (/\[mock:empty\]/.test(userText)) {
+      return {
+        text: "",
+        usage: { input_tokens: userText.length, output_tokens: 0 },
+        raw: { model, mock: true },
+      };
+    }
+    const mkToolCall = (name, id) => {
       const toolCall = {
-        id: "mock-finish-1",
+        id,
         type: "function",
-        function: { name: "finish", arguments: JSON.stringify({ summary: finishSummary }) },
+        function: { name, arguments: "{}" },
       };
       return {
         text: "",
@@ -31,12 +44,14 @@ export default {
         usage: { input_tokens: userText.length, output_tokens: 4 },
         raw: { model, mock: true },
       };
-    }
-    if (requestedTool && !hasToolResult) {
+    };
+    // Completion-contract path: once a tool has run, emit a `finish` call with
+    // the requested summary so tests can exercise the loop's graceful exit.
+    if (finishSummary != null && hasToolResult && toolsAvailable) {
       const toolCall = {
-        id: "mock-call-1",
+        id: "mock-finish-1",
         type: "function",
-        function: { name: requestedTool, arguments: "{}" },
+        function: { name: "finish", arguments: JSON.stringify({ summary: finishSummary }) },
       };
       return {
         text: "",
@@ -46,6 +61,14 @@ export default {
         raw: { model, mock: true },
       };
     }
+    // `[mock:loop:<tool>]` → re-fire the tool every step it's offered, modeling
+    // a model that never stops on its own (drives the loop to its cap).
+    if (loopTool && toolsAvailable) {
+      return mkToolCall(loopTool, "mock-loop-1");
+    }
+    if (requestedTool && !hasToolResult && toolsAvailable) {
+      return mkToolCall(requestedTool, "mock-call-1");
+    }
 
     const sysHint = system ? ` (system: ${system.slice(0, 40)}…)` : "";
     return {

package/src/core/i18n/en.js

@@ -1,9 +1,7 @@
-// Backend strings — English (en).
+// Backend strings — English (en). This is also the default fallback locale.
 export default {
   "telegram.heads_up": "On it — working on that… 🛠️",
   "telegram.reset_ack": "Done, context cleared. Starting fresh. What do you need?",
-  "telegram.error_generic": "Something broke on my side — already logged.",
   "telegram.fallback_listo": "Done.",
-
-  "common.unknown_error": "Something went wrong.",
+  "telegram.fallback_continue": "Made some headway. Want me to keep going?",
 };

package/src/core/i18n/es.js

@@ -4,9 +4,6 @@ export default {
   // Telegram channel
   "telegram.heads_up": "Dale, estoy con eso… 🛠️",
   "telegram.reset_ack": "Listo, contexto borrado. Arranco un hilo nuevo, ¿qué necesitás?",
-  "telegram.error_generic": "Algo se rompió de mi lado — ya lo registré.",
   "telegram.fallback_listo": "Listo.",
-
-  // Generic helpers reused from several surfaces
-  "common.unknown_error": "Algo salió mal.",
+  "telegram.fallback_continue": "Avancé con eso. ¿Querés que siga?",
 };

package/src/core/i18n/index.js

@@ -16,7 +16,11 @@ import es from "./es.js";
 import pt from "./pt.js";
 
 const DICTS = Object.freeze({ en, es, pt });
-const DEFAULT_LANG = "es";
+// English is the universal fallback: any unrecognized language code resolves
+// to "en" rather than forcing a per-country dict. Real agent replies are
+// model-authored and already come back in the user's language; these dicts
+// only cover the few host-emitted strings that never pass through the model.
+const DEFAULT_LANG = "en";
 
 /**
  * Pull the user's preferred language code from a globalConfig snapshot.

package/src/core/i18n/pt.js

@@ -2,8 +2,6 @@
 export default {
   "telegram.heads_up": "Já estou nisso… 🛠️",
   "telegram.reset_ack": "Pronto, contexto limpo. Começando do zero — do que você precisa?",
-  "telegram.error_generic": "Algo quebrou do meu lado — já registrei.",
   "telegram.fallback_listo": "Pronto.",
-
-  "common.unknown_error": "Algo deu errado.",
+  "telegram.fallback_continue": "Avancei com isso. Quer que eu continue?",
 };

package/src/core/routines/runner.js

@@ -157,7 +157,8 @@ async function handleTelegram(ctx, routine) {
   const { channel, chat_id, text } = routine.spec;
   if (!text) throw new Error("telegram routine needs spec.text");
   await tg.send({ channel, chat_id, text });
-  return { status: "ok" };
+  // Return the (interpolated) text so the run detail can show what was sent.
+  return { status: "ok", text };
 }
 
 function handleShell(ctx, routine) {
@@ -296,7 +297,9 @@ export async function runRoutineNow(ctx, routine) {
           ...routine,
           spec: {
             ...routine.spec,
+            // {{pre_output}} works in both the LLM prompt and the telegram text.
             prompt: injectPreOutput(routine.spec?.prompt, preStdout),
+            text: injectPreOutput(routine.spec?.text, preStdout),
           },
         }
       : routine;
@@ -323,6 +326,7 @@ export async function runRoutineNow(ctx, routine) {
   }
 
   // ── Phase 3: post_commands ────────────────────────────────────────────────
+  const postRuns = [];
   if (hasPostCmds) {
     const llmOutput = result?.reply || result?.text || "";
     const postEnv = {
@@ -333,7 +337,8 @@ export async function runRoutineNow(ctx, routine) {
     };
     for (const rawCmd of routine.post_commands) {
       const cmd = resolveArtifactRef(rawCmd, storagePath);
-      await runShellCmd(cmd, postEnv, cwd);
+      const r = await runShellCmd(cmd, postEnv, cwd);
+      postRuns.push({ cmd: rawCmd, exit: r.exitCode, stdout: (r.stdout || "").slice(0, 4000), stderr: (r.stderr || "").slice(0, 2000) });
     }
   }
 
@@ -358,7 +363,14 @@ export async function runRoutineNow(ctx, routine) {
     body: status === "ok"
       ? `routine ${routine.name} ok${skip ? " (skipped LLM)" : ""}`
       : `routine ${routine.name} error: ${errMsg}`,
-    meta: { routine: routine.name, status, skipped: skip, result },
+    meta: {
+      routine: routine.name, status, skipped: skip, result,
+      // Persisted run flow so the UI can replay pre → action → post.
+      flow: {
+        pre: hasPreCmds ? { output: preStdout.slice(0, 8000), exit: preExitCode } : null,
+        post: postRuns.length ? postRuns : null,
+      },
+    },
   });
   return { ...result, last_run_at: lastRun, next_run_at: next };
 }

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

@@ -4,6 +4,7 @@
 //
 // Both are auth-gated (the global middleware applies).
 import { readConfig } from "#core/config/index.js";
+import { exec } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -49,6 +50,34 @@ export function register(app, { scheduler, plugins, config }) {
     setTimeout(() => process.exit(0), 50);
   });
 
+  // Opens the OS-native folder picker on the daemon host and resolves with
+  // the absolute path the user chose. macOS uses osascript; Linux uses
+  // zenity (if present); Windows uses PowerShell's Shell.Application. If the
+  // platform lacks a usable picker — or none is installed — the endpoint
+  // returns 501 so the frontend can fall back to the inline directory list.
+  app.get("/admin/fs/pick-dir", (req, res) => {
+    const prompt = String(req.query.prompt || "Select a folder").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    const platform = process.platform;
+    let cmd;
+    if (platform === "darwin") {
+      // try/end-try makes cancel exit with code 0 + empty stdout so we can
+      // distinguish "cancelled" from "no picker available".
+      cmd = `osascript -e 'try' -e 'POSIX path of (choose folder with prompt "${prompt}")' -e 'on error' -e 'return ""' -e 'end try'`;
+    } else if (platform === "linux") {
+      cmd = `command -v zenity >/dev/null && zenity --file-selection --directory --title="${prompt}" 2>/dev/null || true`;
+    } else if (platform === "win32") {
+      cmd = `powershell -NoProfile -Command "$f = (New-Object -ComObject Shell.Application).BrowseForFolder(0, '${prompt.replace(/'/g, "''")}', 0, 0); if ($f) { $f.Self.Path }"`;
+    } else {
+      return res.status(501).json({ error: "Native folder picker not supported on this platform" });
+    }
+    exec(cmd, { timeout: 5 * 60 * 1000 }, (err, stdout) => {
+      if (err) return res.status(500).json({ error: err.message });
+      const picked = (stdout || "").trim().replace(/[\r\n]+$/g, "");
+      if (!picked) return res.json({ cancelled: true });
+      res.json({ path: picked.replace(/\/+$/, "") });
+    });
+  });
+
   app.get("/admin/fs/dirs", (req, res) => {
     const requested = String(req.query.path || os.homedir());
     const base = path.resolve(requested.replace(/^~(?=$|\/)/, os.homedir()));