@modootoday/pmcp 0.9.1 → 0.10.0

package/README.md

@@ -142,21 +142,25 @@ breaks the specification is reported, and `pmcp validate [<skill-dir>...]` check
 directories or every skill the catalog reaches (name rules and length, description and
 compatibility length, field types, name matching the directory, duplicate names).
 
-`metadata` keeps strings, string lists and maps of those one level down, so
-`requires: {mcp, bin, env, capabilities, gpu-gb}` reaches `skill_describe`; deeper
-nesting is dropped.
+`metadata` keeps strings, string lists and maps of those one level down; `skill_describe`
+reports a map as dotted keys, so `requires: {mcp, gpu-gb}` arrives as `requires.mcp` and
+`requires.gpu-gb`. Deeper nesting is dropped.
+
+Output schemas accept additional properties, so a field added later does not break a
+client that cached an earlier tool list. An answer to a call without the newer inputs keeps
+the earlier shape.
 
 Since 0.9.0 a skill can list `metadata.verified-runtimes`, a list drawn from `claude-code`,
 `codex-cli`, `gemini-cli`, `grok-cli` and `antigravity`, meaning its effect was verified on
-that runtime. `skill_find` and `skill_catalog` items carry `verifiedRuntimes` (omitted when
-empty) and accept `runtime` and `verifiedOnly`. `runtime` never removes a skill: it marks
+that runtime. `skill_find` and `skill_catalog` accept `runtime` and `verifiedOnly`; when either
+is given, items carry `verifiedRuntimes` (omitted when empty). `runtime` never removes a skill: it marks
 each item `verified` and lists verified ones first (within a package group in
 `skill_catalog`). `verifiedOnly` drops the rest, keeping those verified on `runtime`, or on
 any runtime when none is given. Without `runtime` the answer is ordered exactly as before.
 A server can opt in with `rankByClientRuntime: true`: then, when `runtime` is not passed and
 the MCP client's name is recognised (`claude-code`, `codex`, `gemini`, `grok`,
 `antigravity`), that runtime is used for the ordering only, never for filtering.
-`skill_find` answers with `runtime`, the one the ordering used, or `null`.
+`skill_find` then answers with `runtime`, the one the ordering used, or `null`.
 
 `pmcp serve --prompts` also offers one prompt per skill, for hosts that turn prompts into
 commands; the prompt's text is the skill body and its file list, with an optional `task`.
