@agentprojectcontext/apx 1.8.1 → 1.9.0

package/src/daemon/api.js

@@ -43,6 +43,12 @@ import { readAgents } from "../core/parser.js";
 import { parseSessionFrontmatter } from "../core/parser.js";
 import { writeAgentFile, ensureAgentDir, regenerateAgentsMd } from "../core/scaffold.js";
 import { buildAgentSystem } from "../core/agent-system.js";
+import {
+  createArtifact,
+  listArtifacts,
+  readArtifact,
+  removeArtifact,
+} from "../core/artifacts-store.js";
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
@@ -518,6 +524,35 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     }
   });
 
+  // POST /projects/:pid/super-agent/chat
+  app.post("/projects/:pid/super-agent/chat", 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" });
+    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,
+      });
+      projects.rebuild(p.id);
+      res.json({
+        text: saResult.text,
+        usage: saResult.usage,
+        name: saResult.name,
+        trace: saResult.trace,
+      });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
   // GET /projects/:pid/agents/:slug/conversations
   app.get("/projects/:pid/agents/:slug/conversations", (req, res) => {
     const p = project(req, res);
@@ -739,10 +774,14 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     if (!p) return;
     const { id } = req.params;
 
-    const agentsDir = path.join(p.path, ".apc", "agents");
+    const sessionRoots = [
+      path.join(p.storagePath || p.path, "agents"),
+      path.join(p.path, ".apc", "agents"),
+    ];
     let sessionFile = null;
     let agentSlug = null;
-    if (fs.existsSync(agentsDir)) {
+    for (const agentsDir of sessionRoots) {
+      if (!fs.existsSync(agentsDir)) continue;
       for (const slug of fs.readdirSync(agentsDir)) {
         const f = path.join(agentsDir, slug, "sessions", `${id}.md`);
         if (fs.existsSync(f)) {
@@ -751,6 +790,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
           break;
         }
       }
+      if (sessionFile) break;
     }
     if (!sessionFile) return res.status(404).json({ error: `session ${id} not found` });
 
@@ -797,13 +837,13 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
   app.get("/projects/:pid/routines", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    res.json(listRoutines(p.path));
+    res.json(listRoutines(p.storagePath));
   });
 
   app.get("/projects/:pid/routines/:name", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const r = getRoutine(p.path, req.params.name);
+    const r = getRoutine(p.storagePath, req.params.name);
     if (!r) return res.status(404).json({ error: "routine not found" });
     res.json(r);
   });
@@ -812,38 +852,76 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     const p = project(req, res);
     if (!p) return;
     try {
-      const r = upsertRoutine(p.path, req.body || {});
+      // Pass all fields including pipeline extensions.
+      const r = upsertRoutine(p.storagePath, req.body || {});
       res.status(201).json(r);
     } catch (e) {
       res.status(400).json({ error: e.message });
     }
   });
 
