@agentprojectcontext/apx 1.24.0 → 1.27.1

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

@@ -0,0 +1,423 @@
+import { callEngine } from "../engines/index.js";
+import {
+  extractPseudoToolCalls,
+  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 {
+  isShortConfirmation,
+  lastAssistantAskedForConfirmation,
+  isGhostResponse,
+  looksLikeActionRequest,
+} from "./ghost-guard.js";
+import { pseudoToolSystem, shouldRetryWithPseudoTools } from "./pseudo-tools.js";
+import { filterToolSchemas } from "./tools-overlap.js";
+import { isRetryableEngineError, shortRetryReason } from "./retry.js";
+
+async function emitProgress(onEvent, event) {
+  if (typeof onEvent !== "function") return;
+  await onEvent(event);
+}
+
+function summarizeForTrace(r) {
+  if (r === null || r === undefined) return r;
+  const s = JSON.stringify(r);
+  if (s.length <= 400) return r;
+  return s.slice(0, 380) + "…(truncated)";
+}
+
+function fallbackFinalText(trace, error) {
+  const lines = [
+    "Tool execution completed, but the model failed while composing the final answer.",
+    `Engine error: ${String(error?.message || error).slice(0, 220)}`,
+    "Trace:",
+  ];
+  for (const item of trace.slice(-8)) {
+    lines.push(`- ${item.tool}: ${previewTraceResult(item.result)}`);
+  }
+  return lines.join("\n");
+}
+
+function previewTraceResult(result) {
+  if (result === null || result === undefined) return "ok";
+  if (typeof result === "string") return result.slice(0, 180);
+  if (result.error) return `error: ${String(result.error).slice(0, 180)}`;
+  if (result.path) return String(result.path).slice(0, 180);
+  if (result.content) return String(result.content).slice(0, 180);
+  if (result.results) return JSON.stringify(result.results).slice(0, 180);
+  return JSON.stringify(result).slice(0, 180);
+}
+
+// Loop-control tool injected when `completionContract` is on (coding surfaces).
+// With toolChoice:"required" the model can no longer end a turn by emitting
+// prose ("now I'll edit the file." → stop). It must EITHER call a real tool to
+// take the next step, OR call `finish` to declare the task complete. This makes
+// "keep going until done" enforceable by protocol structure — no language
+// heuristics, so it works regardless of the reply language.
+export const FINISH_TOOL_SCHEMA = {
+  type: "function",
+  function: {
+    name: "finish",
+    description:
+      "Call this ONLY when the user's request is fully complete and no step " +
+      "remains. Put your final answer / summary of what you did in `summary` " +
+      "(in the user's language). If anything is still pending, do NOT call " +
+      "finish — call the next tool and keep working instead.",
+    parameters: {
+      type: "object",
+      properties: {
+        summary: {
+          type: "string",
+          description: "Final answer or concise summary of the work completed.",
+        },
+      },
+      required: ["summary"],
+    },
+  },
+};
+
+/**
+ * Shared tool-calling agent loop used by super-agent and future surfaces.
+ */
+export async function runAgent({
+  globalConfig,
+  system,
+  prompt,
+  previousMessages = [],
+  overrideModel = null,
+  toolSchemas,
+  makeToolHandlers,
+  toolHandlerCtx,
+  onEvent = null,
+  signal,
+  onToken = null,
+  agentName = "apx",
+  suppressTools = null, // optional list of tool names to remove from the registry
+  // Per-reply output cap. Defaults to 512 (tuned for chit-chat + small tool
+  // args on cheap-tier TPM budgets). Summarization callers raise this because
+  // "thinking" models (gemini-2.5-flash) burn the budget reasoning and emit
+  // empty text on dense input when it's too low.
+  maxTokens = 512,
+  // Max tool-loop iterations. Defaults to MAX_TOOL_ITERS (tuned for chit-chat
+  // surfaces). The Code module raises this so a multi-step coding task can run
+  // to completion (read → edit → run → verify …) instead of stopping early.
+  maxIters = MAX_TOOL_ITERS,
+  // Structural "keep going until done" contract for coding surfaces. When on:
+  //   1. a `finish` tool is injected into the schema set, and
+  //   2. toolChoice is forced to "required" on EVERY iteration,
+  // so the model can only advance (call a tool) or stop (call finish) — it can
+  // never end the turn by narrating the next step. Language-agnostic by design.
+  completionContract = false,
+}) {
+  const routing = await resolveActiveModel(globalConfig, { overrideModel });
+  // Mutable: lazy-retry can rotate to a different model mid-loop on 429/413/5xx.
+  let activeModel = routing.modelId;
+
+  // Build the chain to walk on retryable failures: everything in
+  // fallbackModels() that isn't `activeModel` already AND wasn't already
+  // marked unhealthy by resolveActiveModel(). No point retrying with Ollama
+  // when /api/tags strict check just told us the model isn't pulled.
+  const triedHealth = new Map(
+    (routing.tried || []).map((t) => [t.modelId, t.healthy !== false])
+  );
+  const retryChain = fallbackModels(globalConfig).filter((m) => {
+    if (m === activeModel) return false;
+    if (triedHealth.get(m) === false) return false;
+    return true;
+  });
+
+  if (routing.fromFallback) {
+    await emitProgress(onEvent, {
+      type: "model_routed",
+      model: activeModel,
+      provider: routing.provider,
+      from_fallback: true,
+      tried: routing.tried,
+    });
+  }
+
+  // Suppression: callers (notably the routine runner) can disable tools whose
+  // output would duplicate post_commands. We filter the schemas the engine
+  // sees AND keep a deny-set so a model that hallucinates a suppressed tool
+  // call gets a clear error rather than firing.
+  let effectiveSchemas = Array.isArray(suppressTools) && suppressTools.length > 0
+    ? filterToolSchemas(toolSchemas, suppressTools)
+    : toolSchemas;
+  const suppressed = new Set(Array.isArray(suppressTools) ? suppressTools : []);
+  if (suppressed.size > 0) {
+    await emitProgress(onEvent, {
+      type: "tools_suppressed",
+      tools: [...suppressed],
+      reason: "post_commands_overlap",
+    });
+  }
+  // Completion contract: only meaningful when there are real tools to choose
+  // between. Inject `finish` so the model has a graceful way to end the turn
+  // under toolChoice:"required".
+  const useContract = completionContract && effectiveSchemas.length > 0;
+  if (useContract) {
+    effectiveSchemas = [...effectiveSchemas, FINISH_TOOL_SCHEMA];
+  }
+
+  const rawHandlers = makeToolHandlers({
+    ...toolHandlerCtx,
+    implicitConfirmation:
+      isShortConfirmation(prompt) && lastAssistantAskedForConfirmation(previousMessages),
+  });
+  const handlers = suppressed.size > 0
+    ? new Proxy(rawHandlers, {
+        get(target, name) {
+          if (typeof name === "string" && suppressed.has(name)) {
+            return async () => ({
+              error: `tool "${name}" is suppressed for this invocation (post_commands already cover this output channel)`,
+            });
+          }
+          return target[name];
+        },
+      })
+    : rawHandlers;
+
+  const conversation = [...previousMessages, { role: "user", content: prompt }];
+  const trace = [];
+  let totalUsage = { input_tokens: 0, output_tokens: 0 };
+  let lastText = "";
+  let usePseudoTools = false;
+  let ackOnlyStreak = 0;
+  // 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
+  // that mutate the world we remember the (name + args) signature and
+  // short-circuit duplicates with a synthetic "already done" result
+  // instead of re-running. Read-only tools are exempt (idempotent and
+  // sometimes legitimately repeated, like list_tasks before/after).
+  const sideEffectExecuted = new Map();
+  const SIDE_EFFECT_TOOLS = new Set([
+    "send_telegram",
+    "create_task",
+    "write_file",
+    "edit_file",
+    "run_shell",
+    "call_runtime",
+    "add_project",
+    "set_identity",
+  ]);
+  const sideEffectSignature = (name, args) => {
+    try {
+      return `${name}:${JSON.stringify(args)}`;
+    } catch {
+      return `${name}:<unserializable>`;
+    }
+  };
+
+  // Engine call wrapped with lazy retry: on 413/429/5xx/rate-limit/etc, try
+  // the next model in `retryChain` instead of bubbling. Stops when the chain
+  // is exhausted; non-retryable errors (auth, bad payload) throw immediately.
+  // See spec/backlog/13 + src/core/agent/retry.js for the classifier.
+  const tryCallEngine = async (params, { allowRetry = true } = {}) => {
+    while (true) {
+      try {
+        return await callEngine({ ...params, modelId: activeModel });
+      } catch (e) {
+        if (!allowRetry || retryChain.length === 0 || !isRetryableEngineError(e)) throw e;
+        const nextModel = retryChain.shift();
+        await emitProgress(onEvent, {
+          type: "engine_failed",
+          model: activeModel,
+          reason: shortRetryReason(e),
+          retry_with: nextModel,
+        });
+        activeModel = nextModel;
+        // After switching providers the pseudo-tools mode (Ollama-only) is no
+        // longer relevant; reset so we use structured tools on the new model.
+        if (usePseudoTools) usePseudoTools = false;
+      }
+    }
+  };
+
+  for (let iter = 0; iter < maxIters; iter++) {
+    await emitProgress(onEvent, { type: "model_start", iteration: iter + 1, model: activeModel });
+    // Force a tool call on iter 0 ONLY when the user message looks like a real
+    // action request ("listame…", "mandá…", "buscá…"). For chit-chat ("hola",
+    // "qué tal") forcing a tool makes weaker models (llama-3.3 via Groq,
+    // qwen3-32b) emit a malformed tool_calls payload — Groq then rejects the
+    // whole turn with 400 "Failed to call a function". Better: let the model
+    // choose between text and tool when the prompt is conversational.
+    const forceTool =
+      effectiveSchemas.length > 0 &&
+      (useContract ||
+        (iter === 0 && looksLikeActionRequest(prompt)) ||
+        (ackOnlyStreak > 0 && ackOnlyStreak <= MAX_CONSECUTIVE_ACKS));
+    let result;
+    try {
+      result = await tryCallEngine({
+        system: usePseudoTools ? pseudoToolSystem(system, effectiveSchemas) : system,
+        messages: conversation,
+        config: globalConfig,
+        tools: usePseudoTools ? null : effectiveSchemas,
+        toolChoice: usePseudoTools ? 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,
+      });
+    } catch (e) {
+      if (usePseudoTools && /^ollama:/i.test(String(activeModel || "")) && /ollama\s+500/i.test(String(e?.message || "")) && trace.length > 0) {
+        await emitProgress(onEvent, { type: "model_retry", reason: "ollama_final_response_500", iteration: iter + 1 });
+        lastText = fallbackFinalText(trace, e);
+        break;
+      }
+      if (!shouldRetryWithPseudoTools(activeModel, e, usePseudoTools)) throw e;
+      usePseudoTools = true;
+      await emitProgress(onEvent, { type: "model_retry", reason: "ollama_structured_tools_500", iteration: iter + 1 });
+      result = await tryCallEngine({
+        system: pseudoToolSystem(system, toolSchemas),
+        messages: conversation,
+        config: globalConfig,
+        tools: null,
+        toolChoice: null,
+        maxTokens,
+        signal,
+        onToken: (iter > 0 && onToken) ? onToken : null,
+      });
+    }
+
+    totalUsage.input_tokens += result.usage?.input_tokens || 0;
+    totalUsage.output_tokens += result.usage?.output_tokens || 0;
+    lastText = result.text || "";
+
+    let toolCalls = result.tool_calls || (result.message && result.message.tool_calls) || null;
+
+    if ((!toolCalls || toolCalls.length === 0) && lastText) {
+      const pseudo = extractPseudoToolCalls(lastText);
+      if (pseudo.length > 0) {
+        toolCalls = pseudo;
+        lastText = cleanTextOfPseudoToolCalls(lastText);
+      }
+    }
+
+    if (!toolCalls || toolCalls.length === 0) {
+      if (iter === 0 && isGhostResponse(lastText) && looksLikeActionRequest(prompt)) {
+        await emitProgress(onEvent, { type: "ghost_response_detected", text: lastText });
+        conversation.push({ role: "assistant", content: lastText });
+        conversation.push({
+          role: "user",
+          content:
+            "Remember: you must execute the action, not just confirm it. " +
+            "Call the tool now — action first, report after.",
+        });
+        continue;
+      }
+      lastText = cleanTextOfPseudoToolCalls(lastText) || lastText;
+      break;
+    }
+
+    const visibleText = cleanTextOfPseudoToolCalls(lastText).trim();
+    if (visibleText) {
+      await emitProgress(onEvent, { type: "assistant_text", text: visibleText, iteration: iter + 1 });
+    }
+
+    conversation.push({
+      role: "assistant",
+      content: result.text || "",
+      tool_calls: toolCalls,
+    });
+
+    let finishSummary = null;
+    for (const tc of toolCalls) {
+      const fn = tc.function || tc;
+      const name = fn.name;
+      let args = fn.arguments;
+      if (typeof args === "string") {
+        try { args = JSON.parse(args); } catch { args = {}; }
+      }
+      args = args || {};
+
+      // Completion contract: `finish` declares the task done. Capture its
+      // summary as the final text and stop processing the rest of this turn.
+      if (name === "finish") {
+        finishSummary = typeof args.summary === "string" ? args.summary : "";
+        break;
+      }
+
+      let toolResult;
+      const traceId = `${iter + 1}:${trace.length + 1}`;
+      await emitProgress(onEvent, {
+        type: "tool_start",
+        trace: { id: traceId, tool: name, args, pending: true },
+        iteration: iter + 1,
+      });
+      // Dedupe identical side-effecting calls within this turn.
+      const sig = SIDE_EFFECT_TOOLS.has(name) ? sideEffectSignature(name, args) : null;
+      if (sig && sideEffectExecuted.has(sig)) {
+        toolResult = {
+          ok: true,
+          deduped: true,
+          note: `Ya ejecuté "${name}" con estos mismos argumentos en este turno; no lo repito.`,
+          previous: sideEffectExecuted.get(sig),
+        };
+        await emitProgress(onEvent, {
+          type: "tool_deduped",
+          trace: { id: traceId, tool: name, args },
+          iteration: iter + 1,
+        });
+      } else {
+        try {
+          const handler = handlers[name];
+          toolResult = handler ? await handler(args) : { error: `unknown tool: ${name}` };
+        } catch (e) {
+          toolResult = { error: e.message };
+        }
+        if (sig) sideEffectExecuted.set(sig, summarizeForTrace(toolResult));
+      }
+
+      const traceItem = { id: traceId, tool: name, args, result: summarizeForTrace(toolResult) };
+      trace.push(traceItem);
+      await emitProgress(onEvent, { type: "tool_result", trace: traceItem, iteration: iter + 1 });
+
+      // Groq (and strict OpenAI) require tool_call_id to be present and
+      // match the id of the tool_call in the previous assistant message.
+      // Real engines populate it; the pseudo-tool parser also assigns one
+      // (`pseudo_<…>`). Either way, surface it on the tool result message
+      // — otherwise Groq returns 400 "tool_call_id is missing".
+      conversation.push({
+        role: "tool",
+        tool_call_id: tc.id || `synth_${iter}_${trace.length}`,
+        tool_name: name,
+        content: JSON.stringify(toolResult),
+      });
+    }
+
+    // Task declared complete via the contract — emit the summary as the final
+    // assistant text and exit the loop.
+    if (finishSummary !== null) {
+      if (finishSummary) {
+        lastText = finishSummary;
+        await emitProgress(onEvent, { type: "assistant_text", text: finishSummary, iteration: iter + 1 });
+      }
+      break;
+    }
+
+    const allAckOnly = toolCalls.every((tc) => {
+      const n = (tc.function?.name) || tc.name;
+      return ACK_ONLY_TOOLS.has(n);
+    });
+    if (allAckOnly) {
+      ackOnlyStreak += 1;
+      await emitProgress(onEvent, { type: "ack_only_iter", iteration: iter + 1, streak: ackOnlyStreak });
+    } else {
+      ackOnlyStreak = 0;
+    }
+  }
+
+  return {
+    text: lastText,
+    usage: totalUsage,
+    name: agentName,
+    trace,
+    model: activeModel,
+    routing,
+  };
+}

package/src/core/agent/self-memory.js

@@ -0,0 +1,155 @@
+// Roby's own notebook — the super-agent's personal, persistent memory.
+//
+// This is distinct from:
+//   - identity.json   → who Roby is (name, personality, owner)
+//   - project agents' .apc/agents/<slug>/memory.md → per-agent, per-project
+//   - sessions        → raw transcripts of past work (search_sessions)
+//
+// It is a single free-form markdown file at ~/.apx/memory.md that Roby keeps
+// itself: durable facts about the owner, ongoing threads, decisions, and the
+// gist of what it has been working on (which it refreshes by skimming its own
+// recent sessions). A bounded slice is injected into every super-agent prompt;
+// the `remember` / `read_self_memory` tools write and read it.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const SELF_MEMORY_PATH = path.join(os.homedir(), ".apx", "memory.md");
+
+// How much of the notebook to inline into the system prompt. The full file is
+// always readable via read_self_memory; this only bounds the always-on slice
+// so a long notebook can't blow the token budget on cheap channels.
+export const SELF_MEMORY_PROMPT_LIMIT = 2000;
+
+export function readSelfMemory() {
+  try {
+    return fs.readFileSync(SELF_MEMORY_PATH, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** Bounded slice for the system prompt. Returns "" when the notebook is empty. */
+export function readSelfMemoryForPrompt(limit = SELF_MEMORY_PROMPT_LIMIT) {
+  const body = readSelfMemory().trim();
+  if (!body) return "";
+  if (body.length <= limit) return body;
+  return body.slice(0, limit).trimEnd() + "\n… (truncated — call read_self_memory for the full notebook)";
+}
+
+// HH:MM (UTC) for the current time — used to tag notes per the cross-channel
+// format "[HH:MM][canal] nota".
+function nowHm() {
+  return new Date().toISOString().slice(11, 16);
+}
+
+/**
+ * Append a dated note to the notebook. Each note is a markdown bullet under a
+ * `## YYYY-MM-DD` heading so the file stays chronologically skimmable. Creates
+ * the file (and ~/.apx) on first write.
+ *
+ * opts.channel — when given, the bullet is tagged "[HH:MM][channel] note" so
+ *   the cross-channel broker (and the RAG indexer) can attribute the note to a
+ *   surface and time. Without it the legacy "- note" form is kept.
+ */
+export function appendSelfMemory(note, opts = {}) {
+  const text = String(note || "").trim();
+  if (!text) throw new Error("nothing to remember (empty note)");
+  fs.mkdirSync(path.dirname(SELF_MEMORY_PATH), { recursive: true });
+
+  const today = new Date().toISOString().slice(0, 10);
+  const existing = readSelfMemory();
+  const heading = `## ${today}`;
+  const oneLine = text.replace(/\n+/g, " ").trim();
+  const channel = String(opts.channel || "").trim().toLowerCase();
+  const tag = channel ? `[${opts.time || nowHm()}][${channel}] ` : "";
+  const bullet = `- ${tag}${oneLine}`;
+
+  let next;
+  if (!existing.trim()) {
+    next = `# Roby's notebook\n\n${heading}\n${bullet}\n`;
+  } else if (existing.includes(heading)) {
+    // Append the bullet under today's existing heading.
+    const lines = existing.split("\n");
+    const idx = lines.lastIndexOf(heading);
+    // Find the end of today's block (next heading or EOF).
+    let insertAt = lines.length;
+    for (let i = idx + 1; i < lines.length; i++) {
+      if (lines[i].startsWith("## ")) {
+        insertAt = i;
+        break;
+      }
+    }
+    // Trim trailing blank lines inside the block before inserting.
+    while (insertAt > idx + 1 && lines[insertAt - 1].trim() === "") insertAt--;
+    lines.splice(insertAt, 0, bullet);
+    next = lines.join("\n");
+    if (!next.endsWith("\n")) next += "\n";
+  } else {
+    const sep = existing.endsWith("\n") ? "" : "\n";
+    next = `${existing}${sep}\n${heading}\n${bullet}\n`;
+  }
+
+  fs.writeFileSync(SELF_MEMORY_PATH, next);
+  return { path: SELF_MEMORY_PATH, note: text };
+}
+
+// Ensure the notebook file exists (created empty-ish on daemon boot, Pieza 1).
+// Returns true if it created the file, false if it already existed.
+export function ensureSelfMemoryFile() {
+  try {
+    if (fs.existsSync(SELF_MEMORY_PATH)) return false;
+    fs.mkdirSync(path.dirname(SELF_MEMORY_PATH), { recursive: true });
+    fs.writeFileSync(SELF_MEMORY_PATH, "# Roby's notebook\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Parse the notebook into structured entries, oldest first. Tolerant of both
+// the legacy "- note" bullets and the tagged "[HH:MM][channel] note" /
+// "[YYYY-MM-DD HH:MM][channel] note" forms. Each entry:
+//   { date, time, channel, ts, text }
+export function parseSelfMemoryEntries(text) {
+  const out = [];
+  let date = "";
+  for (const raw of String(text || "").split("\n")) {
+    const line = raw.trim();
+    const h = line.match(/^##\s+(\d{4}-\d{2}-\d{2})/);
+    if (h) {
+      date = h[1];
+      continue;
+    }
+    const b = line.match(/^[-*]\s+(.*)$/);
+    if (!b) continue;
+    let rest = b[1].trim();
+    let time = "";
+    let channel = "";
+    // [YYYY-MM-DD HH:MM] (full timestamp) takes precedence over a bare time.
+    let m = rest.match(/^\[(\d{4}-\d{2}-\d{2})\s+(\d{1,2}:\d{2})\]\s*/);
+    if (m) {
+      date = m[1];
+      time = m[2];
+      rest = rest.slice(m[0].length);
+    } else {
+      m = rest.match(/^\[(\d{1,2}:\d{2})\]\s*/);
+      if (m) {
+        time = m[1];
+        rest = rest.slice(m[0].length);
+      }
+    }
+    // [channel]
+    const c = rest.match(/^\[([a-z0-9_-]+)\]\s*/i);
+    if (c) {
+      channel = c[1].toLowerCase();
+      rest = rest.slice(c[0].length);
+    }
+    rest = rest.trim();
+    if (!rest) continue;
+    const hm = time ? time.padStart(5, "0") : "00:00";
+    const ts = date ? `${date}T${hm}:00Z` : "";
+    out.push({ date, time, channel: channel || "memory", ts, text: rest });
+  }
+  return out;
+}