@agentprojectcontext/apx 1.10.1 → 1.10.3

package/package.json

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

package/src/cli/commands/session.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { findApfRoot, readAgents } from "../../core/parser.js";
 import { getOrCreateApxId } from "../../core/scaffold.js";
 import { generateSessionId } from "../../core/session-store.js";
-import { ensureProjectStorage } from "../../core/config.js";
+import { projectStorageRoot, ensureProjectStorage } from "../../core/config.js";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 
@@ -18,7 +18,7 @@ function requireRoot() {
 function requireStorageRoot(root) {
   const apxId = getOrCreateApxId(root);
   if (!apxId) throw new Error("could not resolve APX project storage id");
-  return ensureProjectStorage(apxId);
+  return projectStorageRoot(apxId);
 }
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");

package/src/cli/commands/sys.js

@@ -300,31 +300,93 @@ async function submitPrompt(pid, state, previousMessages, renderScreen, close) {
       model: state.activeModel,
     };
 
-    const result = await http.post(`/projects/${pid}/super-agent/chat`, body);
-    state.transcript.pop();
-    for (const trace of result.trace || []) {
-      state.transcript.push({ type: "tool", trace });
+    let result;
+    try {
+      result = await http.streamPost(
+        `/projects/${pid}/super-agent/chat/stream`,
+        body,
+        (event) => handleProgressEvent(event, state, renderScreen)
+      );
+    } catch (e) {
+      if (e.status !== 404) throw e;
+      result = await http.post(`/projects/${pid}/super-agent/chat`, body);
+      removeStatus(state);
+      for (const trace of result.trace || []) {
+        state.transcript.push({ type: "tool", trace });
+      }
     }
 
-    previousMessages.push({ role: "user", content: text });
-    previousMessages.push({ role: "assistant", content: result.text });
-    if (previousMessages.length > 20) previousMessages.splice(0, previousMessages.length - 20);
+    completeSuperAgentResult(result, text, startTime, state, previousMessages);
+  } catch (e) {
+    removeStatus(state);
+    state.transcript.push({ type: "error", text: e.message });
+  }
+
+  renderScreen();
+}
 
-    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-    state.usage.input += result.usage?.input_tokens || 0;
-    state.usage.output += result.usage?.output_tokens || 0;
-    state.usage.percent = Math.min(99, Math.round((state.usage.input / 200000) * 100));
+function removeStatus(state) {
+  const last = state.transcript[state.transcript.length - 1];
+  if (last?.type === "status") state.transcript.pop();
+}
 
+function handleProgressEvent(event, state, renderScreen) {
+  if (event.type === "model_start") {
+    const last = state.transcript[state.transcript.length - 1];
+    if (last?.type === "status") {
+      last.text = event.iteration > 1 ? `Thinking... step ${event.iteration}` : "Thinking...";
+      renderScreen();
+    }
+    return;
+  }
+
+  if (event.type === "assistant_text" && event.text) {
+    removeStatus(state);
     state.transcript.push({
       type: "assistant",
       name: state.activeAgent,
-      text: result.text,
-      meta: `${elapsed}s   ·   In: ${result.usage?.input_tokens || 0} Out: ${result.usage?.output_tokens || 0}`,
+      text: event.text,
+      meta: "intermediate",
     });
-  } catch (e) {
-    state.transcript.pop();
-    state.transcript.push({ type: "error", text: e.message });
+    renderScreen();
+    return;
   }
 
-  renderScreen();
+  if (event.type === "tool_start" && event.trace) {
+    removeStatus(state);
+    state.transcript.push({ type: "tool", trace: event.trace });
+    renderScreen();
+    return;
+  }
+
+  if (event.type === "tool_result" && event.trace) {
+    removeStatus(state);
+    const idx = state.transcript.findIndex(
+      (item) => item.type === "tool" && item.trace?.id && item.trace.id === event.trace.id
+    );
+    if (idx >= 0) state.transcript[idx] = { type: "tool", trace: event.trace };
+    else state.transcript.push({ type: "tool", trace: event.trace });
+    renderScreen();
+  }
+}
+
+function completeSuperAgentResult(result, userText, startTime, state, previousMessages) {
+  removeStatus(state);
+  if (!result) throw new Error("super-agent stream ended without final result");
+
+  previousMessages.push({ role: "user", content: userText });
+  previousMessages.push({ role: "assistant", content: result.text });
+  if (previousMessages.length > 20) previousMessages.splice(0, previousMessages.length - 20);
+
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+  state.usage.input += result.usage?.input_tokens || 0;
+  state.usage.output += result.usage?.output_tokens || 0;
+  state.usage.percent = Math.min(99, Math.round((state.usage.input / 200000) * 100));
+
+  state.transcript.push({
+    type: "assistant",
+    name: state.activeAgent,
+    text: result.text,
+    meta: `${elapsed}s   ·   In: ${result.usage?.input_tokens || 0} Out: ${result.usage?.output_tokens || 0}`,
+  });
 }

