@agentprojectcontext/apx 1.0.3

package/src/daemon/routines.js

@@ -0,0 +1,211 @@
+// Routines: scheduled tasks per project. State persists in .apc/routines.json.
+//
+// Schedule formats:
+//   every:60s | every:5m | every:1h | once:<iso-8601>
+//
+// Kinds:
+//   heartbeat   — log a heartbeat message.   spec: { channel?, message? }
+//   exec_agent  — call an agent engine.       spec: { agent: slug, prompt }
+//   telegram    — send a Telegram message.    spec: { channel?, chat_id?, text }
+//   shell       — run a shell command.        spec: { command, timeout_ms? }
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "node:fs";
+import { callEngine } from "./engines/index.js";
+import { readAgents } from "../core/parser.js";
+import {
+  listRoutines,
+  getRoutine,
+  upsertRoutine,
+  deleteRoutine,
+  setEnabled,
+  updateRunState,
+  getDueRoutines,
+  parseSchedule,
+  computeNextRun,
+} from "../core/routines-store.js";
+
+export {
+  listRoutines,
+  getRoutine,
+  upsertRoutine,
+  deleteRoutine,
+  setEnabled,
+  parseSchedule,
+  computeNextRun,
+};
+
+const TICK_MS = 5_000;
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
+// --------------------- handlers ---------------------------------------------
+
+async function handleHeartbeat(ctx, routine) {
+  const { project } = ctx;
+  const channel = routine.spec.channel || "heartbeat";
+  const message = routine.spec.message || `heartbeat from ${routine.name}`;
+  project.logMessage({
+    channel,
+    direction: "out",
+    author: "apx",
+    body: message,
+    meta: { routine: routine.name },
+  });
+  return { status: "ok", note: `logged to messages on channel '${channel}'` };
+}
+
+async function handleExecAgent(ctx, routine) {
+  const { project, globalConfig } = ctx;
+  const { agent: slug, prompt } = routine.spec;
+  if (!slug || !prompt) throw new Error("exec_agent: spec needs { agent, prompt }");
+
+  const agents = readAgents(project.path);
+  const agent = agents.find((a) => a.slug === slug);
+  if (!agent) throw new Error(`agent ${slug} not found`);
+  const model = agent.fields.Model;
+  if (!model) throw new Error(`agent ${slug} has no model`);
+
+  const f = agent.fields;
+  const parts = [];
+  if (f.Description) parts.push(f.Description);
+  if (f.Role) parts.push(`Role: ${f.Role}`);
+  const memPath = path.join(project.path, ".apc", "agents", slug, "memory.md");
+  if (fs.existsSync(memPath)) parts.push("## Memory\n" + fs.readFileSync(memPath, "utf8"));
+  parts.push(`You were invoked by routine "${routine.name}". Reply briefly, max 4 sentences.`);
+
+  const result = await callEngine({
+    modelId: model,
+    system: parts.join("\n\n"),
+    messages: [{ role: "user", content: prompt }],
+    config: project.config || globalConfig,
+  });
+
+  project.logMessage({
+    agent_slug: slug,
+    channel: "routine",
+    direction: "out",
+    author: slug,
+    body: result.text,
+    meta: { routine: routine.name, usage: result.usage },
+  });
+  return { status: "ok", reply: result.text };
+}
+
+async function handleTelegram(ctx, routine) {
+  const { plugins } = ctx;
+  const tg = plugins?.get("telegram");
+  if (!tg) throw new Error("telegram plugin not loaded");
+  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" };
+}
+
+function handleShell(ctx, routine) {
+  return new Promise((resolve, reject) => {
+    const { command, timeout_ms = 30_000 } = routine.spec;
+    if (!command) return reject(new Error("shell routine needs spec.command"));
+    const child = spawn("sh", ["-c", command], {
+      cwd: ctx.project.path,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => child.kill("SIGTERM"), timeout_ms);
+    child.stdout.on("data", (c) => (stdout += c.toString()));
+    child.stderr.on("data", (c) => (stderr += c.toString()));
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve({ status: "ok", stdout: stdout.trim().slice(0, 4000) });
+      else resolve({ status: "error", code, stderr: stderr.trim().slice(0, 2000) });
+    });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+  });
+}
+
+const HANDLERS = {
+  heartbeat: handleHeartbeat,
+  exec_agent: handleExecAgent,
+  telegram: handleTelegram,
+  shell: handleShell,
+};
+
+// --------------------- 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;
+  let status = "ok";
+  let errMsg = null;
+  try {
+    result = await handler(ctx, routine);
+  } catch (e) {
+    status = "error";
+    errMsg = e.message;
+    result = { status: "error", error: e.message };
+  }
+  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, {
+    last_run_at: lastRun,
+    last_status: status,
+    last_error: errMsg,
+    next_run_at: next,
+    disable: isOnce,
+  });
+  return { ...result, last_run_at: lastRun, next_run_at: next };
+}
+
+export class RoutineScheduler {
+  constructor({ projects, plugins, globalConfig, log }) {
+    this.projects = projects;
+    this.plugins = plugins;
+    this.globalConfig = globalConfig;
+    this.log = log || (() => {});
+    this._timer = null;
+    this._running = false;
+  }
+
+  start() {
+    if (this._timer) return;
+    this._timer = setInterval(
+      () => this._tick().catch((e) => this.log(`routines tick error: ${e.message}`)),
+      TICK_MS
+    );
+    this._timer.unref?.();
+  }
+
+  stop() {
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+  }
+
+  async _tick() {
+    if (this._running) return;
+    this._running = true;
+    try {
+      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);
+        for (const r of due) {
+          this.log(`routine ${r.name} (${r.kind}) firing in project #${proj.id}`);
+          await runRoutineNow(
+            { project: proj, plugins: this.plugins, globalConfig: this.globalConfig },
+            r
+          );
+        }
+      }
+    } finally {
+      this._running = false;
+    }
+  }
+}

