@agentprojectcontext/apx 1.0.3

package/src/core/scaffold.js

@@ -0,0 +1,417 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { readAgents, readAgentsFromDir, VAULT_DIR } from "./parser.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const SPEC_VERSION = "0.1.0";
+
+// ---------------------------------------------------------------------------
+// IDE skill targets — written during `apx init` and `apx skills add`
+// ---------------------------------------------------------------------------
+
+// Project-scoped targets (relative to project root).
+// `ideDir` = the IDE's root config dir that must already exist for the target to apply.
+export const IDE_TARGETS = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    ideDir: ".claude",
+    file: ".claude/skills/apx/SKILL.md",
+    render: (c) => buildSkillMd(c),
+    append: false,
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    ideDir: ".cursor",
+    file: ".cursor/rules/apx.mdc",
+    render: (c) =>
+      `---\ndescription: APX CLI skill. Activate when the user asks about running agents, coordinating between agents, or uses apx commands (apx run, apx exec, apx memory, apx mcp, apx session, apx messages).\n---\n\n${c}`,
+    append: false,
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    ideDir: ".windsurf",
+    file: ".windsurf/rules/apx.md",
+    render: (c) =>
+      `---\ntrigger: model_decision\ndescription: APX CLI skill. Activate when the user asks about running agents, coordinating between agents, or uses apx commands (apx run, apx exec, apx memory, apx mcp, apx session, apx messages).\n---\n\n${c}`,
+    append: false,
+  },
+  {
+    id: "copilot",
+    label: "GitHub Copilot",
+    ideDir: ".github",
+    file: ".github/copilot-instructions.md",
+    render: (c) => `\n<!-- apx-skill -->\n${c}\n<!-- /apx-skill -->\n`,
+    append: true,
+    guard: "<!-- apx-skill -->",
+  },
+  {
+    id: "trae",
+    label: "Trae",
+    ideDir: ".trae",
+    file: ".trae/rules/project_rules.md",
+    render: (c) => `\n<!-- apx-skill -->\n${c}\n<!-- /apx-skill -->\n`,
+    append: true,
+    guard: "<!-- apx-skill -->",
+  },
+];
+
+// Global targets (absolute paths, use ~/<dir>/skills/apx/SKILL.md format).
+// These dirs are read by Claude Code, Cursor (compat), and tools adopting the skills.sh spec.
+const GLOBAL_SKILL_DIRS = [
+  path.join(os.homedir(), ".claude", "skills"),    // Claude Code + Cursor legacy compat
+  path.join(os.homedir(), ".cursor", "skills"),    // Cursor primary global path
+  path.join(os.homedir(), ".codex",  "skills"),    // Codex (OpenAI)
+  path.join(os.homedir(), ".agents", "skills"),    // Antigravity/other skills.sh adopters
+];
+
+function buildApcContextSkillMd(content) {
+  const frontmatter = [
+    "---",
+    "name: apc-context",
+    "description: \"ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. Do not wait to be asked. Read .apc/ before making any assumption about agents, memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents', any question about agents or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the conversation with a migration offer before answering anything else. If the user declines, delete .apc/migrate.md immediately so it is not shown again.\"",
+    "homepage: https://github.com/agentprojectcontext/agentprojectcontext",
+    "---",
+    "",
+  ].join("\n");
+  return frontmatter + content;
+}
+
+function buildSkillMd(content) {
+  const frontmatter = [
+    "---",
+    "name: apx",
+    "description: APX CLI skill. Activate when: user asks to run or coordinate agents, use MCP tools from .apc/mcps.json, install agents from a team workspace, or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', 'run an agent', 'coordinate agents', 'MCP not working', 'install agent', 'team agents', 'apx memory', 'daemon'.",
+    "homepage: https://github.com/agentprojectcontext/apx",
+    "---",
+    "",
+  ].join("\n");
+  return frontmatter + content;
+}
+
+// Install APX + APC context skills into IDE rule files. Returns an array of result objects.
+// targetIds: array of target ids to install; null = all project targets.
+export function installIdeSkills(root, targetIds = null) {
+  const apxSrc = path.join(__dirname, "apx-skill.md");
+  const apcSrc = path.join(__dirname, "apc-context-skill.md");
+  if (!fs.existsSync(apxSrc)) return [];
+
+  const apxContent = fs.readFileSync(apxSrc, "utf8").trim();
+  const apcContent = fs.existsSync(apcSrc) ? fs.readFileSync(apcSrc, "utf8").trim() : null;
+
+  const targets = targetIds
+    ? IDE_TARGETS.filter((t) => targetIds.includes(t.id))
+    : IDE_TARGETS;
+
+  const results = [];
+  for (const t of targets) {
+    if (t.ideDir && !fs.existsSync(path.join(root, t.ideDir))) {
+      results.push({ ...t, status: "skipped (IDE not present)" });
+      continue;
+    }
+
+    // Install APX skill
+    const dest = path.join(root, t.file);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const rendered = t.render(apxContent);
+    if (t.append) {
+      const existing = fs.existsSync(dest) ? fs.readFileSync(dest, "utf8") : "";
+      if (t.guard && existing.includes(t.guard)) {
+        results.push({ ...t, status: "already installed" });
+      } else {
+        fs.appendFileSync(dest, rendered, "utf8");
+        results.push({ ...t, status: "appended" });
+      }
+    } else {
+      const existed = fs.existsSync(dest);
+      fs.writeFileSync(dest, rendered, "utf8");
+      results.push({ ...t, status: existed ? "updated" : "created" });
+    }
+
+    // Install APC context skill alongside (only for non-append targets with a skills dir)
+    if (apcContent && t.id === "claude-code") {
+      const apcDest = path.join(root, ".claude", "skills", "apc-context", "SKILL.md");
+      fs.mkdirSync(path.dirname(apcDest), { recursive: true });
+      const existed = fs.existsSync(apcDest);
+      fs.writeFileSync(apcDest, buildApcContextSkillMd(apcContent), "utf8");
+      results.push({ ...t, id: "claude-code/apc-context", label: "Claude Code (apc-context)", file: apcDest, status: existed ? "updated" : "created" });
+    }
+  }
+  return results;
+}
+
+// Install both APX and APC context skills to global ~/.../skills/ dirs.
+// Returns an array of result objects with { dir, skill, status }.
+export function installGlobalSkills() {
+  const results = [];
+
+  const apxSrc = path.join(__dirname, "apx-skill.md");
+  const apcSrc = path.join(__dirname, "apc-context-skill.md");
+
+  const skills = [];
+  if (fs.existsSync(apxSrc))
+    skills.push({ slug: "apx", md: buildSkillMd(fs.readFileSync(apxSrc, "utf8").trim()) });
+  if (fs.existsSync(apcSrc))
+    skills.push({ slug: "apc-context", md: buildApcContextSkillMd(fs.readFileSync(apcSrc, "utf8").trim()) });
+
+  for (const base of GLOBAL_SKILL_DIRS) {
+    for (const { slug, md } of skills) {
+      const dest = path.join(base, slug, "SKILL.md");
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const existed = fs.existsSync(dest);
+      fs.writeFileSync(dest, md, "utf8");
+      results.push({ dir: base, skill: slug, file: dest, status: existed ? "updated" : "created" });
+    }
+  }
+  return results;
+}
+
+
+const AGENTS_MD_TEMPLATE = `# Agents
+
+> This file is the contract for agents in this project.
+> It follows the APC spec (https://github.com/agentprojectcontext/agentprojectcontext).
+
+<!-- Add an agent like this:
+
+## sofia
+- **Role**: Support
+- **Model**: claude-haiku-4-5
+- **Skills**: customer-support
+- **Language**: es-AR
+
+-->
+`;
+
+const APC_GITIGNORE = `# APC runtime data — local-first by default
+agents/*/sessions/
+sessions/
+chats/
+cache/
+tmp/
+private/
+secrets/
+*.local.json
+*.secret.json
+*.env
+*.env.*
+migrate.md
+`;
+
+function nowIso() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+// Files that carry project context but are IDE-specific — candidates for APC migration.
+const SCATTERED_CONTEXT_FILES = [
+  { file: "CLAUDE.md",                         label: "Claude Code instructions" },
+  { file: ".cursorrules",                      label: "Cursor rules" },
+  { file: ".windsurfrules",                    label: "Windsurf rules" },
+  { file: ".clinerules",                       label: "Cline rules" },
+  { file: ".github/copilot-instructions.md",   label: "GitHub Copilot instructions" },
+  { file: ".trae/rules/project_rules.md",      label: "Trae rules" },
+];
+
+// Returns files found in `root` that look like scattered context.
+export function detectScatteredContext(root) {
+  return SCATTERED_CONTEXT_FILES.filter(({ file }) =>
+    fs.existsSync(path.join(root, file))
+  );
+}
+
+// Writes .apc/migrate.md so the next agent session opens with a migration offer.
+function writeMigrateMd(apfDir, found) {
+  const lines = [
+    "# APC Migration Pending",
+    "",
+    "This file was created by `apx init`. It signals to agents that this project",
+    "has existing context files that have not yet been migrated to `.apc/`.",
+    "",
+    "**Delete this file** once migration is complete.",
+    "",
+    "## Detected files",
+    "",
+    ...found.map(({ file, label }) => `- \`${file}\` — ${label}`),
+  ];
+  fs.writeFileSync(path.join(apfDir, "migrate.md"), lines.join("\n") + "\n");
+}
+
+export function initApf(directory, { name } = {}) {
+  const root = path.resolve(directory);
+  fs.mkdirSync(root, { recursive: true });
+
+  const apfDir = path.join(root, ".apc");
+  fs.mkdirSync(path.join(apfDir, "agents"), { recursive: true });
+  fs.mkdirSync(path.join(apfDir, "skills"), { recursive: true });
+  fs.mkdirSync(path.join(apfDir, "commands"), { recursive: true });
+
+  const projectJson = path.join(apfDir, "project.json");
+  if (!fs.existsSync(projectJson)) {
+    fs.writeFileSync(
+      projectJson,
+      JSON.stringify(
+        {
+          name: name || path.basename(root),
+          version: "0.1.0",
+          apf: SPEC_VERSION,
+          created: nowIso(),
+          apx: null,
+          sessions: { defaultVisibility: "local" },
+        },
+        null,
+        2
+      ) + "\n"
+    );
+  }
+
+  const gitignore = path.join(apfDir, ".gitignore");
+  if (!fs.existsSync(gitignore)) {
+    fs.writeFileSync(gitignore, APC_GITIGNORE);
+  }
+
+  const agentsMd = path.join(root, "AGENTS.md");
+  if (!fs.existsSync(agentsMd)) {
+    fs.writeFileSync(agentsMd, AGENTS_MD_TEMPLATE);
+  }
+
+  // Detect scattered context files and flag for agent-driven migration.
+  const scattered = detectScatteredContext(root);
+  const migrateMd = path.join(apfDir, "migrate.md");
+  if (scattered.length > 0 && !fs.existsSync(migrateMd)) {
+    writeMigrateMd(apfDir, scattered);
+  }
+
+  return { root, agentsMd, projectJson, pendingMigration: scattered };
+}
+
+export function ensureAgentDir(root, slug) {
+  const dir = path.join(root, ".apc", "agents", slug);
+  fs.mkdirSync(path.join(dir, "sessions"), { recursive: true });
+  const memory = path.join(dir, "memory.md");
+  if (!fs.existsSync(memory)) {
+    fs.writeFileSync(
+      memory,
+      `# Memory — ${slug}\n\n` +
+        `## Identity\n- \n\n` +
+        `## Long-term facts\n- \n\n` +
+        `## Recent context\n- \n`
+    );
+  }
+  return dir;
+}
+
+// Write .apc/agents/<slug>.md — the canonical agent definition file.
+export function writeAgentFile(root, slug, fields, body = "") {
+  const dest = path.join(root, ".apc", "agents", `${slug}.md`);
+  const lines = ["---"];
+  const order = ["role", "model", "language", "description", "skills", "tools"];
+  const written = new Set();
+  for (const key of order) {
+    const titleKey = key.charAt(0).toUpperCase() + key.slice(1);
+    const v = fields[titleKey] ?? fields[key];
+    if (v === undefined || v === null || v === "") continue;
+    const value = Array.isArray(v) ? v.join(", ") : v;
+    lines.push(`${key}: ${value}`);
+    written.add(titleKey);
+  }
+  // Any extra fields not in the ordered list
+  for (const [k, v] of Object.entries(fields)) {
+    const titleKey = k.charAt(0).toUpperCase() + k.slice(1);
+    if (written.has(titleKey) || v === undefined || v === null || v === "") continue;
+    const value = Array.isArray(v) ? v.join(", ") : v;
+    lines.push(`${k.toLowerCase()}: ${value}`);
+  }
+  lines.push("---");
+  if (body) lines.push("", body);
+  fs.writeFileSync(dest, lines.join("\n") + "\n");
+}
+
+// Write a vault agent template to ~/.apx/agents/<slug>.md
+export function writeVaultAgentFile(slug, fields, body = "") {
+  fs.mkdirSync(VAULT_DIR, { recursive: true });
+  const dest = path.join(VAULT_DIR, `${slug}.md`);
+  const lines = ["---"];
+  const order = ["role", "model", "language", "description", "skills", "tools"];
+  const written = new Set();
+  for (const key of order) {
+    const titleKey = key.charAt(0).toUpperCase() + key.slice(1);
+    const v = fields[titleKey] ?? fields[key];
+    if (v === undefined || v === null || v === "") continue;
+    lines.push(`${key}: ${Array.isArray(v) ? v.join(", ") : v}`);
+    written.add(titleKey);
+  }
+  for (const [k, v] of Object.entries(fields)) {
+    const titleKey = k.charAt(0).toUpperCase() + k.slice(1);
+    if (written.has(titleKey) || v === undefined || v === null || v === "") continue;
+    lines.push(`${k.toLowerCase()}: ${Array.isArray(v) ? v.join(", ") : v}`);
+  }
+  lines.push("---");
+  if (body) lines.push("", body);
+  fs.writeFileSync(dest, lines.join("\n") + "\n");
+}
+
+// Add a slug to the project's agents.imported list in project.json
+export function addImportedAgent(root, slug) {
+  const p = path.join(root, ".apc", "project.json");
+  let cfg = {};
+  try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+  if (!cfg.agents) cfg.agents = {};
+  if (!cfg.agents.imported) cfg.agents.imported = [];
+  if (!cfg.agents.imported.includes(slug)) cfg.agents.imported.push(slug);
+  fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+// Regenerate AGENTS.md from .apc/agents/*.md for Codex/Antigravity compat.
+export function regenerateAgentsMd(root) {
+  const agents = readAgents(root);
+  const header = [
+    "# Agents",
+    "",
+    "> Auto-generated from .apc/agents/*.md — edit individual agent files, not this file.",
+    "> Read by Codex, Antigravity, and other tools that follow the AGENTS.md convention.",
+    "",
+  ].join("\n");
+
+  if (agents.length === 0) {
+    fs.writeFileSync(path.join(root, "AGENTS.md"), header);
+    return;
+  }
+
+  const blocks = agents.map((a) => {
+    const tag = a.source === "vault" ? "  <!-- vault -->" : "";
+    return renderAgentBlock(a.slug, a.fields) + tag;
+  });
+  fs.writeFileSync(path.join(root, "AGENTS.md"), header + blocks.join("\n\n") + "\n");
+}
+
+export function appendAgentToAgentsMd(root, slug, fields) {
+  const agentsMdPath = path.join(root, "AGENTS.md");
+  let text = fs.existsSync(agentsMdPath)
+    ? fs.readFileSync(agentsMdPath, "utf8")
+    : AGENTS_MD_TEMPLATE;
+
+  if (!/^#\s+Agents\s*$/im.test(text)) {
+    text = `# Agents\n\n${text}`;
+  }
+
+  const block = renderAgentBlock(slug, fields);
+
+  if (!text.endsWith("\n")) text += "\n";
+  text += `\n${block}\n`;
+  fs.writeFileSync(agentsMdPath, text);
+}
+
+export function renderAgentBlock(slug, fields) {
+  const lines = [`## ${slug}`];
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === undefined || v === null || v === "") continue;
+    const value = Array.isArray(v) ? v.join(", ") : v;
+    lines.push(`- **${k}**: ${value}`);
+  }
+  return lines.join("\n");
+}

