@modootoday/pmcp 0.9.1 → 0.10.0

package/dist/service-qpCsOXkQ.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+
+declare const operationSchema: z.ZodEnum<{
+    read: "read";
+    send: "send";
+    inbox: "inbox";
+    ack: "ack";
+    sessions: "sessions";
+}>;
+type MailboxOperation = z.output<typeof operationSchema>;
+declare const sessionsSchema: z.ZodObject<{}, z.core.$strict>;
+declare const sendSchema: z.ZodObject<{
+    recipients: z.ZodArray<z.ZodObject<{
+        actorId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodUUID>;
+    }, z.core.$strict>>;
+    body: z.ZodString;
+    idempotencyKey: z.ZodString;
+    replyToId: z.ZodOptional<z.ZodUUID>;
+}, z.core.$strict>;
+declare const inboxSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    state: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        unread: "unread";
+        unacknowledged: "unacknowledged";
+    }>>;
+    threadId: z.ZodOptional<z.ZodUUID>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const messageSchema: z.ZodObject<{
+    messageId: z.ZodUUID;
+}, z.core.$strict>;
+
+type SqlValue = string | number | null;
+type Row = Record<string, unknown>;
+interface Database {
+    exec(sql: string): void;
+    get(sql: string, ...values: SqlValue[]): Row | undefined;
+    all(sql: string, ...values: SqlValue[]): Row[];
+    run(sql: string, ...values: SqlValue[]): void;
+    close(): void;
+}
+interface ActorCredential {
+    projectId: string;
+    actorId: string;
+    secret: string;
+}
+interface Binding {
+    projectId: string;
+    actorId: string;
+    sessionId: string;
+    generation: number;
+    secret: string;
+}
+interface MailboxConfig {
+    projectId: string;
+    databasePath: string;
+    enabled: boolean;
+}
+type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+};
+declare class MailboxError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(code: string, message: string, retryable?: boolean);
+}
+declare function failure(error: unknown): Result<never>;
+
+declare const PRESENCE_TTL_MS = 120000;
+declare const HEARTBEAT_INTERVAL_MS = 30000;
+declare class MailboxStore {
+    private pending;
+    private closed;
+    readonly config: MailboxConfig;
+    readonly database: Database;
+    readonly now: () => number;
+    private constructor();
+    static open(config: MailboxConfig, now?: () => number): Promise<MailboxStore>;
+    checkSchema(): void;
+    run<T>(operation: () => T, write?: boolean): Promise<T>;
+    registerActor(actorId: string, parentActorId?: string, persist?: (credential: ActorCredential) => void, authorityTtlMs?: number, parentBinding?: Binding): Promise<ActorCredential>;
+    registerChild(parent: Binding, actorId: string, ttlMs?: number): Promise<ActorCredential>;
+    attach(credential: ActorCredential, runtime: string, replaceSessionId?: string, nativeSessionId?: string): Promise<Binding>;
+    assertBinding(binding: Binding): Row;
+    rotateActor(actorId: string, persist?: (credential: ActorCredential) => void): Promise<ActorCredential>;
+    heartbeat(binding: Binding): Promise<void>;
+    detach(binding: Binding): Promise<void>;
+    exportRecords(actorId?: string): Promise<object[]>;
+    backup(destination: string): Promise<void>;
+    close(): Promise<void>;
+}
+declare function restoreBackup(source: string, config: MailboxConfig): Promise<void>;
+
+declare class MailboxService {
+    readonly store: MailboxStore;
+    readonly binding: Binding;
+    constructor(store: MailboxStore, binding: Binding);
+    call(operation: MailboxOperation, input: unknown): Promise<Result<object>>;
+    private send;
+    private visibleMessage;
+    private inbox;
+    private receipt;
+    private sessions;
+}
+
+export { type ActorCredential as A, type Binding as B, HEARTBEAT_INTERVAL_MS as H, MailboxService as M, PRESENCE_TTL_MS as P, type Row as R, type MailboxConfig as a, MailboxStore as b, MailboxError as c, type MailboxOperation as d, type Result as e, failure as f, sessionsSchema as g, inboxSchema as i, messageSchema as m, operationSchema as o, restoreBackup as r, sendSchema as s };