package/src/daemon/runtimes/_spawn.js

@@ -0,0 +1,44 @@
+// Shared spawn helper: runs a command, pipes a string to stdin, captures
+// stdout/stderr, returns when the process exits or the timeout fires.
+import { spawn } from "node:child_process";
+
+const DEFAULT_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+
+export function runProcess({ command, args = [], stdin = "", cwd, env, timeoutMs = DEFAULT_TIMEOUT }) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: { ...process.env, ...(env || {}) },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill("SIGTERM");
+    }, timeoutMs);
+
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (c) => (stdout += c));
+    child.stderr.on("data", (c) => (stderr += c));
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ exitCode: -1, stdout, stderr, error: err.message, killed });
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ exitCode: code, stdout, stderr, killed });
+    });
+
+    if (stdin) {
+      child.stdin.write(stdin);
+    }
+    child.stdin.end();
+  });
+}

package/src/daemon/runtimes/aider.js

@@ -0,0 +1,32 @@
+// Aider runtime adapter. Uses --message for non-interactive mode.
+//   aider --message "<prompt>" --no-auto-commits --yes
+// Reference: https://aider.chat/docs/scripting.html
+
+import { runProcess } from "./_spawn.js";
+
+export default {
+  id: "aider",
+  binary: "aider",
+  versionFlag: "--version",
+
+  async run({ system, prompt, cwd, env, timeoutMs }) {
+    const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
+    const r = await runProcess({
+      command: "aider",
+      args: [
+        "--message", fullPrompt,
+        "--yes-always",
+        "--no-auto-commits",
+      ],
+      cwd,
+      env,
+      timeoutMs,
+    });
+    return {
+      exitCode: r.exitCode,
+      output: r.stdout.trim(),
+      stderr: r.stderr,
+      externalSessionPath: null,
+    };
+  },
+};

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

