@modootoday/pmcp 0.9.2 → 0.10.0

package/README.md

@@ -223,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 };