@agentprojectcontext/apx 1.0.3

package/src/daemon/compact.js

@@ -0,0 +1,140 @@
+// Conversation compaction: collapses a long conversation into a dense summary
+// turn, preserving the last N turns for immediate context.
+//
+// On disk, a compacted file looks like:
+//
+//   ---
+//   ...frontmatter...
+//   status: compacted
+//   compacted_at: 2026-05-08T12:00:00Z
+//   compacted_turns: 47
+//   ---
+//
+//   ## compact — 2026-05-08T12:00:00Z
+//   [Compacted 47 turns on 2026-05-08T12:00:00Z]
+//
+//   <dense summary here>
+//
+//   ## user — ...          ← last KEEP_LAST turns kept verbatim
+//   ...
+//
+// When the chat endpoint reads a compacted conversation it injects the compact
+// block into the system prompt (not into messages[]), so the model has context
+// without burning tokens on old exchanges.
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseConversation } from "./conversations.js";
+import { callEngine } from "./engines/index.js";
+
+const KEEP_LAST = 6;
+
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
+const COMPACT_SYSTEM =
+  "You summarize conversations for AI agent context continuity. " +
+  "Be dense and factual — another AI will read this to continue the work.";
+
+const COMPACT_PROMPT = `Summarize this conversation for future context.
+
+Cover:
+- Main task or goal being worked on
+- Key decisions made and why
+- Files, code, commands modified (exact paths where relevant)
+- Current state: what's done, what's pending or unresolved
+- Errors encountered and how they were resolved
+
+Style: dense and factual. No pleasantries. No meta-commentary. Just the facts.
+
+---
+
+`;
+
+// Resolve the most-recent conversation file for an agent, or the one explicitly
+// named. Returns the full filepath.
+function resolveConvFile(projectRoot, agentSlug, filename) {
+  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "conversations");
+  if (!fs.existsSync(dir)) throw new Error(`no conversations dir for agent "${agentSlug}"`);
+
+  if (filename) {
+    const f = filename.endsWith(".md") ? filename : `${filename}.md`;
+    const p = path.join(dir, f);
+    if (!fs.existsSync(p)) throw new Error(`conversation not found: ${f}`);
+    return p;
+  }
+
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+  if (!files.length) throw new Error(`no conversations found for agent "${agentSlug}"`);
+  return path.join(dir, files[files.length - 1]);
+}
+
+// Rebuild frontmatter string from a plain object.
+function serializeFm(obj) {
+  return Object.entries(obj)
+    .map(([k, v]) => `${k}: ${v ?? ""}`)
+    .join("\n");
+}
+
+export async function compactConversation({
+  projectRoot,
+  agentSlug,
+  filename,
+  modelId,
+  config,
+}) {
+  const filepath = resolveConvFile(projectRoot, agentSlug, filename);
+  const raw = fs.readFileSync(filepath, "utf8");
+  const { fm, turns } = parseConversation(raw);
+
+  // Exclude any existing compact markers from the turn count / transcript.
+  const realTurns = turns.filter((t) => t.role !== "compact");
+  if (realTurns.length === 0) throw new Error("nothing to compact — no user/assistant turns");
+
+  // Build a readable transcript for the model.
+  const transcript = realTurns
+    .map((t) => `[${t.role.toUpperCase()}]\n${t.content}`)
+    .join("\n\n---\n\n");
+
+  const result = await callEngine({
+    modelId,
+    system: COMPACT_SYSTEM,
+    messages: [{ role: "user", content: COMPACT_PROMPT + transcript }],
+    config,
+  });
+
+  const summary = result.text.trim();
+  const ts = nowIso();
+  const turnCount = realTurns.length;
+
+  // Keep the last N real turns verbatim for immediate context.
+  const recentTurns = realTurns.slice(-KEEP_LAST);
+
+  const updatedFm = {
+    ...fm,
+    status: "compacted",
+    compacted_at: ts,
+    compacted_turns: turnCount,
+    last_turn: ts,
+  };
+
+  const compactBlock =
+    `## compact — ${ts}\n` +
+    `[Compacted ${turnCount} turns on ${ts}]\n\n` +
+    `${summary}\n\n`;
+
+  const recentBlocks = recentTurns
+    .map((t) => `## ${t.role} — ${t.ts}\n${t.content}\n\n`)
+    .join("");
+
+  const newContent = `---\n${serializeFm(updatedFm)}\n---\n\n${compactBlock}${recentBlocks}`;
+  fs.writeFileSync(filepath, newContent);
+
+  return {
+    filename: path.basename(filepath),
+    compacted_turns: turnCount,
+    kept_turns: recentTurns.length,
+    model: modelId,
+    summary,
+    usage: result.usage,
+  };
+}