package/dist/stdio.d.ts

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
-import { C as CatalogOptions } from './catalog-BU5VLLyd.js';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { S as SkillServerOptions, C as CatalogOptions } from './server-CwWcRjqz.js';
+import { M as MailboxService } from './service-qpCsOXkQ.js';
+import { M as MailboxAttachmentOptions } from './attachment-tU5FZrgZ.js';
+import 'zod';
 
 /**
  * The stdio entry a host launches.
@@ -11,11 +15,13 @@ import { C as CatalogOptions } from './catalog-BU5VLLyd.js';
 
 /** `node_modules` roots to walk, from argv or from the working directory. */
 declare function resolveRoots(argv: readonly string[], cwd: string): string[];
-interface ServeOptions {
+interface ServeOptions extends Pick<SkillServerOptions, "embedder" | "vectors" | "loadCatalog"> {
+    readonly mailbox?: MailboxService;
     /** One prompt per skill, for hosts that offer prompts as commands. */
     readonly prompts?: boolean;
 }
-declare function serve(catalog: CatalogOptions, serving?: ServeOptions): void;
+declare function serve(catalog: CatalogOptions, serving?: ServeOptions): ReturnType<typeof serveStdio>;
+declare function serveWithMailbox(catalog: CatalogOptions, mailbox: MailboxAttachmentOptions, serving?: ServeOptions): Promise<() => Promise<void>>;
 declare function main(argv?: readonly string[]): void;
 
-export { type ServeOptions, main, resolveRoots, serve };
+export { type ServeOptions, main, resolveRoots, serve, serveWithMailbox };

package/dist/stdio.js

@@ -2,12 +2,17 @@
 import {
   main,
   resolveRoots,
-  serve
-} from "./chunk-AJYMOFVX.js";
-import "./chunk-VQHNG3KM.js";
+  serve,
+  serveWithMailbox
+} from "./chunk-JRSR4JBR.js";
+import "./chunk-VRZFM2M5.js";
+import "./chunk-HNAVQG6R.js";
+import "./chunk-MSTKY33C.js";
+import "./chunk-XOH2CW6P.js";
 export {
   main,
   resolveRoots,
-  serve
+  serve,
+  serveWithMailbox
 };
 //# sourceMappingURL=stdio.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modootoday/pmcp",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "license": "Elastic-2.0",
   "author": "modootoday",
   "description": "An MCP server that finds the skills your installed packages already ship. Reads SKILL.md out of node_modules by shape rather than by path, so it sees the skills, .agent, .claude, .gemini and .codex conventions alike, and keeps session startup flat as the number of installed skills grows.",
