@ai-matrx/coding-sessions 0.1.83 → 0.1.86

package/dist/server/index.js

@@ -1,15 +1,15 @@
 // src/server/index.ts
-import { randomBytes, timingSafeEqual } from "crypto";
+import { randomBytes as randomBytes2, timingSafeEqual } from "crypto";
 import { existsSync as existsSync2 } from "fs";
-import fs7 from "fs/promises";
+import fs9 from "fs/promises";
 import http from "http";
-import path8 from "path";
+import path10 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { WebSocketServer } from "ws";
 
 // 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";
 
@@ -70,10 +70,448 @@ function createRawBackupScheduler(options) {
   };
 }
 
+// src/engine/agent-attach.ts
+import fs2 from "fs/promises";
+import path from "path";
+
+// src/normalize/agent-block.ts
+var AGENT_BLOCK_MARKER = "<ai_matrx_agent ";
+function stripAgentBlock(text) {
+  const removed = text.match(/^<ai_matrx_agent_removed>[\s\S]*?<\/ai_matrx_agent_removed>\s*/);
+  if (removed) return text.slice(removed[0].length);
+  if (!text.startsWith(AGENT_BLOCK_MARKER)) return text;
+  const end = text.indexOf("</ai_matrx_agent>");
+  if (end < 0) return text;
+  let rest = text.slice(end + "</ai_matrx_agent>".length);
+  const skills = rest.match(/^\s*<skills_instructions>[\s\S]*?<\/skills_instructions>/);
+  if (skills) rest = rest.slice(skills[0].length);
+  return rest.replace(/^\s+/, "");
+}
+
+// src/engine/agent-attach.ts
+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 renderFallbackBlock(bundle, skillsRoot) {
+  const skills = renderCodexSkillsList(bundle, skillsRoot);
+  const body = renderAgentInstructions(bundle).trim().replace(/^(<ai_matrx_agent [^>]*>)/, "$1\n\nThe instructions below are your AI Matrx agent for this chat from now on; they replace any AI Matrx agent instructions given earlier.");
+  return skills ? `${body}
+
+${skills}
+
+` : `${body}
+
+`;
+}
+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,
+    skills: bundle.skills.map((skill) => skill.label),
+    tools: options.toolsServed ? bundle.tools.map((tool) => tool.canonical_name) : [],
+    ...options.variables ? { variables: options.variables } : {}
+  };
+}
+var AGENT_REMOVED_BLOCK = "<ai_matrx_agent_removed>The AI Matrx agent instructions given earlier in this chat no longer apply.</ai_matrx_agent_removed>\n\n";
+async function codexCompactionDroppedAgent(rolloutFile, sinceIso) {
+  const text = await fs2.readFile(rolloutFile, "utf8").catch(() => "");
+  if (!text.includes('"type":"compacted"')) return false;
+  let latest = null;
+  for (const line of text.split("\n")) {
+    if (!line.includes('"type":"compacted"')) continue;
+    try {
+      const entry = JSON.parse(line);
+      if (entry.type === "compacted") latest = entry;
+    } catch {
+    }
+  }
+  if (!latest) return false;
+  if (sinceIso && latest.timestamp && latest.timestamp <= sinceIso) return false;
+  return !JSON.stringify(latest.payload?.replacement_history ?? "").includes(AGENT_BLOCK_MARKER.trim());
+}
+
+// src/engine/agents.ts
+import { createHash as createHash2, 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 DEFAULT_SUPABASE_KEY = "sb_publishable_scm0jzEJiFUB5ItiqOx5Fg_8BOjB6oA";
+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 };
+};
+function sortedValues(values) {
+  return Object.keys(values).sort().map((key) => [key, values[key]]);
+}
+var BUNDLE_CACHE_MS = 24 * 60 * 60 * 1e3;
+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 ?? (options?.supabaseUrl ? null : DEFAULT_SUPABASE_KEY);
+  const root = path2.join(dataDir, "agents");
+  let mcpBaseUrl = null;
+  const handlers = /* @__PURE__ */ new Map();
+  const secretToSession = /* @__PURE__ */ new Map();
+  const organizationId = async () => {
+    const raw = typeof options?.organizationId === "function" ? await options.organizationId() : options?.organizationId;
+    return raw && raw.trim() ? raw.trim() : null;
+  };
+  const transport = async () => {
+    const org = await organizationId();
+    return (await agentsClient()).createMatrxTransport({
+      baseUrl: serverUrl,
+      ...credentials ? { credentials } : {},
+      ...org ? { organizationId: org } : {},
+      source: "codingSessionsAgents"
+    });
+  };
+  const cacheDir = path2.join(dataDir, "agents", ".bundles");
+  const cacheKey = (definitionHash, selection, surface) => createHash2("sha256").update(JSON.stringify([definitionHash, sortedValues(selection.variables ?? {}), surface])).digest("hex");
+  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: await organizationId().catch(() => null)
+      };
+    },
+    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 summary = await (await agentsClient()).fetchPortableAgentSummary(await transport(), agentId);
+      return {
+        agentId: summary.agent_id,
+        name: summary.name,
+        variables: summary.variables,
+        versions: summary.versions.map((v) => ({ id: v.id, versionNumber: v.version_number, changedAt: v.changed_at })),
+        latestVersionNumber: summary.version_number,
+        latestVersionId: summary.version_id
+      };
+    },
+    async loadBundle(selection) {
+      await requireSignedIn();
+      const client = await agentsClient();
+      const summary = await client.fetchPortableAgentSummary(await transport(), selection.agentId);
+      const versionId = selection.versionId ?? summary.version_id;
+      const definitionHash = versionId ? summary.versions.find((v) => v.id === versionId)?.definition_hash ?? null : summary.definition_hash;
+      const surface = "matrx-user/code-editor";
+      const file = definitionHash ? path2.join(cacheDir, `${cacheKey(definitionHash, selection, surface)}.json`) : null;
+      if (file) {
+        const cached = await fs3.readFile(file, "utf8").then((text) => JSON.parse(text)).catch(() => null);
+        const fresh = await fs3.stat(file).then((st) => Date.now() - st.mtimeMs < BUNDLE_CACHE_MS).catch(() => false);
+        if (cached && fresh && cached.definition_hash === definitionHash) return cached;
+      }
+      const bundle = await client.fetchPortableAgent(
+        await transport(),
+        versionId ? { versionId } : { agentId: selection.agentId },
+        { variables: selection.variables ?? {}, surface }
+      );
+      if (file && bundle.definition_hash === definitionHash) {
+        await fs3.mkdir(cacheDir, { recursive: true, mode: 448 });
+        await fs3.writeFile(file, JSON.stringify(bundle), { mode: 384 });
+      }
+      return bundle;
+    },
+    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
@@ -444,7 +882,7 @@ function rolloutItem(item, fallbackId, at) {
   const id = str2(item.id) ?? fallbackId;
   switch (item.type) {
     case "UserMessage": {
-      const text = stripCodexInjectedContext(itemText(item.content));
+      const text = stripCodexInjectedContext(stripAgentBlock(itemText(item.content)));
       return text.trim() ? [{ kind: "user", id, text, at }] : [];
     }
     case "AgentMessage": {
@@ -527,7 +965,7 @@ function createCodexRolloutNormalizer() {
           return rolloutItem(payload.item, fallbackId, at);
         }
         if (payload.type === "user_message" && !appItems) {
-          const text = stripCodexInjectedContext(str2(payload.message) ?? "");
+          const text = stripCodexInjectedContext(stripAgentBlock(str2(payload.message) ?? ""));
           return text.trim() ? [{ kind: "user", id: fallbackId, text, at }] : [];
         }
         return [];
@@ -743,7 +1181,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" }
@@ -792,10 +1230,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;
@@ -808,17 +1246,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;
@@ -836,13 +1274,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) => {
@@ -856,14 +1294,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;
@@ -909,7 +1347,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",
@@ -931,11 +1369,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",
@@ -955,21 +1393,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";
@@ -1038,15 +1476,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 [];
   }
@@ -1055,7 +1493,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;
@@ -1065,10 +1503,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);
   }