package/src/daemon/conversations.js

@@ -0,0 +1,108 @@
+// Conversation storage: append-only markdown at .apc/agents/<slug>/conversations/
+// with SQLite mirror for fast querying. Filesystem is source of truth.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
+export function generateConversationId(projectRoot, agentSlug) {
+  const today = new Date().toISOString().slice(0, 10);
+  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "conversations");
+  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 conversationPath(projectRoot, agentSlug, idOrFilename) {
+  const filename = idOrFilename.endsWith(".md") ? idOrFilename : `${idOrFilename}.md`;
+  return path.join(projectRoot, ".apc", "agents", agentSlug, "conversations", filename);
+}
+
+export function startConversation({ projectRoot, agentSlug, engine, system }) {
+  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "conversations");
+  fs.mkdirSync(dir, { recursive: true });
+  const id = generateConversationId(projectRoot, agentSlug);
+  const file = path.join(dir, `${id}.md`);
+  const started = nowIso();
+  const fm =
+    `---\n` +
+    `id: ${id}\n` +
+    `agent: ${agentSlug}\n` +
+    `engine: ${engine}\n` +
+    `started: ${started}\n` +
+    `last_turn: \n` +
+    `status: open\n` +
+    `---\n\n` +
+    (system ? `## system — ${started}\n${system}\n\n` : "");
+  fs.writeFileSync(file, fm);
+  return { id, filename: `${id}.md`, path: file, started };
+}
+
+export function appendTurn({ filePath, role, content }) {
+  const ts = nowIso();
+  const block = `## ${role} — ${ts}\n${content}\n\n`;
+  fs.appendFileSync(filePath, block);
+  // Update last_turn in frontmatter (in-place)
+  let text = fs.readFileSync(filePath, "utf8");
+  text = text.replace(/^last_turn:.*$/m, `last_turn: ${ts}`);
+  fs.writeFileSync(filePath, text);
+  return { ts };
+}
+
+// Parse a conversation file into structured turns. Tolerant — anything that
+// doesn't look like a turn header is ignored.
+export function parseConversation(text) {
+  const fmEnd = text.indexOf("\n---", 4);
+  const fm = {};
+  let body = text;
+  if (text.startsWith("---\n") && fmEnd !== -1) {
+    for (const line of text.slice(4, fmEnd).split("\n")) {
+      const m = line.match(/^([a-zA-Z_]+):\s*(.*)$/);
+      if (m) fm[m[1]] = m[2].trim();
+    }
+    body = text.slice(fmEnd + 4);
+  }
+  const turns = [];
+  const re = /^##\s+(user|assistant|system|tool|compact)\s+—\s+(\S+)\s*\n([\s\S]*?)(?=\n##\s+(?:user|assistant|system|tool|compact)\s+—\s|\n*$)/gm;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    turns.push({
+      role: m[1],
+      ts: m[2],
+      content: m[3].trim(),
+    });
+  }
+  return { fm, turns };
+}
+
+export function readConversation(projectRoot, agentSlug, idOrFilename) {
+  const p = conversationPath(projectRoot, agentSlug, idOrFilename);
+  if (!fs.existsSync(p)) return null;
+  return { ...parseConversation(fs.readFileSync(p, "utf8")), path: p };
+}
+
+export function listConversations(projectRoot, agentSlug) {
+  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "conversations");
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .sort()
+    .reverse()
+    .map((f) => ({ filename: f, id: f.replace(/\.md$/, "") }));
+}
+
+export function setStatus(filePath, status) {
+  let text = fs.readFileSync(filePath, "utf8");
+  text = text.replace(/^status:.*$/m, `status: ${status}`);
+  fs.writeFileSync(filePath, text);
+}

package/src/daemon/db.js