@@ -44,6 +44,10 @@
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
+    },
+    "./mailbox": {
+      "types": "./dist/mailbox/index.d.ts",
+      "import": "./dist/mailbox/index.js"
     }
   },
   "bin": {

package/dist/catalog-BU5VLLyd.d.ts

@@ -1,121 +0,0 @@
-/**
- * SKILL.md frontmatter, read as YAML the way a host reads it, and checked against
- * the Agent Skills specification (https://agentskills.io/specification).
- */
-type MetadataLeaf = string | readonly string[];
-/** A metadata value: a leaf, or a map of leaves one level below the metadata key. */
-type MetadataValue = MetadataLeaf | {
-    readonly [key: string]: MetadataLeaf;
-};
-/**
- * Parsed frontmatter. A value with an unquoted ": " is a common authoring slip
- * the client guide says to recover from by quoting it, so that is retried once.
- */
-declare function frontmatterObject(source: string): Record<string, unknown> | null;
-declare const NAME_MAX = 64;
-declare const DESCRIPTION_MAX = 1024;
-declare const COMPATIBILITY_MAX = 500;
-/**
- * What the specification requires of one SKILL.md, as messages; empty when valid.
- * directory is the name of the folder holding it.
- */
-declare function specProblems(front: Record<string, unknown> | null, directory: string): string[];
-
-/**
- * The skills the installed packages brought with them.
- *
- * Derived from `node_modules` at read time rather than from a list somebody
- * maintains: installing a package is how its skill arrives and uninstalling it
- * is how the skill leaves, so the catalog is always true of the project.
- */
-
-interface SkillEntry {
-    /** `<package>/<slug>`. Unique, and stable while the package is installed. */
-    readonly name: string;
-    readonly package: string;
-    readonly slug: string;
-    /** Frontmatter description. The only text `find` ranks against. */
-    readonly description: string;
-    /** Absolute path to the SKILL.md. `call` reads the body from here. */
-    readonly path: string;
-    /** open, free or paid. Set for marketplace skills, absent for packages. */
-    readonly tier?: string;
-    /** The frontmatter `metadata:` block; maps such as `requires` are kept one level down. */
-    readonly metadata?: Readonly<Record<string, MetadataValue>>;
-    /** Extra search terms. Ranked with the description, never used as triggers. */
-    readonly keywords?: readonly string[];
-    /** What the entry is. Absent means a skill. */
-    readonly kind?: AssetKind;
-    /**
-     * What describe and read may open: a directory, or one file for an asset
-     * that is a single file. Absent means the directory holding `path`.
-     */
-    readonly root?: string;
-}
-/** Everything the catalog serves. Commands are skills; workflows have no kind of their own. */
-declare const ASSET_KINDS: readonly ["skill", "agent", "hook", "mcp"];
-type AssetKind = (typeof ASSET_KINDS)[number];
-declare const kindOf: (entry: Pick<SkillEntry, "kind">) => AssetKind;
-interface CatalogOptions {
-    /** Directories to walk. Each is a `node_modules` root, not a package root. */
-    readonly roots: readonly string[];
-    /** Package name prefixes to consider. Empty means every package. */
-    readonly scopes?: readonly string[];
-    /** Marketplace directories, each holding .claude-plugin/marketplace.json. */
-    readonly marketplaces?: readonly string[];
-    /** Package directories read directly, for a package no node_modules links. */
-    readonly packages?: readonly string[];
-    /** Workspace roots: the root and every member its workspaces globs name. */
-    readonly workspaces?: readonly string[];
-    /** Told about every marketplace skill left out, and why. */
-    readonly onReject?: (rejection: {
-        path: string;
-        reason: string;
-    }) => void;
-    /**
-     * Told about a skill that is served but breaks the Agent Skills specification,
-     * or that lost a name collision. Loading stays lenient, as the client guide asks.
-     */
-    readonly onWarning?: (warning: {
-        path: string;
-        reason: string;
-    }) => void;
-}
-/**
- * Directories a walk does not enter. Kept as short as the evidence allows: a
- * name here is a package whose skill will never be found, and the cost of one
- * extra readdir is far below the cost of missing a skill. Measured 20260906 --
- * `lib` was on this list and hid playwright's `lib/skill/SKILL.md`, which is
- * the most widely installed skill in the real world.
- */
-declare const SKIPPED_DIRS: ReadonlySet<string>;
-/**
- * How deep below a package root a SKILL.md is looked for. Three reaches every
- * convention in use (skills, .agent/skills, .claude/skills, .gemini/skills,
- * .codex/skills); four was measured to find nothing more.
- */
-declare const MAX_SKILL_DEPTH = 3;
-/**
- * Top-level scalar fields of a SKILL.md frontmatter, parsed as YAML, so a folded
- * `description: >-` arrives as its text rather than as the indicator.
- */
-declare function readFrontmatter(source: string): Record<string, string>;
-/** The body after the frontmatter, or the whole file when there is none. */
-declare function readBody(source: string): string;
-/**
- * Every skill reachable from the given roots, sorted by name.
- *
- * A package with no skills directory contributes nothing and costs one
- * `existsSync` per convention. A skill with no description is skipped rather
- * than listed:
- * `find` ranks descriptions, so one without a description can only ever be
- * found by already knowing its name, and listing it would spend a session's
- * tokens on an entry that cannot answer.
- */
-declare function readCatalog(options: CatalogOptions): SkillEntry[];
-/** A catalog entry without its body, which is what `catalog` returns. */
-declare function withoutBody({ path, ...rest }: SkillEntry): Omit<SkillEntry, "path">;
-/** Path relative to a root, for a message a reader can act on. */
-declare function displayPath(root: string, entry: SkillEntry): string;
-
-export { type AssetKind as A, type CatalogOptions as C, DESCRIPTION_MAX as D, type MetadataValue as M, NAME_MAX as N, type SkillEntry as S, ASSET_KINDS as a, COMPATIBILITY_MAX as b, MAX_SKILL_DEPTH as c, type MetadataLeaf as d, SKIPPED_DIRS as e, displayPath as f, frontmatterObject as g, readCatalog as h, readFrontmatter as i, kindOf as k, readBody as r, specProblems as s, withoutBody as w };

package/dist/chunk-7DD2ADL2.js

@@ -1,160 +0,0 @@
-import {
-  openDatabase
-} from "./chunk-R2QPKEI4.js";
-
-// src/embed.ts
-var DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
-var PLAIN = {
-  queryPrefix: "",
-  passagePrefix: "",
-  pooling: "mean"
-};
-var E5 = {
-  queryPrefix: "query: ",
-  passagePrefix: "passage: ",
-  pooling: "mean"
-};
-var KNOWN_ENCODERS = {
-  "Xenova/multilingual-e5-small": E5,
-  "Xenova/multilingual-e5-base": E5,
-  "Xenova/multilingual-e5-large": E5,
-  "Xenova/bge-m3": { ...PLAIN, pooling: "cls" }
-};
-function encoderSpec(modelId) {
-  return KNOWN_ENCODERS[modelId] ?? PLAIN;
-}
-var ENTRY_SCHEMA = `
-  CREATE TABLE IF NOT EXISTS entry_vector (
-    name TEXT NOT NULL,
-    model_id TEXT NOT NULL,
-    dims INTEGER NOT NULL,
-    description_hash TEXT NOT NULL,
-    vector BLOB NOT NULL,
-    PRIMARY KEY (name, model_id)
-  );
-`;
-var TRANSFORMERS = "@huggingface/transformers";
-async function loadEmbedder(modelId = DEFAULT_MODEL_ID, options = {}) {
-  let module;
-  try {
-    module = options.module ?? await import(TRANSFORMERS);
-  } catch {
-    return null;
-  }
-  const factory = module.pipeline;
-  if (typeof factory !== "function") return null;
-  if (module.env) {
-    if (options.cacheDir !== void 0)
-      module.env["cacheDir"] = options.cacheDir;
-    if (options.localOnly) module.env["allowRemoteModels"] = false;
-  }
-  const encode = await factory("feature-extraction", modelId, {
-    dtype: options.dtype ?? "q8"
-  });
-  const spec = encoderSpec(modelId);
-  let dims = 0;
-  const run = async (text) => {
-    const output = await encode(text, {
-      pooling: spec.pooling,
-      normalize: true
-    });
-    const vector = Float32Array.from(output.data);
-    dims = vector.length;
-    return vector;
-  };
-  return {
-    modelId,
-    get dims() {
-      return dims;
-    },
-    embed: (text) => run(spec.queryPrefix + text),
-    embedPassage: (text) => run(spec.passagePrefix + text)
-  };
-}
-async function encodeEntries(embedder, entries, previous = /* @__PURE__ */ new Map()) {
-  const out = /* @__PURE__ */ new Map();
-  const passage = (text) => embedder.embedPassage ? embedder.embedPassage(text) : embedder.embed(text);
-  for (const entry of entries) {
-    const hash = describeHash(entry.description);
-    const kept = previous.get(entry.name);
-    if (kept && kept.hash === hash) {
-      out.set(entry.name, kept);
-      continue;
-    }
-    out.set(entry.name, { hash, vector: await passage(entry.description) });
-  }
-  return out;
-}
-function describeHash(description) {
-  let hash = 2166136261;
-  for (let i = 0; i < description.length; i++) {
-    hash ^= description.charCodeAt(i);
-    hash = Math.imul(hash, 16777619) >>> 0;
-  }
-  return hash.toString(16).padStart(8, "0");
-}
-async function openEntryVectors(path) {
-  const opened = await openDatabase(path);
-  if (opened === null) return null;
-  const db = opened.db;
-  db.exec(ENTRY_SCHEMA);
-  return {
-    read(modelId) {
-      const out = /* @__PURE__ */ new Map();
-      const rows = db.prepare(
-        "SELECT name, dims, vector FROM entry_vector WHERE model_id = ?"
-      ).all(modelId);
-      for (const row of rows) {
-        const bytes = row.vector;
-        const vector = new Float32Array(
-          bytes.buffer.slice(
-            bytes.byteOffset,
-            bytes.byteOffset + bytes.byteLength
-          )
-        );
-        if (vector.length === row.dims) out.set(row.name, vector);
-      }
-      return out;
-    },
-    stale(modelId, entries) {
-      const rows = db.prepare(
-        "SELECT name, description_hash FROM entry_vector WHERE model_id = ?"
-      ).all(modelId);
-      const stored = new Map(
-        rows.map((row) => [row.name, row.description_hash])
-      );
-      const out = [];
-      for (const [name, description] of entries) {
-        if (stored.get(name) !== describeHash(description)) out.push(name);
-      }
-      return out;
-    },
-    write(modelId, name, description, vector) {
-      db.prepare(
-        `INSERT INTO entry_vector (name, model_id, dims, description_hash, vector)
-         VALUES (?, ?, ?, ?, ?)
-         ON CONFLICT(name, model_id) DO UPDATE SET
-           dims = excluded.dims,
-           description_hash = excluded.description_hash,
-           vector = excluded.vector`
-      ).run(
-        name,
-        modelId,
-        vector.length,
-        describeHash(description),
-        new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength)
-      );
-    },
-    close() {
-      db.close();
-    }
-  };
-}
-
-export {
-  DEFAULT_MODEL_ID,
-  loadEmbedder,
-  encodeEntries,
-  openEntryVectors
-};
-//# sourceMappingURL=chunk-7DD2ADL2.js.map