@@ -1078,14 +1516,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);
       }
@@ -1094,7 +1532,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);
@@ -1167,9 +1605,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;
   }
@@ -1290,7 +1728,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: [],
@@ -1344,9 +1782,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;
@@ -1355,11 +1793,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 = {};
@@ -1397,10 +1835,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(() => {
     });
   }
@@ -1557,9 +1995,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) {
@@ -1569,12 +2007,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 : [],
@@ -1616,9 +2054,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(() => {
     });
   }
@@ -1628,27 +2066,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;
@@ -1659,8 +2097,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;
@@ -1676,7 +2114,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 };
   }
@@ -1700,31 +2138,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() {
@@ -1824,29 +2262,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]) {
@@ -1963,7 +2402,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,
@@ -2001,7 +2440,36 @@ 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 = [];
+    let cliPrompt = prompt;
+    let delivered = null;
+    if (!session.agent && session.agentRemovedDue) {
+      if (provider === "codex") cliPrompt = `${AGENT_REMOVED_BLOCK}${prompt}`;
+      delivered = { agentRemovedDue: false };
+    }
+    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 });
+      if (provider === "codex" && session.agent.blockDue) {
+        cliPrompt = `${renderFallbackBlock(bundle, path9.join(attachment.dir, "skills"))}${prompt}`;
+      }
+      delivered = { agent: { ...session.agent, blockDue: false, deliveredAt: run.startedAt } };
     }
     const child = forkWorker();
     const liveRun = {
@@ -2017,6 +2485,10 @@ async function createCodingSessionsEngine(options = {}) {
     };
     live.set(runId, liveRun);
     emitItem(liveRun, { kind: "user", id: `run-${runId}`, text: prompt, at: run.startedAt });
+    if (delivered) {
+      const current = index.session(session.id);
+      if (current) saveSession({ ...current, ...delivered });
+    }
     const splitter = createLineSplitter();
     const claude = provider === "claude" ? createClaudeNormalizer() : null;
     const codex = provider === "codex" ? createCodexStreamNormalizer(runId.slice(0, 8)) : null;
@@ -2055,6 +2527,7 @@ async function createCodingSessionsEngine(options = {}) {
         }
       }
       void pruneDriverScratch();