@@ -0,0 +1,81 @@
+// ProjectManager: in-memory registry of open projects.
+// Projects are identified by path; no SQLite — filesystem is the source of truth.
+import fs from "node:fs";
+import path from "node:path";
+import { appendMessageToFs } from "../core/messages-store.js";
+import { effectiveConfig } from "./project-config.js";
+import { readAgents } from "../core/parser.js";
+
+export class ProjectManager {
+  constructor(globalConfig = {}) {
+    this.byId = new Map();   // id -> { id, path, config, logMessage }
+    this.byPath = new Map(); // absolute path -> entry
+    this._nextId = 1;
+    this.globalConfig = globalConfig;
+  }
+
+  setGlobalConfig(cfg) {
+    this.globalConfig = cfg;
+    for (const entry of this.byId.values()) {
+      entry.config = effectiveConfig(this.globalConfig, entry.path);
+    }
+  }
+
+  register(projectPath) {
+    const abs = path.resolve(projectPath);
+    if (this.byPath.has(abs)) return this.byPath.get(abs);
+    const projectJson = path.join(abs, ".apc", "project.json");
+    if (!fs.existsSync(projectJson)) {
+      throw new Error(`not an APC project: ${abs}`);
+    }
+    // Ensure directories exist for projects initialized before they were added.
+    fs.mkdirSync(path.join(abs, ".apc", "commands"), { recursive: true });
+    fs.mkdirSync(path.join(abs, ".apc", "messages"), { recursive: true });
+
+    const entry = {
+      id: this._nextId++,
+      path: abs,
+      config: effectiveConfig(this.globalConfig, abs),
+    };
+    entry.logMessage = (payload) => appendMessageToFs({ projectRoot: abs, ...payload });
+    this.byId.set(entry.id, entry);
+    this.byPath.set(abs, entry);
+    return entry;
+  }
+
+  get(id) {
+    return this.byId.get(Number(id)) || null;
+  }
+
+  getByPath(p) {
+    return this.byPath.get(path.resolve(p)) || null;
+  }
+
+  list() {
+    return Array.from(this.byId.values()).map((e) => {
+      let name = path.basename(e.path);
+      try {
+        const meta = JSON.parse(
+          fs.readFileSync(path.join(e.path, ".apc", "project.json"), "utf8")
+        );
+        if (meta.name) name = meta.name;
+      } catch {}
+      return { id: e.id, path: e.path, name, agents: readAgents(e.path).length };
+    });
+  }
+
+  unregister(id) {
+    const entry = this.byId.get(Number(id));
+    if (!entry) return false;
+    this.byId.delete(entry.id);
+    this.byPath.delete(entry.path);
+    return true;
+  }
+
+  rebuild(id) {
+    const entry = this.get(id);
+    if (!entry) throw new Error(`unknown project id ${id}`);
+    entry.config = effectiveConfig(this.globalConfig, entry.path);
+    return { projectRoot: entry.path, agents: readAgents(entry.path).length };
+  }
+}

package/src/daemon/engines/anthropic.js

@@ -0,0 +1,58 @@
+// Anthropic Messages API adapter (https://docs.anthropic.com/en/api/messages).
+// No SDK dependency — direct fetch, keeps the daemon lean.
+
+const API_BASE = "https://api.anthropic.com/v1/messages";
+const API_VERSION = "2023-06-01";
+
+function getKey(config) {
+  return config.api_key || process.env.ANTHROPIC_API_KEY || "";
+}
+
+export default {
+  id: "anthropic",
+
+  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {} }) {
+    const key = getKey(config);
+    if (!key) throw new Error("anthropic: no api_key (set ANTHROPIC_API_KEY or engines.anthropic.api_key)");
+    if (!model) throw new Error("anthropic: model required");
+
+    const body = {
+      model,
+      max_tokens: maxTokens,
+      temperature,
+      messages: messages.map((m) => ({
+        role: m.role === "assistant" ? "assistant" : "user",
+        content: typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+      })),
+    };
+    if (system) body.system = system;
+
+    const res = await fetch(API_BASE, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-api-key": key,
+        "anthropic-version": API_VERSION,
+      },
+      body: JSON.stringify(body),
+    });
+    const json = await res.json();
+    if (!res.ok) {
+      throw new Error(
+        `anthropic ${res.status}: ${json?.error?.message || JSON.stringify(json)}`
+      );
+    }
+    const text = (json.content || [])
+      .filter((b) => b.type === "text")
+      .map((b) => b.text)
+      .join("");
+    return {
+      text,
+      usage: {
+        input_tokens: json.usage?.input_tokens || 0,
+        output_tokens: json.usage?.output_tokens || 0,
+      },
+      raw: json,
+    };
+  },
+};

package/src/daemon/engines/gemini.js

