@pyxmate/memory 1.26.6 → 1.27.1

package/dist/mcp-64KVRH7F.mjs

@@ -0,0 +1,944 @@
+import {
+  createHttpClient,
+  mcpJson,
+  mcpKeychainError,
+  mcpMissingCredentials,
+  mcpText,
+  parseRetryAfterMs,
+  parseRetryAfterSeconds
+} from "./chunk-THLUBOGD.mjs";
+import {
+  KeychainError,
+  getDefaultKeychain
+} from "./chunk-7TATCSSN.mjs";
+import "./chunk-6EEEOV6B.mjs";
+import {
+  MCP_ACTOR_META_KEY,
+  normalizeMemoryActorLabel
+} from "./chunk-RWQTBXUC.mjs";
+import {
+  HOSTED_FILE_INGEST_PROTOCOL,
+  HOSTED_FILE_INGEST_RETRYABLE_CODES,
+  parseHostedFileIngestAuthorization,
+  parseHostedFileIngestCommitResult,
+  parseHostedFileIngestJobView,
+  parseHostedFileIngestPublishResult,
+  requireHostedFileIngestFilename
+} from "./chunk-HTQBKJTD.mjs";
+import {
+  syncMemoryRulesFromServer
+} from "./chunk-QR5K7ETI.mjs";
+import "./chunk-QD7G23CN.mjs";
+import {
+  EXIT
+} from "./chunk-4DXEQC6X.mjs";
+
+// src/mcp/credentials.ts
+function createReadCredentials(providerFactory) {
+  return async () => {
+    const provider = providerFactory();
+    try {
+      const creds = await provider.read();
+      if (!creds) return { ok: false, result: mcpMissingCredentials() };
+      return { ok: true, credentials: creds };
+    } catch (err) {
+      if (err instanceof KeychainError) {
+        return { ok: false, result: mcpKeychainError(err.message, err.guidance) };
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      return { ok: false, result: mcpKeychainError(msg, "") };
+    }
+  };
+}
+
+// src/mcp/proxy-server.ts
+import { createHash as createHash2, randomUUID as randomUUID3 } from "crypto";
+import { readFile as readFile2, stat as stat2 } from "fs/promises";
+import { basename as basename2, isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
+import { setTimeout as delay2 } from "timers/promises";
+import { Client as McpClient } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/mcp/file-ingest-intents.ts
+import { randomUUID } from "crypto";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+var DELIVERED_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
+var DEFAULT_FILE_INGEST_INTENT_DIR = join(homedir(), ".pyx-memory", "file-ingests");
+function parseIntent(raw, file) {
+  const value = JSON.parse(raw);
+  const fp = value?.fingerprint;
+  if (value?.version !== 1 || typeof value.jobId !== "string" || typeof value.endpoint !== "string" || typeof value.delivered !== "boolean" || typeof value.createdAt !== "string" || typeof value.updatedAt !== "string" || typeof fp?.path !== "string" || typeof fp.byteLength !== "number" || typeof fp.sha256 !== "string") {
+    throw new Error(`file ingest intent ${file} is not a version 1 record; remove it to continue`);
+  }
+  return value;
+}
+async function readIntents(dir) {
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  return Promise.all(
+    names.filter((name) => name.endsWith(".json")).map(async (name) => {
+      const file = join(dir, name);
+      return { file, intent: parseIntent(await readFile(file, "utf8"), file) };
+    })
+  );
+}
+function createFileIngestIntentStore(dir = DEFAULT_FILE_INGEST_INTENT_DIR) {
+  return {
+    async findUndelivered(endpoint, path, namespaceId) {
+      const records = await readIntents(dir);
+      const prunedBefore = Date.now() - DELIVERED_RETENTION_MS;
+      await Promise.all(
+        records.filter(({ intent }) => intent.delivered && Date.parse(intent.updatedAt) < prunedBefore).map(({ file }) => rm(file, { force: true }))
+      );
+      return records.map(({ intent }) => intent).filter(
+        (intent) => !intent.delivered && intent.endpoint === endpoint && intent.fingerprint.path === path && intent.fingerprint.namespaceId === namespaceId
+      ).sort((a, b) => a.createdAt.localeCompare(b.createdAt))[0];
+    },
+    async save(intent) {
+      await mkdir(dir, { recursive: true, mode: 448 });
+      const file = join(dir, `${intent.jobId}.json`);
+      const temp = join(dir, `.${intent.jobId}.${randomUUID()}.tmp`);
+      await writeFile(temp, `${JSON.stringify(intent)}
+`, { mode: 384, flag: "wx" });
+      await rename(temp, file);
+    }
+  };
+}
+
+// src/mcp/hosted-file-ingest.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { createReadStream, openAsBlob } from "fs";
+import { stat } from "fs/promises";
+import { basename, isAbsolute, resolve } from "path";
+import { setTimeout as delay } from "timers/promises";
+function parseHostedFileIngestDescriptor(meta) {
+  if (meta === null || typeof meta !== "object") return void 0;
+  const value = meta[HOSTED_FILE_INGEST_PROTOCOL.metaKey];
+  if (value === null || typeof value !== "object") return void 0;
+  const { protocolVersion, endpoint, maxBytes } = value;
+  if (protocolVersion !== HOSTED_FILE_INGEST_PROTOCOL.version || typeof endpoint !== "string" || // Same-origin absolute path only: the keychain bearer goes with every request.
+  !endpoint.startsWith("/") || endpoint.startsWith("//") || typeof maxBytes !== "number" || !Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    return void 0;
+  }
+  return { endpoint, maxBytes };
+}
+function toMicrocents(cents) {
+  const microcents = typeof cents === "number" && cents >= 0 ? Math.round(cents * 1e6) : Number.NaN;
+  return Number.isSafeInteger(microcents) ? String(microcents) : void 0;
+}
+function parseArgs(args) {
+  const { path, description, namespaceId, maxCostCents, cancel } = args;
+  const maxCostMicrocents = maxCostCents === void 0 ? void 0 : toMicrocents(maxCostCents);
+  if (typeof path !== "string" || path.length === 0) {
+    return "`path` must be a non-empty local file path.";
+  }
+  if (description !== void 0 && typeof description !== "string") {
+    return "`description` must be a string.";
+  }
+  if (namespaceId !== void 0 && (typeof namespaceId !== "string" || namespaceId.length === 0)) {
+    return "`namespaceId` must be a non-empty string.";
+  }
+  if (cancel !== void 0 && typeof cancel !== "boolean") return "`cancel` must be a boolean.";
+  if (maxCostCents !== void 0 && maxCostMicrocents === void 0) {
+    return "`maxCostCents` must be a non-negative number of cents.";
+  }
+  return {
+    path: isAbsolute(path) ? path : resolve(path),
+    description: description || null,
+    namespaceId: namespaceId ?? null,
+    maxCostMicrocents,
+    cancel: cancel === true
+  };
+}
+var CATALOG_STEPS = /* @__PURE__ */ new Set(["begin", "prepare", "commit", "publish"]);
+var DEADLINE_MS = {
+  begin: 15e3,
+  authorize: 15e3,
+  cancel: 15e3,
+  upload: 12e4,
+  prepare: 9e4,
+  commit: 16e4,
+  publish: 6e4
+};
+var RETRY_BUDGET_MS = 5 * 6e4;
+var DEFAULT_RETRY_AFTER_S = 2;
+var MAX_RETRY_AFTER_S = 30;
+var RESUME = "Call this tool again with the same arguments to resume the job.";
+var NEW_IMPORT = "Call this tool again to start a new import.";
+var NEXT_BY_CODE = /* @__PURE__ */ new Map([
+  [
+    "runtime_upgrade_required",
+    "The pyx-memory instance needs a runtime upgrade before file ingest can continue; call this tool again with the same arguments once it is upgraded."
+  ],
+  [
+    "file_ingest_job_limit",
+    "This instance already has as many unfinished imports as it allows: finish or cancel another one (cancel: true with its path), then call this tool again with the same arguments."
+  ],
+  [
+    "file_ingest_disabled",
+    "Hosted file ingest is switched off on the server; call this tool again with the same arguments later to resume."
+  ],
+  [
+    "file_too_large",
+    "The file is larger than hosted file ingest accepts: call with cancel: true to drop this import, then import a smaller file."
+  ],
+  [
+    "file_ingest_cancel_requested",
+    "The job is being cancelled: call this tool with cancel: true to confirm."
+  ]
+]);
+var ENDED_CODES = /* @__PURE__ */ new Set(["file_ingest_cancelled", "file_ingest_expired"]);
+var COST_CODES = /* @__PURE__ */ new Set([
+  "file_ingest_authorization_required",
+  "file_ingest_ceiling_exceeded",
+  "file_ingest_quota_paused",
+  "file_ingest_limit_exceeded"
+]);
+function nextAfter(res) {
+  if (res.status === 402) {
+    return "The wallet balance is too low: top up, then call this tool again with the same arguments to resume.";
+  }
+  return NEXT_BY_CODE.get(res.code ?? "") ?? RESUME;
+}
+var errorText = (err) => err instanceof Error ? err.message : String(err);
+var text = (result) => result.content.map((part) => part.text).join("\n");
+var fail = (result) => ({ ok: false, result });
+var refuse = (message) => fail(mcpText(message, true));
+var label = (intent) => `${basename(intent.fingerprint.path)} (job ${intent.jobId})`;
+async function hashFile(path) {
+  const hash = createHash("sha256");
+  let byteLength = 0;
+  for await (const chunk of createReadStream(path)) {
+    hash.update(chunk);
+    byteLength += chunk.length;
+  }
+  return { byteLength, sha256: hash.digest("hex") };
+}
+async function matchIntent(intent, args, size) {
+  const fp = intent.fingerprint;
+  const changed = args.description !== fp.description || typeof size === "number" && (size !== fp.byteLength || (await hashFile(args.path)).sha256 !== fp.sha256);
+  if (!changed) return { ok: true, value: intent };
+  return refuse(
+    `${args.path} no longer matches ${label(intent)}: its content or description changed since that import started.
+Call this tool with cancel: true to abandon job ${intent.jobId}, then call again to import the file as it is now.`
+  );
+}
+function isRetryable(res) {
+  return res.status === 429 || res.status === 503 || HOSTED_FILE_INGEST_RETRYABLE_CODES.includes(res.code ?? "");
+}
+async function pause(ms, signal) {
+  await delay(ms, void 0, { signal }).catch((err) => {
+    if (!signal?.aborted) throw err;
+  });
+}
+function retryAfterMs(header) {
+  const seconds = parseRetryAfterSeconds(header) ?? DEFAULT_RETRY_AFTER_S;
+  return Math.min(seconds, MAX_RETRY_AFTER_S) * 1e3;
+}
+function formatCents(microcents, decimals) {
+  const step = 10n ** BigInt(6 - decimals);
+  const units = (BigInt(microcents) + step - 1n) / step;
+  const scale = 10n ** BigInt(decimals);
+  return `${units / scale}.${String(units % scale).padStart(decimals, "0")}`;
+}
+function unwrapEnvelope(body) {
+  if (body === null || typeof body !== "object" || body.success !== true) {
+    throw new Error("the response is not a {success: true, data} envelope");
+  }
+  return body.data;
+}
+function createHostedFileIngestDriver(credentials, guard, intents, fetchImpl = fetch) {
+  const http = createHttpClient(credentials, fetchImpl);
+  const origin = new URL(credentials.endpoint).origin;
+  const stopped = (call, step, detail, next = RESUME) => mcpText(`Import of ${label(call.intent)} stopped at ${step}: ${detail}
+${next}`, true);
+  const interrupted = (call) => refuse(`The call was cancelled; ${label(call.intent)} keeps its progress.
+${RESUME}`);
+  const published = (call, publication) => mcpText(
+    `Ingested ${call.filename}: ${publication.entryCount} chunks stored (replaced ${publication.retiredCount}). job ${call.intent.jobId}`
+  );
+  async function record(call, state) {
+    if (call.intent.lastState === state) return;
+    call.intent.lastState = state;
+    call.intent.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await intents.save(call.intent);
+  }
+  async function deliver(call, result) {
+    call.intent.delivered = true;
+    call.intent.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await intents.save(call.intent);
+    return result;
+  }
+  function accept(call, step, body, parse) {
+    try {
+      return { ok: true, value: parse(unwrapEnvelope(body)) };
+    } catch (err) {
+      return fail(stopped(call, step, `invalid server response: ${errorText(err)}`));
+    }
+  }
+  async function exchange(call, step, attempt, parse) {
+    for (; ; ) {
+      await guard();
+      const res = await attempt(randomUUID2());
+      if (call.signal?.aborted) return interrupted(call);
+      if (res.ok) return accept(call, step, res.data, parse);
+      const waitMs = retryAfterMs(res.retryAfter);
+      if (!isRetryable(res) || Date.now() + waitMs > call.retryUntil)
+        return refused(call, step, res);
+      await pause(waitMs, call.signal);
+    }
+  }
+  function post(call, step, route, body, parse) {
+    const { namespaceId } = call.intent.fingerprint;
+    const scoped = CATALOG_STEPS.has(step) && namespaceId !== null;
+    return exchange(
+      call,
+      step,
+      (idempotencyKey) => http.requestJson({
+        method: "POST",
+        path: `${call.descriptor.endpoint}${route}`,
+        body: scoped ? { ...body, namespaceId } : body,
+        idempotencyKey,
+        timeoutMs: DEADLINE_MS[step],
+        signal: call.signal
+      }),
+      parse
+    );
+  }
+  async function upload(call, job) {
+    const token = job.upload?.token;
+    if (token === void 0) {
+      return fail(stopped(call, "upload", "the server issued no upload token"));
+    }
+    const { path, byteLength, sha256 } = call.intent.fingerprint;
+    let body;
+    try {
+      const current = await hashFile(path);
+      body = await openAsBlob(path);
+      if (current.sha256 !== sha256 || current.byteLength !== byteLength || body.size !== byteLength) {
+        throw new Error("it changed since the import started");
+      }
+    } catch (err) {
+      return fail(
+        stopped(
+          call,
+          "upload",
+          `cannot send ${path}: ${errorText(err)}`,
+          `Restore the file and call again to resume, or call with cancel: true to abandon job ${call.intent.jobId}.`
+        )
+      );
+    }
+    return exchange(
+      call,
+      "upload",
+      (idempotencyKey) => http.requestBytes({
+        method: "PUT",
+        path: `${call.descriptor.endpoint}/${call.intent.jobId}/content`,
+        body,
+        headers: { [HOSTED_FILE_INGEST_PROTOCOL.uploadTokenHeader]: token },
+        idempotencyKey,
+        timeoutMs: DEADLINE_MS.upload,
+        signal: call.signal
+      }),
+      parseHostedFileIngestJobView
+    );
+  }
+  async function refused(call, step, res) {
+    const detail = res.code === void 0 ? text(res.result) : `${text(res.result)} (${res.code})`;
+    if (CATALOG_STEPS.has(step) && COST_CODES.has(res.code ?? "")) {
+      return fail(await costRefusal(call, step, detail));
+    }
+    if (step === "prepare" && res.status === 422 || ENDED_CODES.has(res.code ?? "")) {
+      return fail(await deliver(call, stopped(call, step, detail, NEW_IMPORT)));
+    }
+    return { ok: false, status: res.status, result: stopped(call, step, detail, nextAfter(res)) };
+  }
+  async function costRefusal(call, step, detail) {
+    const auth = await post(
+      call,
+      "authorize",
+      `/${call.intent.jobId}/authorize`,
+      {},
+      parseHostedFileIngestAuthorization
+    );
+    if (!auth.ok) return stopped(call, step, detail);
+    await record(call, auth.value.state);
+    const { ceilingMicrocents, estimateMicrocents, settledMicrocents } = auth.value;
+    const cents = (microcents) => microcents === null ? "unknown" : `${formatCents(microcents, 2)} cents`;
+    return await authorizationStop(call, step, auth.value) ?? stopped(
+      call,
+      step,
+      `${detail}. The spending ceiling is ${cents(ceilingMicrocents)}, the estimated total ${cents(estimateMicrocents)}; charged so far ${formatCents(settledMicrocents, 4)} cents.`,
+      `Call this tool again with the same arguments and a maxCostCents above ${cents(ceilingMicrocents)} to continue.`
+    );
+  }
+  async function authorizationStop(call, step, auth, entryCount) {
+    const charged = `Charged so far: ${formatCents(auth.settledMicrocents, 4)} cents.`;
+    const chunks = entryCount === void 0 ? "its chunks" : `its ${entryCount} chunks`;
+    const stop = (detail, next) => stopped(call, step, `${detail} ${charged}`, next);
+    const resume = `call this tool again with the same arguments and maxCostCents of at least ${auth.estimateMicrocents === null ? "the estimate" : formatCents(auth.estimateMicrocents, 2)} to resume`;
+    switch (auth.state) {
+      case "quota_paused":
+        return stop(
+          `the import was paused before storing ${chunks}.`,
+          `${resume[0]?.toUpperCase()}${resume.slice(1)}.`
+        );
+      case "limit_exceeded":
+        return stop(
+          "the document exceeds the hosted limits for extracted text or chunks.",
+          `Call with cancel: true to abandon job ${call.intent.jobId}, then import the document in smaller parts.`
+        );
+      case "cancel_requested":
+        return stop(
+          "the job is being cancelled.",
+          "Call this tool with cancel: true to confirm the cancellation."
+        );
+      case "cancelled":
+      case "expired":
+      case "failed":
+        return deliver(call, stop(`the job is ${auth.state}.`, NEW_IMPORT));
+    }
+    if (auth.authorized) return void 0;
+    if (auth.estimateMicrocents === null) {
+      return stop("the server has no cost estimate for the job yet.", RESUME);
+    }
+    const estimate = formatCents(auth.estimateMicrocents, 2);
+    const ceiling = auth.ceilingMicrocents === null ? "" : ` The current ceiling is ${formatCents(auth.ceilingMicrocents, 2)} cents.`;
+    return stop(
+      `storing ${chunks} needs your approval: the estimated cost is ${estimate} cents.${ceiling}`,
+      `Call this tool again with the same arguments and maxCostCents of at least ${estimate} to continue.`
+    );
+  }
+  async function commitPages(call, job, manifest) {
+    const committed = new Set(job.committedPages);
+    for (const page of manifest.pages) {
+      if (committed.has(page.pageIndex)) continue;
+      const commit = await post(
+        call,
+        "commit",
+        `/${call.intent.jobId}/commit`,
+        { manifestSha256: manifest.manifestSha256, page },
+        parseHostedFileIngestCommitResult
+      );
+      if (!commit.ok) return commit.result;
+    }
+    return void 0;
+  }
+  async function finish(call, job, maxCostMicrocents) {
+    const manifest = job.manifest;
+    if (!manifest) return stopped(call, "prepare", "the prepared job has no manifest");
+    const auth = await post(
+      call,
+      "authorize",
+      `/${call.intent.jobId}/authorize`,
+      maxCostMicrocents === void 0 ? {} : { maxCostMicrocents },
+      parseHostedFileIngestAuthorization
+    );
+    if (!auth.ok) return auth.result;
+    await record(call, auth.value.state);
+    const halted = await authorizationStop(call, "authorize", auth.value, manifest.entryCount) ?? await commitPages(call, job, manifest);
+    if (halted) return halted;
+    const publish = await post(
+      call,
+      "publish",
+      `/${call.intent.jobId}/publish`,
+      { manifestSha256: manifest.manifestSha256, entryCount: manifest.entryCount },
+      parseHostedFileIngestPublishResult
+    );
+    if (!publish.ok) return publish.result;
+    await record(call, "published");
+    return deliver(call, published(call, publish.value));
+  }
+  async function ended(call, job) {
+    if (job.state === "published") {
+      return job.publication ? deliver(call, published(call, job.publication)) : stopped(call, "begin", "the published job has no publication result");
+    }
+    const what = job.state === "failed" ? `failed: ${job.error ? `${job.error.message} (${job.error.code})` : "no reason given"}` : `is ${job.state}.`;
+    return deliver(call, mcpText(`Import of ${label(call.intent)} ${what}
+${NEW_IMPORT}`, true));
+  }
+  async function ingest(call, maxCostMicrocents) {
+    const { fingerprint, jobId } = call.intent;
+    let next = await post(
+      call,
+      "begin",
+      "",
+      {
+        jobId,
+        filename: call.filename,
+        byteLength: fingerprint.byteLength,
+        sha256: fingerprint.sha256,
+        ...fingerprint.description === null ? {} : { description: fingerprint.description }
+      },
+      parseHostedFileIngestJobView
+    );
+    while (next.ok) {
+      const job = next.value;
+      await record(call, job.state);
+      switch (job.state) {
+        case "awaiting_upload":
+          next = await upload(call, job);
+          break;
+        case "uploaded":
+          next = await post(call, "prepare", `/${jobId}/prepare`, {}, parseHostedFileIngestJobView);
+          break;
+        case "prepared":
+          return finish(call, job, maxCostMicrocents);
+        default:
+          return ended(call, job);
+      }
+    }
+    return next.result;
+  }
+  async function cancel(call) {
+    const res = await post(
+      call,
+      "cancel",
+      `/${call.intent.jobId}/cancel`,
+      {},
+      parseHostedFileIngestAuthorization
+    );
+    if (!res.ok) {
+      if (res.status !== 404) return res.result;
+      return deliver(
+        call,
+        mcpText(`The server has no ${label(call.intent)}; nothing to cancel.
+${NEW_IMPORT}`, true)
+      );
+    }
+    const { state, settledMicrocents } = res.value;
+    await record(call, state);
+    const charged = `Charged: ${formatCents(settledMicrocents, 4)} cents.`;
+    switch (state) {
+      case "cancelled":
+        return deliver(
+          call,
+          mcpText(`Cancelled ${label(call.intent)}. ${charged}
+${NEW_IMPORT}`, true)
+        );
+      case "published":
+      case "expired":
+      case "failed":
+        return deliver(
+          call,
+          mcpText(
+            `${label(call.intent)} was already ${state}; nothing to cancel. ${charged}
+${NEW_IMPORT}`,
+            true
+          )
+        );
+      default:
+        return mcpText(
+          `Cancel of ${label(call.intent)} is ${state}: it stops once outstanding work settles. ${charged}
+Call this tool with cancel: true again to confirm.`,
+          true
+        );
+    }
+  }
+  async function openIntent(descriptor, args, existing) {
+    const size = await stat(args.path).then(
+      (info) => info.size,
+      (err) => err
+    );
+    if (existing) return matchIntent(existing, args, size);
+    if (typeof size !== "number") return refuse(`Failed to read ${args.path}: ${size.message}.`);
+    if (size === 0) return refuse(`${args.path} is empty.`);
+    if (size > descriptor.maxBytes) {
+      return refuse(`File too large: ${size} bytes > ${descriptor.maxBytes} cap.`);
+    }
+    try {
+      requireHostedFileIngestFilename(basename(args.path), "the file name");
+    } catch (err) {
+      return refuse(`Cannot import ${args.path}: ${errorText(err)}.`);
+    }
+    const { byteLength, sha256 } = await hashFile(args.path);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const intent = {
+      version: 1,
+      jobId: randomUUID2(),
+      endpoint: origin,
+      fingerprint: {
+        path: args.path,
+        byteLength,
+        sha256,
+        description: args.description,
+        namespaceId: args.namespaceId
+      },
+      lastState: null,
+      delivered: false,
+      createdAt: now,
+      updatedAt: now
+    };
+    await intents.save(intent);
+    return { ok: true, value: intent };
+  }
+  return async (descriptor, rawArgs, signal) => {
+    const args = parseArgs(rawArgs);
+    if (typeof args === "string") return mcpText(args, true);
+    let intent;
+    const callOn = (value) => ({
+      descriptor,
+      intent: value,
+      filename: basename(value.fingerprint.path),
+      signal,
+      retryUntil: Date.now() + RETRY_BUDGET_MS
+    });
+    try {
+      await guard();
+      const existing = await intents.findUndelivered(origin, args.path, args.namespaceId);
+      if (args.cancel) {
+        if (!existing) return mcpText(`No hosted import of ${args.path} to cancel.`, true);
+        intent = existing;
+        return await cancel(callOn(intent));
+      }
+      const opened = await openIntent(descriptor, args, existing);
+      if (!opened.ok) return opened.result;
+      intent = opened.value;
+      return await ingest(callOn(intent), args.maxCostMicrocents);
+    } catch (err) {
+      return mcpText(intent ? `${errorText(err)}
+job ${intent.jobId}` : errorText(err), true);
+    }
+  };
+}
+
+// src/mcp/tools/shared.ts
+var LOCAL_UPLOAD_META_KEY = "pyx.dev/local-upload";
+
+// src/mcp/proxy-server.ts
+var REMOTE_MCP_PATH = "/mcp";
+function createMcpIdempotentFetch(fetchImpl = fetch, sessionNonce = randomUUID3()) {
+  const wrapped = async (input, init) => {
+    const upstream = input instanceof Request ? input : new Request(String(input), init);
+    const method = init?.method ?? upstream.method;
+    const body = init?.body ?? (input instanceof Request ? await input.clone().text() : void 0);
+    const headers = new Headers(init?.headers ?? upstream.headers);
+    if (method.toUpperCase() === "POST" && !headers.has("Idempotency-Key")) {
+      if (typeof body !== "string") {
+        throw new Error("remote MCP POST body must be text for stable request idempotency");
+      }
+      const key = createHash2("sha256").update("pyx-mcp-idempotency-v1\0").update(sessionNonce).update("\0").update(body).digest("hex");
+      headers.set("Idempotency-Key", `mcp-${key}`);
+    }
+    return fetchImpl(input, { ...init, method, headers, body });
+  };
+  return Object.assign(wrapped, { preconnect: fetch.preconnect });
+}
+function resultText(result) {
+  return result.content.map((c) => c.type === "text" ? c.text : "").join(" ").trim();
+}
+function createCredentialGuard(readCredentials, snapshot) {
+  return async () => {
+    const read = await readCredentials();
+    if (!read.ok) {
+      throw new Error(
+        `${resultText(read.result) || "pyx-memory credentials are unavailable. Run: pyx-mem login"}
+This attempt was not sent. Then reconnect the pyx-memory MCP server.`
+      );
+    }
+    if (read.credentials.endpoint !== snapshot.endpoint || read.credentials.apiKey !== snapshot.apiKey) {
+      throw new Error(
+        "pyx-memory credentials changed since this MCP session started (different endpoint or account). This attempt was not sent. Reconnect the pyx-memory MCP server to use the current sign-in."
+      );
+    }
+  };
+}
+function createGuardedFetch(guard, fetchImpl = fetch) {
+  const wrapped = async (input, init) => {
+    await guard();
+    return fetchImpl(input, init);
+  };
+  return Object.assign(wrapped, { preconnect: fetch.preconnect });
+}
+var RETRYABLE_MCP_METHODS = /* @__PURE__ */ new Set([
+  "initialize",
+  "notifications/initialized",
+  "tools/list",
+  "prompts/list"
+]);
+var MCP_RETRY_BUDGET_MS = 2e4;
+var MIN_RESEND_SPACING_MS = 1e3;
+function isRetryableMcpMessage(input, init) {
+  const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+  if (method.toUpperCase() !== "POST" || typeof init?.body !== "string") return false;
+  let message;
+  try {
+    message = JSON.parse(init.body);
+  } catch {
+    return false;
+  }
+  if (typeof message !== "object" || message === null) return false;
+  const { method: rpc } = message;
+  return typeof rpc === "string" && RETRYABLE_MCP_METHODS.has(rpc);
+}
+function resendDelayMs(res, deadline) {
+  if (res.status !== 429 && res.status !== 503) return void 0;
+  const retryAfterMs2 = parseRetryAfterMs(res.headers.get("retry-after"));
+  if (retryAfterMs2 === void 0) return void 0;
+  const waitMs = Math.max(retryAfterMs2, MIN_RESEND_SPACING_MS);
+  return Date.now() + waitMs > deadline ? void 0 : waitMs;
+}
+function createMcpRetryAfterFetch(fetchImpl = fetch, retryUntil = () => Date.now() + MCP_RETRY_BUDGET_MS) {
+  const wrapped = async (input, init) => {
+    if (!isRetryableMcpMessage(input, init)) return fetchImpl(input, init);
+    const deadline = retryUntil();
+    const signal = init?.signal ?? (input instanceof Request ? input.signal : void 0);
+    for (; ; ) {
+      const res = await fetchImpl(input, init);
+      const waitMs = resendDelayMs(res, deadline);
+      if (waitMs === void 0) return res;
+      await res.body?.cancel();
+      await delay2(waitMs, void 0, { signal });
+    }
+  };
+  return Object.assign(wrapped, { preconnect: fetch.preconnect });
+}
+async function connectRemoteMcp(client, url, apiKey, fetchImpl, budgetMs = MCP_RETRY_BUDGET_MS) {
+  const connectUntil = Date.now() + budgetMs;
+  let connecting = true;
+  const transport = new StreamableHTTPClientTransport(url, {
+    requestInit: { headers: { Authorization: `Bearer ${apiKey}` } },
+    fetch: createMcpIdempotentFetch(
+      createMcpRetryAfterFetch(
+        fetchImpl,
+        () => connecting ? connectUntil : Date.now() + budgetMs
+      )
+    )
+  });
+  try {
+    await client.connect(transport);
+  } finally {
+    connecting = false;
+  }
+}
+function extractLocalUpload(meta) {
+  if (meta === null || typeof meta !== "object") return void 0;
+  const descriptor = meta[LOCAL_UPLOAD_META_KEY];
+  if (descriptor === null || typeof descriptor !== "object") return void 0;
+  const obj = descriptor;
+  if (typeof obj.pathArg !== "string" || typeof obj.endpoint !== "string" || typeof obj.fileField !== "string") {
+    return void 0;
+  }
+  if (!obj.endpoint.startsWith("/") || obj.endpoint.startsWith("//")) {
+    return void 0;
+  }
+  return obj;
+}
+async function readCappedLocalFile(rawPath, descriptor) {
+  if (typeof rawPath !== "string" || rawPath.length === 0) {
+    return {
+      ok: false,
+      result: mcpText(`\`${descriptor.pathArg}\` must be a non-empty local file path.`, true)
+    };
+  }
+  const abs = isAbsolute2(rawPath) ? rawPath : resolve2(rawPath);
+  try {
+    if (typeof descriptor.maxBytes === "number") {
+      const info = await stat2(abs);
+      if (info.size > descriptor.maxBytes) {
+        return {
+          ok: false,
+          result: mcpText(`File too large: ${info.size} bytes > ${descriptor.maxBytes} cap.`, true)
+        };
+      }
+    }
+    return { ok: true, bytes: await readFile2(abs), name: basename2(abs) };
+  } catch (err) {
+    return {
+      ok: false,
+      result: mcpText(
+        `Failed to read ${abs}: ${err instanceof Error ? err.message : String(err)}.`,
+        true
+      )
+    };
+  }
+}
+function createLocalFileUploader(credentials, readCredentials, fetchImpl = fetch) {
+  const guard = createCredentialGuard(readCredentials, credentials);
+  return async (descriptor, args) => {
+    try {
+      await guard();
+      const file = await readCappedLocalFile(args[descriptor.pathArg], descriptor);
+      if (!file.ok) return file.result;
+      const http = createHttpClient(credentials, fetchImpl);
+      const res = await http.requestMultipart({
+        path: descriptor.endpoint,
+        formData: async () => {
+          await guard();
+          const form = new FormData();
+          form.set(descriptor.fileField, new File([new Uint8Array(file.bytes)], file.name));
+          for (const key of descriptor.optionalArgs ?? []) {
+            const value = args[key];
+            if (typeof value === "string" && value.length > 0) form.set(key, value);
+          }
+          return form;
+        }
+      });
+      return res.ok ? mcpJson(res.data) : res.result;
+    } catch (err) {
+      return mcpText(err instanceof Error ? err.message : String(err), true);
+    }
+  };
+}
+function createProxyServer(client, version, uploadLocalFile, hostedFileIngest) {
+  const caps = client.getServerCapabilities();
+  const server = new Server(client.getServerVersion() ?? { name: "pyx-memory", version }, {
+    capabilities: {
+      // Advertise the PRESENCE of tools/prompts, but NOT their `listChanged`
+      // sub-capability: this proxy does not relay the remote's list_changed
+      // notifications, so claiming listChanged would be a capability the host
+      // could rely on but we never honor (Codex: keep the proxy transparent).
+      ...caps?.tools ? { tools: {} } : {},
+      ...caps?.prompts ? { prompts: {} } : {}
+    },
+    instructions: client.getInstructions()
+  });
+  const bridges = /* @__PURE__ */ new Map();
+  const bridging = uploadLocalFile !== void 0 || hostedFileIngest !== void 0;
+  const bridgeOf = (meta) => {
+    const hosted = hostedFileIngest ? parseHostedFileIngestDescriptor(meta) : void 0;
+    if (hosted) return { kind: "hosted", descriptor: hosted };
+    const local = uploadLocalFile ? extractLocalUpload(meta) : void 0;
+    return local ? { kind: "local", descriptor: local } : void 0;
+  };
+  let listedOnce = false;
+  let listingsStarted = 0;
+  let listingApplied = 0;
+  const listAndRefresh = async (params) => {
+    const listing = ++listingsStarted;
+    const result = await client.listTools(params);
+    const { tools, nextCursor } = result;
+    if (!Array.isArray(tools) || listing < listingApplied) return result;
+    listingApplied = listing;
+    listedOnce = true;
+    if (params?.cursor === void 0 && nextCursor === void 0) bridges.clear();
+    for (const tool of tools) {
+      const bridge = bridgeOf(tool._meta);
+      if (bridge) bridges.set(tool.name, bridge);
+      else bridges.delete(tool.name);
+    }
+    return result;
+  };
+  if (caps?.tools) {
+    server.setRequestHandler(ListToolsRequestSchema, (req) => listAndRefresh(req.params));
+    server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+      if (bridging && !listedOnce) {
+        try {
+          await listAndRefresh();
+        } catch {
+        }
+      }
+      const bridge = bridges.get(req.params.name);
+      const args = req.params.arguments ?? {};
+      if (bridge?.kind === "hosted" && hostedFileIngest) {
+        return await hostedFileIngest(bridge.descriptor, args, extra.signal);
+      }
+      if (bridge?.kind === "local" && uploadLocalFile) {
+        return await uploadLocalFile(bridge.descriptor, args);
+      }
+      const actor = normalizeMemoryActorLabel(server.getClientVersion()?.name);
+      const params = { ...req.params };
+      if (actor !== null || params._meta !== void 0) {
+        params._meta = { ...params._meta };
+        delete params._meta[MCP_ACTOR_META_KEY];
+        if (actor !== null) params._meta[MCP_ACTOR_META_KEY] = actor;
+      }
+      return client.callTool(params);
+    });
+  }
+  if (caps?.prompts) {
+    server.setRequestHandler(
+      ListPromptsRequestSchema,
+      (req) => client.listPrompts(req.params)
+    );
+    server.setRequestHandler(
+      GetPromptRequestSchema,
+      (req) => client.getPrompt(req.params)
+    );
+  }
+  return server;
+}
+async function runMcpProxyServer(opts) {
+  const version = opts.version ?? (true ? "1.27.1" : "0.0.0-dev");
+  const read = await opts.readCredentials();
+  if (!read.ok) {
+    throw new Error(
+      resultText(read.result) || "pyx-memory credentials are unavailable. Run: pyx-mem login"
+    );
+  }
+  const { endpoint, apiKey } = read.credentials;
+  const url = new URL(`${endpoint.replace(/\/+$/, "")}${REMOTE_MCP_PATH}`);
+  const guard = createCredentialGuard(opts.readCredentials, read.credentials);
+  const client = new McpClient({ name: "pyx-mem-proxy", version }, { capabilities: {} });
+  try {
+    await connectRemoteMcp(client, url, apiKey, createGuardedFetch(guard));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Could not reach the pyx-memory remote MCP at ${url.href}: ${msg}. Verify the endpoint and key with \`pyx-mem doctor\`.`
+    );
+  }
+  try {
+    const server = createProxyServer(
+      client,
+      version,
+      createLocalFileUploader(read.credentials, opts.readCredentials),
+      createHostedFileIngestDriver(read.credentials, guard, createFileIngestIntentStore())
+    );
+    const transport = new StdioServerTransport();
+    const closed = new Promise((resolve3) => {
+      transport.onclose = () => resolve3();
+    });
+    process.stdin.once("end", () => void transport.close());
+    await server.connect(transport);
+    void opts.onConnected?.(client);
+    await closed;
+  } finally {
+    await client.close().catch(() => {
+    });
+  }
+}
+
+// src/cli/commands/mcp.ts
+async function mcpCommand() {
+  const readCredentials = createReadCredentials(() => getDefaultKeychain());
+  try {
+    await runMcpProxyServer({
+      readCredentials,
+      onConnected: (client) => syncMemoryRulesFromServer(client)
+    });
+    return EXIT.OK;
+  } catch (err) {
+    process.stderr.write(`Internal error: ${err instanceof Error ? err.message : String(err)}
+`);
+    return EXIT.USAGE;
+  }
+}
+function resolveMcpMode(flags) {
+  if (flags.bundled === true) {
+    return {
+      ok: false,
+      error: "The bundled stdio MCP server was removed in v1.3.0. `pyx-mem mcp` now uses the hosted zero-touch path (server-owned tools + instructions; your key stays in the OS keychain). Drop `--bundled`. For a self-hosted server, point at it with `pyx-mem login --endpoint <url>` first."
+    };
+  }
+  return { ok: true };
+}
+export {
+  mcpCommand,
+  resolveMcpMode
+};