@agentprojectcontext/apx 1.14.1 → 1.15.0

package/src/daemon/super-agent-tools/tools/ask-questions.js

@@ -0,0 +1,28 @@
+export default {
+  name: "ask_questions",
+  schema: {
+    function: {
+      name: "ask_questions",
+      description: "Ask the user one or more specific questions to clarify the task or gather requirements.",
+      parameters: {
+        type: "object",
+        properties: {
+          questions: {
+            type: "array",
+            items: { type: "string" },
+            description: "A list of questions for the user."
+          }
+        },
+        required: ["questions"]
+      }
+    }
+  },
+  makeHandler: () => async ({ questions }) => {
+    // This tool is used by the agent to explicitly signal that it is waiting for 
+    // answers to specific questions. The UI can then highlight these.
+    return { 
+      status: "Questions presented to user. Waiting for input.", 
+      count: questions.length 
+    };
+  }
+};

package/src/daemon/super-agent.js

@@ -68,6 +68,47 @@ HARD RULES (do not deviate):
 21. **SKILLS — ON DEMAND**: The "# Available skills" section below lists every skill available to you (slug + description, NO body). When the user asks about specific APX/APC commands, project structure, agent runtimes, or anything where exact syntax or detailed behavior matches a skill description (in ANY language — match semantically, not by keyword), call load_skill({slug}) to fetch the full markdown body. If a CWD is in the contextNote, pass it as project_path so project-scoped skills resolve. If the user explicitly asks "what skills do you have?", you can either read the catalog below directly OR call list_skills to get a fresh enumeration. Do NOT load skills for trivial / unrelated questions — that wastes tokens. Don't guess CLI syntax when a skill can tell you; load it.
 22. **NEVER PASTE BASE64 OR DATA URIs IN MESSAGE TEXT**: When you need to send an image, audio, or file via Telegram (or any channel), you MUST pass it via the dedicated parameter — NEVER embed it in the text field. Concretely: after browser_screenshot returns its base64 field, call send_telegram({text: "<short caption>", photo_base64: "<that base64>"}). Do NOT write text like 'Aquí está: ![screenshot](data:image/png;base64,...)' — Telegram (and most chat clients) do NOT render data URIs or markdown images; the user sees thousands of garbage characters. Same for files: use document_path / document_base64 / document_url, NOT the text field. The text field is exclusively for human-readable prose (and becomes the caption when media is attached). If unsure, save the image to /tmp/screenshot-<ts>.png first (browser_screenshot supports save_to_tmp=true and returns a path field) and pass that path to send_telegram via photo_path — never inline the bytes in text.`;
 
+function compactToolSchema(schema) {
+  const fn = schema?.function || {};
+  const params = fn.parameters || {};
+  const properties = params.properties || {};
+  return {
+    name: fn.name,
+    description: fn.description,
+    required: params.required || [],
+    properties: Object.fromEntries(
+      Object.entries(properties).map(([name, spec]) => [
+        name,
+        {
+          type: spec?.type || "string",
+          enum: spec?.enum,
+          description: spec?.description,
+        },
+      ])
+    ),
+  };
+}
+
+function pseudoToolSystem(system) {
+  const catalog = TOOL_SCHEMAS.map(compactToolSchema);
+  return [
+    system,
+    "# Structured tool fallback",
+    "The engine rejected native structured tools. You can still call tools by emitting plain JSON.",
+    "When you need a tool, respond ONLY with one JSON object per line:",
+    "{\"name\":\"tool_name\",\"arguments\":{\"arg\":\"value\"}}",
+    "After tool results arrive, continue the task or give the final answer normally.",
+    "Available tools:",
+    JSON.stringify(catalog),
+  ].join("\n\n");
+}
+
+function shouldRetryWithPseudoTools(modelId, error, alreadyPseudo) {
+  if (alreadyPseudo) return false;
+  const message = String(error?.message || "");
+  return /^ollama:/i.test(String(modelId || "")) && /ollama\s+500/i.test(message);
+}
+
 function isShortConfirmation(text) {
   return /^(yes|y|si|si dale|dale|ok|okay|confirm|confirmed|go|proceed|do it)\b/i
     .test(String(text || "").trim());
@@ -115,6 +156,7 @@ export async function runSuperAgent({
   previousMessages = [],
   overrideModel = null,
   onEvent = null,
+  signal,
 }) {
   if (!isSuperAgentEnabled(globalConfig)) {
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
@@ -187,6 +229,7 @@ export async function runSuperAgent({
   const trace = [];
   let totalUsage = { input_tokens: 0, output_tokens: 0 };
   let lastText = "";
+  let usePseudoTools = false;
 
   for (let iter = 0; iter < MAX_TOOL_ITERS; iter++) {
     await emitProgress(onEvent, { type: "model_start", iteration: iter + 1 });
@@ -195,15 +238,38 @@ export async function runSuperAgent({
     // acting on an action request. On later iterations (after tool results
     // have been fed back) tool_choice is "auto" so the model can produce its
     // final text summary.
-    const result = await callEngine({
-      modelId: activeModel,
-      system,
-      messages: conversation,
-      config: globalConfig,
-      tools: TOOL_SCHEMAS,
-      toolChoice: iter === 0 ? "required" : "auto",
-      maxTokens: 1024,
-    });
+    let result;
+    try {
+      result = await callEngine({
+        modelId: activeModel,
+        system: usePseudoTools ? pseudoToolSystem(system) : system,
+        messages: conversation,
+        config: globalConfig,
+        tools: usePseudoTools ? null : TOOL_SCHEMAS,
+        toolChoice: usePseudoTools ? null : (iter === 0 ? "required" : "auto"),
+        maxTokens: 1024,
+        signal,
+      });
+    } 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 callEngine({
+        modelId: activeModel,
+        system: pseudoToolSystem(system),
+        messages: conversation,
+        config: globalConfig,
+        tools: null,
+        toolChoice: null,
+        maxTokens: 1024,
+        signal,
+      });
+    }
     totalUsage.input_tokens += result.usage?.input_tokens || 0;
     totalUsage.output_tokens += result.usage?.output_tokens || 0;
     lastText = result.text || "";
@@ -317,3 +383,25 @@ function summarizeForTrace(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);
+}

package/src/core/apc-context-skill.md

@@ -1,105 +0,0 @@
-
-# Agent Project Context
-
-This project uses APC. APC stores portable project context in `.apc/` and `AGENTS.md`.
-
-APC does not store raw runtime sessions. Sessions, conversations, messages, caches, provider
-threads, and private runtime memory stay in the IDE, CLI, daemon, or user-level store that created
-them.
-
-## FIRST: check for pending migration
-
-Before doing anything else, check if `.apc/migrate.md` exists:
-
-```bash
-cat .apc/migrate.md 2>/dev/null
-```
-
-If it exists, offer to migrate before answering anything else. Read detected files, separate durable
-project context from runtime/private state, and migrate only what belongs in APC.
-
-If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.
-
-## Migration rule: think, do not copy
-
-Classify content:
-
-| Content | Action |
-|---|---|
-| Agent definitions: role, model, skills, description | Put in `.apc/agents/<slug>.md` and/or `AGENTS.md` |
-| Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
-| Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
-| Durable safe facts useful to all contributors | Add to `.apc/agents/<slug>/memory.md` only after curation |
-| MCP expectations without secrets | Add to `.apc/mcps.json` |
-| Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
-| Secrets, tokens, credentials, private headers | Do not store in repository |
-| IDE UI settings or personal aliases | Leave in IDE/user config |
-| Instructions to store sessions under `.apc/` | Drop as obsolete |
-
-## APC structure
-
-```text
-AGENTS.md                        ← root project contract
-.apc/
-  project.json                   ← project metadata
-  .gitignore                     ← safety guard
-  agents/<slug>.md               ← agent definition
-  agents/<slug>/memory.md        ← optional curated project memory
-  skills/<name>.md               ← reusable project instructions
-  mcps.json                      ← MCP hints without secrets
-```
-
-Do not store:
-
-```text
-.apc/agents/<slug>/sessions/
-.apc/sessions/
-.apc/conversations/
-.apc/messages/
-.apc/project.db
-.apc/cache/
-.apc/tmp/
-.apc/private/
-.apc/secrets/
-```
-
-## Operating rules
-
-1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
-2. Read agent definitions from `.apc/agents/<slug>.md` when present.
-3. Read curated project memory from `.apc/agents/<slug>/memory.md` when present.
-4. Write only durable, safe, curated facts to APC memory.
-5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
-6. Keep secrets out of APC and out of git.
-7. Treat `.apc/mcps.json` as MCP configuration hints, not as an MCP implementation.
-
-## Sessions
-
-Sessions belong to the runtime that created them.
-
-Examples:
-
-```text
-Codex runtime storage
-Claude Code runtime storage
-OpenCode runtime storage
-~/.apx/projects/<project-id>/agents/<slug>/sessions/
-```
-
-At task end, provide the user a concise result. If project memory should be updated, write a short
-sanitized fact to `.apc/agents/<slug>/memory.md` only when useful and safe.
-
-## APX
-
-APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
-across Codex, Claude Code, OpenCode, Aider, Cursor Agent, Gemini CLI, Qwen Code, or direct LLM
-engines. Those are APX runtime features, not APC portable-core requirements.
-
-The APX super-agent uses `~/.apx/projects/default` for system-level work when no project is named.
-APX routines can run heartbeat, shell, Telegram, project agent, or super-agent tasks on a schedule.
-
-APX runtime state belongs outside the repository:
-
-```text
-~/.apx/projects/<project-id>/
-```

package/src/core/apx-skill.md

@@ -1,135 +0,0 @@
-# APX — Agent Project Context Runtime
-
-The daemon runs on `127.0.0.1:7430` and auto-starts on first `apx` call.
-
-APX reads APC project context from `.apc/`, but APX runtime state belongs outside the repository
-under `~/.apx/projects/<project-id>/`.
-
-The APX super-agent has an always-available default workspace at `~/.apx/projects/default`.
-When no project is named, system-level work belongs there.
-
----
-
-## Coordinate with other agents
-
-**First: can you spawn a subagent natively in this IDE?**
-
-If yes — do that. No APX needed. Claude Code, Cursor, and other IDEs can spawn subagents directly using your current context.
-
-Use `apx run` only when:
-- The user explicitly asks to run the agent in a specific external runtime ("run this in Codex", "run the QA agent outside this session")
-- You need to run an agent in a runtime different from the one you're in
-- You're orchestrating from outside any IDE (e.g. a script, Telegram bot, CI)
-
-```bash
-# Run agent in an external runtime — full isolated session
-apx run <slug> --runtime claude-code "<prompt>"
-apx run <slug> --runtime codex        "<prompt>"
-apx run <slug> --runtime opencode     "<prompt>"
-apx run <slug> --runtime aider        "<prompt>"
-apx run <slug> --runtime cursor-agent "<prompt>"
-apx run <slug> --runtime gemini-cli   "<prompt>"
-apx run <slug> --runtime qwen-code    "<prompt>"
-
-# Example: run the qa agent in codex with a specific task
-apx run qa --runtime codex "run the full test suite and report failures"
-```
-
-The output is the agent's full stdout. If it printed `APC_RESULT: <value>`, that value is captured as structured output.
-
-```bash
-# Quick one-shot LLM call (no external CLI needed, uses ~/.apx/config.json engine key)
-apx exec <slug> "<prompt>"
-```
-
-## Command accuracy
-
-Do not invent APX subcommands. Before telling another runtime to call APX, verify the exact CLI
-form with `apx --help` or `apx <command> --help`.
-
-Known Telegram form:
-
-```bash
-apx telegram status
-apx telegram send "message"
-apx telegram send "message" --chat 123456
-```
-
-Do not use guessed aliases such as `apx send-telegram` or `apx telegram "message"` unless current
-`apx --help` shows that exact form.
-
-## MCP tools
-
-MCPs declared in `.apc/mcps.json` are proxied through the APX daemon. Use `apx mcp` only for MCPs registered there — not for MCPs that are already running locally in your IDE session.
-
-```bash
-apx mcp list                            # MCPs registered in .apc/mcps.json
-apx mcp tools <server>                  # tools a server exposes
-apx mcp run   <server> <tool> '<json>'  # call a tool
-
-# Example:
-apx mcp tools filesystem
-apx mcp run filesystem read_file '{"path": "README.md"}'
-```
-
-## Memory
-
-Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
-
-```bash
-apx memory <slug>                       # read agent's memory.md
-apx memory <slug> --append "<fact>"     # append a durable note
-apx memory <slug> --replace < file.md  # replace entire memory from stdin
-```
-
-## Sessions
-
-Sessions are APX runtime state. They do not belong in `.apc/`.
-
-```bash
-apx session new <slug> --title "What you did"   # create APX local session file
-apx session list <slug>                          # list sessions
-apx session check                                # exits 1 if session already active
-```
-
-## Observe activity
-
-```bash
-apx messages tail                               # last 50 messages, all channels
-apx messages chat --channel telegram -n 20      # chat view with user/agent/system type
-apx messages tail --channel runtime             # only agent invocations
-apx messages tail --agent <slug> -n 20
-```
-
-Message rows expose `type` (`user`, `agent`, `tool`, `system`) and `actor_id`; use `messages chat`
-when you need a readable transcript.
-
-## APX tool permissions
-
-```bash
-apx permission show
-apx permission set automatico   # total | automatico | permiso
-```
-
-`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP,
-runtime, outbound, config, or filesystem mutation actions.
-
-## Routines
-
-```bash
-apx routine list
-apx routine get <name>
-apx routine history <name>
-apx routine add clima --kind super_agent --schedule every:5m \
-  --permission-mode total \
-  --spec '{"prompt":"Check weather and send Telegram update."}'
-```
-
-Routine kinds: `heartbeat`, `exec_agent`, `super_agent`, `telegram`, `shell`.
-
-## APC_RESULT
-
-Print on the last meaningful line of your output so the invoker captures it:
-```
-APC_RESULT: <one-line summary or value>
-```