@modootoday/pmcp 0.9.1 → 0.10.0

package/dist/cli.js

@@ -1,31 +1,51 @@
 #!/usr/bin/env node
 import {
-  loadEmbedder,
-  openEntryVectors
-} from "./chunk-7DD2ADL2.js";
-import {
-  ConfigError,
   ProjectError,
   TOOLS,
   doctor,
-  findConfig,
+  prepareSearch,
   project,
-  readConfig,
   readSpec,
   renderFrontmatter,
   spawnRunner,
   splitFrontmatter,
   validateCatalog,
   validateSkillDir
-} from "./chunk-QCOJ3WCM.js";
-import "./chunk-R2QPKEI4.js";
+} from "./chunk-ZUFFVIHQ.js";
+import {
+  loadEmbedder,
+  openEntryVectors
+} from "./chunk-XEH4ZGGJ.js";
 import {
-  serve
-} from "./chunk-AJYMOFVX.js";
+  serve,
+  serveWithMailbox
+} from "./chunk-JRSR4JBR.js";
 import {
   kindOf,
   readCatalog
-} from "./chunk-VQHNG3KM.js";
+} from "./chunk-VRZFM2M5.js";
+import {
+  MailboxError,
+  MailboxService,
+  MailboxStore,
+  failure,
+  initializeMailboxConfig,
+  mailboxConfigFrom,
+  readBinding,
+  readCredential,
+  restoreBackup,
+  writePrivateJson
+} from "./chunk-HNAVQG6R.js";
+import {
+  ConfigError,
+  findConfig,
+  readConfig
+} from "./chunk-MSTKY33C.js";
+import {
+  embeddingModels,
+  operationSchema,
+  resolveEncoder
+} from "./chunk-XOH2CW6P.js";
 
 // src/cli/command.ts
 var ArgumentError = class extends Error {
@@ -204,6 +224,13 @@ var Ui = class {
   }
 };
 
