@agentprojectcontext/apx 1.33.1 → 1.34.0

package/src/core/runtime-skills/apc-context/SKILL.md

@@ -0,0 +1,159 @@
+---
+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
+---
+
+# Agent Project Context
+
+This project uses APC. APC stores portable project context in `.apc/` and `AGENTS.md`.
+
+APC does not store raw runtime sessions. Sessions, conversations, messages, caches, provider
+threads, and private runtime memory stay in the IDE, CLI, daemon, or user-level store that created
+them.
+
+## FIRST: check for pending migration
+
+Before doing anything else, check if `.apc/migrate.md` exists:
+
+```bash
+cat .apc/migrate.md 2>/dev/null
+```
+
+If it exists, open with this offer before answering anything else:
+
+> I see this project was initialized with Agent Project Context (APC).
+>
+> I found context files that may need migration:
+> [list files from .apc/migrate.md]
+>
+> I can read them, separate durable project context from runtime/private state, and migrate only
+> what belongs in APC.
+>
+> Want me to start?
+
+If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.
+
+## Migration rule: think, do not copy
+
+Read detected files first. Also read `AGENTS.md` if it exists.
+
+Classify content:
+
+| Content | Action |
+|---|---|
+| Agent definitions: name, model, description | Put in `.apc/agents/<name>.md` and/or `AGENTS.md` |
+| Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
+| Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
+| Durable safe facts useful to all contributors | Add to `.apc/agents/<name>/memory.md` only after curation |
+| MCP expectations without secrets | Add to `.apc/mcps.json` |
+| Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
+| Secrets, tokens, credentials, private headers | Do not store in repository |
+| IDE UI settings or personal aliases | Leave in IDE/user config |
+| Instructions to store sessions under `.apc/` | Drop as obsolete |
+
+After migration:
+
+1. Update `AGENTS.md` as the root project contract.
+2. Create or update `.apc/agents/`, `.apc/skills/`, `.apc/mcps.json` as needed.
+3. Do not create `.apc/**/sessions`, `.apc/messages`, or `.apc/conversations`.
+4. Delete obsolete source files only when their useful project context was migrated or intentionally dropped.
+5. Delete `.apc/migrate.md`.
+6. Summarize what moved, what stayed local, and what was dropped.
+
+## APC structure
+
+```text
+AGENTS.md                        ← root project contract
+.apc/
+  project.json                   ← project metadata
+  .gitignore                     ← safety guard
+  agents/<name>.md               ← agent definition
+  agents/<name>/memory.md        ← optional curated project memory
+  skills/<name>.md               ← reusable project instructions
+  mcps.json                      ← MCP hints without secrets
+```
+
+Do not store:
+
+```text
+.apc/agents/<name>/sessions/
+.apc/sessions/
+.apc/conversations/
+.apc/messages/
+.apc/cache/
+.apc/tmp/
+.apc/private/
+.apc/secrets/
+```
+
+## Visibility rules
+
+| Data | Visibility | Commit? |
+|---|---|---|
+| Agent definitions, skills, project rules | `stable` / `project` | Yes |
+| Curated safe `memory.md` | `project` | Yes, if team-safe |
+| MCP hints without secrets | `project` | Yes |
+| Sessions, conversations, messages | `local` | No; runtime-owned |
+| Secrets, tokens, `*.secret.json`, `*.env` | `private` | Never |
+| Caches, temp files, databases | `ephemeral` | No |
+
+## Operating rules
+
+1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
+2. Read agent definitions from `.apc/agents/<name>.md` when present.
+3. Read curated project memory from `.apc/agents/<name>/memory.md` when present.
+4. Write only durable, safe, curated facts to APC memory.
+5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
+6. Keep secrets out of APC and out of git.
+7. Treat `.apc/mcps.json` as MCP configuration hints, not as an MCP implementation.
+
+## Normalization
+
+If agent formats are broken or use legacy fields (role, skills in YAML), offer to normalize:
+
+```yaml
+---
+name: agent-name
+model: inherit
+description: Semantic activation trigger
+---
+```
+
+Identify and fix inconsistencies in `model` (use technical IDs or `inherit`) and ensure `description` is present for semantic activation.
+
+## Sessions
+
+Sessions belong to the runtime that created them.
+
+Examples:
+
+```text
+Codex runtime storage
+Claude Code runtime storage
+OpenCode runtime storage
+~/.apx/projects/<project-id>/agents/<name>/sessions/
+```
+
+At task end, provide the user a concise result. If project memory should be updated, write a short
+sanitized fact to `.apc/agents/<name>/memory.md` only when useful and safe.
+
+## APX
+
+Read `.apc/project.json` if present. It may contain an `apx` field:
+
+- `"installed"`: APX is available; use `apx` commands when useful.
+- `"declined"`: user chose not to install; do not suggest or run APX.
+- missing or `null`: unknown; do not assume APX is available.
+
+If APX is installed, it may manage runtime state outside the repository:
+
+```text
+~/.apx/projects/<project-id>/
+```
+
+APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
+across Codex, Claude Code, OpenCode, Aider, or direct LLM engines. Those are APX runtime features,
+not APC portable-core requirements.
+
+Never use APX to write secrets or raw sessions into `.apc/`.