+      if (provider === "codex" && final.status === "completed") void checkCompaction(session.id);
     };
     let settled = false;
     child.on("message", (raw) => {
@@ -2169,16 +2642,39 @@ async function createCodingSessionsEngine(options = {}) {
       provider,
       runId,
       cwd: session.cwd,
-      prompt,
+      prompt: cliPrompt,
       model,
       effort: session.effort ?? null,
       resumeSessionId: session.providerSessionId,
       shimPath,
       realCommand,
-      identity
+      identity,
+      agentArgs
     });
     return run;
   }
+  async function checkCompaction(sessionId) {
+    const session = index.session(sessionId);
+    if (!session?.agent || session.agent.blockDue || !session.providerSessionId) return;
+    const file = await findSessionFile("codex", session.providerSessionId, homes);
+    if (!file || !await codexCompactionDroppedAgent(file, session.agent.deliveredAt ?? null)) return;
+    const current = index.session(sessionId);
+    if (current?.agent) {
+      saveSession({ ...current, agent: { ...current.agent, blockDue: true } });
+    }
+  }
+  async function attachAgent(sessionId, selection, options2) {
+    const bundle = await agents.loadBundle(selection);
+    await agents.saveSessionBundle(sessionId, bundle);
+    return {
+      ...sessionAgentRecord(bundle, {
+        toolsServed: await agents.mcpUrlFor(sessionId) !== null,
+        variables: selection.variables ?? {}
+      }),
+      blockDue: options2.blockDue,
+      deliveredAt: null
+    };
+  }
   function killGroup(liveRun) {
     const target = liveRun.pgid;
     if (target === null) return;
@@ -2194,7 +2690,7 @@ async function createCodingSessionsEngine(options = {}) {
     }, 3e3);
   }
   async function pruneDriverScratch() {
-    const runsDir = path7.join(
+    const runsDir = path9.join(
       stateDir,
       "instances",
       "default",
@@ -2205,9 +2701,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() {
@@ -2248,7 +2744,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,
@@ -2266,17 +2762,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.`);
     }
@@ -2338,7 +2834,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
         }))
       );
     },
@@ -2383,7 +2879,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) {
@@ -2421,48 +2917,63 @@ 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 draft = newSession({
+        provider: input.provider,
+        cwd,
+        title: titleFrom(prompt),
+        model: input.model?.trim() || null,
+        effort: input.effort?.trim() || null,
+        origin: "started",
+        providerSessionId: null
+      });
+      if (input.agent) draft.agent = await attachAgent(draft.id, input.agent, { blockDue: false });
+      const session = saveSession(draft);
       const run = await startRun(session, prompt);
       return { session: index.session(session.id) ?? session, run, queued: false };
     },
     async takeover(input) {
       const existing = index.session(input.providerSessionId);
-      if (existing) return existing;
+      if (existing) {
+        if (!input.agent) return existing;
+        return engine.setAgent(existing.id, input.agent);
+      }
       const cwd = await assertFolder(input.cwd);
-      return saveSession(
-        newSession({
-          provider: input.provider,
-          cwd,
-          title: input.title?.trim() || "Taken-over chat",
-          model: null,
-          origin: "takeover",
-          providerSessionId: input.providerSessionId
-        })
-      );
+      const draft = newSession({
+        provider: input.provider,
+        cwd,
+        title: input.title?.trim() || "Taken-over chat",
+        model: null,
+        origin: "takeover",
+        providerSessionId: input.providerSessionId
+      });
+      if (input.agent) draft.agent = await attachAgent(draft.id, input.agent, { blockDue: input.provider === "codex" });
+      return saveSession(draft);
+    },
+    async setAgent(sessionId, selection) {
+      const session = index.session(String(sessionId ?? ""));
+      if (!session) throw new Error("This session is not in the list anymore.");
+      if (!selection) {
+        const told = session.provider === "codex" && session.agent?.deliveredAt != null;
+        return saveSession({ ...session, agent: null, agentRemovedDue: told });
+      }
+      const agent = await attachAgent(session.id, selection, {
+        blockDue: session.provider === "codex" && session.providerSessionId !== null
+      });
+      return saveSession({ ...session, agent, agentRemovedDue: false });
     },
     async send(sessionId, rawPrompt) {
       const prompt = rawPrompt.trim();
@@ -2514,6 +3025,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;
@@ -2583,7 +3109,11 @@ var BRIDGE_METHODS = [
   "setChatPreference",
   "searchChats",
   "openFolder",
-  "setSessionOptions"
+  "setSessionOptions",
+  "agentAccess",
+  "agentCatalogRpc",
+  "agentDetails",
+  "setAgent"
 ];
 var BridgeError = class extends Error {
   constructor(message, code) {
@@ -2627,14 +3157,14 @@ var MIME = {
   ".map": "application/json"
 };
 function moduleDir2() {
-  return path8.dirname(fileURLToPath2(import.meta.url));
+  return path10.dirname(fileURLToPath2(import.meta.url));
 }
 function defaultUiDir() {
   for (const candidate of [
-    path8.resolve(moduleDir2(), "..", "ui"),
-    path8.resolve(moduleDir2(), "..", "..", "dist", "ui")
+    path10.resolve(moduleDir2(), "..", "ui"),
+    path10.resolve(moduleDir2(), "..", "..", "dist", "ui")
   ]) {
-    if (existsSync2(path8.join(candidate, "index.html"))) return candidate;
+    if (existsSync2(path10.join(candidate, "index.html"))) return candidate;
   }
   return null;
 }
@@ -2657,19 +3187,19 @@ async function serveStatic(uiDir, req, res) {
     return;
   }
   const requested = decodeURIComponent(url.pathname);
-  let file = path8.resolve(uiDir, `.${requested}`);
+  let file = path10.resolve(uiDir, `.${requested}`);
   if (!file.startsWith(uiDir)) {
     res.writeHead(403).end();
     return;
   }
-  const stat = await fs7.stat(file).catch(() => null);
-  if (!stat || stat.isDirectory()) file = path8.join(uiDir, "index.html");
-  const body = await fs7.readFile(file).catch(() => null);
+  const stat = await fs9.stat(file).catch(() => null);
+  if (!stat || stat.isDirectory()) file = path10.join(uiDir, "index.html");
+  const body = await fs9.readFile(file).catch(() => null);
   if (!body) {
     res.writeHead(404).end();
     return;
   }
-  const ext = path8.extname(file);
+  const ext = path10.extname(file);
   res.writeHead(200, {
     "content-type": MIME[ext] ?? "application/octet-stream",
     "cache-control": ext === ".html" ? "no-store" : "public, max-age=31536000, immutable",
@@ -2678,6 +3208,46 @@ async function serveStatic(uiDir, req, res) {
   });
   res.end(body);
 }
+var MAX_MCP_BODY = 4 * 1024 * 1024;
+async function handleMcp(engine, secret, req, res, allowedOrigin) {
+  if (!allowedOrigin(req.headers.origin) || !/^[A-Za-z0-9_-]{16,}$/.test(secret)) {
+    res.writeHead(403).end();
+    return;
+  }
+  if (req.method !== "POST") {
+    res.writeHead(405, { allow: "POST" }).end();
+    return;
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_MCP_BODY) {
+      res.writeHead(413).end();
+      return;
+    }
+    chunks.push(chunk);
+  }
+  let body;
+  try {
+    body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    res.writeHead(400, { "content-type": "application/json" });
+    res.end(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error." } }));
+    return;
+  }
+  const reply = engine.handleMcp ? await engine.handleMcp(secret, body) : null;
+  if (!reply) {
+    res.writeHead(404).end();
+    return;
+  }
+  if (reply.body === void 0) {
+    res.writeHead(reply.status).end();
+    return;
+  }
+  res.writeHead(reply.status, { "content-type": "application/json" });
+  res.end(JSON.stringify(reply.body));
+}
 function attachSocket(socket, bridge) {
   const unsubscribe = bridge.subscribe((event) => {
     if (socket.readyState === socket.OPEN) socket.send(JSON.stringify({ event }));
@@ -2708,7 +3278,7 @@ function attachSocket(socket, bridge) {
   socket.on("close", unsubscribe);
 }
 async function startCodingSessionsHost(options = {}) {
-  const token = options.token ?? randomBytes(24).toString("base64url");
+  const token = options.token ?? randomBytes2(24).toString("base64url");
   const engine = options.engine ?? await createCodingSessionsEngine(options);
   const bridge = createHostBridge(engine);
   const uiDir = options.uiDir ?? defaultUiDir();
@@ -2719,6 +3289,13 @@ async function startCodingSessionsHost(options = {}) {
   };
   const server = http.createServer((req, res) => {
     const url2 = new URL(req.url ?? "/", `http://${HOST}`);
+    if (url2.pathname.startsWith("/mcp/")) {
+      handleMcp(engine, url2.pathname.slice("/mcp/".length), req, res, allowedOrigin).catch(() => {
+        if (!res.headersSent) res.writeHead(500);
+        res.end();
+      });
+      return;
+    }
     if (url2.pathname === "/health") {
       res.writeHead(200, { "content-type": "application/json" });
       res.end(JSON.stringify({ ok: true, service: "@ai-matrx/coding-sessions" }));
@@ -2749,6 +3326,7 @@ async function startCodingSessionsHost(options = {}) {
       server.off("error", reject);
       const address = server.address();
       if (address && typeof address === "object") port = address.port;
+      engine.setMcpBaseUrl?.(`http://${HOST}:${port}`);
       resolve();
     });
   });
@@ -2759,6 +3337,7 @@ async function startCodingSessionsHost(options = {}) {
     token,
     engine,
     async close() {
+      engine.setMcpBaseUrl?.(null);
       for (const client of wss.clients) client.terminate();
       await new Promise((resolve) => wss.close(() => resolve()));
       await new Promise((resolve) => server.close(() => resolve()));