@@ -219,18 +223,183 @@ An MCP config (`.mcp.json`) is never served as written: every `env` and `headers
 replaced with `<redacted>`, whichever entry reaches the file, and listed digests describe
 the redacted bytes.
 
-Pass `semantic: { cacheDir, localOnly: true }` to rank by meaning: the handler encodes
+Pass `semantic: { modelId: "embeddinggemma-2", cacheDir, localOnly: true }` to rank by meaning: the handler encodes
 the catalog at start with `@huggingface/transformers` and the multilingual model, so an
 intent in one language finds a description in another. Requests rank lexically until
 `ready()` settles, and stay lexical when the encoder cannot load (`onError` says why).
 
+## Optional local mailbox
+
+Mailbox is disabled by default. The six catalog tools stay read-only. A launcher
+that supplies a private actor credential adds five tools: mailbox_send,
+mailbox_inbox, mailbox_read, mailbox_ack, and mailbox_sessions. Read and ack
+record durable receipts; peer text is data and does not authorize execution.
+
+```sh
+pmcp mailbox init --config ./pmcp.toml
+pmcp mailbox actor --config ./pmcp.toml --actor reviewer --actor-file /private/reviewer.actor.json
+pmcp serve --config ./pmcp.toml --mailbox-actor-file /private/reviewer.actor.json --mailbox-runtime codex-cli
+```
+
+Initialization preserves existing configuration and creates a project UUID.
+State defaults to XDG_STATE_HOME/pmcp/projects/<project UUID>, outside the
+repository. Credential and binding files contain secrets: keep them private,
+outside source control and container images. Commands do not print credentials.
+An optional mailbox-binding-file records the current attachment for a trusted
+launcher. Replacement requires the exact mailbox-replace-session ID; stale
+sessions are fenced. Canonical runtimes are codex-cli, claude-code, gemini-cli,
+grok-cli, and antigravity; the Antigravity executable is agy.
+
+The mailbox CLI also supports send, inbox, read, ack, sessions, rotate, export,
+backup, and restore. Actor operations accept a private actor-file or existing
+binding-file and JSON input file. Administration requires explicit operator
+intent. Backups and exports are sensitive. Encrypted recovery bundles are
+available through the mailbox API; key custody belongs to the operator.
+
+```ts
+import { MailboxService, MailboxStore } from "@modootoday/pmcp/mailbox";
+
+const store = await MailboxStore.open({
+  enabled: true,
+  projectId,
+  databasePath,
+});
+const credential = await store.registerActor("reviewer");
+const binding = await store.attach(credential, "codex-cli");
+const mailbox = new MailboxService(store, binding);
+```
+
+Pass mailbox to createSkillServer or registerMailboxTools on an existing server.
+For HTTP, provide mailboxFor(caller) to createSkillHttpHandler; the host resolves
+authenticated callers to authorized bindings. Tool arguments cannot choose a
+sender identity. The host owns attachment heartbeat and cleanup. Child actors
+have bounded authority and may reply only to their parent. Generation changes,
+parent expiry, and credential rotation revoke stale child authority.
+
+The public package contains one reusable local domain. Organization identity,
+fleet policy, enterprise audit retention, native process supervision, provider
+credentials, and automatic runtime input delivery belong to a host or dedicated
+harness. Existing arbitrary terminal sessions are not captured. Elastic License
+2.0 and NOTICE continue to apply.
+
+## Switching embedding models
+
+List the built-in presets with `pmcp models` (or `pmcp models --json`). Select a
+model once in your project's `pmcp.toml`; both indexing and the stdio server use
+the same settings:
+
+```toml
+[embedding]
+model = "embeddinggemma-2"
+dimensions = 256
+cache_dir = ".cache/pmcp/models"
+```
+
+```sh
+pmcp index
+pmcp serve
+```
+
+Indexing explicitly downloads missing model artifacts. Serving reads only local
+artifacts and an existing, complete index. A missing model, stale catalog or
+incompatible vectors keeps ranking lexical and reports the reason on stderr.
+`pmcp index --dry-run` plans work without loading a model or writing files;
+`pmcp index --local-only` refuses downloads. Use `[embedding] enabled = false`
+or `pmcp serve --lexical` to disable semantic ranking.
+
+| Preset                | Default precision | Supported output dimensions |
+| --------------------- | ----------------- | --------------------------- |
+| `e5-small`            | `q8`              | 384                         |
+| `embeddinggemma-300m` | `q4`              | 768, 512, 256, 128          |
+| `embeddinggemma-2`    | `q4`              | 768, 512, 256, 128          |
+
+E5 remains the default. Gemma presets use qualified, pinned revisions, listed by
+`pmcp models --json`; E5 retains its existing `main` revision for compatibility.
+Gemma dimension reduction truncates and re-normalizes the projected embedding;
+it reduces vector storage, not loaded model memory.
+
+CLI flags override individual config fields: `--model`, `--dtype`,
+`--dimensions`, `--model-revision`, `--model-path`, `--model-cache`,
+`--query-prefix`, `--passage-prefix` and `--pooling`. Omit precision and dimensions
+in the file when you want each model's defaults. Use `--no-config` for an
+independent CLI selection. Config paths resolve relative to the TOML file;
+CLI model paths resolve relative to the working directory.
+
+Query caches also include the encoder identity, so sharing a cache between
+same-width profiles cannot reuse another encoder's query vector. Library hosts
+using openIntentCache must open a cache with the selected output width when
+changing dimensions; pass the encoder's indexKey as its modelId for explicit
+profile-scoped cache metadata.
+
+Each model, revision, precision, output width and encoder specification has its
+own vector identity. Switching preserves other models' indexes; switching back
+reuses unchanged vectors. `--force` re-encodes only the selected model. A local
+`model_path` must contain the declared revision's artifacts; change `revision`
+and reindex after replacing them. The directory's location is not its identity.
+
+Custom Transformers.js feature-extraction models need no source edits:
+
+```toml
+[embedding]
+model = "your-organization/your-onnx-model"
+dtype = "q8"
+revision = "your-pinned-revision"
+
+[embedding.encoder]
+query_prefix = "query: "
+passage_prefix = "passage: "
+pooling = "mean"
+```
+
+Use the model's documented prefixes and pooling (`mean` or `cls`); unknown models
+default to unprefixed mean pooling. A native `sentence_embedding` export may use
+`projected = true`. Explicit dimension reduction is supported for the listed
+presets. Other architectures require compatible Transformers.js exports.
+
+The library API shares the same presets and identity rules:
+
+```js
+import { loadEmbedder, prepareSearch } from "@modootoday/pmcp";
+
+const encoder = await loadEmbedder("embeddinggemma-2", {
+  dimensions: 256,
+  modelPath: "/opt/models/embeddinggemma-2",
+  localOnly: true,
+});
+const search = await prepareSearch(
+  { roots: ["node_modules"] },
+  {
+    indexPath: "node_modules/.cache/pmcp/vectors.sqlite",
+    modelId: "embeddinggemma-2",
+    dimensions: 256,
+    embedder: encoder ?? undefined,
+  },
+);
+```
+
+HTTP hosts use these options under `semantic`; HTTP catalogs are encoded in
+memory at startup rather than reading the CLI's persisted index. Model runtime
+settings are passed to each loader without changing global download or cache
+policy, so hosts can prepare different encoders in one process.
+
 ## Runtime and licence
 
-Node.js 22 or later, or Bun 1.3 or later. Default ranking is lexical. Semantic
+Node.js 22 or later, or Bun 1.3 or later. Ranking is lexical until an index and
+encoder are ready. Semantic
 ranking (the `index` command, or the HTTP handler's `semantic` option) needs
 `@huggingface/transformers` installed separately; it is not part of the default
 installation. The default encoder is `Xenova/multilingual-e5-small` (MIT, about
 130 MB), so vectors indexed with the earlier English-only default are re-encoded.
 
+The optional encoder also supports the ONNX Community EmbeddingGemma 300M and
+EmbeddingGemma 2 exports. It uses their projected sentence embeddings and task
+prefixes. EmbeddingGemma 2 loads its text encoder without vision or audio models.
+EmbeddingGemma was qualified with Transformers.js 4.3.1. Install a version
+supporting the chosen export and keep model
+weights outside the npm package. Regenerate document vectors when changing the
+encoder. Quantization reduces weight storage; application RAM and latency need
+workload measurements. EmbeddingGemma 300M uses the Gemma terms; EmbeddingGemma 2
+is listed under Apache-2.0 in its model card.
+
 Elastic License 2.0. See `LICENSE` and `NOTICE` for terms and dependency notices.
 Documentation: <https://pmcp.build>.

package/dist/attachment-tU5FZrgZ.d.ts

@@ -0,0 +1,17 @@
+import { a as MailboxConfig, M as MailboxService } from './service-qpCsOXkQ.js';
+
+interface MailboxAttachmentOptions {
+    readonly config: MailboxConfig;
+    readonly actorFile: string;
+    readonly runtime: string;
+    readonly bindingFile?: string;
+    readonly replaceSessionId?: string;
+    readonly nativeSessionId?: string;
+    readonly onExpired?: () => void;
+}
+declare function attachMailbox(options: MailboxAttachmentOptions): Promise<{
+    service: MailboxService;
+    close: () => Promise<void>;
+}>;
+
+export { type MailboxAttachmentOptions as M, attachMailbox as a };