+  // ---- Artifacts (managed files in storagePath/artifacts/) ---------
+  app.get("/projects/:pid/artifacts", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    res.json(listArtifacts(p.storagePath));
+  });
+
+  app.post("/projects/:pid/artifacts", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { name, content = "" } = req.body || {};
+    if (!name) return res.status(400).json({ error: "name required" });
+    try {
+      const filePath = createArtifact(p.storagePath, name, content);
+      res.status(201).json({ name, path: filePath });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.get("/projects/:pid/artifacts/:name", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    try {
+      res.json(readArtifact(p.storagePath, decodeURIComponent(req.params.name)));
+    } catch (e) {
+      res.status(404).json({ error: e.message });
+    }
+  });
+
+  app.delete("/projects/:pid/artifacts/:name", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const ok = removeArtifact(p.storagePath, decodeURIComponent(req.params.name));
+    res.status(ok ? 204 : 404).end();
+  });
+
   app.delete("/projects/:pid/routines/:name", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const ok = deleteRoutine(p.path, req.params.name);
+    const ok = deleteRoutine(p.storagePath, req.params.name);
     res.status(ok ? 204 : 404).end();
   });
 
   app.post("/projects/:pid/routines/:name/enable", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    setRoutineEnabled(p.path, req.params.name, true);
+    setRoutineEnabled(p.storagePath, req.params.name, true);
     res.json({ ok: true });
   });
 
   app.post("/projects/:pid/routines/:name/disable", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    setRoutineEnabled(p.path, req.params.name, false);
+    setRoutineEnabled(p.storagePath, req.params.name, false);
     res.json({ ok: true });
   });
 
   app.post("/projects/:pid/routines/:name/run", async (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const r = getRoutine(p.path, req.params.name);
+    const r = getRoutine(p.storagePath, req.params.name);
     if (!r) return res.status(404).json({ error: "routine not found" });
     try {
       const result = await runRoutineNow({ project: p, projects, plugins, registries, globalConfig: config }, r);

package/src/daemon/routines.js

@@ -11,10 +11,15 @@
 //   shell       — run a shell command.        spec: { command, timeout_ms? }
 
 import { spawn } from "node:child_process";
+import { execFile } from "node:child_process";
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
 import { callEngine } from "./engines/index.js";
 import { runSuperAgent } from "./super-agent.js";
 import { readAgents } from "../core/parser.js";
 import { buildAgentSystem } from "../core/agent-system.js";
+import { resolveArtifactRef, ARTIFACTS_SKIP_SIGNAL } from "../core/artifacts-store.js";
 import {
   listRoutines,
   getRoutine,
@@ -169,29 +174,152 @@ const HANDLERS = {
   shell: handleShell,
 };
 
+// --------------------- pipeline: pre/post shell commands --------------------
+
+// Run a single shell command. Returns { exitCode, stdout, stderr }.
+function runShellCmd(cmd, env = {}, cwd = os.homedir()) {
+  return new Promise((resolve) => {
+    const child = spawn("sh", ["-c", cmd], {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (c) => (stdout += c.toString()));
+    child.stderr.on("data", (c) => (stderr += c.toString()));
+    child.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
+    child.on("error", (e) => resolve({ exitCode: 1, stdout: "", stderr: e.message }));
+  });
+}
+
+// Inject {{pre_output}} into a prompt string.
+function injectPreOutput(prompt, preOutput) {
+  if (!prompt || typeof prompt !== "string") return prompt;
+  return prompt.replace(/\{\{pre_output\}\}/g, preOutput || "");
+}
+
+// Determine whether to skip the LLM call based on skip_prompt_on + pre results.
+function shouldSkipPrompt(routine, preExitCode, preStdout) {
+  const mode = routine.skip_prompt_on || "signal";
+  if (mode === "always") return true;
+  if (mode === "never") return false;
+  if (mode === "signal") return preStdout.includes(ARTIFACTS_SKIP_SIGNAL);
+  if (mode === "pre_failure") return preExitCode !== 0;
+  if (mode === "pre_success") return preExitCode === 0;
+  return false;
+}
+
 // --------------------- runtime: run one + loop ------------------------------
 
 export async function runRoutineNow(ctx, routine) {
-  const handler = HANDLERS[routine.kind];
-  if (!handler) throw new Error(`unknown routine kind: ${routine.kind}`);
-  let result;
+  // Determine the working directory for shell commands.
+  const cwd = ctx.project?.path || os.homedir();
+  const storagePath = ctx.project?.storagePath || os.homedir();
+
+  const hasPreCmds  = Array.isArray(routine.pre_commands)  && routine.pre_commands.length  > 0;
+  const hasPostCmds = Array.isArray(routine.post_commands) && routine.post_commands.length > 0;
+
+  let preStdout = "";
+  let preExitCode = 0;
+  let preOutputFile = null;
+
+  // ── Phase 1: pre_commands ──────────────────────────────────────────────────
+  if (hasPreCmds) {
+    const combinedOut = [];
+    for (const rawCmd of routine.pre_commands) {
+      // Resolve "artifact:<name>" shorthand to its absolute path.
+      const cmd = resolveArtifactRef(rawCmd, storagePath);
+      const { exitCode, stdout, stderr } = await runShellCmd(cmd, {}, cwd);
+      combinedOut.push(stdout);
+      if (stderr) combinedOut.push(stderr);
+      preExitCode = exitCode;
+      if (exitCode !== 0 && (routine.skip_prompt_on === "pre_failure" || routine.skip_prompt_on === "signal")) {
+        // Stop running further pre_commands on failure when mode cares about exit code.
+        break;
+      }
+    }
+    preStdout = combinedOut.join("");
+
+    // Write pre output to a temp file so post_commands can reference it via
+    // $APX_PRE_OUTPUT_FILE even if the output is large.
+    try {
+      preOutputFile = path.join(os.tmpdir(), `apx-pre-${routine.name}-${Date.now()}.txt`);
+      fs.writeFileSync(preOutputFile, preStdout);
+    } catch { preOutputFile = null; }
+  }
+
+  // Env vars injected into post_commands and available in shell pre_commands output.
+  const pipelineEnv = {
+    APX_PRE_EXIT: String(preExitCode),
+    APX_PRE_OUTPUT: preStdout.slice(0, 32_000), // guard against huge outputs
+    APX_PRE_OUTPUT_FILE: preOutputFile || "",
+    APX_ROUTINE: routine.name,
+  };
+
+  // ── Phase 2: LLM / handler ────────────────────────────────────────────────
+  const skip = hasPreCmds && shouldSkipPrompt(routine, preExitCode, preStdout);
+
+  let result = { status: "ok" };
   let status = "ok";
   let errMsg = null;
-  try {
-    result = await handler(ctx, routine);
-    if (result?.status === "error") {
+
+  if (!skip) {
+    // Inject {{pre_output}} into exec_agent and super_agent prompts.
+    const enrichedRoutine = (hasPreCmds && preStdout)
+      ? {
+          ...routine,
+          spec: {
+            ...routine.spec,
+            prompt: injectPreOutput(routine.spec?.prompt, preStdout),
+          },
+        }
+      : routine;
+
+    const handler = HANDLERS[enrichedRoutine.kind];
+    if (!handler) {
       status = "error";
-      errMsg = result.error || result.stderr || `routine ${routine.name} returned error status`;
+      errMsg = `unknown routine kind: ${enrichedRoutine.kind}`;
+    } else {
+      try {
+        result = await handler(ctx, enrichedRoutine);
+        if (result?.status === "error") {
+          status = "error";
+          errMsg = result.error || result.stderr || `routine ${routine.name} returned error status`;
+        }
+      } catch (e) {
+        status = "error";
+        errMsg = e.message;
+        result = { status: "error", error: e.message };
+      }
     }
-  } catch (e) {
-    status = "error";
-    errMsg = e.message;
-    result = { status: "error", error: e.message };
+  } else {
+    result = { status: "ok", skipped: true, note: "pre_commands signalled skip" };
   }
+
+  // ── Phase 3: post_commands ────────────────────────────────────────────────
+  if (hasPostCmds) {
+    const llmOutput = result?.reply || result?.text || "";
+    const postEnv = {
+      ...pipelineEnv,
+      APX_LLM_OUTPUT: llmOutput.slice(0, 32_000),
+      APX_STATUS: status,
+      APX_SKIPPED: skip ? "1" : "0",
+    };
+    for (const rawCmd of routine.post_commands) {
+      const cmd = resolveArtifactRef(rawCmd, storagePath);
+      await runShellCmd(cmd, postEnv, cwd);
+      // Post-command failures are logged but don't change routine status.
+    }
+  }
+
+  // Cleanup temp file.
+  if (preOutputFile) try { fs.unlinkSync(preOutputFile); } catch {}
+
   const lastRun = nowIso();
   const next = computeNextRun({ schedule: routine.schedule, last_run_at: lastRun });
   const isOnce = parseSchedule(routine.schedule).kind === "once";
-  updateRunState(ctx.project.path, routine.name, {
+  updateRunState(ctx.project.storagePath, routine.name, {
     last_run_at: lastRun,
     last_status: status,
     last_error: errMsg,
@@ -205,9 +333,9 @@ export async function runRoutineNow(ctx, routine) {
     actor_id: "apx:routine",
     author: "apx",
     body: status === "ok"
-      ? `routine ${routine.name} ok`
+      ? `routine ${routine.name} ok${skip ? " (skipped LLM)" : ""}`
       : `routine ${routine.name} error: ${errMsg}`,
-    meta: { routine: routine.name, status, result },
+    meta: { routine: routine.name, status, skipped: skip, result },
   });
   return { ...result, last_run_at: lastRun, next_run_at: next };
 }
@@ -246,7 +374,7 @@ export class RoutineScheduler {
       const nowStr = nowIso();
       for (const proj of this.projects.list().map((p) => this.projects.get(p.id))) {
         if (!proj) continue;
-        const due = getDueRoutines(proj.path, nowStr);
+        const due = getDueRoutines(proj.storagePath, nowStr);
         for (const r of due) {
           this.log(`routine ${r.name} (${r.kind}) firing in project #${proj.id}`);
           await runRoutineNow(

package/src/daemon/runtimes/claude-code.js

@@ -3,8 +3,31 @@
 // Returns one JSON line with the result and session_id.
 // Reference: https://docs.claude.com/en/docs/claude-code/headless
 
+import fs from "node:fs";
+import path from "node:path";
 import { runProcess } from "./_spawn.js";
 
+export function encodeClaudeProjectPath(cwd) {
+  return String(cwd || process.cwd()).replace(/[^A-Za-z0-9]/g, "-");
+}
+
+export function resolveClaudeSessionPath({ cwd, sessionId, home = process.env.HOME || process.env.USERPROFILE || "" }) {
+  if (!sessionId || !home) return null;
+  const projectsDir = path.join(home, ".claude", "projects");
+  const encodedCwd = encodeClaudeProjectPath(cwd);
+  const expected = path.join(projectsDir, encodedCwd, `${sessionId}.jsonl`);
+  if (fs.existsSync(expected)) return expected;
+
+  try {
+    for (const dir of fs.readdirSync(projectsDir)) {
+      const candidate = path.join(projectsDir, dir, `${sessionId}.jsonl`);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  } catch {}
+
+  return expected;
+}
+
 export default {
   id: "claude-code",
   binary: "claude",
@@ -40,12 +63,7 @@ export default {
     }
 
     if (sessionId) {
-      // Claude Code's session directory naming: replace BOTH "/" and "_" with
-      // "-" (verified empirically against ~/.claude/projects/). The trailing
-      // file is `<sessionId>.jsonl`.
-      const home = process.env.HOME || process.env.USERPROFILE || "";
-      const encodedCwd = (cwd || process.cwd()).replace(/[/_]/g, "-");
-      externalSessionPath = `${home}/.claude/projects/${encodedCwd}/${sessionId}.jsonl`;
+      externalSessionPath = resolveClaudeSessionPath({ cwd, sessionId });
     }
 
     return {

package/src/daemon/super-agent-tools/index.js

@@ -18,6 +18,7 @@ import callRuntime from "./tools/call-runtime.js";
 import sendTelegram from "./tools/send-telegram.js";
 import setIdentity from "./tools/set-identity.js";
 import setPermissionMode from "./tools/set-permission-mode.js";
+import searchFiles from "./tools/search-files.js";
 import { createPermissionGuard } from "./helpers.js";
 
 const TOOLS = [
@@ -41,6 +42,7 @@ const TOOLS = [
   sendTelegram,
   setIdentity,
   setPermissionMode,
+  searchFiles,
 ];
 
 export const TOOL_SCHEMAS = TOOLS.map((tool) => tool.schema);

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

@@ -1,4 +1,12 @@
+import fs from "node:fs";
+import path from "node:path";
 import { readAgents } from "../../../core/parser.js";
+import {
+  buildApfHint,
+  closeRuntimeSession,
+  createRuntimeSession,
+  extractApfResult,
+} from "../../apc-runtime-context.js";
 import { getRuntime, RUNTIME_IDS } from "../../runtimes/index.js";
 import { buildAgentSystem, confirmedProperty, resolveProject } from "../helpers.js";
 
@@ -20,18 +28,51 @@ function resolveProjectForAgent(projects, project, slug) {
   return resolveProject(projects, project);
 }
 
+function projectName(project) {
+  try {
+    const meta = JSON.parse(fs.readFileSync(path.join(project.path, ".apc", "project.json"), "utf8"));
+    if (meta.name) return meta.name;
+  } catch {}
+  return path.basename(project.path);
+}
+
+function buildRuntimeSystem(project, agent, runtime, sessionId, caller) {
+  const agentSlug = agent?.slug || "apx";
+  const hint = buildApfHint({
+    projectName: projectName(project),
+    projectPath: project.path,
+    agentSlug,
+    sessionId,
+  });
+  if (agent) {
+    return buildAgentSystem(project, agent, {
+      invocation: "runtime",
+      runtime,
+      caller,
+      extraParts: [hint],
+    });
+  }
+
+  return [
+    "You are APX running inside an external coding runtime.",
+    "No APC agent was explicitly selected for this run.",
+    "Use the project context and runtime tools directly. Do not impersonate a project agent.",
+    hint,
+  ].join("\n\n");
+}
+
 export default {
   name: "call_runtime",
   schema: {
     type: "function",
     function: {
       name: "call_runtime",
-      description: "Spawn an external CLI runtime (Claude Code, Codex, OpenCode, Aider) impersonating an APC agent.",
+      description: "Spawn an external CLI runtime (Claude Code, Codex, OpenCode, Aider), optionally impersonating an APC agent.",
       parameters: {
         type: "object",
         properties: {
           project: { type: "string" },
-          agent: { type: "string", description: "APC agent slug from AGENTS.md, not runtime name" },
+          agent: { type: "string", description: "Optional APC agent slug from AGENTS.md, not runtime name. Omit when the user did not name an agent." },
           runtime: {
             type: "string",
             enum: ["claude-code", "codex", "opencode", "aider"],
@@ -41,16 +82,16 @@ export default {
           timeout_s: { type: "integer", description: "seconds before SIGTERM; default 300" },
           confirmed: confirmedProperty("true only after explicit user confirmation for this exact runtime command"),
         },
-        required: ["agent", "runtime", "prompt"],
+        required: ["runtime", "prompt"],
       },
     },
   },
   makeHandler: ({ projects, requirePermission }) => async ({ project, agent: slug, runtime, prompt, timeout_s = 300, confirmed = false }) => {
     requirePermission("call_runtime", { dangerous: true, confirmed });
 
-    const p = resolveProjectForAgent(projects, project, slug);
-    const agent = readAgents(p.path).find((a) => a.slug === slug);
-    if (!agent) {
+    const p = slug ? resolveProjectForAgent(projects, project, slug) : resolveProject(projects, project);
+    const agent = slug ? readAgents(p.path).find((a) => a.slug === slug) : null;
+    if (slug && !agent) {
       const directory = projects.list().map((entry) => ({
         project: entry.name,
         kind: entry.id === 0 ? "default" : "project",
@@ -67,45 +108,74 @@ export default {
       return { error: `${e.message}. Available runtimes: ${RUNTIME_IDS.join(", ")}` };
     }
 
-    const r = await rt.run({
-      system: buildAgentSystem(p, agent, {
-        invocation: "runtime",
-        runtime,
-        caller: "super_agent_tool",
-      }),
-      prompt,
-      cwd: p.path,
-      timeoutMs: timeout_s * 1000,
+    const actor = agent?.slug || "apx";
+    const session = createRuntimeSession({
+      projectRoot: p.path,
+      storageRoot: p.storagePath,
+      agentSlug: actor,
+      runtime,
+      title: `Runtime: ${runtime}${agent ? ` (${agent.slug})` : ""}`,
     });
 
-    p.logMessage({
-      agent_slug: slug,
-      channel: "runtime",
-      direction: "in",
-      author: "user",
-      body: prompt,
-      meta: { runtime, invoked_by: "super_agent_tool" },
-    });
-    p.logMessage({
-      agent_slug: slug,
-      channel: "runtime",
-      direction: "out",
-      author: slug,
-      body: r.output || "",
-      meta: {
+    try {
+      const r = await rt.run({
+        system: buildRuntimeSystem(p, agent, runtime, session.id, "super_agent_tool"),
+        prompt,
+        cwd: p.path,
+        timeoutMs: timeout_s * 1000,
+      });
+
+      const result = extractApfResult(r.output) || (r.output || "").slice(0, 200);
+      closeRuntimeSession({
+        filePath: session.path,
+        externalSessionPath: r.externalSessionPath || null,
+        exitCode: r.exitCode,
+        result,
+      });
+
+      p.logMessage({
+        agent_slug: actor,
+        channel: "runtime",
+        direction: "in",
+        author: "user",
+        body: prompt,
+        meta: { runtime, invoked_by: "super_agent_tool", apc_session: session.id },
+      });
+      p.logMessage({
+        agent_slug: actor,
+        channel: "runtime",
+        direction: "out",
+        author: actor,
+        body: r.output || "",
+        meta: {
+          runtime,
+          exit_code: r.exitCode,
+          external_session_path: r.externalSessionPath || null,
+          session_id: r.sessionId || null,
+          apc_session: session.id,
+          invoked_by: "super_agent_tool",
+        },
+      });
+
+      return {
         runtime,
+        agent: agent?.slug || null,
+        apc_session: session.id,
         exit_code: r.exitCode,
+        output: (r.output || "").slice(0, 4000),
+        truncated: (r.output || "").length > 4000,
         external_session_path: r.externalSessionPath || null,
-        invoked_by: "super_agent_tool",
-      },
-    });
-
-    return {
-      runtime,
-      exit_code: r.exitCode,
-      output: (r.output || "").slice(0, 4000),
-      truncated: (r.output || "").length > 4000,
-      external_session_path: r.externalSessionPath || null,
-    };
+        session_id: r.sessionId || null,
+      };
+    } catch (e) {
+      try {
+        closeRuntimeSession({
+          filePath: session.path,
+          exitCode: -1,
+          result: `error: ${e.message.slice(0, 200)}`,
+        });
+      } catch {}
+      throw e;
+    }
   },
 };