+// src/commands/reindex.ts
+import { existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+// src/commands/embedding.ts
+import { resolve } from "path";
+
 // src/commands/roots.ts
 var CATALOG_OPTIONS = [
   {
@@ -290,6 +317,87 @@ function catalogFrom(context, onReject) {
   return readCatalog(catalogOptionsFrom(context, onReject));
 }
 
+// src/commands/embedding.ts
+var EMBEDDING_OPTIONS = [
+  {
+    name: "model",
+    describe: "Embedding preset or model ID; list presets with pmcp models",
+    placeholder: "<name>"
+  },
+  {
+    name: "dtype",
+    describe: "Weight precision; uses the selected model default when omitted",
+    placeholder: "<q4|q8|fp32>"
+  },
+  {
+    name: "dimensions",
+    describe: "Supported output width; uses the model's full output when omitted",
+    placeholder: "<number>"
+  },
+  {
+    name: "model-revision",
+    describe: "Model revision used for loading and index identity",
+    placeholder: "<revision>"
+  },
+  {
+    name: "model-path",
+    describe: "Local model artifact directory",
+    placeholder: "<dir>"
+  },
+  {
+    name: "model-cache",
+    describe: "Model cache directory",
+    placeholder: "<dir>"
+  },
+  {
+    name: "query-prefix",
+    describe: "Custom model's query instruction prefix",
+    placeholder: "<text>"
+  },
+  {
+    name: "passage-prefix",
+    describe: "Custom model's document instruction prefix",
+    placeholder: "<text>"
+  },
+  {
+    name: "pooling",
+    describe: "Custom model's pooling method",
+    placeholder: "<mean|cls>"
+  }
+];
+function embeddingFrom(context) {
+  const configuration = configFrom(context)?.embedding ?? {};
+  const dimension = one(context.args, "dimensions");
+  const modelPath = one(context.args, "model-path");
+  const cacheDir = one(context.args, "model-cache");
+  const queryPrefix = one(context.args, "query-prefix");
+  const passagePrefix = one(context.args, "passage-prefix");
+  const pooling = one(context.args, "pooling");
+  const selection = {
+    ...configuration,
+    modelId: one(context.args, "model") ?? configuration.modelId,
+    dtype: one(context.args, "dtype") ?? configuration.dtype,
+    dimensions: dimension === void 0 ? configuration.dimensions : Number(dimension),
+    revision: one(context.args, "model-revision") ?? configuration.revision,
+    modelPath: modelPath === void 0 ? configuration.modelPath : resolve(context.cwd, modelPath),
+    cacheDir: cacheDir === void 0 ? configuration.cacheDir : resolve(context.cwd, cacheDir),
+    encoder: {
+      ...configuration.encoder,
+      ...queryPrefix === void 0 ? {} : { queryPrefix },
+      ...passagePrefix === void 0 ? {} : { passagePrefix },
+      ...pooling === void 0 ? {} : { pooling }
+    }
+  };
+  try {
+    resolveEncoder(selection.modelId, selection);
+  } catch (error) {
+    throw new ArgumentError(
+      error instanceof Error ? error.message : "Invalid embedding options"
+    );
+  }
+  return selection;
+}
+
 // src/commands/reindex.ts
 function indexPath(root) {
   return `${root}/.cache/pmcp/vectors.sqlite`;
@@ -300,10 +408,12 @@ var indexCommand = {
   usage: "pmcp index [--root <dir>] [--model <id>]",
   options: [
     ...CATALOG_OPTIONS,
+    ...EMBEDDING_OPTIONS,
+    { name: "local-only", describe: "Refuse model downloads", boolean: true },
     {
-      name: "model",
-      describe: "Encoder to use. Rows from another model are never scored.",
-      placeholder: "<id>"
+      name: "force",
+      describe: "Re-encode the selected model even when descriptions match",
+      boolean: true
     },
     {
       name: "json",
@@ -323,8 +433,28 @@ var indexCommand = {
       return 1;
     }
     const dryRun = context.args.flags.has("dry-run");
-    const model = one(context.args, "model");
-    const embedder = await loadEmbedder(model);
+    const selection = embeddingFrom(context);
+    const selected = resolveEncoder(selection.modelId, selection);
+    const path = indexPath(rootsFrom(context)[0] ?? ".");
+    const descriptions = new Map(
+      entries.map((entry2) => [entry2.name, entry2.description])
+    );
+    const force = context.args.flags.has("force");
+    if (dryRun) {
+      const existing = existsSync(path) ? await openEntryVectors(path, { readOnly: true }) : null;
+      try {
+        const pending = !force && existing ? existing.stale(selected.indexKey, descriptions) : [...descriptions.keys()];
+        for (const name of pending) context.ui.line(`  would encode ${name}`);
+        context.ui.info("dry run, nothing written");
+        return 0;
+      } finally {
+        existing?.close();
+      }
+    }
+    const embedder = await loadEmbedder(selected.modelId, {
+      ...selection,
+      localOnly: context.args.flags.has("local-only")
+    });
     if (embedder === null) {
       context.ui.error(
         "semantic ranking needs an encoder that is not installed"
@@ -333,9 +463,8 @@ var indexCommand = {
       context.ui.info("ranking stays lexical until then, which is the default");
       return 3;
     }
-    const store = await openEntryVectors(
-      indexPath(rootsFrom(context)[0] ?? ".")
-    );
+    mkdirSync(dirname(path), { recursive: true });
+    const store = await openEntryVectors(path);
     if (store === null) {
       context.ui.error(
         "no sqlite in this runtime, so vectors cannot be stored"
@@ -343,29 +472,29 @@ var indexCommand = {
       return 1;
     }
     try {
-      const descriptions = new Map(entries.map((e) => [e.name, e.description]));
-      const stale = new Set(store.stale(embedder.modelId, descriptions));
+      const key = embedder.indexKey ?? selected.indexKey;
+      const stale = new Set(
+        force ? [...descriptions.keys()] : store.stale(key, descriptions)
+      );
       const todo = entries.filter((entry2) => stale.has(entry2.name));
       context.ui.info(
         `${todo.length} of ${entries.length} to encode`,
         embedder.modelId
       );
-      if (dryRun) {
-        for (const entry2 of todo)
-          context.ui.line(`  would encode ${entry2.name}`);
-        context.ui.info("dry run, nothing written");
-        return 0;
-      }
       for (const entry2 of todo) {
         const vector = embedder.embedPassage ? await embedder.embedPassage(entry2.description) : await embedder.embed(entry2.description);
-        store.write(embedder.modelId, entry2.name, entry2.description, vector);
+        store.write(key, entry2.name, entry2.description, vector);
       }
-      const indexed = store.read(embedder.modelId).size;
+      const indexed = store.read(key).size;
       if (context.args.flags.has("json")) {
         context.ui.data(
           `${JSON.stringify(
             {
               model: embedder.modelId,
+              indexKey: key,
+              dtype: selected.dtype,
+              revision: selected.revision,
+              dimensions: embedder.dims || selected.dimensions,
               encoded: todo.length,
               indexed,
               catalog: entries.length
@@ -391,6 +520,31 @@ var indexCommand = {
   }
 };
 
+// src/commands/models.ts
+var modelsCommand = {
+  name: "models",
+  describe: "List embedding presets without loading or downloading models",
+  usage: "pmcp models [--json]",
+  options: [
+    { name: "json", describe: "Emit preset metadata as JSON", boolean: true }
+  ],
+  run(context) {
+    const models = embeddingModels();
+    if (context.args.flags.has("json")) {
+      context.ui.data(`${JSON.stringify(models, null, 2)}
+`);
+      return 0;
+    }
+    context.ui.table(
+      models.map((model) => [
+        model.name,
+        `${model.modelId} (${model.dtype}; dimensions: ${model.dimensions.join(", ")})`
+      ])
+    );
+    return 0;
+  }
+};
+
 // src/commands/list.ts
 var listCommand = {
   name: "list",
@@ -446,6 +600,11 @@ var listCommand = {
   }
 };
 
+// src/cli/invocation.ts
+function invocation(env = process.env) {
+  return env["npm_command"] === "exec" ? "npx -y @modootoday/pmcp" : "pmcp";
+}
+
 // src/commands/serve.ts
 var serveCommand = {
   name: "serve",
@@ -453,31 +612,101 @@ var serveCommand = {
   usage: "pmcp serve [--root <dir>] [--scope <prefix>] [--marketplace <dir>] [--package <dir>] [--workspace <dir>] [--config <file> | --no-config] [--prompts]",
   options: [
     ...CATALOG_OPTIONS,
+    ...EMBEDDING_OPTIONS,
+    {
+      name: "lexical",
+      describe: "Skip semantic index and model loading",
+      boolean: true
+    },
+    {
+      name: "mailbox-actor-file",
+      describe: "Private launcher actor credential for opt-in mailbox",
+      placeholder: "<file>"
+    },
+    {
+      name: "mailbox-binding-file",
+      describe: "Private attachment file written by the launcher",
+      placeholder: "<file>"
+    },
+    {
+      name: "mailbox-runtime",
+      describe: "Launcher-assigned canonical runtime",
+      placeholder: "<runtime>"
+    },
+    {
+      name: "mailbox-replace-session",
+      describe: "Exact old attachment ID to replace",
+      placeholder: "<id>"
+    },
+    {
+      name: "mailbox-native-session",
+      describe: "Launcher-owned native session ID",
+      placeholder: "<id>"
+    },
     {
       name: "prompts",
       describe: "Also offer one prompt per skill, for hosts that turn prompts into commands.",
       boolean: true
     }
   ],
-  run(context) {
-    serve(catalogOptionsFrom(context), {
-      prompts: context.args.flags.has("prompts")
+  async run(context) {
+    const selection = embeddingFrom(context);
+    const project2 = configFrom(context);
+    const mailbox = project2 ? mailboxConfigFrom(project2, context.env) : void 0;
+    const actorFile = one(context.args, "mailbox-actor-file") ?? context.env.PMCP_MAILBOX_ACTOR_FILE;
+    const runtime = one(context.args, "mailbox-runtime") ?? context.env.PMCP_MAILBOX_RUNTIME;
+    const catalog = catalogOptionsFrom(context);
+    const search = context.args.flags.has("lexical") || selection.enabled === false ? void 0 : await prepareSearch(catalog, {
+      indexPath: indexPath(rootsFrom(context)[0] ?? "."),
+      ...selection,
+      localOnly: true
     });
+    if (search && search.reason !== "index_missing") {
+      const hint = search.reason ? ` reason=${search.reason}; run ${invocation(context.env)} index with the selected model` : "";
+      process.stderr.write(`pmcp: search ranking=${search.ranking}${hint}
+`);
+    }
+    const serving = {
+      prompts: context.args.flags.has("prompts"),
+      ...search?.options
+    };
+    if (actorFile) {
+      if (!mailbox?.enabled)
+        throw new ArgumentError("Enable [mailbox] before attaching an actor");
+      if (!runtime)
+        throw new ArgumentError(
+          "Provide --mailbox-runtime or PMCP_MAILBOX_RUNTIME"
+        );
+      await serveWithMailbox(
+        catalogOptionsFrom(context),
+        {
+          config: mailbox,
+          actorFile,
+          runtime,
+          bindingFile: one(context.args, "mailbox-binding-file") ?? context.env.PMCP_MAILBOX_BINDING_FILE,
+          replaceSessionId: one(context.args, "mailbox-replace-session"),
+          nativeSessionId: one(context.args, "mailbox-native-session")
+        },
+        serving
+      );
+      return 0;
+    }
+    if ([...context.args.options.keys()].some(
+      (name) => name.startsWith("mailbox-")
+    ) || runtime || context.env.PMCP_MAILBOX_BINDING_FILE) {
+      throw new ArgumentError("Provide a launcher mailbox actor file");
+    }
+    serve(catalogOptionsFrom(context), serving);
     return 0;
   }
 };
 
-// src/cli/invocation.ts
-function invocation(env = process.env) {
-  return env["npm_command"] === "exec" ? "npx -y @modootoday/pmcp" : "pmcp";
-}
-
 // src/remote/session.ts
 import {
   chmodSync,
   closeSync,
   fchmodSync,
-  mkdirSync,
+  mkdirSync as mkdirSync2,
   openSync,
   readFileSync,
   rmSync,
@@ -609,7 +838,7 @@ function readSession(home) {
 function writeSession(session, home) {
   const path = sessionPath(home);
   const directory = globalDir(home);
-  mkdirSync(directory, { recursive: true, mode: 448 });
+  mkdirSync2(directory, { recursive: true, mode: 448 });
   chmodSync(directory, 448);
   const fd = openSync(path, "w", 384);
   try {
@@ -655,7 +884,7 @@ var DEFAULT_RESOURCE = "https://api.pmcp.build";
 var DEFAULT_SCOPE = "pmcp:catalog:read pmcp:distribution:read";
 var fetcher = (url, init) => fetch(url, init);
 var setting = (env, name, fallback) => env[name] ?? fallback;
-var wait = (ms) => new Promise((resolve5) => setTimeout(resolve5, ms));
+var wait = (ms) => new Promise((resolve7) => setTimeout(resolve7, ms));
 var loginCommand = {
   name: "login",
   describe: "Sign in on this machine, to obtain skills this project lacks",
@@ -824,7 +1053,7 @@ function sayStanding(context, line) {
 
 // src/installed.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { dirname, join as join2, resolve } from "path";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 function object(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -845,7 +1074,7 @@ function locate(name, project2) {
       );
     } catch (error) {
       if (!absent(error)) return { name, reason: "unreadable_manifest" };
-      const parent = dirname(directory);
+      const parent = dirname2(directory);
       if (parent === directory) return { name, reason: "not_installed" };
       directory = parent;
       continue;
@@ -867,7 +1096,7 @@ function locate(name, project2) {
   }
 }
 function readInstalledDependencies(projectDirectory) {
-  const project2 = resolve(projectDirectory);
+  const project2 = resolve2(projectDirectory);
   const manifest = JSON.parse(
     readFileSync2(join2(project2, "package.json"), "utf8")
   );
@@ -902,8 +1131,8 @@ function readInstalledDependencies(projectDirectory) {
 
 // src/install/plan.ts
 import { createHash } from "crypto";
-import { existsSync, readFileSync as readFileSync3 } from "fs";
-import { dirname as dirname2, join as join3, relative, resolve as resolve2, sep } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname3, join as join3, relative, resolve as resolve3, sep } from "path";
 import semver from "semver";
 function matchingSkills(catalog, inventory) {
   const matches = [];
@@ -955,25 +1184,25 @@ function manifestAt(directory) {
   return value;
 }
 function installContext(directory) {
-  const project2 = resolve2(directory);
+  const project2 = resolve3(directory);
   const manifest = manifestAt(project2);
   let root = project2;
   let ancestor = project2;
   for (; ; ) {
-    if (ancestor !== project2 && existsSync(join3(ancestor, "package.json"))) {
+    if (ancestor !== project2 && existsSync2(join3(ancestor, "package.json"))) {
       const candidate = manifestAt(ancestor);
       if (candidate.workspaces !== void 0) {
         root = ancestor;
         break;
       }
-      if (LOCKS.some((file) => existsSync(join3(ancestor, file)))) break;
+      if (LOCKS.some((file) => existsSync2(join3(ancestor, file)))) break;
     }
-    if (existsSync(join3(ancestor, ".git")) || dirname2(ancestor) === ancestor)
+    if (existsSync2(join3(ancestor, ".git")) || dirname3(ancestor) === ancestor)
       break;
-    ancestor = dirname2(ancestor);
+    ancestor = dirname3(ancestor);
   }
   const owner = manifestAt(root);
-  const lockNames = LOCKS.filter((file) => existsSync(join3(root, file)));
+  const lockNames = LOCKS.filter((file) => existsSync2(join3(root, file)));
   const lockManagers = new Set(
     lockNames.map((file) => {
       if (file.startsWith("bun.")) return "bun";
@@ -997,7 +1226,7 @@ function installContext(directory) {
     throw new Error(
       "declare packageManager or install project dependencies first"
     );
-  if (root !== project2 && LOCKS.some((file) => existsSync(join3(project2, file)))) {
+  if (root !== project2 && LOCKS.some((file) => existsSync2(join3(project2, file)))) {
     throw new Error(
       "nested project has its own lockfile; resolve the workspace boundary first"
     );
@@ -1114,7 +1343,7 @@ function planInstall(options) {
 }
 
 // src/commands/remote-options.ts
-import { resolve as resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 
 // src/remote/catalog.ts
 import { readFileSync as readFileSync5, statSync } from "fs";
@@ -1122,7 +1351,7 @@ import semver2 from "semver";
 import { z } from "zod";
 
 // src/remote/catalog-cache.ts
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync4, renameSync, writeFileSync } from "fs";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, renameSync, writeFileSync } from "fs";
 import { join as join4 } from "path";
 var MAX_CACHE_BYTES = 8 * 1024 * 1024;
 function memoryCatalogCache() {
@@ -1156,7 +1385,7 @@ function fileCatalogCache(dir) {
     write(origin, entry2) {
       try {
         if (entry2.body.length > MAX_CACHE_BYTES) return;
-        mkdirSync2(dir, { recursive: true });
+        mkdirSync3(dir, { recursive: true });
         const temporary = `${path}.${String(process.pid)}`;
         writeFileSync(
           temporary,
@@ -1347,7 +1576,7 @@ var REMOTE_OPTIONS = [
   { name: "json", describe: "Print machine-readable results.", boolean: true }
 ];
 function projectFrom(context) {
-  return resolve3(context.cwd, one(context.args, "project") ?? ".");
+  return resolve4(context.cwd, one(context.args, "project") ?? ".");
 }
 function apiOrigin(context) {
   return one(context.args, "api") ?? context.env["PMCP_API_ORIGIN"] ?? DEFAULT_API_ORIGIN;
@@ -1357,7 +1586,7 @@ async function remoteCatalog(context) {
   if (file) {
     if (one(context.args, "api"))
       throw new Error("choose --catalog or --api, not both");
-    return readCatalogFile(resolve3(context.cwd, file));
+    return readCatalogFile(resolve4(context.cwd, file));
   }
   return fetchCatalog(apiOrigin(context), fetch, fileCatalogCache(globalDir()));
 }
@@ -1582,7 +1811,7 @@ function applyInstallPlan(plan, runner = packageManagerRunner) {
 // src/install/verify-content.ts
 import { createHash as createHash2 } from "crypto";
 import { readdirSync, readFileSync as readFileSync6, statSync as statSync2 } from "fs";
-import { join as join5, relative as relative2, resolve as resolve4, sep as sep2 } from "path";
+import { join as join5, relative as relative2, resolve as resolve5, sep as sep2 } from "path";
 var SKILL = "SKILL.md";
 var SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", ".cache"]);
 function skillFiles(root) {
@@ -1623,7 +1852,7 @@ function contentDigest(files) {
   return `sha256:${hash.digest("hex")}`;
 }
 function verifyInstalledContent(project2, packageName2, expected) {
-  const root = resolve4(project2, "node_modules", ...packageName2.split("/"));
+  const root = resolve5(project2, "node_modules", ...packageName2.split("/"));
   const files = skillFiles(root);
   const actual = contentDigest(files);
   return {
@@ -2005,14 +2234,14 @@ import { homedir as homedir2 } from "os";
 // src/project/edit.ts
 import {
   cpSync,
-  existsSync as existsSync2,
-  mkdirSync as mkdirSync3,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync4,
   readFileSync as readFileSync7,
   rmSync as rmSync3,
   statSync as statSync3,
   writeFileSync as writeFileSync3
 } from "fs";
-import { basename, dirname as dirname3, join as join7 } from "path";
+import { basename, dirname as dirname4, join as join7 } from "path";
 var CROSS_TOOL = ["name", "description"];
 var tomlValue = (value) => JSON.stringify(value);
 function findEntry(entries, wanted) {
@@ -2045,14 +2274,14 @@ function addEntry(root, entry2) {
   }
   if (kind === "skill") {
     const dest2 = join7(root, ".agents/skills", name);
-    if (existsSync2(dest2))
+    if (existsSync3(dest2))
       throw new ProjectError(`.agents/skills/${name} already exists`);
-    const source = entry2.root ?? dirname3(entry2.path);
-    mkdirSync3(dirname3(dest2), { recursive: true });
+    const source = entry2.root ?? dirname4(entry2.path);
+    mkdirSync4(dirname4(dest2), { recursive: true });
     if (statSync3(source).isDirectory()) {
       cpSync(source, dest2, { recursive: true });
     } else {
-      mkdirSync3(dest2);
+      mkdirSync4(dest2);
     }
     const head = renderFrontmatter({
       ...meta,
@@ -2067,7 +2296,7 @@ ${body.replace(/^\n/u, "")}`
     return { kind, name, path: `.agents/skills/${name}` };
   }
   const dest = join7(root, ".agents/agents", name);
-  if (existsSync2(dest))
+  if (existsSync3(dest))
     throw new ProjectError(`.agents/agents/${name} already exists`);
   const kept = {};
   const moved = {};
@@ -2075,7 +2304,7 @@ ${body.replace(/^\n/u, "")}`
     if (CROSS_TOOL.includes(key)) kept[key] = value;
     else moved[key] = value;
   }
-  mkdirSync3(dest, { recursive: true });
+  mkdirSync4(dest, { recursive: true });
   writeFileSync3(
     join7(dest, "agent.md"),
     `${renderFrontmatter(kept)}
@@ -2087,7 +2316,7 @@ ${body.replace(/^\n/u, "")}`
       `[agents.${name}.claude]`,
       ...Object.entries(moved).map(([k, v]) => `${k} = ${tomlValue(v)}`)
     ];
-    const before = existsSync2(config) ? readFileSync7(config, "utf8") : "";
+    const before = existsSync3(config) ? readFileSync7(config, "utf8") : "";
     const sep3 = before === "" || before.endsWith("\n\n") ? "" : "\n";
     writeFileSync3(config, `${before}${sep3}${lines.join("\n")}
 `);
@@ -2110,14 +2339,14 @@ function withoutTables(toml, name) {
 function removeAsset(root, name) {
   const removed = [];
   for (const rel of [`.agents/skills/${name}`, `.agents/agents/${name}`]) {
-    if (!existsSync2(join7(root, rel))) continue;
+    if (!existsSync3(join7(root, rel))) continue;
     rmSync3(join7(root, rel), { recursive: true, force: true });
     removed.push(rel);
   }
   if (removed.length === 0)
     throw new ProjectError(`no skill or agent named ${name} in .agents/`);
   const config = join7(root, "pmcp.toml");
-  if (existsSync2(config)) {
+  if (existsSync3(config)) {
     const before = readFileSync7(config, "utf8");
     const after = withoutTables(before, name);
     if (after !== before) writeFileSync3(config, after);
@@ -2287,11 +2516,214 @@ var validateCommand = {
   }
 };
 
+// src/commands/mailbox.ts
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { resolve as resolve6 } from "path";
+var allowed = {
+  init: ["config", "state-dir"],
+  actor: ["config", "actor", "actor-file", "parent-binding"],
+  rotate: ["config", "actor", "actor-file", "operator"],
+  send: ["config", "actor-file", "binding-file", "input"],
+  inbox: ["config", "actor-file", "binding-file", "input"],
+  read: ["config", "actor-file", "binding-file", "input"],
+  ack: ["config", "actor-file", "binding-file", "input"],
+  sessions: ["config", "actor-file", "binding-file"],
+  export: ["config", "operator", "output", "scope-actor"],
+  backup: ["config", "operator", "output"],
+  restore: ["config", "operator", "input", "output"]
+};
+function required(context, name) {
+  const value = one(context.args, name);
+  if (!value) throw new ArgumentError(`Provide --${name}`);
+  return value;
+}
+var mailboxCommand = {
+  name: "mailbox",
+  describe: "Manage opt-in local peer mail and launcher credentials",
+  usage: "pmcp mailbox operation [--config <file>] [options]",
+  options: [
+    { name: "config", describe: "Project pmcp.toml", placeholder: "<file>" },
+    {
+      name: "state-dir",
+      describe: "Private mailbox state directory",
+      placeholder: "<dir>"
+    },
+    { name: "actor", describe: "Registered actor ID", placeholder: "<id>" },
+    {
+      name: "actor-file",
+      describe: "Private actor credential file",
+      placeholder: "<file>"
+    },
+    {
+      name: "binding-file",
+      describe: "Private existing attachment file",
+      placeholder: "<file>"
+    },
+    {
+      name: "parent-binding",
+      describe: "Live parent attachment for bounded child delegation",
+      placeholder: "<file>"
+    },
+    {
+      name: "input",
+      describe: "Operation input JSON or backup source",
+      placeholder: "<file>"
+    },
+    {
+      name: "output",
+      describe: "New export or backup destination",
+      placeholder: "<file>"
+    },
+    {
+      name: "scope-actor",
+      describe: "Limit export to one actor's correspondence",
+      placeholder: "<id>"
+    },
+    {
+      name: "operator",
+      describe: "Explicit local administrator intent",
+      boolean: true
+    }
+  ],
+  async run(context) {
+    const [verb, ...extra] = context.args.positional;
+    const supported = verb ? allowed[verb] : void 0;
+    if (!supported || extra.length > 0)
+      throw new ArgumentError("Provide one supported mailbox operation");
+    for (const key of [...context.args.options.keys(), ...context.args.flags]) {
+      if (!supported.includes(key))
+        throw new ArgumentError(`--${key} is not supported by mailbox ${verb}`);
+    }
+    if (verb === "init") {
+      const config2 = initializeMailboxConfig(
+        resolve6(context.cwd, one(context.args, "config") ?? "pmcp.toml"),
+        one(context.args, "state-dir")
+      );
+      const store2 = await MailboxStore.open(config2);
+      await store2.close();
+      context.ui.data(
+        `${JSON.stringify({ ok: true, data: { projectId: config2.projectId } })}
+`
+      );
+      return 0;
+    }
+    const project2 = configFrom(context);
+    const config = project2 ? mailboxConfigFrom(project2, context.env) : void 0;
+    if (!config?.enabled)
+      throw new MailboxError(
+        "mailbox_disabled",
+        "Enable [mailbox] in pmcp.toml first"
+      );
+    if (["export", "backup", "restore", "rotate"].includes(verb)) {
+      if (!context.args.flags.has("operator"))
+        throw new ArgumentError("Provide --operator for local administration");
+    }
+    if (verb === "restore") {
+      await restoreBackup(required(context, "input"), {
+        ...config,
+        databasePath: resolve6(context.cwd, required(context, "output"))
+      });
+      context.ui.data(
+        `${JSON.stringify({ ok: true, data: { restored: true } })}
+`
+      );
+      return 0;
+    }
+    const store = await MailboxStore.open(config);
+    let binding;
+    let ownsBinding = false;
+    try {
+      if (verb === "actor") {
+        const parentFile = one(context.args, "parent-binding");
+        const parent = parentFile ? readBinding(parentFile) : void 0;
+        const destination = required(context, "actor-file");
+        const credential2 = await store.registerActor(
+          required(context, "actor"),
+          parent?.actorId,
+          (value) => writePrivateJson(destination, value),
+          6e4,
+          parent
+        );
+        context.ui.data(
+          `${JSON.stringify({ ok: true, data: { actorId: credential2.actorId } })}
+`
+        );
+        return 0;
+      }
+      if (verb === "rotate") {
+        const destination = required(context, "actor-file");
+        const credential2 = await store.rotateActor(
+          required(context, "actor"),
+          (value) => writePrivateJson(destination, value)
+        );
+        context.ui.data(
+          `${JSON.stringify({ ok: true, data: { actorId: credential2.actorId } })}
+`
+        );
+        return 0;
+      }
+      if (verb === "backup" || verb === "export") {
+        const destination = required(context, "output");
+        if (verb === "backup") {
+          await store.backup(destination);
+        } else {
+          const records = await store.exportRecords(
+            one(context.args, "scope-actor")
+          );
+          writeFileSync4(
+            destination,
+            `${records.map((record) => JSON.stringify(record)).join("\n")}
+`,
+            { flag: "wx", mode: 384 }
+          );
+        }
+        context.ui.data(
+          `${JSON.stringify({ ok: true, data: { completed: verb } })}
+`
+        );
+        return 0;
+      }
+      const operation = operationSchema.parse(verb);
+      const actorFile = one(context.args, "actor-file");
+      const bindingFile = one(context.args, "binding-file");
+      if (Boolean(actorFile) === Boolean(bindingFile))
+        throw new ArgumentError("Choose one --actor-file or --binding-file");
+      if (bindingFile) {
+        binding = readBinding(bindingFile);
+      } else {
+        binding = await store.attach(readCredential(actorFile), "operator");
+        ownsBinding = true;
+      }
+      const inputFile = one(context.args, "input");
+      const input = inputFile ? JSON.parse(readFileSync8(inputFile, "utf8")) : {};
+      const result = await new MailboxService(store, binding).call(
+        operation,
+        input
+      );
+      context.ui.data(`${JSON.stringify(result)}
+`);
+      return result.ok ? 0 : 1;
+    } catch (error) {
+      if (error instanceof ArgumentError) throw error;
+      context.ui.data(`${JSON.stringify(failure(error))}
+`);
+      return 1;
+    } finally {
+      try {
+        if (ownsBinding && binding) await store.detach(binding);
+      } finally {
+        await store.close();
+      }
+    }
+  }
+};
+
 // src/commands/index.ts
 var COMMANDS = [
   serveCommand,
   listCommand,
   indexCommand,
+  modelsCommand,
   loginCommand,
   logoutCommand,
   whoamiCommand,
@@ -2301,7 +2733,8 @@ var COMMANDS = [
   syncCommand,
   projectCommand,
   doctorCommand,
-  validateCommand
+  validateCommand,
+  mailboxCommand
 ];
 var PLANNED = [];
 var GLOBAL = /* @__PURE__ */ new Set(["-q", "--quiet", "--no-color", "--color"]);
@@ -2347,7 +2780,7 @@ function dispatch(argv, options = {}) {
   }
   return run(command, rest, { ui, env, cwd });
 }
-var VERSION = "0.9.1";
+var VERSION = "0.10.0";
 async function run(command, argv, context) {
   try {
     return await command.run({