package/src/core/runtime-skills/apx/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: apx
+description: "APX CLI umbrella — which sub-skill handles each operation (sessions, MCPs, routines, tasks, telegram, projects, agents, runtimes). Activate when the user mentions `apx`, the APX daemon, or wants to coordinate/run/delegate agents. Not for `.apc/` alone (use apc-context). Triggers: 'apx', 'apx run', 'apx daemon', 'coordinate agents', 'apx help'."
+homepage: https://github.com/agentprojectcontext/apx
+---
+
+# APX — Agent Project Context Runtime
+
+APX is a daemon (`127.0.0.1:7430`, auto-starts on first call) that turns external coding CLIs (Claude Code, Codex, OpenCode, Aider, …) and configurable agents into a unified orchestration surface.
+
+It reads APC project context from `.apc/` (committed) but keeps runtime state outside the repo under `~/.apx/projects/<project-id>/`. The super-agent has a default workspace at `~/.apx/projects/default` for system-level work.
+
+---
+
+## When to use APX (vs. spawning a subagent natively)
+
+If you can spawn a subagent natively in the IDE you're in (Claude Code, Cursor, …) — **do that**. No APX needed.
+
+Use APX when:
+- The user explicitly asks for a specific external runtime ("run this in Codex", "delegate to OpenCode").
+- You need to run an agent in a runtime different from the one you're in.
+- You're orchestrating from outside any IDE (a script, Telegram bot, CI, routine).
+
+---
+
+## Sub-skill index — open the one that matches the task
+
+| Topic | Sub-skill | When |
+|-------|-----------|------|
+| Delegate to an external coding CLI | **apx-runtime** | `apx run <agent> --runtime claude-code\|codex\|...` |
+| List / read / resume / summarise / continue sessions across engines | **apx-sessions** | `apx session resume`, `apx sessions list`, "import a codex session" |
+| Use a registered MCP tool | **apx-mcp** | `apx mcp run`, "call MCP filesystem", "the MCP is failing" |
+| Add / configure / use a project agent | **apx-agent** | "add an agent", "import from vault", per-agent model, agent memory |
+| Register / list / configure a project | **apx-project** | "register this project", `apx project list`, per-project config |
+| Per-project TODO list | **apx-task** | "add a task", "remind me to…", "what's pending" |
+| Scheduled / recurring agents | **apx-routine** | `apx routine add`, every-5m, cron-like jobs |
+| Telegram I/O | **apx-telegram** | configure bot, channels, send a message |
+| Voice channel (TTS, speech) — *optional* | **apx-voice** | only if voice is being set up |
+| Build a new MCP server — *internal/dev* | **apx-mcp-builder** | when developing a brand-new MCP from scratch |
+| Author a new APX skill — *internal/dev* | **apx-skill-builder** | when adding to APX itself |
+
+> Sub-skills marked *internal/dev* are not pushed to IDE skill dirs by default. They live in the APX repo and are loaded by APX itself; install one to your IDE with `apx skills add <slug> --global` if you want it there.
+
+---
+
+## Generic patterns (apply to every sub-skill)
+
+### Verify commands before recommending them
+
+Do not invent APX subcommands. Confirm exact CLI form with `apx --help` or `apx <command> --help` before telling another runtime to invoke APX. Avoid guessed aliases (e.g. `apx send-telegram` is *not* a thing — see apx-telegram).
+
+### `APC_RESULT` contract — structured return values
+
+When you want APX to capture a structured value from an agent (any runtime), instruct the agent to print on its last meaningful line:
+
+```
+APC_RESULT: <one-line value>
+```
+
+APX's `extractApfResult()` parses that and stores it as the session's `result` field. Useful for automation, routines, and CI.
+
+### Tool permissions
+
+```bash
+apx permission show
+apx permission set automatico   # total | automatico | permiso
+```
+
+`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP, runtime, outbound, config, or filesystem mutation actions.
+
+### Memory
+
+Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
+
+```bash
+apx memory <slug>                       # read agent's memory.md
+apx memory <slug> --append "<fact>"     # append a durable note
+apx memory <slug> --replace < file.md  # replace entire memory from stdin
+```
+
+### Observe activity
+
+```bash
+apx messages tail                               # last 50 messages, all channels
+apx messages chat --channel telegram -n 20      # readable chat view
+apx messages tail --channel runtime --agent <slug> -n 20
+```
+
+---
+
+## Anti-patterns
+
+- Don't activate APX-sessions inside a request that's purely about `apx run` orchestration — use apx-runtime.
+- Don't activate apx-mcp-builder unless the user is actually authoring a new MCP server (it's a deep developer guide, not a usage guide).
+- Don't push state to `.apc/` that belongs in `~/.apx/projects/<id>/` (sessions, conversations, runtime logs).

package/src/core/runtime-skills/apx-mcp/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: apx-mcp
+description: How to register, list, debug, and scope MCP servers in APX. Use BEFORE adding any MCP — three scopes (shared/runtime/global) with different commit and secrecy semantics.
+---
+
+# apx-mcp
+
+APX exposes Model Context Protocol (MCP) servers to agents. Three scopes, each in a different file with different rules:
+
+| Scope | File | Committed? | Secrets OK? | When |
+|---|---|---|---|---|
+| `shared` | `<repo>/.apc/mcps.json` | yes | **no** | Team-wide MCPs (filesystem, brave, github public) |
+| `runtime` | `~/.apx/projects/<apxId>/mcps.json` (chmod 0600) | no | yes | Per-project local — tokens, machine-specific endpoints |
+| `global` | `~/.apx/mcps.json` | n/a | yes | Machine-wide — not tied to any project |
+
+Resolution priority when a name appears in more than one: **runtime > shared > global**. Conflicts surface in `apx mcp check`.
+
+## Concrete CLI calls
+
+```bash
+# List (all scopes, this is the default)
+apx mcp list --project iacrmar
+apx mcp list --scope runtime --project iacrmar
+apx mcp list --scope shared  --project iacrmar
+apx mcp list --scope global
+
+# Inspect sources and conflicts
+apx mcp check --project iacrmar
+
+# Add — shared (commit to repo)
+apx mcp add filesystem --command npx --project iacrmar \
+  -- -y @modelcontextprotocol/server-filesystem .
+
+# Add — runtime (per-project, local, secrets safe)
+apx mcp add github --scope runtime --project iacrmar \
+  --command npx --env GITHUB_TOKEN=ghp_xxx \
+  -- -y @modelcontextprotocol/server-github
+
+# Add — global (machine-wide, not tied to a project)
+apx mcp add brave --scope global \
+  --command npx --env BRAVE_API_KEY=BSAxxx \
+  -- -y @modelcontextprotocol/server-brave-search
+
+# Remove (pass --scope when the MCP isn't in the default scope:
+# shared inside an APC project, else global)
+apx mcp remove filesystem --project iacrmar
+apx mcp remove github     --scope runtime --project iacrmar
+
+# Toggle (defaults to the scope that owns the MCP)
+apx mcp enable  filesystem --project iacrmar
+apx mcp disable filesystem --project iacrmar
+
+# Call a tool through the daemon (useful for debugging)
+apx mcp run filesystem read_file '{"path":"README.md"}'
+```
+
+## When the user asks for a new MCP
+
+Decision tree:
+1. **Has secrets / tokens?** → `runtime` scope. Always.
+2. **Is part of the project's shared dev environment?** → `shared` (committed).
+3. **Used across all your projects?** → `global`.
+
+Default if none is obvious: `shared` when inside an APC project, `global` outside.
+
+## Common command shapes by transport
+
+```bash
+# stdio MCP (most common — npx, uvx, node, python)
+apx mcp add <name> --command npx -- -y <package-or-flag-list>
+apx mcp add <name> --command uvx -- <python-cli-name>
+apx mcp add <name> --command python -- /abs/path/to/server.py
+
+# Env vars (one --env per var)
+apx mcp add <name> --command npx \
+  --env GITHUB_TOKEN=ghp_xxx \
+  --env GITHUB_OWNER=manuel \
+  -- -y @modelcontextprotocol/server-github
+```
+
+Anything after `--` is forwarded verbatim as args to the command. Quote carefully.
+
+## Anti-examples
+
+```bash
+# DON'T put tokens in shared scope. It commits.
+apx mcp add github --scope shared --env GITHUB_TOKEN=ghp_xxx ...
+# ↑ Token ends up in .apc/mcps.json in your repo. Use --scope runtime.
+
+# DON'T remove an MCP from the wrong scope.
+apx mcp remove github          # if github lives in runtime, this errors with a hint
+# ↑ Daemon returns 409 with the right scope to use.
+
+# DON'T expect IDE-foreign configs (~/.cursor/mcps.json, ~/.claude/mcps.json) to be
+# removable via apx mcp remove. APX reads them as advisory (source=cursor/claude/etc)
+# but won't write them. Edit the IDE config directly.
+```
+
+## Debugging connection issues
+
+```bash
+apx mcp check --project iacrmar             # what scopes APX sees + which files exist
+apx mcp run <name> <tool> '{...}'            # spawn the server and call a tool for real
+apx log -f                                   # tail unified log for spawn errors
+```
+
+A server that "doesn't show tools" usually means: the command failed to start (env vars missing, package not found), or the server crashed during initialize. The unified log has the stderr buffer.
+
+> `apx mcp tools <name>` is a placeholder stub (prints a "coming in v0.2" notice, lists nothing). To verify a server actually spawns, call a tool with `apx mcp run`.
+
+## Don't
+
+- Don't mix scopes for the same MCP name unless you actually want shadowing. The result is "the one with highest priority wins, others stay invisible."
+- Don't edit `~/.apx/projects/<id>/mcps.json` by hand; use `apx mcp add --scope runtime`. The file is chmod 0600 — the CLI keeps it that way.
+- Don't add tokens via `--env KEY=` inline if your shell history is public. Set them in your shell first, then `--env KEY=$KEY`.
+- Don't forget to `apx daemon reload` after editing config — actually `apx mcp` does this for you, but if you hand-edited the JSON, it's manual.

package/src/core/runtime-skills/{claude-code.md → claude-code/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: claude-code
 description: "Activate ONLY when the user explicitly mentions Claude Code, Claude CLI, claude command, Anthropic Claude Code, installing Claude Code, using Claude Code, or APX runtime claude-code. Do not activate for generic Claude model discussion."
 homepage: https://docs.anthropic.com/en/docs/claude-code

package/src/core/runtime-skills/{codex-cli.md → codex-cli/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: codex-cli
 description: "Activate ONLY when the user explicitly mentions Codex CLI, OpenAI Codex, @openai/codex, codex command, codex exec, installing Codex, using Codex, ~/.codex, or APX runtime codex."
 homepage: https://developers.openai.com/codex

package/src/core/runtime-skills/{opencode-cli.md → opencode-cli/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: opencode-cli
 description: "Activate ONLY when the user explicitly mentions OpenCode, opencode command, installing OpenCode, using OpenCode, OpenCode provider setup, or APX runtime opencode."
 homepage: https://opencode.ai/docs

package/src/core/runtime-skills/{openrouter.md → openrouter/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: openrouter
 description: "Activate ONLY when the user explicitly mentions OpenRouter, OPENROUTER_API_KEY, OpenRouter models, installing OpenRouter provider config, or using OpenRouter with APX, OpenCode, LiteLLM, or an OpenAI-compatible client."
 homepage: https://openrouter.ai/docs

package/src/{host/daemon/env-detect.js → core/runtimes/detect.js}

@@ -1,7 +1,7 @@
 // Best-effort detection of installed agent CLIs and LLM runners.
 // We just probe the binary with `--version` (or equivalent) and don't fail if
 // it isn't there — caller decides what to do with absence.
-import { runProcess } from "./runtimes/_spawn.js";
+import { runProcess } from "#host/daemon/runtimes/_spawn.js";
 
 const PROBES = [
   // Coding-agent CLIs (runtimes/)

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 };
+}