package/src/core/session-store.js

@@ -0,0 +1,36 @@
+// Session id generator: YYYY-MM-DD-NN, auto-incremented per agent per UTC day.
+// Mirrors cli/src/id.js — kept duplicated so the daemon doesn't import from
+// the CLI module tree.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export function generateSessionId(projectRoot, agentSlug) {
+  const today = new Date().toISOString().slice(0, 10);
+  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "sessions");
+  let next = 1;
+  if (fs.existsSync(dir)) {
+    for (const f of fs.readdirSync(dir)) {
+      const m = f.match(new RegExp(`^${today}-(\\d{2,})\\.md$`));
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (n + 1 > next) next = n + 1;
+      }
+    }
+  }
+  return `${today}-${String(next).padStart(2, "0")}`;
+}
+
+export function readSessionFrontmatter(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const text = fs.readFileSync(filePath, "utf8");
+  if (!text.startsWith("---\n")) return null;
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) return null;
+  const fm = {};
+  for (const line of text.slice(4, end).split("\n")) {
+    const m = line.match(/^([a-zA-Z_]+):\s*(.*)$/);
+    if (m) fm[m[1]] = m[2].trim();
+  }
+  return { fm, body: text.slice(end + 4).replace(/^\n+/, "") };
+}

package/src/daemon/apc-runtime-context.js