package/src/cli/http.js

@@ -91,9 +91,66 @@ async function request(method, path, body, opts = {}) {
   return json;
 }
 
+async function streamRequest(method, path, body, onEvent, opts = {}) {
+  if (opts.autoStart !== false) await ensureDaemon();
+  else if (!(await ping())) {
+    throw new Error(`apx daemon not running (no response on ${baseUrl()})`);
+  }
+
+  const res = await fetch(`${baseUrl()}${path}`, {
+    method,
+    headers: body ? { "content-type": "application/json" } : {},
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch {}
+    const err = new Error(json?.error || `${method} ${path} → ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+
+  if (!res.body?.getReader) {
+    throw new Error("streaming response is not supported by this Node.js runtime");
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let finalResult = null;
+
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() || "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const event = JSON.parse(line);
+      if (event.type === "final") finalResult = event.result;
+      if (event.type === "error") throw new Error(event.error || "stream error");
+      await onEvent?.(event);
+    }
+  }
+
+  buffer += decoder.decode();
+  if (buffer.trim()) {
+    const event = JSON.parse(buffer);
+    if (event.type === "final") finalResult = event.result;
+    if (event.type === "error") throw new Error(event.error || "stream error");
+    await onEvent?.(event);
+  }
+
+  return finalResult;
+}
+
 export const http = {
   get: (p, opts) => request("GET", p, undefined, opts),
   post: (p, body, opts) => request("POST", p, body, opts),
+  streamPost: (p, body, onEvent, opts) => streamRequest("POST", p, body, onEvent, opts),
   put: (p, body, opts) => request("PUT", p, body, opts),
   patch: (p, body, opts) => request("PATCH", p, body, opts),
   delete: (p, opts) => request("DELETE", p, undefined, opts),

package/src/cli/terminal-chat/renderer.js

@@ -229,6 +229,11 @@ function addToolBlock(lines, item, width) {
   addLine(lines, "", C.bg);
   addLine(lines, margin + C.muted + `→ ${label}${target ? " " + fit(String(target), inner) : ""}`, C.bg);
 
+  if (trace.pending) {
+    addLine(lines, margin + C.dim + "  " + C.muted + "running...", C.bg);
+    return;
+  }
+
   if (trace.tool === "write_file") {
     const heading = `# Wrote ${args.path || "file"}`;
     addLine(lines, margin + C.panel + " " + C.muted + heading + " ".repeat(Math.max(0, inner - visible(heading))), C.bg);

package/src/core/scaffold.js

@@ -256,6 +256,7 @@ export function getOrCreateApxId(root) {
   try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
   if (cfg.apx_id) return cfg.apx_id;
   const apxId = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+  console.log(`[apx] Generating new stable ID ${apxId} for project at ${root}`);
   cfg.apx_id = apxId;
   fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
   return apxId;

package/src/daemon/api.js

@@ -525,6 +525,50 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
   });
 
   // POST /projects/:pid/super-agent/chat
+  app.post("/projects/:pid/super-agent/chat/stream", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { prompt, contextNote, previousMessages, model } = req.body || {};
+    if (!prompt) return res.status(400).json({ error: "prompt required" });
+
+    res.setHeader("content-type", "application/x-ndjson; charset=utf-8");
+    res.setHeader("cache-control", "no-cache, no-transform");
+    res.setHeader("x-accel-buffering", "no");
+    res.flushHeaders?.();
+
+    const send = (event) => {
+      res.write(JSON.stringify(event) + "\n");
+    };
+
+    try {
+      const saResult = await runSuperAgent({
+        globalConfig: config,
+        projects,
+        plugins,
+        registries,
+        prompt,
+        contextNote: contextNote || `Context: Project ${p.id} (${p.name}) at ${p.path}`,
+        previousMessages: previousMessages || [],
+        overrideModel: model,
+        onEvent: send,
+      });
+      projects.rebuild(p.id);
+      send({
+        type: "final",
+        result: {
+          text: saResult.text,
+          usage: saResult.usage,
+          name: saResult.name,
+          trace: saResult.trace,
+        },
+      });
+      res.end();
+    } catch (e) {
+      send({ type: "error", error: e.message });
+      res.end();
+    }
+  });
+
   app.post("/projects/:pid/super-agent/chat", async (req, res) => {
     const p = project(req, res);
     if (!p) return;

package/src/daemon/db.js

@@ -37,9 +37,11 @@ export class ProjectManager {
     // Ensure directories exist for projects initialized before they were added.
     fs.mkdirSync(path.join(abs, ".apc", "commands"), { recursive: true });
 
-    // Ensure stable APX storage root exists (~/.apx/projects/<apx_id>/).
+    // Resolve stable APX storage ID (read from .apc/project.json).
     const apxId = getOrCreateApxId(abs);
-    const storagePath = ensureProjectStorage(apxId);
+    // Don't create the physical storage folder yet.
+    // Just resolve where it SHOULD be.
+    const storagePath = path.join(path.dirname(DEFAULT_PROJECT_STORE), apxId || "null");
 
     const entry = {
       id: this._nextId++,
@@ -48,8 +50,15 @@ export class ProjectManager {
       apxId,
       config: effectiveConfig(this.globalConfig, abs),
     };
-    // Project runtime messages stay in APX local storage.
-    entry.logMessage = (payload) => appendMessageToFs({ projectRoot: storagePath, ...payload });
+
+    // Lazy message logger: ensure directory exists ONLY when writing.
+    entry.logMessage = (payload) => {
+      if (entry.apxId) {
+        ensureProjectStorage(entry.apxId);
+      }
+      return appendMessageToFs({ projectRoot: entry.storagePath, ...payload });
+    };
+
     this.byId.set(entry.id, entry);
     this.byPath.set(abs, entry);
     return entry;

package/src/daemon/engines/mock.js

@@ -8,6 +8,23 @@ export default {
   async chat({ system, messages, model = "mock" }) {
     const last = [...messages].reverse().find((m) => m.role === "user");
     const userText = last?.content || "";
+    const requestedTool = userText.match(/\[mock:tool:([a-z_]+)\]/)?.[1];
+    const hasToolResult = messages.some((m) => m.role === "tool");
+    if (requestedTool && !hasToolResult) {
+      const toolCall = {
+        id: "mock-call-1",
+        type: "function",
+        function: { name: requestedTool, arguments: "{}" },
+      };
+      return {
+        text: "",
+        tool_calls: [toolCall],
+        message: { tool_calls: [toolCall] },
+        usage: { input_tokens: userText.length, output_tokens: 4 },
+        raw: { model, mock: true },
+      };
+    }
+
     const sysHint = system ? ` (system: ${system.slice(0, 40)}…)` : "";
     return {
       text: `[mock:${model}] received: ${userText}${sysHint}`,

package/src/daemon/super-agent-tools/tools/call-runtime.js

@@ -7,6 +7,8 @@ import {
   createRuntimeSession,
   extractApfResult,
 } from "../../apc-runtime-context.js";
+import { detectAll } from "../../env-detect.js";
+import { runProcess } from "../../runtimes/_spawn.js";
 import { getRuntime, RUNTIME_IDS } from "../../runtimes/index.js";
 import { buildAgentSystem, confirmedProperty, resolveProject } from "../helpers.js";
 
@@ -61,18 +63,43 @@ function buildRuntimeSystem(project, agent, runtime, sessionId, caller) {
   ].join("\n\n");
 }
 
+async function runtimeAvailability(runtime, rt) {
+  const probe = await runProcess({
+    command: rt.binary,
+    args: rt.versionFlag ? [rt.versionFlag] : ["--version"],
+    timeoutMs: 3000,
+  });
+  if (probe.exitCode === 0 || probe.stdout || probe.stderr) {
+    return { ok: true };
+  }
+
+  const detected = await detectAll();
+  const current = detected.find((d) => d.id === runtime || d.binary === rt.binary);
+  if (current?.installed) {
+    return { ok: true, detected };
+  }
+  return {
+    ok: false,
+    reason: current?.reason || `${rt.binary} not found`,
+    detected,
+    installed: detected
+      .filter((d) => d.category === "runtime" && d.installed)
+      .map((d) => d.id),
+  };
+}
+
 export default {
   name: "call_runtime",
   schema: {
     type: "function",
     function: {
       name: "call_runtime",
-      description: "Spawn an external CLI runtime (Claude Code, Codex, OpenCode, Aider, Cursor Agent, Gemini CLI, Qwen Code), optionally impersonating an APC agent.",
+      description: "Spawn an external CLI runtime (Claude Code, Codex, OpenCode, Aider, Cursor Agent, Gemini CLI, Qwen Code). Omit agent for the base APX/default self-run.",
       parameters: {
         type: "object",
         properties: {
           project: { type: "string" },
-          agent: { type: "string", description: "Optional APC agent slug from AGENTS.md, not runtime name. Omit when the user did not name an agent." },
+          agent: { type: "string", description: "APC agent slug. MANDATORY OMIT if you are acting as yourself (APX/vos mismo/default). Use ONLY if the user named a specific agent from AGENTS.md." },
           runtime: {
             type: "string",
             enum: RUNTIME_IDS,
@@ -108,6 +135,19 @@ export default {
       return { error: `${e.message}. Available runtimes: ${RUNTIME_IDS.join(", ")}` };
     }
 
+    const availability = await runtimeAvailability(runtime, rt);
+    if (!availability.ok) {
+      return {
+        error: `runtime "${runtime}" is not installed or not runnable (${availability.reason})`,
+        runtime,
+        binary: rt.binary,
+        installed_runtimes: availability.installed,
+        hint: availability.installed.length
+          ? `Try one of: ${availability.installed.join(", ")}`
+          : "No external runtime CLIs were detected. Run apx env detect for details.",
+      };
+    }
+
     const actor = agent?.slug || "apx";
     const session = createRuntimeSession({
       projectRoot: p.path,
@@ -163,6 +203,7 @@ export default {
         apc_session: session.id,
         exit_code: r.exitCode,
         output: (r.output || "").slice(0, 4000),
+        stderr: (r.stderr || "").slice(0, 2000),
         truncated: (r.output || "").length > 4000,
         external_session_path: r.externalSessionPath || null,
         session_id: r.sessionId || null,

package/src/daemon/super-agent.js

@@ -53,13 +53,14 @@ HARD RULES (do not deviate):
 7. Stay brief: under 6 sentences unless asked for detail.
 8. You DO see recent prior turns of this chat as previous messages when applicable. **Use them ONLY to disambiguate references** (e.g. "el primero" → first project mentioned earlier). For ANY factual data — agent details, MCP details, file contents, memory — RE-CALL the tool. Past turns are context, not a cache. Models change, agents change, files change.
 9. /reset or /new from the user means "forget previous turns and answer this one fresh" — if you see those prefixes the operator already cleared the context for you.
-10. DELEGATION RULE: when the user asks an agent to do a task, use call_agent (unless they specify opening it in a runtime, then see rule 11).
-11. DISPATCH RULE: when the user asks to work inside Claude, Codex, OpenCode, Aider, Cursor, Gemini CLI, or Qwen Code, use call_runtime({runtime: 'claude-code'|'codex'|'opencode'|'aider'|'cursor-agent'|'gemini-cli'|'qwen-code', prompt: <user's request>}). If they explicitly name an agent to spawn, pass agent: <slug>. If they don't name an agent, DO NOT pass an agent argument. When an agent is passed, its memory + skills become the system prompt of the runtime.
-12. PROJECT RULE: when the user gives no project, use project "default". Do not infer a non-default project from old chat history unless the user references it. If they mention a path or project name, look it up or add it with add_project.
-13. VAULT RULE: when the user wants a new existing agent/template, call list_vault_agents first. If a suitable vault agent exists, import_agent into the chosen project. If none fits, say briefly what is missing.
-14. NO-PENDING RULE: never say "give me a second", "I will do it", or "I will try later" as a final answer. Either call the tool in this same turn or say what blocks you.
-15. IDENTITY RULE: when the user asks you to change your name, call yourself something, or update your personality/language, call set_identity and persist the change. Then confirm with your new name.
-16. ROUTINES RULE: NEVER create a routine in the default project (id=0). Routines MUST be tied to a specific registered project. Before adding a routine, call list_projects to find the correct project id or name. Then pass --project <id|name> to apx routine add. If no project fits, ask the user which project to use. Creating routines in project 0/default mixes unrelated projects' schedules and corrupts state.`;
+10. **SELF-RUN RULE**: If the user says "vos mismo", "tu mismo", "same", "base", "default", "sin agente", or does not explicitly name an agent slug, act as APX. **DO NOT** call list_agents. **DO NOT** pass an 'agent' argument to tools.
+11. DELEGATION RULE: When the user asks a named APC agent to do a task, use call_agent (unless they specify opening it in a runtime, then see rule 12).
+12. **DISPATCH RULE**: Use call_runtime for external runtimes. If the user named an agent, pass it. If they didn't, **DO NOT PASS ANY AGENT**. Running with an empty agent field is how you run as yourself.
+13. PROJECT RULE: When the user gives no project, use project "default". Do not infer a non-default project from old chat history unless the user references it. If they mention a path or project name, look it up or add it with add_project.
+14. VAULT RULE: When the user wants a new existing agent/template, call list_vault_agents first. If a suitable vault agent exists, import_agent into the chosen project. If none fits, say briefly what is missing.
+15. NO-PENDING RULE: never say "give me a second", "I will do it", or "I will try later" as a final answer. Either call the tool in this same turn or say what blocks you.
+16. IDENTITY RULE: when the user asks you to change your name, call yourself something, or update your personality/language, call set_identity and persist the change. Then confirm with your new name.
+17. ROUTINES RULE: NEVER create a routine in the default project (id=0). Routines MUST be tied to a specific registered project. Before adding a routine, call list_projects to find the correct project id or name. Then pass --project <id|name> to apx routine add. If no project fits, ask the user which project to use. Creating routines in project 0/default mixes unrelated projects' schedules and corrupts state.`;
 
 function isShortConfirmation(text) {
   return /^(yes|y|si|si dale|dale|ok|okay|confirm|confirmed|go|proceed|do it)\b/i
@@ -87,6 +88,7 @@ export async function runSuperAgent({
   contextNote = "",
   previousMessages = [],
   overrideModel = null,
+  onEvent = null,
 }) {
   if (!isSuperAgentEnabled(globalConfig)) {
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
@@ -141,6 +143,7 @@ export async function runSuperAgent({
   let lastText = "";
 
   for (let iter = 0; iter < MAX_TOOL_ITERS; iter++) {
+    await emitProgress(onEvent, { type: "model_start", iteration: iter + 1 });
     const result = await callEngine({
       modelId: activeModel,
       system,
@@ -174,6 +177,11 @@ export async function runSuperAgent({
       break;
     }
 
+    const visibleText = cleanTextOfPseudoToolCalls(lastText).trim();
+    if (visibleText) {
+      await emitProgress(onEvent, { type: "assistant_text", text: visibleText, iteration: iter + 1 });
+    }
+
     // Append the assistant turn (with its tool_calls) and execute each call.
     conversation.push({
       role: "assistant",
@@ -191,6 +199,12 @@ export async function runSuperAgent({
       args = args || {};
 
       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,
+      });
       try {
         const handler = handlers[name];
         if (!handler) {
@@ -202,7 +216,13 @@ export async function runSuperAgent({
         toolResult = { error: e.message };
       }
 
-      trace.push({ tool: name, args, result: 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,
+      });
 
       conversation.push({
         role: "tool",
@@ -220,6 +240,11 @@ export async function runSuperAgent({
   };
 }
 
+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);