package/dist/chunk-AJYMOFVX.js

@@ -1,41 +0,0 @@
-import {
-  createSkillServer
-} from "./chunk-VQHNG3KM.js";
-
-// src/stdio.ts
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
-function resolveRoots(argv, cwd) {
-  const given = argv.filter((arg) => !arg.startsWith("-"));
-  return given.length > 0 ? given : [`${cwd}/node_modules`];
-}
-function serve(catalog, serving = {}) {
-  const options = {
-    ...catalog,
-    ...serving,
-    onReject: ({ path, reason }) => process.stderr.write(`pmcp: skipped ${path}: ${reason}
-`),
-    onWarning: ({ path, reason }) => process.stderr.write(`pmcp: warning ${path}: ${reason}
-`)
-  };
-  serveStdio(() => createSkillServer(options), {
-    // stdout is the protocol. A diagnostic written there corrupts the stream,
-    // so out-of-band errors go to stderr and nowhere else.
-    onerror: (error) => process.stderr.write(`pmcp: ${error.message}
-`)
-  });
-}
-function main(argv = process.argv.slice(2)) {
-  const scopeArg = argv.find((arg) => arg.startsWith("--scope="));
-  const scopes = scopeArg ? scopeArg.slice("--scope=".length).split(",") : [];
-  serve({
-    roots: resolveRoots(argv, process.cwd()),
-    ...scopes.length > 0 ? { scopes } : {}
-  });
-}
-
-export {
-  resolveRoots,
-  serve,
-  main
-};
-//# sourceMappingURL=chunk-AJYMOFVX.js.map