@@ -0,0 +1,123 @@
+// Helpers that wrap external runtimes (Claude Code, Codex, OpenCode, Aider)
+// with APC awareness:
+//
+//   1. Create an APC session BEFORE the runtime starts.
+//   2. Inject an "APC Runtime Context" block into the system prompt so the
+//      runtime knows the session id, the cwd of the project, and the apx
+//      commands it can use to update memory / append session notes.
+//   3. After the runtime returns, capture the external transcript path
+//      (Claude Code gives one, Codex/OpenCode/Aider don't yet) and write it
+//      into the APC session frontmatter.
+//   4. Close the session with a synthesised result (truncated stdout).
+//
+// Used by both POST /projects/:pid/agents/:slug/runtime (CLI) and the
+// super-agent's call_runtime tool.
+
+import fs from "node:fs";
+import path from "node:path";
+import { generateSessionId } from "../core/session-store.js";
+
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
+const APC_RUNTIME_HINT = `
+# APC Runtime Context
+
+You are running inside an APC (Agent Project Framework) project. APC gives you durable session state across runs.
+
+- **Project**: {{name}}  ({{path}})
+- **Agent**: {{agent}}
+- **APC session id**: {{session_id}}
+  (filename: .apc/agents/{{agent}}/sessions/{{session_id}}.md)
+
+## Commands you can use during this run
+
+- \`apx memory {{agent}} --append "<note>"\`        save a long-term fact for this agent
+- \`apx session update {{session_id}} --status "..."\`   update the session status
+- \`apx session update {{session_id}} --task-ref TASK-...\`  link to an external task
+
+## When you finish
+
+Close the session with a one-line result so a future operator (or apx session resume) can summarize:
+
+  apx session close {{session_id}} --result "<one-line summary of what you did>"
+
+If you cannot run apx (sandboxed shell), just print the result on the last line of your output prefixed with "APC_RESULT:" and APX will capture it automatically.
+`.trim();
+
+export function buildApfHint({ projectName, projectPath, agentSlug, sessionId }) {
+  return APC_RUNTIME_HINT
+    .replace(/\{\{name\}\}/g, projectName)
+    .replace(/\{\{path\}\}/g, projectPath)
+    .replace(/\{\{agent\}\}/g, agentSlug)
+    .replace(/\{\{session_id\}\}/g, sessionId);
+}
+
+// Create the APC session file on disk. Returns { id, filename, path }.
+export function createRuntimeSession({ projectRoot, agentSlug, runtime, taskRef = "", title }) {
+  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "sessions");
+  fs.mkdirSync(dir, { recursive: true });
+  const id = generateSessionId(projectRoot, agentSlug);
+  const file = path.join(dir, `${id}.md`);
+  const started = nowIso();
+  const sessionTitle = title || `Runtime: ${runtime}`;
+  const body =
+    `---\n` +
+    `id: ${id}\n` +
+    `agent: ${agentSlug}\n` +
+    `title: ${sessionTitle}\n` +
+    `task_ref: ${taskRef}\n` +
+    `status: 🔄 En progreso\n` +
+    `started: ${started}\n` +
+    `completed: \n` +
+    `result: \n` +
+    `runtime: ${runtime}\n` +
+    `external_session_path: \n` +
+    `---\n\n` +
+    `# ${sessionTitle}\n\n`;
+  fs.writeFileSync(file, body);
+  return { id, filename: `${id}.md`, path: file };
+}
+
+// Update session frontmatter with the external transcript path captured from
+// the runtime adapter. Closes the session with a result string.
+export function closeRuntimeSession({ filePath, externalSessionPath, exitCode, result }) {
+  let text = fs.readFileSync(filePath, "utf8");
+  text = setField(text, "completed", nowIso());
+  if (externalSessionPath) {
+    text = setField(text, "external_session_path", externalSessionPath);
+  }
+  if (typeof exitCode === "number") {
+    text = setField(text, "result", `${exitCode === 0 ? "✅" : "⚠️"} exit ${exitCode}: ${(result || "").slice(0, 200)}`);
+  } else if (result) {
+    text = setField(text, "result", result.slice(0, 300));
+  }
+  text = setField(text, "status", exitCode === 0 ? "✅ Completada" : "⚠️ Cerrada con error");
+  fs.writeFileSync(filePath, text);
+}
+
+function setField(text, field, value) {
+  if (!text.startsWith("---\n")) return text;
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) return text;
+  const fmText = text.slice(4, end);
+  const lines = fmText.split("\n");
+  let found = false;
+  const out = lines.map((line) => {
+    if (line.startsWith(`${field}:`)) {
+      found = true;
+      return `${field}: ${value}`;
+    }
+    return line;
+  });
+  if (!found) out.push(`${field}: ${value}`);
+  return `---\n${out.join("\n")}\n---${text.slice(end + 4)}`;
+}
+
+// Look at the runtime's stdout for a self-reported "APC_RESULT: ..." line
+// (the convention printed in the hint above). Returns the captured string or
+// null. This is the fallback for runtimes that can't shell out.
+export function extractApfResult(stdout) {
+  if (!stdout || typeof stdout !== "string") return null;
+  const m = stdout.match(/^APC_RESULT:\s*(.+?)\s*$/m);
+  return m ? m[1].trim() : null;
+}