@ai-matrx/coding-sessions 0.1.83 → 0.1.85

package/dist/engine/index.js

@@ -1,6 +1,6 @@
 // src/engine/index.ts
 import { execFile as execFile3, fork } from "child_process";
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import { existsSync } from "fs";
 import { formatFileSize } from "@ai-matrx/kit/format";
 
@@ -98,10 +98,379 @@ function createAiMatrxRawBackupSink(options) {
   };
 }
 
+// src/engine/agent-attach.ts
+import fs2 from "fs/promises";
+import path from "path";
+var AGENT_MCP_SERVER_NAME = "matrx-agent";
+var AGENT_PLUGIN_NAME = "matrx-agent";
+function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+function versionWords(bundle) {
+  return bundle.version_number !== null ? String(bundle.version_number) : "latest";
+}
+function renderAgentInstructions(bundle, options = {}) {
+  const included = bundle.skills.filter((skill) => skill.tier === "included");
+  const listed2 = bundle.skills.filter((skill) => skill.tier === "listed");
+  const parts = [`<ai_matrx_agent name="${escapeAttr(bundle.name)}" version="${versionWords(bundle)}">`];
+  if (included.length > 0) {
+    parts.push(
+      "## Skills (always in effect)",
+      ...included.map((skill) => `### ${skill.label}
+
+${skill.body.trim()}`)
+    );
+  }
+  if (options.claudeSkills && listed2.length > 0) {
+    parts.push(
+      [
+        "## Your skills",
+        "When a request matches one of these, load it with your Skill tool and follow it before answering:",
+        ...listed2.map((skill) => `- ${AGENT_PLUGIN_NAME}:${skill.slug} \u2014 ${skill.description || skill.label}`)
+      ].join("\n")
+    );
+  }
+  if (included.length > 0 || options.claudeSkills && listed2.length > 0) parts.push("## Your instructions");
+  parts.push(bundle.instructions.trim());
+  parts.push("</ai_matrx_agent>");
+  return `${parts.filter(Boolean).join("\n\n")}
+`;
+}
+function renderCodexSkillsList(bundle, skillsRoot) {
+  const listed2 = bundle.skills.filter((skill) => skill.tier === "listed");
+  if (listed2.length === 0) return "";
+  const lines = [
+    "<skills_instructions>",
+    "## AI Matrx agent skills",
+    "A skill is a set of instructions stored in a `SKILL.md` file. Each entry has a name, a description and the absolute path of its file. When a task matches a skill's description, read that file and follow it.",
+    "### Available skills",
+    ...listed2.map(
+      (skill) => `- ${skill.slug}: ${skill.description || skill.label} (file: ${path.join(skillsRoot, skill.slug, "SKILL.md")})`
+    ),
+    "</skills_instructions>"
+  ];
+  return lines.join("\n");
+}
+function tomlString(value) {
+  const scalar = value.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
+  return JSON.stringify(scalar).replace(/\u007f/g, "\\u007f");
+}
+async function writeAgentAttachment(dir, bundle, options) {
+  const pluginDir = path.join(dir, "plugin");
+  const skillsRoot = path.join(dir, "skills");
+  await fs2.mkdir(path.join(pluginDir, ".claude-plugin"), { recursive: true, mode: 448 });
+  await fs2.mkdir(skillsRoot, { recursive: true, mode: 448 });
+  const instructions = renderAgentInstructions(bundle);
+  const instructionsFile = path.join(dir, "instructions.md");
+  await fs2.writeFile(instructionsFile, renderAgentInstructions(bundle, { claudeSkills: true }), { mode: 384 });
+  await fs2.writeFile(
+    path.join(pluginDir, ".claude-plugin", "plugin.json"),
+    `${JSON.stringify(
+      {
+        name: AGENT_PLUGIN_NAME,
+        description: `Skills of the AI Matrx agent "${bundle.name}"`,
+        version: versionWords(bundle) === "latest" ? "1.0.0" : `${versionWords(bundle)}.0.0`
+      },
+      null,
+      2
+    )}
+`,
+    { mode: 384 }
+  );
+  const listed2 = bundle.skills.filter((skill) => skill.tier === "listed");
+  const wanted = new Set(listed2.map((skill) => skill.slug));
+  for (const root of [path.join(pluginDir, "skills"), skillsRoot]) {
+    await fs2.mkdir(root, { recursive: true, mode: 448 });
+    for (const existing of await fs2.readdir(root).catch(() => [])) {
+      if (!wanted.has(existing)) await fs2.rm(path.join(root, existing), { recursive: true, force: true });
+    }
+    for (const skill of listed2) {
+      const skillDir = path.join(root, skill.slug);
+      await fs2.mkdir(skillDir, { recursive: true, mode: 448 });
+      await fs2.writeFile(path.join(skillDir, "SKILL.md"), skill.content, { mode: 384 });
+    }
+  }
+  let mcpConfigFile = null;
+  const mcpUrl = options.mcpUrl && bundle.tools.length > 0 ? options.mcpUrl : null;
+  const mcpPath = path.join(dir, "mcp.json");
+  if (mcpUrl) {
+    mcpConfigFile = mcpPath;
+    await fs2.writeFile(
+      mcpPath,
+      `${JSON.stringify({ mcpServers: { [AGENT_MCP_SERVER_NAME]: { type: "http", url: mcpUrl } } }, null, 2)}
+`,
+      { mode: 384 }
+    );
+  } else {
+    await fs2.rm(mcpPath, { force: true });
+  }
+  const skillsList = renderCodexSkillsList(bundle, skillsRoot);
+  return {
+    dir,
+    instructionsFile,
+    pluginDir,
+    mcpConfigFile,
+    mcpUrl,
+    // Same order as Claude's: the skills list first, the agent's words last.
+    codexInstructions: skillsList ? `${skillsList}
+
+${instructions}` : instructions
+  };
+}
+function agentArgsFor(provider, attachment, options) {
+  if (provider === "claude") {
+    const args2 = [
+      // Every turn: without snapshot off, a resumed Claude drops appended instructions.
+      "--append-system-prompt-file",
+      attachment.instructionsFile,
+      "--system-prompt-snapshot",
+      "off",
+      "--plugin-dir",
+      attachment.pluginDir
+    ];
+    if (attachment.mcpConfigFile) args2.push("--mcp-config", attachment.mcpConfigFile);
+    return args2;
+  }
+  const args = [];
+  if (!options.resuming) args.push("-c", `developer_instructions=${tomlString(attachment.codexInstructions)}`);
+  if (attachment.mcpUrl) {
+    const key = `mcp_servers.${AGENT_MCP_SERVER_NAME}`;
+    args.push(
+      "-c",
+      `${key}.url=${tomlString(attachment.mcpUrl)}`,
+      "-c",
+      `${key}.default_tools_approval_mode="approve"`
+    );
+  }
+  return args;
+}
+function sessionAgentRecord(bundle, options) {
+  const unavailable = bundle.unavailable.map((u) => ({ kind: u.kind, name: u.name, reason: u.reason }));
+  const missingSkills = unavailable.filter((u) => u.kind === "skill").length;
+  const missingTools = unavailable.filter((u) => u.kind === "tool").length;
+  if (!options.toolsServed && bundle.tools.length > 0) {
+    for (const tool of bundle.tools) {
+      unavailable.push({ kind: "tool", name: tool.canonical_name, reason: "Tools need the coding sessions host" });
+    }
+  }
+  const toolsLoaded = options.toolsServed ? bundle.tools.length : 0;
+  const loaded = [
+    { part: "instructions", loaded: bundle.instructions.trim() ? 1 : 0, total: 1 },
+    { part: "skills", loaded: bundle.skills.length, total: bundle.skills.length + missingSkills },
+    { part: "tools", loaded: toolsLoaded, total: bundle.tools.length + missingTools }
+  ];
+  return {
+    agentId: bundle.agent_id,
+    versionId: bundle.version_id,
+    versionNumber: bundle.version_number,
+    name: bundle.name,
+    definitionHash: bundle.definition_hash,
+    loaded,
+    unavailable
+  };
+}
+
+// src/engine/agents.ts
+import { randomBytes, randomUUID } from "crypto";
+import fs3 from "fs/promises";
+import path2 from "path";
+var DEFAULT_SERVER_URL = "https://server.app.matrxserver.com";
+var DEFAULT_SUPABASE_URL = "https://db.matrxserver.com";
+var AGENT_CATALOG_RPCS = /* @__PURE__ */ new Set([
+  "agx_get_list_full",
+  "agx_search",
+  "agx_resolve_agent_address",
+  "ues_get_bulk",
+  "ues_list",
+  "ues_set",
+  "ues_touch"
+]);
+var agentsClient = async () => {
+  const [matrx, portable, mcp] = await Promise.all([
+    import("@ai-matrx/agents/matrx"),
+    import("@ai-matrx/agents/portable"),
+    import("@ai-matrx/agents/portable/mcp")
+  ]);
+  return { ...matrx, ...portable, ...mcp };
+};
+var SIGNED_OUT_AGENT_MESSAGE = "Sign in to AI Matrx to use your agents.";
+function userIdOf(credential) {
+  if (!credential || credential.kind !== "user") return null;
+  const payload = credential.accessToken.split(".")[1];
+  if (!payload) return null;
+  try {
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return typeof claims.sub === "string" ? claims.sub : null;
+  } catch {
+    return null;
+  }
+}
+function createAgentConnection(options, dataDir) {
+  const credentials = options?.credentials ?? null;
+  const serverUrl = (options?.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, "");
+  const supabaseUrl = (options?.supabaseUrl ?? DEFAULT_SUPABASE_URL).replace(/\/+$/, "");
+  const supabaseKey = options?.supabaseKey ?? null;
+  const root = path2.join(dataDir, "agents");
+  let mcpBaseUrl = null;
+  const handlers = /* @__PURE__ */ new Map();
+  const secretToSession = /* @__PURE__ */ new Map();
+  const organizationId = () => {
+    const raw = typeof options?.organizationId === "function" ? options.organizationId() : options?.organizationId;
+    return raw && raw.trim() ? raw.trim() : null;
+  };
+  const transport = async () => (await agentsClient()).createMatrxTransport({
+    baseUrl: serverUrl,
+    ...credentials ? { credentials } : {},
+    ...organizationId() ? { organizationId: () => organizationId() } : {},
+    source: "codingSessionsAgents"
+  });
+  const credential = async () => credentials ? credentials.get() : null;
+  const requireSignedIn = async () => {
+    if (!await credential()) throw new Error(SIGNED_OUT_AGENT_MESSAGE);
+  };
+  const sessionDir = (sessionId) => path2.join(root, sessionId.replace(/[^A-Za-z0-9_-]/g, "_"));
+  async function meta(sessionId) {
+    const file = path2.join(sessionDir(sessionId), "session.json");
+    const existing = await fs3.readFile(file, "utf8").then((text) => JSON.parse(text)).catch(() => null);
+    if (existing?.mcpSecret && existing.conversationId) return existing;
+    const created = { mcpSecret: randomBytes(24).toString("base64url"), conversationId: randomUUID() };
+    await fs3.mkdir(sessionDir(sessionId), { recursive: true, mode: 448 });
+    await fs3.writeFile(file, JSON.stringify(created), { mode: 384 });
+    return created;
+  }
+  async function findSessionBySecret(secret) {
+    for (const name of await fs3.readdir(root).catch(() => [])) {
+      const found = await fs3.readFile(path2.join(root, name, "session.json"), "utf8").then((text) => JSON.parse(text).mcpSecret === secret).catch(() => false);
+      if (found) {
+        secretToSession.set(secret, name);
+        return name;
+      }
+    }
+    return null;
+  }
+  async function readSessionBundle(sessionId) {
+    return fs3.readFile(path2.join(sessionDir(sessionId), "bundle.json"), "utf8").then((text) => JSON.parse(text)).catch(() => null);
+  }
+  return {
+    async access() {
+      const current = await credential().catch(() => null);
+      const userId = userIdOf(current);
+      return {
+        configured: credentials !== null && supabaseKey !== null,
+        signedIn: userId !== null,
+        userId,
+        organizationId: organizationId()
+      };
+    },
+    async catalogRpc(request) {
+      if (!AGENT_CATALOG_RPCS.has(request.fn)) {
+        return { data: null, error: { message: `Not an agent catalogue read: ${request.fn}` } };
+      }
+      const current = await credential();
+      if (!current || current.kind !== "user") return { data: null, error: { message: SIGNED_OUT_AGENT_MESSAGE, code: "signed_out" } };
+      if (!supabaseKey) return { data: null, error: { message: "This host has no AI Matrx database key.", code: "not_configured" } };
+      const query = new URLSearchParams();
+      if (request.order) query.set("order", `${request.order.column}.${request.order.ascending === false ? "desc" : "asc"}`);
+      if (request.range) {
+        query.set("offset", String(request.range[0]));
+        query.set("limit", String(request.range[1] - request.range[0] + 1));
+      }
+      const headers = {
+        apikey: supabaseKey,
+        Authorization: `Bearer ${current.accessToken}`,
+        "Content-Type": "application/json",
+        // Every catalogue RPC lives in `public`; the database's default
+        // exposed schema is not `public`, so name it (supabase-js does).
+        "Content-Profile": "public",
+        "Accept-Profile": "public"
+      };
+      if (request.count) headers.Prefer = `count=${request.count}`;
+      const qs = query.toString();
+      const response = await fetch(`${supabaseUrl}/rest/v1/rpc/${encodeURIComponent(request.fn)}${qs ? `?${qs}` : ""}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(request.args ?? {})
+      });
+      const text = await response.text();
+      const body = text ? JSON.parse(text) : null;
+      if (!response.ok) {
+        const err = body ?? {};
+        return {
+          data: null,
+          error: { message: err.message ?? `HTTP ${response.status}`, code: err.code, details: err.details ?? null, hint: err.hint ?? null }
+        };
+      }
+      const range = response.headers.get("content-range");
+      const total = range?.split("/")[1];
+      return { data: body, error: null, count: total && total !== "*" ? Number(total) : null };
+    },
+    async details(agentId) {
+      await requireSignedIn();
+      const { fetchPortableAgent, fetchPortableAgentVersions } = await agentsClient();
+      const [bundle, versions] = await Promise.all([
+        fetchPortableAgent(await transport(), { agentId }),
+        fetchPortableAgentVersions(await transport(), agentId).catch(() => [])
+      ]);
+      return {
+        agentId: bundle.agent_id,
+        name: bundle.name,
+        variables: bundle.variables,
+        versions: versions.map((v) => ({ id: v.id, versionNumber: v.version_number, changedAt: v.changed_at })).sort((a, b) => b.versionNumber - a.versionNumber),
+        latestVersionNumber: bundle.version_number
+      };
+    },
+    async loadBundle(selection) {
+      await requireSignedIn();
+      const { fetchPortableAgent } = await agentsClient();
+      return fetchPortableAgent(
+        await transport(),
+        selection.versionId ? { versionId: selection.versionId } : { agentId: selection.agentId },
+        { variables: selection.variables ?? {} }
+      );
+    },
+    async saveSessionBundle(sessionId, bundle) {
+      await fs3.mkdir(sessionDir(sessionId), { recursive: true, mode: 448 });
+      await fs3.writeFile(path2.join(sessionDir(sessionId), "bundle.json"), JSON.stringify(bundle), { mode: 384 });
+      await meta(sessionId);
+    },
+    readSessionBundle,
+    sessionDir,
+    async mcpUrlFor(sessionId) {
+      if (!mcpBaseUrl) return null;
+      const { mcpSecret } = await meta(sessionId);
+      secretToSession.set(mcpSecret, sessionId);
+      return `${mcpBaseUrl}/mcp/${mcpSecret}`;
+    },
+    setMcpBaseUrl(baseUrl) {
+      mcpBaseUrl = baseUrl ? baseUrl.replace(/\/+$/, "") : null;
+    },
+    async handleMcp(secret, body) {
+      let handler = handlers.get(secret);
+      if (!handler) {
+        const sessionId = secretToSession.get(secret) ?? await findSessionBySecret(secret);
+        if (!sessionId) return null;
+        const bundle = await readSessionBundle(sessionId);
+        if (!bundle) return null;
+        const { conversationId } = await meta(sessionId);
+        const { createAgentToolsMcpHandler } = await agentsClient();
+        handler = createAgentToolsMcpHandler({
+          bundle,
+          credentials,
+          organizationId: () => organizationId(),
+          baseUrl: serverUrl,
+          conversationId
+        });
+        handlers.set(secret, handler);
+      }
+      return handler.handle(body);
+    }
+  };
+}
+
 // src/engine/index.ts
-import fs6 from "fs/promises";
+import fs8 from "fs/promises";
 import os5 from "os";
-import path7 from "path";
+import path9 from "path";
 import { fileURLToPath } from "url";
 
 // src/normalize/claude.ts
@@ -771,7 +1140,7 @@ function describeProblem(provider, problem) {
 import { execFile } from "child_process";
 import { accessSync, constants as fsConstants, readdirSync, readFileSync, realpathSync } from "fs";
 import os from "os";
-import path from "path";
+import path3 from "path";
 var SOURCE_LABEL = {
   codex: { "desktop-app": "from ChatGPT app", path: "from PATH", "npm-global": "from npm", configured: "set by host" },
   claude: { "desktop-app": "from Claude app", path: "from PATH", "npm-global": "from npm", configured: "set by host" }
@@ -820,10 +1189,10 @@ function exeName(name, platform) {
 }
 function allOnPath(name, pathValue, platform = process.platform) {
   const found = [];
-  for (const dir of pathValue.split(path.delimiter)) {
+  for (const dir of pathValue.split(path3.delimiter)) {
     if (!dir) continue;
     for (const file of exeName(name, platform)) {
-      const candidate = path.join(dir, file);
+      const candidate = path3.join(dir, file);
       if (executable(candidate)) {
         found.push(candidate);
         break;
@@ -836,17 +1205,17 @@ function desktopAppCandidates(provider, platform, home, applications) {
   if (platform !== "darwin") return [];
   if (provider === "codex") {
     return applications.map(
-      (apps) => path.join(apps, "ChatGPT.app", "Contents", "Resources", "codex-cli", "bin", "codex")
+      (apps) => path3.join(apps, "ChatGPT.app", "Contents", "Resources", "codex-cli", "bin", "codex")
     );
   }
-  const root = path.join(home, "Library", "Application Support", "Claude", "claude-code");
+  const root = path3.join(home, "Library", "Application Support", "Claude", "claude-code");
   let versions = [];
   try {
     versions = readdirSync(root);
   } catch {
     return [];
   }
-  return versions.map((v) => path.join(root, v, "claude.app", "Contents", "MacOS", "claude"));
+  return versions.map((v) => path3.join(root, v, "claude.app", "Contents", "MacOS", "claude"));
 }
 function npmGlobalPrefix(env) {
   const fromEnv = env.npm_config_prefix ?? env.NPM_CONFIG_PREFIX;
@@ -864,13 +1233,13 @@ function declaredVersion(provider, source, file) {
   if (source !== "desktop-app") return null;
   if (provider === "codex") {
     try {
-      const pkg = JSON.parse(readFileSync(path.join(path.dirname(path.dirname(file)), "codex-package.json"), "utf8"));
+      const pkg = JSON.parse(readFileSync(path3.join(path3.dirname(path3.dirname(file)), "codex-package.json"), "utf8"));
       return typeof pkg.version === "string" ? parseVersion(pkg.version) : null;
     } catch {
       return null;
     }
   }
-  return parseVersion(path.basename(path.resolve(file, "..", "..", "..", "..")));
+  return parseVersion(path3.basename(path3.resolve(file, "..", "..", "..", "..")));
 }
 function runVersion(file, env) {
   return new Promise((resolve) => {
@@ -884,14 +1253,14 @@ async function discoverBinaries(provider, options) {
   const platform = options.platform ?? process.platform;
   const home = options.home ?? options.env.HOME ?? os.homedir();
   const listed2 = [
-    ...desktopAppCandidates(provider, platform, home, options.applications ?? ["/Applications", path.join(home, "Applications")]).filter(executable).map((p) => ({ path: p, source: "desktop-app" })),
+    ...desktopAppCandidates(provider, platform, home, options.applications ?? ["/Applications", path3.join(home, "Applications")]).filter(executable).map((p) => ({ path: p, source: "desktop-app" })),
     ...allOnPath(provider, options.env.PATH ?? "", platform).map((p) => ({ path: p, source: "path" }))
   ];
   const prefix = await npmGlobalPrefix(options.env);
   if (prefix) {
-    const dir = platform === "win32" ? prefix : path.join(prefix, "bin");
+    const dir = platform === "win32" ? prefix : path3.join(prefix, "bin");
     for (const file of exeName(provider, platform)) {
-      const candidate = path.join(dir, file);
+      const candidate = path3.join(dir, file);
       if (executable(candidate)) {
         listed2.push({ path: candidate, source: "npm-global" });
         break;
@@ -937,7 +1306,7 @@ async function resolveBinary(provider, options) {
 
 // src/engine/clean-env.ts
 import os2 from "os";
-import path2 from "path";
+import path4 from "path";
 var ALLOWED_NAMES = /* @__PURE__ */ new Set([
   "HOME",
   "USER",
@@ -959,11 +1328,11 @@ var ALLOWED_NAMES = /* @__PURE__ */ new Set([
 var ALLOWED_PREFIXES = ["LC_"];
 function wellKnownBinDirs(home) {
   return [
-    path2.join(home, ".local", "bin"),
-    path2.join(home, ".claude", "local"),
-    path2.join(home, ".npm-global", "bin"),
-    path2.join(home, ".bun", "bin"),
-    path2.join(home, ".volta", "bin"),
+    path4.join(home, ".local", "bin"),
+    path4.join(home, ".claude", "local"),
+    path4.join(home, ".npm-global", "bin"),
+    path4.join(home, ".bun", "bin"),
+    path4.join(home, ".volta", "bin"),
     "/opt/homebrew/bin",
     "/usr/local/bin",
     "/usr/bin",
@@ -983,21 +1352,21 @@ function buildCleanEnv(hostEnv, extra = {}) {
   }
   const home = out.HOME ?? os2.homedir();
   out.HOME = home;
-  const hostPath = (hostEnv.PATH ?? "").split(path2.delimiter).filter(Boolean);
+  const hostPath = (hostEnv.PATH ?? "").split(path4.delimiter).filter(Boolean);
   const merged = [];
   for (const dir of [...hostPath, ...wellKnownBinDirs(home)]) {
     if (!merged.includes(dir)) merged.push(dir);
   }
-  out.PATH = merged.join(path2.delimiter);
+  out.PATH = merged.join(path4.delimiter);
   for (const [name, value] of Object.entries(extra)) out[name] = value;
   return out;
 }
 
 // src/engine/files.ts
 import { createReadStream } from "fs";
-import fs2 from "fs/promises";
+import fs4 from "fs/promises";
 import os3 from "os";
-import path3 from "path";
+import path5 from "path";
 
 // src/engine/activity.ts
 import { execFile as execFile2 } from "child_process";
@@ -1066,15 +1435,15 @@ function describeActivity(input) {
 // src/engine/files.ts
 function defaultProviderHomes(home = os3.homedir()) {
   return {
-    claudeProjects: path3.join(home, ".claude", "projects"),
-    codexSessions: path3.join(home, ".codex", "sessions"),
-    codexIndex: path3.join(home, ".codex", "session_index.jsonl")
+    claudeProjects: path5.join(home, ".claude", "projects"),
+    codexSessions: path5.join(home, ".codex", "sessions"),
+    codexIndex: path5.join(home, ".codex", "session_index.jsonl")
   };
 }
 var UUIDISH = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
 async function safeReaddir(dir) {
   try {
-    return await fs2.readdir(dir, { withFileTypes: true });
+    return await fs4.readdir(dir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -1083,7 +1452,7 @@ async function statCandidate(provider, file) {
   const match = UUIDISH.exec(file);
   if (!match?.[1]) return null;
   try {
-    const stat = await fs2.stat(file);
+    const stat = await fs4.stat(file);
     return { provider, file, id: match[1], mtimeMs: stat.mtimeMs, size: stat.size };
   } catch {
     return null;
@@ -1093,10 +1462,10 @@ async function claudeCandidates(root) {
   const out = [];
   for (const project of await safeReaddir(root)) {
     if (!project.isDirectory()) continue;
-    const dir = path3.join(root, project.name);
+    const dir = path5.join(root, project.name);
     const entries = await safeReaddir(dir);
     const stats = await Promise.all(
-      entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => statCandidate("claude", path3.join(dir, e.name)))
+      entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => statCandidate("claude", path5.join(dir, e.name)))
     );
     for (const s of stats) if (s) out.push(s);
   }
@@ -1106,14 +1475,14 @@ async function codexCandidates(root) {
   const out = [];
   for (const year of await safeReaddir(root)) {
     if (!year.isDirectory()) continue;
-    for (const month of await safeReaddir(path3.join(root, year.name))) {
+    for (const month of await safeReaddir(path5.join(root, year.name))) {
       if (!month.isDirectory()) continue;
-      for (const day of await safeReaddir(path3.join(root, year.name, month.name))) {
+      for (const day of await safeReaddir(path5.join(root, year.name, month.name))) {
         if (!day.isDirectory()) continue;
-        const dir = path3.join(root, year.name, month.name, day.name);
+        const dir = path5.join(root, year.name, month.name, day.name);
         const entries = await safeReaddir(dir);
         const stats = await Promise.all(
-          entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", path3.join(dir, e.name)))
+          entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", path5.join(dir, e.name)))
         );
         for (const s of stats) if (s) out.push(s);
       }
@@ -1122,7 +1491,7 @@ async function codexCandidates(root) {
   return out;
 }
 async function readSlice(file, start, length) {
-  const handle = await fs2.open(file, "r");
+  const handle = await fs4.open(file, "r");
   try {
     const buffer = Buffer.alloc(length);
     const { bytesRead } = await handle.read(buffer, 0, length, start);
@@ -1195,9 +1564,9 @@ async function readCodexIndex(file) {
   const names = /* @__PURE__ */ new Map();
   let text;
   try {
-    const stat = await fs2.stat(file);
+    const stat = await fs4.stat(file);
     const budget = 4 * 1024 * 1024;
-    text = stat.size <= budget ? await fs2.readFile(file, "utf8") : completeLines(await readSlice(file, stat.size - budget, budget), true);
+    text = stat.size <= budget ? await fs4.readFile(file, "utf8") : completeLines(await readSlice(file, stat.size - budget, budget), true);
   } catch {
     return names;
   }
@@ -1318,7 +1687,7 @@ var MAX_HISTORY_BUDGET = 256 * 1024 * 1024;
 async function readSessionFile(provider, file, endOffset, maxBytes = HISTORY_BUDGET) {
   let size;
   try {
-    size = (await fs2.stat(file)).size;
+    size = (await fs4.stat(file)).size;
   } catch {
     return {
       items: [],
@@ -1372,9 +1741,9 @@ async function describeSessionFile(candidate, codexNames) {
 }
 
 // src/engine/preferences.ts
-import { randomUUID } from "crypto";
-import fs3 from "fs/promises";
-import path4 from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import fs5 from "fs/promises";
+import path6 from "path";
 var PreferenceStore = class {
   constructor(dir) {
     this.dir = dir;
@@ -1383,11 +1752,11 @@ var PreferenceStore = class {
   data = {};
   writing = Promise.resolve();
   get file() {
-    return path4.join(this.dir, "preferences.json");
+    return path6.join(this.dir, "preferences.json");
   }
   async load() {
     try {
-      const parsed = JSON.parse(await fs3.readFile(this.file, "utf8"));
+      const parsed = JSON.parse(await fs5.readFile(this.file, "utf8"));
       this.data = typeof parsed === "object" && parsed !== null ? parsed : {};
     } catch {
       this.data = {};
@@ -1425,10 +1794,10 @@ var PreferenceStore = class {
   persist() {
     const snapshot = JSON.stringify(this.data, null, 1);
     this.writing = this.writing.then(async () => {
-      await fs3.mkdir(this.dir, { recursive: true });
-      const tmp = `${this.file}.${randomUUID()}.tmp`;
-      await fs3.writeFile(tmp, snapshot, { mode: 384 });
-      await fs3.rename(tmp, this.file);
+      await fs5.mkdir(this.dir, { recursive: true });
+      const tmp = `${this.file}.${randomUUID2()}.tmp`;
+      await fs5.writeFile(tmp, snapshot, { mode: 384 });
+      await fs5.rename(tmp, this.file);
     }).catch(() => {
     });
   }
@@ -1585,9 +1954,9 @@ async function searchLocalChats(query, options = {}) {
 }
 
 // src/engine/store.ts
-import { randomUUID as randomUUID2 } from "crypto";
-import fs4 from "fs/promises";
-import path5 from "path";
+import { randomUUID as randomUUID3 } from "crypto";
+import fs6 from "fs/promises";
+import path7 from "path";
 var MAX_RUNS = 2e3;
 var RunIndex = class {
   constructor(dir) {
@@ -1597,12 +1966,12 @@ var RunIndex = class {
   data = { version: 1, sessions: [], runs: [] };
   writing = Promise.resolve();
   get file() {
-    return path5.join(this.dir, "index.json");
+    return path7.join(this.dir, "index.json");
   }
   async load() {
-    await fs4.mkdir(this.dir, { recursive: true });
+    await fs6.mkdir(this.dir, { recursive: true });
     try {
-      const parsed = JSON.parse(await fs4.readFile(this.file, "utf8"));
+      const parsed = JSON.parse(await fs6.readFile(this.file, "utf8"));
       this.data = {
         version: 1,
         sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
@@ -1644,9 +2013,9 @@ var RunIndex = class {
   persist() {
     const snapshot = JSON.stringify(this.data, null, 1);
     this.writing = this.writing.then(async () => {
-      const tmp = `${this.file}.${randomUUID2()}.tmp`;
-      await fs4.writeFile(tmp, snapshot, { mode: 384 });
-      await fs4.rename(tmp, this.file);
+      const tmp = `${this.file}.${randomUUID3()}.tmp`;
+      await fs6.writeFile(tmp, snapshot, { mode: 384 });
+      await fs6.rename(tmp, this.file);
     }).catch(() => {
     });
   }
@@ -1656,27 +2025,27 @@ var RunIndex = class {
   /** A stable Paperclip agent/company identity for this install, so the
    *  driver's scratch state is reused rather than growing per run. */
   async identity() {
-    const file = path5.join(this.dir, "identity.json");
+    const file = path7.join(this.dir, "identity.json");
     try {
-      const parsed = JSON.parse(await fs4.readFile(file, "utf8"));
+      const parsed = JSON.parse(await fs6.readFile(file, "utf8"));
       if (typeof parsed.companyId === "string" && typeof parsed.agentId === "string") {
         return { companyId: parsed.companyId, agentId: parsed.agentId };
       }
     } catch {
     }
-    const identity = { companyId: randomUUID2(), agentId: randomUUID2() };
-    await fs4.writeFile(file, JSON.stringify(identity), { mode: 384 });
+    const identity = { companyId: randomUUID3(), agentId: randomUUID3() };
+    await fs6.writeFile(file, JSON.stringify(identity), { mode: 384 });
     return identity;
   }
 };
 
 // src/engine/user-defaults.ts
-import fs5 from "fs/promises";
+import fs7 from "fs/promises";
 import os4 from "os";
-import path6 from "path";
+import path8 from "path";
 async function readJson(file) {
   try {
-    const parsed = JSON.parse(await fs5.readFile(file, "utf8"));
+    const parsed = JSON.parse(await fs7.readFile(file, "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
     return null;
@@ -1687,8 +2056,8 @@ function str3(value) {
 }
 async function claudeDefaults(cwd, home = os4.homedir()) {
   const files = [
-    ...cwd ? [path6.join(cwd, ".claude", "settings.local.json"), path6.join(cwd, ".claude", "settings.json")] : [],
-    path6.join(home, ".claude", "settings.json")
+    ...cwd ? [path8.join(cwd, ".claude", "settings.local.json"), path8.join(cwd, ".claude", "settings.json")] : [],
+    path8.join(home, ".claude", "settings.json")
   ];
   let model = null;
   let effort = null;
@@ -1704,7 +2073,7 @@ async function claudeDefaults(cwd, home = os4.homedir()) {
 async function codexDefaults(home = os4.homedir()) {
   let text;
   try {
-    text = await fs5.readFile(path6.join(home, ".codex", "config.toml"), "utf8");
+    text = await fs7.readFile(path8.join(home, ".codex", "config.toml"), "utf8");
   } catch {
     return { model: null, effort: null };
   }
@@ -1728,31 +2097,31 @@ var EFFORT_LEVELS = {
 // src/engine/index.ts
 var RAW_TRANSCRIPT_MAX_BYTES = 200 * 1048576;
 function moduleDir() {
-  return path7.dirname(fileURLToPath(import.meta.url));
+  return path9.dirname(fileURLToPath(import.meta.url));
 }
 function resolveWorkerPath() {
   const dir = moduleDir();
   for (const candidate of [
-    path7.join(dir, "worker.js"),
-    path7.join(dir, "worker.ts"),
-    path7.join(dir, "..", "engine", "worker.js"),
-    path7.join(dir, "..", "engine", "worker.ts")
+    path9.join(dir, "worker.js"),
+    path9.join(dir, "worker.ts"),
+    path9.join(dir, "..", "engine", "worker.js"),
+    path9.join(dir, "..", "engine", "worker.ts")
   ]) {
     if (existsSync(candidate)) return candidate;
   }
   throw new Error(`[coding-sessions] The driver worker is missing next to ${dir}.`);
 }
 async function installShim(dataDir) {
-  const source = path7.resolve(moduleDir(), "..", "..", "bin", "cli-shim.sh");
+  const source = path9.resolve(moduleDir(), "..", "..", "bin", "cli-shim.sh");
   if (!existsSync(source)) throw new Error(`[coding-sessions] The CLI shim is missing at ${source}.`);
-  const body = await fs6.readFile(source, "utf8");
-  const target = path7.join(dataDir, "bin", "cli-shim.sh");
-  const current = await fs6.readFile(target, "utf8").catch(() => null);
+  const body = await fs8.readFile(source, "utf8");
+  const target = path9.join(dataDir, "bin", "cli-shim.sh");
+  const current = await fs8.readFile(target, "utf8").catch(() => null);
   if (current !== body) {
-    await fs6.mkdir(path7.dirname(target), { recursive: true });
-    await fs6.writeFile(target, body, { mode: 493 });
+    await fs8.mkdir(path9.dirname(target), { recursive: true });
+    await fs8.writeFile(target, body, { mode: 493 });
   }
-  await fs6.chmod(target, 493);
+  await fs8.chmod(target, 493);
   return target;
 }
 function nowIso() {
@@ -1852,29 +2221,30 @@ function describeAuthStatus(provider, probe) {
   };
 }
 async function createCodingSessionsEngine(options = {}) {
-  const dataDir = options.dataDir ?? path7.join(os5.homedir(), ".matrx", "coding-sessions");
-  const stateDir = path7.join(dataDir, "paperclip-state");
+  const dataDir = options.dataDir ?? path9.join(os5.homedir(), ".matrx", "coding-sessions");
+  const stateDir = path9.join(dataDir, "paperclip-state");
   const homes = options.homes ?? defaultProviderHomes();
   const index = new RunIndex(dataDir);
   await index.load();
   const preferences = new PreferenceStore(dataDir);
   await preferences.load();
-  await fs6.mkdir(stateDir, { recursive: true });
+  await fs8.mkdir(stateDir, { recursive: true });
   const identity = await index.identity();
+  const agents = createAgentConnection(options.agents, dataDir);
   const backups = options.rawBackup ? createRawBackupScheduler({
     sink: options.rawBackup,
     findFile: (provider, providerSessionId) => findSessionFile(provider, providerSessionId, homes),
     onError: (error) => console.warn("[coding-sessions] raw transcript backup failed:", error)
   }) : null;
   const discoveredSeen = /* @__PURE__ */ new Map();
-  const healthFile = path7.join(dataDir, "provider-health.json");
+  const healthFile = path9.join(dataDir, "provider-health.json");
   let health = {};
   try {
-    health = JSON.parse(await fs6.readFile(healthFile, "utf8"));
+    health = JSON.parse(await fs8.readFile(healthFile, "utf8"));
   } catch {
     health = {};
   }
-  const saveHealth = () => fs6.writeFile(healthFile, JSON.stringify(health), { mode: 384 }).catch(() => void 0);
+  const saveHealth = () => fs8.writeFile(healthFile, JSON.stringify(health), { mode: 384 }).catch(() => void 0);
   function noteRunOutcome(provider, status, texts) {
     if (status === "completed") {
       if (health[provider]) {
@@ -1991,7 +2361,7 @@ async function createCodingSessionsEngine(options = {}) {
   async function startRun(session, prompt) {
     const provider = session.provider;
     const realCommand = await commandFor(provider);
-    const runId = randomUUID3();
+    const runId = randomUUID4();
     const model = session.model ?? (provider === "claude" ? (await userDefaults(provider, session.cwd)).model ?? null : null);
     const run = {
       runId,
@@ -2029,7 +2399,26 @@ async function createCodingSessionsEngine(options = {}) {
     let fileOffset = null;
     if (session.providerSessionId) {
       const file = await findSessionFile(provider, session.providerSessionId, homes);
-      if (file) fileOffset = (await fs6.stat(file).catch(() => null))?.size ?? null;
+      if (file) fileOffset = (await fs8.stat(file).catch(() => null))?.size ?? null;
+    }
+    let agentArgs = [];
+    if (session.agent) {
+      const bundle = await agents.readSessionBundle(session.id);
+      if (!bundle) {
+        const failed = saveRun({
+          ...run,
+          status: "failed",
+          endedAt: nowIso(),
+          error: `The agent ${session.agent.name} could not be loaded on this computer anymore. Start a new session to load it again.`
+        });
+        const current = index.session(session.id);
+        if (current) saveSession({ ...current, lastRunStatus: "failed" });
+        return failed;
+      }
+      const attachment = await writeAgentAttachment(agents.sessionDir(session.id), bundle, {
+        mcpUrl: await agents.mcpUrlFor(session.id)
+      });
+      agentArgs = agentArgsFor(provider, attachment, { resuming: session.providerSessionId !== null });
     }
     const child = forkWorker();
     const liveRun = {
@@ -2203,7 +2592,8 @@ async function createCodingSessionsEngine(options = {}) {
       resumeSessionId: session.providerSessionId,
       shimPath,
       realCommand,
-      identity
+      identity,
+      agentArgs
     });
     return run;
   }
@@ -2222,7 +2612,7 @@ async function createCodingSessionsEngine(options = {}) {
     }, 3e3);
   }
   async function pruneDriverScratch() {
-    const runsDir = path7.join(
+    const runsDir = path9.join(
       stateDir,
       "instances",
       "default",
@@ -2233,9 +2623,9 @@ async function createCodingSessionsEngine(options = {}) {
       "claude-runtime",
       "runs"
     );
-    const entries = await fs6.readdir(runsDir).catch(() => []);
+    const entries = await fs8.readdir(runsDir).catch(() => []);
     await Promise.all(
-      entries.filter((name) => !live.has(name)).map((name) => fs6.rm(path7.join(runsDir, name), { recursive: true, force: true }).catch(() => void 0))
+      entries.filter((name) => !live.has(name)).map((name) => fs8.rm(path9.join(runsDir, name), { recursive: true, force: true }).catch(() => void 0))
     );
   }
   async function probe() {
@@ -2276,7 +2666,7 @@ async function createCodingSessionsEngine(options = {}) {
   function newSession(input) {
     const at = nowIso();
     return {
-      id: randomUUID3(),
+      id: randomUUID4(),
       provider: input.provider,
       providerSessionId: input.providerSessionId,
       cwd: input.cwd,
@@ -2294,17 +2684,17 @@ async function createCodingSessionsEngine(options = {}) {
   function resolveFolder(raw) {
     const trimmed = raw.trim();
     if (!trimmed) return null;
-    return path7.resolve(trimmed.replace(/^~(?=$|\/)/, os5.homedir()));
+    return path9.resolve(trimmed.replace(/^~(?=$|\/)/, os5.homedir()));
   }
   async function checkFolder(raw) {
     const target = resolveFolder(raw);
     if (!target) return { path: "", exists: false, isDirectory: false };
-    const stat = await fs6.stat(target).catch(() => null);
+    const stat = await fs8.stat(target).catch(() => null);
     return { path: target, exists: stat !== null, isDirectory: stat?.isDirectory() === true };
   }
   async function assertFolder(cwd) {
-    const resolved = path7.resolve(cwd.replace(/^~(?=$|\/)/, os5.homedir()));
-    const stat = await fs6.stat(resolved).catch(() => null);
+    const resolved = path9.resolve(cwd.replace(/^~(?=$|\/)/, os5.homedir()));
+    const stat = await fs8.stat(resolved).catch(() => null);
     if (!stat?.isDirectory()) {
       throw new Error(`The folder ${resolved} doesn't exist on this computer.`);
     }
@@ -2366,7 +2756,7 @@ async function createCodingSessionsEngine(options = {}) {
         folders.map(async ([folder, lastUsedAt]) => ({
           path: folder,
           lastUsedAt,
-          exists: (await fs6.stat(folder).catch(() => null))?.isDirectory() === true
+          exists: (await fs8.stat(folder).catch(() => null))?.isDirectory() === true
         }))
       );
     },
@@ -2411,7 +2801,7 @@ async function createCodingSessionsEngine(options = {}) {
     async createFolder(raw) {
       const target = resolveFolder(raw);
       if (!target) throw new Error("Type a folder path first.");
-      await fs6.mkdir(target, { recursive: true });
+      await fs8.mkdir(target, { recursive: true });
       return checkFolder(target);
     },
     async sessionActivity(provider, providerSessionId) {
@@ -2449,31 +2839,35 @@ async function createCodingSessionsEngine(options = {}) {
           reason: `${PROVIDER_LABEL[provider]} has no saved transcript for this chat on this computer.`
         };
       }
-      const stat = await fs6.stat(file);
+      const stat = await fs8.stat(file);
       if (stat.size > RAW_TRANSCRIPT_MAX_BYTES) {
         return {
           available: false,
           reason: `This transcript is ${formatFileSize(stat.size)}, larger than the ${formatFileSize(RAW_TRANSCRIPT_MAX_BYTES)} this page can hand over. It is at ${file}.`
         };
       }
-      const content = await fs6.readFile(file, "utf8");
-      return { available: true, fileName: path7.basename(file), bytes: stat.size, content };
+      const content = await fs8.readFile(file, "utf8");
+      return { available: true, fileName: path9.basename(file), bytes: stat.size, content };
     },
     async start(input) {
       const prompt = input.prompt.trim();
       if (!prompt) throw new Error("Type what you want done before starting.");
       const cwd = await assertFolder(input.cwd);
-      const session = saveSession(
-        newSession({
-          provider: input.provider,
-          cwd,
-          title: titleFrom(prompt),
-          model: input.model?.trim() || null,
-          effort: input.effort?.trim() || null,
-          origin: "started",
-          providerSessionId: null
-        })
-      );
+      const bundle = input.agent ? await agents.loadBundle(input.agent) : null;
+      const draft = newSession({
+        provider: input.provider,
+        cwd,
+        title: titleFrom(prompt),
+        model: input.model?.trim() || null,
+        effort: input.effort?.trim() || null,
+        origin: "started",
+        providerSessionId: null
+      });
+      if (bundle) {
+        await agents.saveSessionBundle(draft.id, bundle);
+        draft.agent = sessionAgentRecord(bundle, { toolsServed: await agents.mcpUrlFor(draft.id) !== null });
+      }
+      const session = saveSession(draft);
       const run = await startRun(session, prompt);
       return { session: index.session(session.id) ?? session, run, queued: false };
     },
@@ -2542,6 +2936,21 @@ async function createCodingSessionsEngine(options = {}) {
       if (opts && "effort" in opts) next.effort = typeof opts.effort === "string" && opts.effort.trim() ? opts.effort.trim() : null;
       return saveSession(next);
     },
+    async agentAccess() {
+      return agents.access();
+    },
+    async agentCatalogRpc(request) {
+      return agents.catalogRpc(request);
+    },
+    async agentDetails(agentId) {
+      return agents.details(String(agentId ?? ""));
+    },
+    setMcpBaseUrl(baseUrl) {
+      agents.setMcpBaseUrl(baseUrl);
+    },
+    async handleMcp(secret, body) {
+      return agents.handleMcp(secret, body);
+    },
     async dispose() {
       for (const liveRun of live.values()) {
         liveRun.stopRequested = true;