@agentprojectcontext/apx 1.33.0 → 1.34.0

package/src/core/stores/code-sessions.js

@@ -13,6 +13,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { nowIso } from "../util/time.js";
 import { shortId as makeShortId } from "../util/ids.js";
+import { CODE_MODES, DEFAULT_CODE_MODE } from "../constants/code-modes.js";
 
 function sessionsDir(storagePath) {
   return path.join(storagePath, "code-sessions");
@@ -91,7 +92,7 @@ export function createCodeSession(storagePath, fields = {}) {
     createdAt: ts,
     updatedAt: ts,
     model: fields.model || null,
-    mode: fields.mode === "plan" ? "plan" : "build",
+    mode: fields.mode === CODE_MODES.PLAN ? CODE_MODES.PLAN : DEFAULT_CODE_MODE,
     agentSlug: fields.agentSlug || null,
     git: fields.git && typeof fields.git === "object" ? fields.git : null,
     messages: [],
@@ -109,7 +110,7 @@ export function updateCodeSession(storagePath, id, patch = {}) {
   if (!session) return null;
   if (patch.title != null) session.title = String(patch.title).trim() || session.title;
   if (patch.model !== undefined) session.model = patch.model || null;
-  if (patch.mode === "plan" || patch.mode === "build") session.mode = patch.mode;
+  if (patch.mode === CODE_MODES.PLAN || patch.mode === CODE_MODES.BUILD) session.mode = patch.mode;
   if (patch.agentSlug !== undefined) session.agentSlug = patch.agentSlug || null;
   if (patch.git !== undefined) session.git = patch.git;
   session.updatedAt = nowIso();
@@ -147,3 +148,50 @@ export function appendTurn(storagePath, id, turn) {
   writeJson(sessionFile(storagePath, id), session);
   return session;
 }
+
+// ---------------------------------------------------------------------------
+// Transcript → engine history
+// ---------------------------------------------------------------------------
+
+// One-line summary of an ask_questions tool call. Without it the next turn's
+// history shows only "user answered X" with no record that the model had
+// asked something — which makes the model ask again forever.
+function summarizeAskQuestionsPart(part) {
+  const raw = part?.args?.questions;
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  const lines = raw
+    .map((q) => {
+      if (typeof q === "string") return `- ${q}`;
+      if (!q || typeof q !== "object" || typeof q.question !== "string") return null;
+      const opts = Array.isArray(q.options) ? q.options : [];
+      const optStr = opts
+        .map((o) => (typeof o === "string" ? o : (o && typeof o.label === "string" ? o.label : "")))
+        .filter(Boolean)
+        .join(", ");
+      return optStr ? `- ${q.question} (opciones: ${optStr})` : `- ${q.question}`;
+    })
+    .filter(Boolean);
+  if (lines.length === 0) return null;
+  return `[ask_questions]\n${lines.join("\n")}`;
+}
+
+/**
+ * Flatten a stored rich transcript into the [{role, content}] history the
+ * super-agent loop expects. Text parts are concatenated; tool parts are
+ * normally internal, except ask_questions which is surfaced as a one-line
+ * summary so the model doesn't lose track of what it already asked.
+ */
+export function codeSessionHistory(session) {
+  return (session?.messages || []).map((m) => {
+    const chunks = [];
+    for (const p of m.parts || []) {
+      if (!p) continue;
+      if (p.kind === "text" && p.text) chunks.push(p.text);
+      else if (p.kind === "tool" && p.tool === "ask_questions") {
+        const summary = summarizeAskQuestionsPart(p);
+        if (summary) chunks.push(summary);
+      }
+    }
+    return { role: m.role, content: chunks.join("\n\n").trim() };
+  });
+}

package/src/core/stores/routine-memory.js

@@ -2,7 +2,7 @@
 //
 // Path: <projectStoragePath>/routines/<routineId>/memory.md
 //
-// The routine handler (host/daemon/routines.js) creates the file on first read
+// The routine handler (core/routines/runner.js) creates the file on first read
 // and injects a bounded slice into the super-agent prompt via
 // channelMeta.routineMemory. The routine can write back with future tooling;
 // today we only read.

package/src/core/stores/sessions-search.js

@@ -0,0 +1,121 @@
+// Cross-agent, cross-conversation session search + locator.
+// Walks the on-disk session and conversation files for each project and
+// returns matches with a small excerpt window. Used by the HTTP adapter and
+// (planned) CLI session find.
+import fs from "node:fs";
+import path from "node:path";
+import { apcAgentsDir } from "../apc/paths.js";
+
+const EXCERPT_CHARS = 300;
+const EXCERPT_LINES_BEFORE = 1;
+const EXCERPT_LINES_AFTER = 3;
+
+function scanFile(filePath, needle) {
+  try {
+    const text = fs.readFileSync(filePath, "utf8");
+    if (!text.toLowerCase().includes(needle)) return null;
+    const lines = text.split("\n");
+    const matchLine = lines.findIndex((l) => l.toLowerCase().includes(needle));
+    const excerpt = lines
+      .slice(Math.max(0, matchLine - EXCERPT_LINES_BEFORE), matchLine + EXCERPT_LINES_AFTER)
+      .join("\n");
+    return excerpt.slice(0, EXCERPT_CHARS);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Search for `needle` across one project's session + conversation files.
+ *
+ * @param project   { id, path, storagePath } record from ProjectManager
+ * @param needle    lowercase query string
+ * @param remaining max matches to add (search short-circuits when reached)
+ * @returns matches array (may be empty)
+ */
+export function searchProjectSessions(project, needle, remaining) {
+  const matches = [];
+  if (!project || remaining <= 0) return matches;
+
+  // 1) Legacy session files in the repo (.apc/agents/<slug>/sessions/)
+  const sessionAgentsDir = apcAgentsDir(project.path);
+  if (fs.existsSync(sessionAgentsDir)) {
+    for (const slug of fs.readdirSync(sessionAgentsDir)) {
+      const sessionsDir = path.join(sessionAgentsDir, slug, "sessions");
+      if (!fs.existsSync(sessionsDir)) continue;
+      for (const f of fs.readdirSync(sessionsDir).filter((x) => x.endsWith(".md"))) {
+        const filePath = path.join(sessionsDir, f);
+        const excerpt = scanFile(filePath, needle);
+        if (excerpt != null) {
+          matches.push({
+            type: "session",
+            project: project.id,
+            agent: slug,
+            filename: f,
+            path: filePath,
+            excerpt,
+          });
+          if (matches.length >= remaining) return matches;
+        }
+      }
+    }
+  }
+
+  // 2) Conversation files in daemon storage (~/.apx/projects/<id>/agents/<slug>/conversations/)
+  const convAgentsDir = path.join(project.storagePath, "agents");
+  if (fs.existsSync(convAgentsDir)) {
+    for (const slug of fs.readdirSync(convAgentsDir)) {
+      const convDir = path.join(convAgentsDir, slug, "conversations");
+      if (!fs.existsSync(convDir)) continue;
+      for (const f of fs.readdirSync(convDir).filter((x) => x.endsWith(".md"))) {
+        const filePath = path.join(convDir, f);
+        const excerpt = scanFile(filePath, needle);
+        if (excerpt != null) {
+          matches.push({
+            type: "conversation",
+            project: project.id,
+            agent: slug,
+            filename: f,
+            path: filePath,
+            excerpt,
+          });
+          if (matches.length >= remaining) return matches;
+        }
+      }
+    }
+  }
+
+  return matches;
+}
+
+/** Run searchProjectSessions across an array of projects, capping at `limit`. */
+export function searchSessions(projectList, query, limit) {
+  const needle = String(query || "").toLowerCase();
+  const matches = [];
+  for (const p of projectList) {
+    if (!p) continue;
+    const remaining = limit - matches.length;
+    if (remaining <= 0) break;
+    matches.push(...searchProjectSessions(p, needle, remaining));
+  }
+  return matches.slice(0, limit);
+}
+
+/**
+ * Find the conversation file (under daemon storage) for a given session id,
+ * scanning a list of candidate projects. Returns { project, agentSlug, filename }
+ * or null. `id` is taken as bare or with .md suffix.
+ */
+export function findSessionFile(projectList, id) {
+  const filename = id.endsWith(".md") ? id : `${id}.md`;
+  for (const p of projectList) {
+    if (!p) continue;
+    const agentsDir = path.join(p.storagePath, "agents");
+    if (!fs.existsSync(agentsDir)) continue;
+    for (const slug of fs.readdirSync(agentsDir)) {
+      const f = path.join(agentsDir, slug, "conversations", filename);
+      if (fs.existsSync(f)) return { project: p, agentSlug: slug, filename };
+    }
+  }
+  return null;
+}

package/src/core/stores/sessions.js

@@ -4,6 +4,11 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { nowIso } from "../util/time.js";
+
+export function agentSessionsDir(storageRoot, agentSlug) {
+  return path.join(storageRoot, "agents", agentSlug, "sessions");
+}
 
 export function generateSessionId(storageRoot, agentSlug) {
   const today = new Date().toISOString().slice(0, 10);
@@ -34,3 +39,36 @@ export function readSessionFrontmatter(filePath) {
   }
   return { fm, body: text.slice(end + 4).replace(/^\n+/, "") };
 }
+
+function slugifyTitle(title) {
+  return (
+    String(title || "")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "") || "session"
+  );
+}
+
+/**
+ * Create a new dated session file under
+ * `<storageRoot>/agents/<agentSlug>/sessions/YYYY-MM-DD-<titleSlug>.md`,
+ * with collision suffix (`-2`, `-3`, …) and standard frontmatter.
+ * Returns { filename, path, started }.
+ */
+export function createAgentSessionFile(storageRoot, agentSlug, { title, body = "" }) {
+  if (!title) throw new Error("createAgentSessionFile: title required");
+  const dir = agentSessionsDir(storageRoot, agentSlug);
+  fs.mkdirSync(dir, { recursive: true });
+  const titleSlug = slugifyTitle(title);
+  const today = new Date().toISOString().slice(0, 10);
+  let candidate = path.join(dir, `${today}-${titleSlug}.md`);
+  let n = 2;
+  while (fs.existsSync(candidate)) {
+    candidate = path.join(dir, `${today}-${titleSlug}-${n}.md`);
+    n++;
+  }
+  const started = nowIso();
+  const content = `---\ntitle: ${title}\nstarted: ${started}\n---\n\n# ${title}\n\n${body}\n`;
+  fs.writeFileSync(candidate, content);
+  return { filename: path.basename(candidate), path: candidate, started };
+}

package/src/core/vars/index.js

@@ -0,0 +1,14 @@
+export {
+  globalVarsPath,
+  projectVarsPath,
+  readGlobalVars,
+  writeGlobalVars,
+  readProjectVars,
+  writeProjectVars,
+  loadAllVars,
+  setVar,
+  deleteVar,
+  maskValue,
+} from "./sources.js";
+
+export { interpolate, findRefs, MissingVarError } from "./interpolate.js";

package/src/core/vars/interpolate.js

@@ -0,0 +1,86 @@
+// ${var.NAME} interpolation engine.
+//
+// Used at MCP boot (and any other site that opts in) so files committed to
+// the repo can hold references like
+//   "Authorization": "Bearer ${var.ASANA_TOKEN}"
+// while the real value lives in ~/.apx/vars.json or
+// <storagePath>/vars.json (see ./sources.js).
+//
+// Semantics:
+//   - Only top-level strings inside the input object/array are walked
+//     recursively. Numbers/booleans/null pass through.
+//   - A `${var.NAME}` token where NAME is missing throws a MissingVarError
+//     listing every missing name (so the UI can show a single useful message
+//     instead of "first failure wins").
+//   - Names match [A-Z0-9_] / [a-z0-9_] / dot — we don't enforce a charset
+//     beyond "no whitespace and no closing brace". Stay liberal here, strict
+//     at the UI.
+
+const VAR_RE = /\$\{var\.([^}\s]+)\}/g;
+
+export class MissingVarError extends Error {
+  constructor(missing) {
+    super(
+      `Undefined variable${missing.length > 1 ? "s" : ""}: ${missing
+        .map((n) => `\${var.${n}}`)
+        .join(", ")}`
+    );
+    this.name = "MissingVarError";
+    this.missing = missing;
+  }
+}
+
+// Collect every `${var.NAME}` reference found in `value` (deep walk).
+// Returns an array of unique names in encounter order.
+export function findRefs(value) {
+  const seen = new Set();
+  const walk = (v) => {
+    if (typeof v === "string") {
+      let m;
+      VAR_RE.lastIndex = 0;
+      while ((m = VAR_RE.exec(v)) !== null) seen.add(m[1]);
+      return;
+    }
+    if (Array.isArray(v)) {
+      for (const x of v) walk(x);
+      return;
+    }
+    if (v && typeof v === "object") {
+      for (const x of Object.values(v)) walk(x);
+    }
+  };
+  walk(value);
+  return Array.from(seen);
+}
+
+// Replace every `${var.NAME}` inside `value` using the `vars` lookup. Missing
+// names accumulate and surface as a single MissingVarError at the end so
+// callers can show "missing: TOKEN_A, TOKEN_B" in one shot.
+export function interpolate(value, vars) {
+  const missing = new Set();
+
+  const replaceString = (s) => {
+    return s.replace(VAR_RE, (_, name) => {
+      if (Object.prototype.hasOwnProperty.call(vars, name)) {
+        return String(vars[name]);
+      }
+      missing.add(name);
+      return _;
+    });
+  };
+
+  const walk = (v) => {
+    if (typeof v === "string") return replaceString(v);
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === "object") {
+      const out = {};
+      for (const [k, x] of Object.entries(v)) out[k] = walk(x);
+      return out;
+    }
+    return v;
+  };
+
+  const result = walk(value);
+  if (missing.size) throw new MissingVarError(Array.from(missing));
+  return result;
+}

package/src/core/vars/sources.js

@@ -0,0 +1,151 @@
+// Variable storage for APX. Two scopes:
+//   global  — ~/.apx/vars.json                              (chmod 0600)
+//   project — <storagePath>/vars.json                       (chmod 0600)
+//             i.e. ~/.apx/projects/<apxId>/vars.json
+//
+// Both files live outside the project repo so values never get committed.
+// The .apc/ files committed to the repo only reference vars by name
+// (e.g. `${var.ASANA_TOKEN}`) — actual values live here.
+//
+// Each file is a flat object: { "NAME": "value", ... }. Names are
+// uppercase letters / digits / underscore by convention (we don't enforce it
+// — anything safe to interpolate works).
+//
+// project wins over global when the same name exists in both.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const APX_HOME = path.join(os.homedir(), ".apx");
+const GLOBAL_VARS_FILE = path.join(APX_HOME, "vars.json");
+const PROJECT_VARS_FILENAME = "vars.json";
+
+export function globalVarsPath() {
+  return GLOBAL_VARS_FILE;
+}
+
+export function projectVarsPath(storagePath) {
+  if (!storagePath) return null;
+  return path.join(storagePath, PROJECT_VARS_FILENAME);
+}
+
+function readJsonSafe(absPath) {
+  if (!absPath || !fs.existsSync(absPath)) return {};
+  try {
+    const json = JSON.parse(fs.readFileSync(absPath, "utf8"));
+    return json && typeof json === "object" && !Array.isArray(json) ? json : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeJsonSecure(absPath, obj) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(obj, null, 2) + "\n");
+  try {
+    fs.chmodSync(absPath, 0o600);
+  } catch {
+    // Best effort on non-POSIX filesystems.
+  }
+}
+
+export function readGlobalVars() {
+  return readJsonSafe(GLOBAL_VARS_FILE);
+}
+
+export function writeGlobalVars(obj) {
+  writeJsonSecure(GLOBAL_VARS_FILE, obj);
+}
+
+export function readProjectVars(storagePath) {
+  return readJsonSafe(projectVarsPath(storagePath));
+}
+
+export function writeProjectVars(storagePath, obj) {
+  if (!storagePath) throw new Error("writeProjectVars: storagePath required");
+  writeJsonSecure(projectVarsPath(storagePath), obj);
+}
+
+function sanitizeMap(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) {
+    out[k] = String(v)
+      .replace(/[\u200B-\u200F\u202A-\u202E\u2060\uFEFF]/g, "")
+      .replace(/\u00A0/g, " ")
+      .trim();
+  }
+  return out;
+}
+
+// Aggregate project + global with project winning.
+// Returns { project, global, effective, sources } where sources[name] is
+// "project" or "global" so callers know where each effective value came from.
+// Values are sanitized at read time so legacy entries written before the
+// save-time trim land also come out clean.
+export function loadAllVars({ storagePath } = {}) {
+  const project = sanitizeMap(storagePath ? readProjectVars(storagePath) : {});
+  const global = sanitizeMap(readGlobalVars());
+  const effective = { ...global, ...project };
+  const sources = {};
+  for (const name of Object.keys(global)) sources[name] = "global";
+  for (const name of Object.keys(project)) sources[name] = "project";
+  return { project, global, effective, sources };
+}
+
+// Strip leading/trailing whitespace + invisible chars (ZWSP, BOM, …). The #1
+// reason a pasted token "doesn't work" is a stray newline picked up from the
+// copy buffer; defaulting to trim removes that whole class of bugs while
+// leaving real values untouched.
+function sanitizeVarValue(raw) {
+  return String(raw)
+    .replace(/[\u200B-\u200F\u202A-\u202E\u2060\uFEFF]/g, "")
+    .replace(/\u00A0/g, " ")
+    .trim();
+}
+
+// Convenience: set/unset on either scope. Returns the new full object.
+export function setVar({ storagePath, scope, name, value }) {
+  const v = sanitizeVarValue(value);
+  if (scope === "project") {
+    if (!storagePath) throw new Error("project scope requires storagePath");
+    const obj = readProjectVars(storagePath);
+    obj[name] = v;
+    writeProjectVars(storagePath, obj);
+    return obj;
+  }
+  if (scope === "global") {
+    const obj = readGlobalVars();
+    obj[name] = v;
+    writeGlobalVars(obj);
+    return obj;
+  }
+  throw new Error(`unknown scope "${scope}"`);
+}
+
+export function deleteVar({ storagePath, scope, name }) {
+  if (scope === "project") {
+    if (!storagePath) throw new Error("project scope requires storagePath");
+    const obj = readProjectVars(storagePath);
+    if (!(name in obj)) return false;
+    delete obj[name];
+    writeProjectVars(storagePath, obj);
+    return true;
+  }
+  if (scope === "global") {
+    const obj = readGlobalVars();
+    if (!(name in obj)) return false;
+    delete obj[name];
+    writeGlobalVars(obj);
+    return true;
+  }
+  throw new Error(`unknown scope "${scope}"`);
+}
+
+// Mask helper for read paths — never send the raw value to the UI by default.
+export function maskValue(value) {
+  if (value == null) return "";
+  const s = String(value);
+  if (s.length <= 4) return "•".repeat(s.length);
+  return "•".repeat(Math.min(s.length - 4, 8)) + s.slice(-4);
+}

package/src/core/voice/audio-decode.js

@@ -0,0 +1,38 @@
+// Decode the `audio` field from a voice/turn request into a filesystem path
+// the STT layer can read. Three input shapes:
+//   - undefined / null  → returns null (caller falls through to text-only)
+//   - filesystem path   → returns it as-is (cleanup: false)
+//   - base64 (raw or `data:...;base64,...`) → writes to tmp, cleanup: true
+//
+// `cleanup: true` means the caller must `fs.unlinkSync(decoded.path)` when
+// done. Pure helper, no daemon dependencies.
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+
+const MAX_PATH_LEN = 1024;
+
+export async function decodeAudioInput({ audio, format = "webm" }) {
+  if (!audio) return null;
+  // A short string that starts with "/" and exists on disk is treated as a
+  // path. Anything else is interpreted as base64 (optionally with a data:
+  // prefix).
+  if (
+    typeof audio === "string" &&
+    audio.length < MAX_PATH_LEN &&
+    audio.startsWith("/") &&
+    fs.existsSync(audio)
+  ) {
+    return { path: audio, cleanup: false };
+  }
+  let b64 = audio;
+  const m = /^data:[^;]+;base64,(.+)$/.exec(b64);
+  if (m) b64 = m[1];
+  const buf = Buffer.from(b64, "base64");
+  if (!buf.length) throw new Error("decodeAudioInput: decoded audio is empty");
+  const ext = String(format || "webm").replace(/^\./, "");
+  const tmp = path.join(os.tmpdir(), `apx-voice-${Date.now()}-${randomUUID()}.${ext}`);
+  fs.writeFileSync(tmp, buf);
+  return { path: tmp, cleanup: true };
+}