package/dist/chunk-R2QPKEI4.js

@@ -1,134 +0,0 @@
-import {
-  normaliseIntent
-} from "./chunk-VQHNG3KM.js";
-
-// src/cache.ts
-async function openDatabase(path) {
-  try {
-    const { DatabaseSync } = await import(`node:${"sqlite"}`);
-    return { db: new DatabaseSync(path), provider: "node:sqlite" };
-  } catch {
-  }
-  try {
-    const { Database } = await import(`bun:${"sqlite"}`);
-    const bun = new Database(path, { create: true });
-    return {
-      db: {
-        exec: (sql) => bun.run(sql),
-        prepare: (sql) => bun.query(sql),
-        close: () => bun.close()
-      },
-      provider: "bun:sqlite"
-    };
-  } catch {
-    return null;
-  }
-}
-var DEFAULT_INTENT_CACHE_LIMIT = 4096;
-var SCHEMA = `
-  CREATE TABLE IF NOT EXISTS intent_vector (
-    intent   TEXT    NOT NULL PRIMARY KEY,
-    model_id TEXT    NOT NULL,
-    dims     INTEGER NOT NULL,
-    vector   BLOB    NOT NULL,
-    used_at  INTEGER NOT NULL
-  );
-  CREATE INDEX IF NOT EXISTS intent_vector_used_at ON intent_vector (used_at);
-`;
-async function openIntentCache(options) {
-  const opened = await openDatabase(options.path);
-  if (!opened) return null;
-  const { db, provider } = opened;
-  try {
-    db.exec("PRAGMA journal_mode = WAL");
-    db.exec(SCHEMA);
-  } catch {
-    db.close();
-    return null;
-  }
-  const limit = options.limit ?? DEFAULT_INTENT_CACHE_LIMIT;
-  const now = options.now ?? (() => Date.now());
-  let hits = 0;
-  let misses = 0;
-  let mismatched = 0;
-  const selectRow = db.prepare("SELECT model_id, dims, vector FROM intent_vector WHERE intent = ?");
-  const touch = db.prepare(
-    "UPDATE intent_vector SET used_at = ? WHERE intent = ?"
-  );
-  const upsert = db.prepare(
-    `INSERT INTO intent_vector (intent, model_id, dims, vector, used_at)
-     VALUES (?, ?, ?, ?, ?)
-     ON CONFLICT(intent) DO UPDATE SET
-       model_id = excluded.model_id,
-       dims     = excluded.dims,
-       vector   = excluded.vector,
-       used_at  = excluded.used_at`
-  );
-  const countRows = db.prepare(
-    "SELECT count(*) AS n FROM intent_vector"
-  );
-  const evict = db.prepare(
-    `DELETE FROM intent_vector WHERE intent IN (
-       SELECT intent FROM intent_vector ORDER BY used_at ASC LIMIT ?
-     )`
-  );
-  return {
-    get(intent) {
-      const key = normaliseIntent(intent);
-      const row = selectRow.get(key) ?? null;
-      if (!row) {
-        misses += 1;
-        return null;
-      }
-      if (row.model_id !== options.modelId || row.dims !== options.dims) {
-        mismatched += 1;
-        return null;
-      }
-      hits += 1;
-      touch.run(now(), key);
-      const bytes = row.vector;
-      return new Float32Array(
-        bytes.buffer.slice(
-          bytes.byteOffset,
-          bytes.byteOffset + bytes.byteLength
-        )
-      );
-    },
-    put(intent, vector) {
-      if (vector.length !== options.dims) {
-        throw new Error(
-          `intent vector is ${vector.length} wide, cache holds ${options.dims}`
-        );
-      }
-      const key = normaliseIntent(intent);
-      upsert.run(
-        key,
-        options.modelId,
-        options.dims,
-        new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength),
-        now()
-      );
-      const rows = countRows.get()?.n ?? 0;
-      if (rows > limit) evict.run(rows - limit);
-    },
-    stats() {
-      return {
-        hits,
-        misses,
-        mismatched,
-        rows: countRows.get()?.n ?? 0,
-        provider
-      };
-    },
-    close() {
-      db.close();
-    }
-  };
-}
-
-export {
-  openDatabase,
-  DEFAULT_INTENT_CACHE_LIMIT,
-  openIntentCache
-};
-//# sourceMappingURL=chunk-R2QPKEI4.js.map