@@ -0,0 +1,55 @@
+// Google Gemini adapter (https://ai.google.dev/api/generate-content).
+// Direct fetch, no SDK.
+
+const API_BASE = "https://generativelanguage.googleapis.com/v1beta/models";
+
+function getKey(config) {
+  return config.api_key || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || "";
+}
+
+export default {
+  id: "gemini",
+
+  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, config = {} }) {
+    const key = getKey(config);
+    if (!key) throw new Error("gemini: no api_key (set GEMINI_API_KEY or engines.gemini.api_key)");
+    if (!model) throw new Error("gemini: model required");
+
+    // Gemini's API splits roles into 'user' and 'model'. System goes in
+    // systemInstruction at the top level.
+    const contents = messages.map((m) => ({
+      role: m.role === "assistant" ? "model" : "user",
+      parts: [{ text: typeof m.content === "string" ? m.content : JSON.stringify(m.content) }],
+    }));
+
+    const body = {
+      contents,
+      generationConfig: { temperature, maxOutputTokens: maxTokens },
+    };
+    if (system) body.systemInstruction = { parts: [{ text: system }] };
+
+    const url = `${API_BASE}/${encodeURIComponent(model)}:generateContent?key=${key}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    const json = await res.json();
+    if (!res.ok) {
+      throw new Error(
+        `gemini ${res.status}: ${json?.error?.message || JSON.stringify(json)}`
+      );
+    }
+    const text = (json.candidates?.[0]?.content?.parts || [])
+      .map((p) => p.text)
+      .join("");
+    return {
+      text,
+      usage: {
+        input_tokens: json.usageMetadata?.promptTokenCount || 0,
+        output_tokens: json.usageMetadata?.candidatesTokenCount || 0,
+      },
+      raw: json,
+    };
+  },
+};

package/src/daemon/engines/index.js

@@ -0,0 +1,65 @@
+// Engine adapter registry. Maps a model id → provider → adapter.
+//
+// Model id grammar (in agents.<slug>.model):
+//   "<provider>:<model>"   explicit, e.g. "ollama:llama3.2", "anthropic:claude-haiku-4-5"
+//   "<model>"              inferred: claude-* → anthropic, gpt-* → openai, gemini-* → gemini
+//
+// Each adapter exports a default object:
+//   { id, chat({system, messages, model, temperature, maxTokens}) → {text, usage, raw} }
+//
+// API keys come from ~/.apx/config.json `engines.<provider>.api_key` or env vars
+// (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY).
+// Ollama needs no key, just a base_url (default http://localhost:11434).
+
+import anthropic from "./anthropic.js";
+import openai from "./openai.js";
+import ollama from "./ollama.js";
+import gemini from "./gemini.js";
+import mock from "./mock.js";
+
+const ADAPTERS = { anthropic, openai, ollama, gemini, mock };
+
+export function resolveProvider(modelId) {
+  if (typeof modelId !== "string" || !modelId) {
+    throw new Error("model id is empty");
+  }
+  if (modelId.includes(":")) {
+    const [provider, ...rest] = modelId.split(":");
+    return { provider: provider.toLowerCase(), model: rest.join(":") };
+  }
+  if (/^claude/i.test(modelId)) return { provider: "anthropic", model: modelId };
+  if (/^gpt|^o1|^o3|^o4/i.test(modelId)) return { provider: "openai", model: modelId };
+  if (/^gemini/i.test(modelId)) return { provider: "gemini", model: modelId };
+  if (modelId === "mock") return { provider: "mock", model: "mock" };
+  throw new Error(
+    `cannot infer provider for model "${modelId}" — use explicit "<provider>:<model>" form`
+  );
+}
+
+export function getAdapter(provider) {
+  const a = ADAPTERS[provider];
+  if (!a) {
+    throw new Error(
+      `unknown engine provider "${provider}". Known: ${Object.keys(ADAPTERS).join(", ")}`
+    );
+  }
+  return a;
+}
+
+export async function callEngine({ modelId, system, messages, config, temperature, maxTokens, tools }) {
+  const { provider, model } = resolveProvider(modelId);
+  const adapter = getAdapter(provider);
+  const providerCfg =
+    (config && config.engines && config.engines[provider]) || {};
+  return adapter.chat({
+    system,
+    messages,
+    model,
+    temperature,
+    maxTokens,
+    tools,
+    config: providerCfg,
+  });
+}
+
+export const ENGINE_IDS = Object.keys(ADAPTERS);

package/src/daemon/engines/mock.js

@@ -0,0 +1,18 @@
+// Mock engine for tests and offline development. No network. Echoes back the
+// last user message with a small transformation so it's distinguishable from
+// the input. Use model "mock" or "mock:anything".
+
+export default {
+  id: "mock",
+
+  async chat({ system, messages, model = "mock" }) {
+    const last = [...messages].reverse().find((m) => m.role === "user");
+    const userText = last?.content || "";
+    const sysHint = system ? ` (system: ${system.slice(0, 40)}…)` : "";
+    return {
+      text: `[mock:${model}] received: ${userText}${sysHint}`,
+      usage: { input_tokens: userText.length, output_tokens: 32 },
+      raw: { model, mock: true },
+    };
+  },
+};

package/src/daemon/engines/ollama.js

@@ -0,0 +1,66 @@
+// Ollama adapter (https://github.com/ollama/ollama/blob/main/docs/api.md#generate-a-chat-completion).
+// Local-only. No API key. Default base_url http://localhost:11434.
+
+function baseUrl(config) {
+  return config.base_url || process.env.OLLAMA_HOST || "http://localhost:11434";
+}
+
+export default {
+  id: "ollama",
+
+  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, tools, config = {} }) {
+    if (!model) throw new Error("ollama: model required");
+
+    // The caller can pass `messages` as either:
+    //   [{role, content}]                       — usual shape
+    //   [{role, content, tool_calls?}, {role: "tool", tool_call_id?, content}, ...]
+    // We forward those fields straight through so the agent loop works.
+    const fullMessages = [];
+    if (system) fullMessages.push({ role: "system", content: system });
+    for (const m of messages) {
+      const out = { role: m.role };
+      if (m.content !== undefined) {
+        out.content =
+          typeof m.content === "string" ? m.content : JSON.stringify(m.content);
+      } else {
+        out.content = "";
+      }
+      if (m.tool_calls) out.tool_calls = m.tool_calls;
+      if (m.tool_name) out.tool_name = m.tool_name; // Ollama uses this field on role:"tool"
+      fullMessages.push(out);
+    }
+
+    const body = {
+      model,
+      messages: fullMessages,
+      stream: false,
+      options: { temperature, num_predict: maxTokens },
+    };
+    if (Array.isArray(tools) && tools.length > 0) {
+      body.tools = tools;
+    }
+
+    const url = `${baseUrl(config).replace(/\/$/, "")}/api/chat`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`ollama ${res.status}: ${text}`);
+    }
+    const json = await res.json();
+    const message = json.message || {};
+    return {
+      text: message.content || "",
+      tool_calls: message.tool_calls || null,
+      message,
+      usage: {
+        input_tokens: json.prompt_eval_count || 0,
+        output_tokens: json.eval_count || 0,
+      },
+      raw: json,
+    };
+  },
+};

package/src/daemon/engines/openai.js

@@ -0,0 +1,58 @@
+// OpenAI Chat Completions adapter (https://platform.openai.com/docs/api-reference/chat).
+// Direct fetch, no SDK.
+
+const API_BASE = "https://api.openai.com/v1/chat/completions";
+
+function getKey(config) {
+  return config.api_key || process.env.OPENAI_API_KEY || "";
+}
+
+export default {
+  id: "openai",
+
+  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {} }) {
+    const key = getKey(config);
+    if (!key) throw new Error("openai: no api_key (set OPENAI_API_KEY or engines.openai.api_key)");
+    if (!model) throw new Error("openai: model required");
+
+    const fullMessages = [];
+    if (system) fullMessages.push({ role: "system", content: system });
+    for (const m of messages) {
+      fullMessages.push({
+        role: m.role,
+        content: typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+      });
+    }
+
+    const body = {
+      model,
+      messages: fullMessages,
+      temperature,
+      max_tokens: maxTokens,
+    };
+
+    const res = await fetch(API_BASE, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify(body),
+    });
+    const json = await res.json();
+    if (!res.ok) {
+      throw new Error(
+        `openai ${res.status}: ${json?.error?.message || JSON.stringify(json)}`
+      );
+    }
+    const text = json.choices?.[0]?.message?.content || "";
+    return {
+      text,
+      usage: {
+        input_tokens: json.usage?.prompt_tokens || 0,
+        output_tokens: json.usage?.completion_tokens || 0,
+      },
+      raw: json,
+    };
+  },
+};