@@ -0,0 +1,60 @@
+// Claude Code runtime adapter. Uses the headless `-p` mode:
+//   claude -p "<prompt>"  --append-system-prompt "<system>"  --output-format json
+// Returns one JSON line with the result and session_id.
+// Reference: https://docs.claude.com/en/docs/claude-code/headless
+
+import { runProcess } from "./_spawn.js";
+
+export default {
+  id: "claude-code",
+  binary: "claude",
+  versionFlag: "--version",
+
+  async run({ system, prompt, cwd, env, timeoutMs }) {
+    const args = ["-p", prompt, "--output-format", "json"];
+    if (system) {
+      args.push("--append-system-prompt", system);
+    }
+    const r = await runProcess({
+      command: "claude",
+      args,
+      cwd,
+      env,
+      timeoutMs,
+    });
+
+    let output = r.stdout.trim();
+    let sessionId = null;
+    let externalSessionPath = null;
+    let parsed = null;
+
+    if (output) {
+      try {
+        // headless --output-format json emits a single-line JSON result
+        parsed = JSON.parse(output);
+        if (parsed.result) output = parsed.result;
+        sessionId = parsed.session_id || null;
+      } catch {
+        // not JSON — keep raw stdout
+      }
+    }
+
+    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`;
+    }
+
+    return {
+      exitCode: r.exitCode,
+      output,
+      stderr: r.stderr,
+      externalSessionPath,
+      sessionId,
+      raw: parsed,
+    };
+  },
+};

package/src/daemon/runtimes/codex.js

@@ -0,0 +1,30 @@
+// OpenAI Codex CLI runtime adapter.
+//   codex exec "<prompt>"
+// System prompt is prepended to the prompt body since Codex doesn't have a
+// dedicated --system flag in `exec` mode.
+// Reference: https://github.com/openai/codex
+
+import { runProcess } from "./_spawn.js";
+
+export default {
+  id: "codex",
+  binary: "codex",
+  versionFlag: "--version",
+
+  async run({ system, prompt, cwd, env, timeoutMs }) {
+    const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
+    const r = await runProcess({
+      command: "codex",
+      args: ["exec", fullPrompt],
+      cwd,
+      env,
+      timeoutMs,
+    });
+    return {
+      exitCode: r.exitCode,
+      output: r.stdout.trim(),
+      stderr: r.stderr,
+      externalSessionPath: null,
+    };
+  },
+};

package/src/daemon/runtimes/index.js

@@ -0,0 +1,39 @@
+// Runtime adapters: spawn external agent CLIs (Claude Code, Codex, OpenCode,
+// Aider, ...) with the agent's system prompt + the prompt we want to run, and
+// capture their output. Unlike engines/ — which talk directly to model APIs —
+// runtimes/ delegate the whole conversation to the external tool. APX only
+// records the invocation, the prompt, the captured output, and where the tool
+// stored its own session (if it tells us).
+//
+// Each runtime exports:
+//   {
+//     id,
+//     binary,                         executable name to look for in PATH
+//     versionFlag,                    flag to print the version
+//     async run({ system, prompt, cwd, env, timeoutMs })
+//          → { exitCode, output, externalSessionPath?, raw? }
+//   }
+
+import claudeCode from "./claude-code.js";
+import codex from "./codex.js";
+import opencode from "./opencode.js";
+import aider from "./aider.js";
+
+const REGISTRY = {
+  "claude-code": claudeCode,
+  codex,
+  opencode,
+  aider,
+};
+
+export const RUNTIME_IDS = Object.keys(REGISTRY);
+
+export function getRuntime(id) {
+  const r = REGISTRY[id];
+  if (!r) {
+    throw new Error(
+      `unknown runtime "${id}". Known: ${RUNTIME_IDS.join(", ")}`
+    );
+  }
+  return r;
+}

package/src/daemon/runtimes/opencode.js

@@ -0,0 +1,28 @@
+// OpenCode runtime adapter. Uses headless run:
+//   opencode run "<prompt>"
+// Reference: https://opencode.ai/docs/
+
+import { runProcess } from "./_spawn.js";
+
+export default {
+  id: "opencode",
+  binary: "opencode",
+  versionFlag: "--version",
+
+  async run({ system, prompt, cwd, env, timeoutMs }) {
+    const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
+    const r = await runProcess({
+      command: "opencode",
+      args: ["run", fullPrompt],
+      cwd,
+      env,
+      timeoutMs,
+    });
+    return {
+      exitCode: r.exitCode,
+      output: r.stdout.trim(),
+      stderr: r.stderr,
+      externalSessionPath: null,
+    };
+  },
+};

package/src/daemon/smoke.js

@@ -0,0 +1,54 @@
+// Smoke test: register the example project and verify agents, sessions, MCPs
+// are readable from the filesystem without any SQLite.
+//
+//   node src/smoke.js
+//
+// Exits non-zero on failure.
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { ProjectManager } from "./db.js";
+import { McpRegistry } from "./mcp-runner.js";
+import { readAgents } from "../core/parser.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const EXAMPLE = path.resolve(__dirname, "..", "..", "examples", "my-first-project");
+
+function assert(cond, msg) {
+  if (!cond) {
+    console.error("FAIL:", msg);
+    process.exit(1);
+  }
+}
+
+const projects = new ProjectManager();
+const entry = projects.register(EXAMPLE);
+console.log("registered project", entry.id, entry.path);
+
+const agents = readAgents(entry.path);
+console.log("agents:", agents.map((a) => `${a.slug} (${a.fields.Role || "-"}, ${a.fields.Model || "-"})`));
+assert(agents.length === 2, `expected 2 agents, got ${agents.length}`);
+assert(agents.find((a) => a.slug === "sofia"), "sofia missing");
+assert(agents.find((a) => a.slug === "martin"), "martin missing");
+
+// Sessions: scan .apc/agents/sofia/sessions/
+const sofiaSessions = (() => {
+  const dir = path.join(entry.path, ".apc", "agents", "sofia", "sessions");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+})();
+console.log("sofia sessions:", sofiaSessions);
+assert(sofiaSessions.length >= 1, "expected at least one sofia session");
+
+const reg = new McpRegistry(entry.path);
+const list = reg.list();
+console.log("mcps:", list.map((m) => `${m.name} (${m.source})`));
+assert(list.find((m) => m.name === "filesystem" && m.source === "apc"), "filesystem MCP missing");
+assert(list.find((m) => m.name === "brave" && m.source === "apc"), "brave MCP missing");
+const conflicts = reg.conflicts();
+console.log("conflicts:", conflicts);
+reg.shutdown();
+
+console.log("OK");