@appstrate/afps-shared 0.8.0 → 0.9.0

package/README.md

@@ -35,6 +35,7 @@ import each module by subpath.
 | `./file-field`                       | File-field parsing helpers.                                                                                                                                 |
 | `./token-usage`                      | Token-usage accounting shapes.                                                                                                                              |
 | `./backoff`                          | Retry backoff computation.                                                                                                                                  |
+| `./jsonpath`                         | The single-value RFC 9535 JSONPath subset every integration-manifest path field is read with (`identity_claims`, login-engine selectors).                   |
 
 ```ts
 import { guardedFetch } from "@appstrate/afps-shared/guarded-fetch";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Zero-dependency AFPS helpers shared by @appstrate/core and @appstrate/afps-runtime (companion-file checks, semver resolution, SRI integrity, credential templates, delivery.http projection)",
   "license": "Apache-2.0",
   "type": "module",
@@ -51,7 +51,8 @@
     "./unzip-bounded": "./src/unzip-bounded.ts",
     "./archive-prefix": "./src/archive-prefix.ts",
     "./backoff": "./src/backoff.ts",
-    "./mime": "./src/mime.ts"
+    "./mime": "./src/mime.ts",
+    "./jsonpath": "./src/jsonpath.ts"
   },
   "dependencies": {
     "@types/semver": "^7.8.0",

package/src/api-tool-naming.ts

@@ -1,7 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Appstrate
 
-import { MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH } from "./mcp-naming.ts";
+import {
+  fnv1a64Hex,
+  MCP_TOOL_NAME_MAX_LENGTH,
+  MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH,
+} from "./mcp-naming.ts";
 
 /** Canonical unprefixed name of the credential-injecting API tool. */
 export const API_CALL_TOOL_NAME = "api_call";
@@ -36,7 +40,7 @@ const API_TOOL_AUTH_HASH_HEX_LENGTH = API_TOOL_AUTH_TOKEN_LENGTH - 2;
  */
 export function apiToolAuthToken(authKey: string): string {
   if (authKey.length <= API_TOOL_RAW_AUTH_KEY_MAX_LENGTH) return authKey;
-  return `h0${fnv1a64(authKey).slice(0, API_TOOL_AUTH_HASH_HEX_LENGTH)}`;
+  return `h0${fnv1a64Hex(authKey).slice(0, API_TOOL_AUTH_HASH_HEX_LENGTH)}`;
 }
 
 /** Throw when two distinct auth keys collapse onto the same bounded token. */
@@ -54,17 +58,6 @@ export function assertUniqueApiToolAuthTokens(authKeys: readonly string[]): void
   }
 }
 
-function fnv1a64(value: string): string {
-  let hash = 0xcbf29ce484222325n;
-  const prime = 0x100000001b3n;
-  const mask = 0xffffffffffffffffn;
-  for (const byte of new TextEncoder().encode(value)) {
-    hash ^= BigInt(byte);
-    hash = (hash * prime) & mask;
-  }
-  return hash.toString(16).padStart(16, "0");
-}
-
 /** Derive the unprefixed api_call name for one auth surface. */
 export function apiCallToolNameForAuth(authKey: string, multiAuth: boolean): string {
   return multiAuth ? `${API_CALL_TOOL_NAME}__${apiToolAuthToken(authKey)}` : API_CALL_TOOL_NAME;

package/src/companion-files.ts

@@ -76,6 +76,27 @@ export function companionFilesFromRecord(files: Record<string, Uint8Array>): Com
   };
 }
 
+/**
+ * Candidate spellings for a manifest-declared archive path, in order.
+ *
+ * A manifest may write `./server.js` or `server.js`; zip entries are stored
+ * without the `./` prefix. Only the leading `./` is normalised — `..`
+ * segments and absolute paths are NOT resolved, so this cannot widen the
+ * lookup beyond the archive root.
+ */
+function archivePathCandidates(declared: string): string[] {
+  const stripped = declared.startsWith("./") ? declared.slice(2) : declared;
+  return stripped === declared ? [declared] : [declared, stripped];
+}
+
+/** First candidate spelling of `declared` present in `files`, else null. */
+function resolveArchivePath(files: CompanionFileSource, declared: string): string | null {
+  for (const candidate of archivePathCandidates(declared)) {
+    if (files.has(candidate)) return candidate;
+  }
+  return null;
+}
+
 /**
  * Validate companion-file presence per AFPS §3.3 / §3.4 for the given
  * package type. Returns the first violation encountered, or `null` when
@@ -84,9 +105,8 @@ export function companionFilesFromRecord(files: Record<string, Uint8Array>): Com
  * The check is intentionally minimal and presence-focused:
  *   - `agent` → `prompt.md` present at root, non-empty bytes (§3.2).
  *   - `skill` → `SKILL.md` present at root, with a YAML frontmatter `name`
- *     (§3.3). Missing `description` is tolerated here: this function is the
- *     LOADER-side gate. The stricter producer-side rule lives in
- *     {@link checkSkillMarkdown}.
+ *     (§3.3). Missing `description` is tolerated — this is the LOADER gate;
+ *     the producer rule is {@link checkSkillMarkdown}.
  *   - `mcp-server` → file at `manifest.server.entry_point` present in the
  *     archive (§3.4 "self-contained — every runtime dep bundled").
  *   - `integration` → no required companion (§3.5).
@@ -130,13 +150,6 @@ export function checkCompanionFiles(
         path: "SKILL.md",
       };
     }
-    // LENIENT on purpose, and deliberately NOT the shared parser — see
-    // {@link checkSkillMarkdown}. This function runs on the LOADER side too
-    // (`extractRootFromAfps` → the run launcher's package catalog), where the
-    // archive is an already-published, immutable artifact. Its acceptance set
-    // must never shrink: anything it rejects is an agent that stops running
-    // for a defect nobody can fix in place. `hasFrontmatterName` is therefore
-    // frozen — the permissive substring probe, unchanged.
     if (!hasFrontmatterName(new TextDecoder().decode(bytes))) {
       return {
         reason: "SKILL_MISSING_FRONTMATTER_NAME",
@@ -159,7 +172,14 @@ export function checkCompanionFiles(
         message: "mcp-server manifest must declare server.entry_point",
       };
     }
-    if (!files.has(entryPoint)) {
+    // MCPB manifests conventionally write the entry point relative-explicit
+    // (`./server.js`), while archive entries are stored flat (`server.js`).
+    // Both spellings name the same file, so resolve either — an exact
+    // `has(entryPoint)` rejected every package in this repo's own
+    // `system-packages/` tree when imported through `POST /api/packages/import`,
+    // while the on-disk system-package loader accepted them. One archive, two
+    // verdicts, depending on which door it came through.
+    if (!resolveArchivePath(files, entryPoint)) {
       return {
         reason: "MCP_SERVER_MISSING_ENTRY_POINT",
         message: `mcp-server archive missing server.entry_point payload: ${entryPoint}`,
@@ -185,21 +205,10 @@ function isEffectivelyEmpty(bytes: Uint8Array): boolean {
 }
 
 /**
- * LOADER-side name probe. FROZEN — byte-for-byte what it was before the
- * producer-side rule existed, and deliberately NOT routed through
- * {@link parseSkillFrontmatter}.
- *
- * The distinction that forces the duplication: this probe decides whether an
- * ALREADY-PUBLISHED bundle loads, and a published bundle is immutable. Any
- * input it used to accept and would now reject is an agent that stops running
- * for a defect nobody can fix in place. The shared parser reads only column-0
- * keys — correct for authoring, but it would newly reject `  name: triage`,
- * `metadata:\n  name: triage` and `skill_name: triage`, all of which this
- * substring probe accepts and some published artifact may well contain.
- *
- * So its acceptance set may never shrink. Nothing here is to be "unified" with
- * the parser below: they answer different questions for different sides of the
- * artifact lifecycle.
+ * Deliberately NOT {@link parseSkillFrontmatter}: published artifacts exist
+ * whose frontmatter `yaml` cannot parse at all (17 in production at the time of
+ * writing, each an unquoted `description: … : …`) and the run launcher has to
+ * keep serving them, so this probe's acceptance set may never shrink.
  */
 function hasFrontmatterName(content: string): boolean {
   const fmMatch = content.match(/^---[^\S\n]*\n([\s\S]*?)\n---/);
@@ -209,114 +218,37 @@ function hasFrontmatterName(content: string): boolean {
   if (!nameMatch) return false;
   const raw = (nameMatch[1] ?? "").trim();
   if (raw.length === 0) return false;
-  // Strip surrounding quotes, the way a YAML quoted scalar would be read.
   const unquoted = /^(['"])(.*)\1$/.exec(raw);
   const value = unquoted ? unquoted[2] : raw;
   return (value ?? "").trim().length > 0;
 }
 
-// ─────────────────────────────────────────────
-// SKILL.md YAML frontmatter — the PRODUCER-side parser
-// ─────────────────────────────────────────────
-
-/**
- * Maximum length of a skill frontmatter `name`, in Unicode CODE POINTS (Agent
- * Skills specification, https://agentskills.io/specification).
- */
+/** Agent Skills bounds, in code points. */
 export const SKILL_NAME_MAX_LENGTH = 64;
-
-/**
- * Maximum length of a skill frontmatter `description`, in Unicode CODE POINTS
- * — the Agent Skills specification (https://agentskills.io/specification)
- * counts characters, and a code point is what "character" means there.
- *
- * NOT a parity constant: Pi measures `description.length`, i.e. UTF-16 units,
- * and only emits a warning past the bound rather than dropping the skill. The
- * platform enforces the spec instead, because the artifact it mints is
- * immutable and other consumers (Codex, Claude Code) are not so forgiving.
- */
 export const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
 
-/**
- * Agent Skills `name` rule: lowercase `a-z`, `0-9` and `-` only, no leading or
- * trailing hyphen, no consecutive hyphens. Length is checked separately
- * against {@link SKILL_NAME_MAX_LENGTH} so the violation message can name the
- * bound.
- *
- * NOT the same namespace as a package id. A package id is `@scope/name`
- * validated by `SLUG_PATTERN` (`@appstrate/core/naming`) — unbounded in
- * length and tolerant of `--`. The frontmatter `name` is the BARE skill slug
- * an agent runtime addresses (`triage`, never `@acme/triage`), and it is the
- * Agent Skills rule that governs it. The two are deliberately different and
- * neither validator may be substituted for the other.
- */
+/** The bare slug an agent runtime addresses — NOT a `@scope/name` package id. */
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
-/** Length in Unicode code points — `"🙂".length` is 2, this returns 1. */
 function codePointLength(value: string): number {
   return [...value].length;
 }
 
-/** Does `name` satisfy the Agent Skills `name` rule (shape AND length)? */
 export function isValidSkillName(name: string): boolean {
   return codePointLength(name) <= SKILL_NAME_MAX_LENGTH && SKILL_NAME_PATTERN.test(name);
 }
 
-/** Parsed `SKILL.md` YAML frontmatter. */
+/** Parsed `SKILL.md` frontmatter. Never throws; a parse failure is `error`. */
 export interface SkillFrontmatter {
-  /** Whether a closed `--- … ---` frontmatter block was found. */
   found: boolean;
-  /**
-   * True when the document opens with `---` but never closes the block. Told
-   * apart from "no frontmatter at all" so the author gets the actual fault.
-   */
+  /** Opens with `---` but never closes the block. */
   unterminated: boolean;
-  /**
-   * Why the block could not be read as `{ name, description }` — a YAML syntax
-   * error, a document that is not a mapping, or a field that is not a string.
-   * `null` when the block parsed cleanly. Never thrown: `extractSkillMeta`'s
-   * contract is to degrade to empty fields plus a warning.
-   */
   error: string | null;
-  /** Frontmatter `name`, or `""` when absent/blank. */
   name: string;
-  /** Frontmatter `description`, or `""` when absent/blank. */
   description: string;
 }
 
-/**
- * Parse the `name` / `description` of a `SKILL.md` YAML frontmatter block.
- *
- * PARITY WITH THE CONSUMER IS THE POINT. The runtime that actually loads a
- * skill — `@earendil-works/pi-coding-agent`, `dist/utils/frontmatter.js` —
- * normalises newlines, requires the document to start with `---`, cuts the
- * block at the first `\n---`, and hands the slice to `yaml`'s `parse`. This
- * function does the same, against the same library at the same major, so the
- * gate cannot accept a document the consumer then fails to PARSE.
- *
- * Parsing is where parity is exact. The RULES are not symmetric, on purpose:
- * Pi only WARNS on a name or description that breaks the Agent Skills spec
- * (and measures the description in UTF-16 units, so `"🙂".length` is 2), while
- * this gate refuses it. The bounds below therefore follow the SPEC — which
- * says characters, hence code points — not Pi's warning threshold. Being
- * stricter than the consumer is safe: it costs an author one edit. Being
- * looser is not: it mints an immutable artifact the consumer drops.
- *
- * The hand-rolled scanner this replaces got that wrong in both directions: it
- * accepted `description: a: b` and `name:x`, which `yaml` refuses outright,
- * and it had to re-implement block scalars, quoted escapes, comments,
- * continuation lines and duplicate detection — each an opportunity to diverge
- * from a spec the library already implements. `uniqueKeys` and `strict` are
- * passed explicitly rather than left to their defaults so a future default
- * change cannot loosen the gate in silence.
- *
- * NOTHING is normalised away that the runtime keeps — a leading BOM above all.
- * Pi tests `normalized.startsWith("---")`, which a BOM defeats, so it reads no
- * frontmatter at all and drops the skill. Stripping the BOM here would make
- * this function read a name and description the runtime never sees, which is
- * exactly the divergence it exists to prevent; {@link checkSkillMarkdown}
- * refuses such a file instead.
- */
+/** Parses the way the skill runtime does, so the gate cannot accept what it fails to read. */
 export function parseSkillFrontmatter(content: string): SkillFrontmatter {
   const empty = { found: false, unterminated: false, error: null, name: "", description: "" };
 
@@ -338,8 +270,6 @@ export function parseSkillFrontmatter(content: string): SkillFrontmatter {
     };
   }
 
-  // An empty block yields `null`; the runtime coerces that to `{}` and so do
-  // we, which makes it a missing NAME rather than a malformed document.
   const mapping = parsed ?? {};
   if (typeof mapping !== "object" || Array.isArray(mapping)) {
     return {
@@ -358,15 +288,7 @@ export function parseSkillFrontmatter(content: string): SkillFrontmatter {
   return { found: true, unterminated: false, error: null, name, description };
 }
 
-/**
- * Read one frontmatter field as a trimmed string.
- *
- * An ABSENT key and an empty YAML scalar (`description:`, which parses to
- * `null`, as does an explicit `description: null`) are indistinguishable once
- * parsed and both mean "not provided" — they yield `""` so the caller reports
- * the field as MISSING. Any other non-string (a number, a boolean, a list, a
- * nested mapping) is a malformed document, not a missing field.
- */
+/** An absent key and an empty scalar both mean "not provided" and yield `""`. */
 function readStringField(record: Record<string, unknown>, key: string): string | { error: string } {
   const value = record[key];
   if (value === undefined || value === null) return "";
@@ -384,73 +306,37 @@ function describeType(value: unknown): string {
   return `a ${typeof value}`;
 }
 
-/** Does the text begin with a UTF-8 byte-order mark? */
 function startsWithBom(content: string): boolean {
   return content.charCodeAt(0) === 0xfeff;
 }
 
-/**
- * Decode `SKILL.md` bytes for {@link checkSkillMarkdown}.
- *
- * `ignoreBOM: true` is the whole point, and its name is backwards: it means
- * "do not CONSUME the BOM", i.e. keep U+FEFF as a character. A default
- * `TextDecoder` silently swallows it, so a write path that decoded stored or
- * archived bytes the ordinary way would hand the gate a BOM-free string, pass
- * it, and freeze bytes the runtime cannot read. Every write path that starts
- * from bytes rather than from a request body decodes through THIS function.
- */
+/** `ignoreBOM: true` reads backwards: it means "do not CONSUME the BOM". */
 export function decodeSkillMarkdown(bytes: Uint8Array): string {
   return new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
 }
 
-/** First line of an error message — YAML errors carry a multi-line excerpt. */
 function firstLine(err: unknown): string {
   const message = err instanceof Error ? err.message : String(err);
   return message.split("\n")[0]!.trim();
 }
 
-// ─────────────────────────────────────────────
-// SKILL.md — the PRODUCER-side gate
-// ─────────────────────────────────────────────
-
 /**
- * Validate a `SKILL.md`'s frontmatter against the FULL AFPS §3.3 rule, as a
- * producer must: a `name` conforming to the Agent Skills specification
- * (https://agentskills.io/specification) and a non-empty `description` of at
- * most {@link SKILL_DESCRIPTION_MAX_LENGTH} code points. Returns the first
- * violation, or `null`.
- *
- * WHY THIS IS SEPARATE FROM {@link checkCompanionFiles}. That function runs on
- * both sides of the artifact lifecycle, and the loader side reads
- * already-published, immutable bundles: a skill published before this rule
- * existed must keep loading, or every run of an agent that depends on it fails
- * at launch for a defect nobody can now fix in place. So the rule is applied
- * at the moment content is AUTHORED — editor create, draft save, publish,
- * restore, fork, and the ROOT of every import — and never at load. AFPS spells
- * both fields SHOULD; the platform mints these artifacts and holds itself to
- * MUST.
- *
- * Takes the decoded text, not a file source: every write path already has the
- * `SKILL.md` in hand (a request body, a draft column, a ZIP entry), and
- * "is SKILL.md present at all" is `checkCompanionFiles`'s question.
+ * The producer-side AFPS §3.3 gate: an Agent Skills `name`
+ * (https://agentskills.io/specification) plus a non-empty bounded `description`.
  */
 export function checkSkillMarkdown(content: string): CompanionFileViolation | null {
-  // FIRST, because everything below reads a document the runtime cannot: Pi's
-  // `parseFrontmatter` tests `startsWith("---")`, which a BOM defeats, so it
-  // reads an empty frontmatter and `loadSkillFromFile` returns `skill: null` —
-  // the skill is silently dropped at run time. The platform's own loader is
-  // more forgiving (it decodes archive bytes through a default `TextDecoder`,
-  // which eats the BOM), so nothing downstream would have complained: the
-  // version would be minted, immutable, and simply never load in the agent.
-  //
-  // Rejected rather than stripped: silently rewriting an author's bytes would
-  // make the artifact disagree with the file they wrote.
+  // Rejected rather than stripped, and it stays rejected now that Pi >= 0.85
+  // strips a BOM itself: a minted version is immutable and has to load on every
+  // runtime image the platform ships, including the 0.84.x ones that test
+  // startsWith("---"), read no frontmatter behind a BOM and drop the skill.
+  // The platform's own loader eats it either way, so without this check the
+  // version would be minted and simply never load on those images.
   if (startsWithBom(content)) {
     return {
       reason: "SKILL_INVALID_FRONTMATTER",
       message:
         "skill SKILL.md starts with a byte-order mark (U+FEFF); remove it — " +
-        "the runtime cannot read frontmatter behind a BOM",
+        "older runtimes read no frontmatter behind a BOM and drop the skill",
       path: "SKILL.md",
     };
   }
@@ -506,18 +392,8 @@ export function checkSkillMarkdown(content: string): CompanionFileViolation | nu
     };
   }
 
-  // CONTAINMENT: what this gate accepts must be a SUBSET of what the loader
-  // accepts. The two read the frontmatter differently on purpose — a real YAML
-  // parser here, a frozen substring probe there — and YAML is the more
-  // permissive of the two: `name:\n  triage`, `name : triage` and a
-  // BOM-prefixed document are all valid YAML that `hasFrontmatterName` cannot
-  // see. Without this check, create and publish would mint an IMMUTABLE version
-  // the run launcher then refuses to load — the one failure mode this whole
-  // split exists to prevent, and unfixable once published.
-  //
-  // Stated as a check rather than by loosening the loader, because the loader's
-  // acceptance set may never shrink, and rather than by tightening the parser,
-  // because the parser must keep matching the runtime.
+  // Containment: `name:\n  triage` is valid YAML the loader's probe cannot
+  // read, so accepting it would mint a version the run launcher cannot load.
   if (!hasFrontmatterName(content)) {
     return {
       reason: "SKILL_INVALID_FRONTMATTER_NAME",

package/src/jsonpath.ts

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * The JSONPath dialect of AFPS integration manifests — a single-value RFC 9535
+ * subset: `$`, `.name` (member-name-shorthand), `['name']` / `["name"]` (RFC
+ * 9535 string literals and escapes), `[0]` / `[-1]` (RFC 9535 `int`). Anything
+ * else throws {@link JsonPathSyntaxError} rather than silently missing.
+ */
+
+export class JsonPathSyntaxError extends Error {
+  override readonly name = "JsonPathSyntaxError";
+}
+
+type JsonPathSegment = string | number;
+
+const SIMPLE_ESCAPES: Record<string, string> = {
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "\t",
+  "/": "/",
+  "\\": "\\",
+};
+
+const isDigit = (ch: string) => ch >= "0" && ch <= "9";
+const isNameFirst = (ch: string) =>
+  (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z") || ch === "_" || ch.charCodeAt(0) >= 0x80;
+const isBlank = (ch: string | undefined) => ch === " " || ch === "\t" || ch === "\n" || ch === "\r";
+
+/** Tokenize `path` into member names and array indices. Throws on anything outside the subset. */
+export function parseJsonPath(path: string): JsonPathSegment[] {
+  const fail = (at: number, what: string): never => {
+    throw new JsonPathSyntaxError(`jsonpath '${path}' at offset ${at}: ${what}`);
+  };
+  if (path[0] !== "$") fail(0, "must start with '$'");
+
+  const segments: JsonPathSegment[] = [];
+  let i = 1;
+  const skipBlank = () => {
+    while (isBlank(path[i])) i++;
+  };
+
+  const readString = (quote: string): string => {
+    const start = i;
+    i++;
+    let out = "";
+    while (i < path.length) {
+      const ch = path[i]!;
+      if (ch === quote) {
+        i++;
+        return out;
+      }
+      if (ch.charCodeAt(0) < 0x20) fail(i, "unescaped control character in string");
+      if (ch !== "\\") {
+        out += ch;
+        i++;
+        continue;
+      }
+      const esc = path[i + 1];
+      if (esc === quote) out += quote;
+      else if (esc !== undefined && esc in SIMPLE_ESCAPES) out += SIMPLE_ESCAPES[esc];
+      else if (esc === "u") {
+        const unit = readHex4(i + 2);
+        if (unit >= 0xdc00 && unit <= 0xdfff) fail(i, "lone low surrogate escape");
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+          const low = path.startsWith("\\u", i + 6) ? readHex4(i + 8) : -1;
+          if (low < 0xdc00 || low > 0xdfff)
+            fail(i, "high surrogate escape without a low surrogate");
+          out += String.fromCharCode(unit, low);
+          i += 12;
+          continue;
+        }
+        out += String.fromCharCode(unit);
+        i += 6;
+        continue;
+      } else fail(i, `invalid escape '\\${esc ?? ""}'`);
+      i += 2;
+    }
+    return fail(start, "unterminated string");
+  };
+
+  const readHex4 = (at: number): number => {
+    const hex = path.slice(at, at + 4);
+    if (!/^[0-9A-Fa-f]{4}$/.test(hex)) fail(at, "\\u must be followed by 4 hex digits");
+    return parseInt(hex, 16);
+  };
+
+  const readInt = (): number => {
+    const start = i;
+    if (path[i] === "-") i++;
+    const digitsAt = i;
+    while (isDigit(path[i] ?? "")) i++;
+    const text = path.slice(start, i);
+    if (i === digitsAt) fail(start, "expected an index");
+    if (text === "-0" || (path[digitsAt] === "0" && i - digitsAt > 1)) {
+      fail(start, `index '${text}' is not an RFC 9535 int (no leading zeros, no -0)`);
+    }
+    const n = Number(text);
+    if (!Number.isSafeInteger(n)) fail(start, `index '${text}' is out of range`);
+    return n;
+  };
+
+  while (i < path.length) {
+    const ch = path[i]!;
+    if (ch === ".") {
+      i++;
+      const start = i;
+      const first = path[i];
+      if (first === ".") fail(start, "recursive descent is not supported");
+      if (first === "*") fail(start, "a wildcard is not supported");
+      if (first !== undefined && isDigit(first)) {
+        fail(
+          start,
+          "a member name cannot start with a digit — write an index as [0] or a member as ['0']",
+        );
+      }
+      if (first === undefined || !isNameFirst(first)) fail(start, "expected a member name");
+      while (i < path.length && (isNameFirst(path[i]!) || isDigit(path[i]!))) i++;
+      segments.push(path.slice(start, i));
+    } else if (ch === "[") {
+      i++;
+      skipBlank();
+      const sel = path[i];
+      if (sel === "'" || sel === '"') segments.push(readString(sel));
+      else if (sel === "-" || (sel !== undefined && isDigit(sel))) segments.push(readInt());
+      else if (sel === undefined) fail(i, "unterminated '['");
+      else
+        fail(i, `unsupported selector '${sel}' (wildcards, filters and slices are not supported)`);
+      skipBlank();
+      if (path[i] === ",") fail(i, "a union of selectors is not supported");
+      if (path[i] === ":") fail(i, "a slice is not supported");
+      if (path[i] !== "]") fail(i, path[i] === undefined ? "unterminated '['" : "expected ']'");
+      i++;
+    } else {
+      fail(i, `unexpected character '${ch}'`);
+    }
+  }
+  return segments;
+}
+
+/**
+ * Evaluate `path` against `root`. Returns `undefined` when the path is valid
+ * but selects nothing; throws {@link JsonPathSyntaxError} when it is invalid.
+ * Members are own properties only, so `$.constructor` cannot reach a prototype.
+ */
+export function evaluateJsonPath(root: unknown, path: string): unknown {
+  let cur: unknown = root;
+  for (const seg of parseJsonPath(path)) {
+    if (cur === null || typeof cur !== "object") return undefined;
+    if (typeof seg === "number") {
+      if (!Array.isArray(cur)) return undefined;
+      cur = cur[seg < 0 ? cur.length + seg : seg];
+    } else {
+      // Not `Object.hasOwn`: the web app compiles this leaf against ES2020.
+      if (Array.isArray(cur) || !Object.prototype.hasOwnProperty.call(cur, seg)) return undefined;
+      cur = (cur as Record<string, unknown>)[seg];
+    }
+  }
+  return cur;
+}

package/src/mcp-naming.ts

@@ -13,7 +13,6 @@ export const MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH = 20;
  * snake-case namespace capped before collision suffixing.
  */
 export function normaliseMcpToolNamespace(raw: string): string {
-  if (typeof raw !== "string") return "";
   const out = trimUnderscores(
     raw
       .replace(/^@/, "")
@@ -24,18 +23,61 @@ export function normaliseMcpToolNamespace(raw: string): string {
 }
 
 /**
- * Canonicalise an untrusted upstream tool body before adding our namespace.
- * An upstream namespace is stripped so `drive__api-call` becomes `api_call`,
- * matching McpHost's outward naming contract.
+ * Exposed tool-name grammar: `{snake_namespace}__{body}`, the body in the LLM
+ * providers' `^[a-zA-Z0-9_-]{1,64}$` alphabet (56-char ceiling: re-prefix headroom).
+ */
+const MCP_TOOL_NAME_PATTERN = /^[a-z0-9][a-z0-9_]*__[A-Za-z0-9_-]+$/;
+
+export function isValidMcpToolName(name: string): boolean {
+  return name.length <= MCP_TOOL_NAME_MAX_LENGTH && MCP_TOOL_NAME_PATTERN.test(name);
+}
+
+/**
+ * Map an untrusted upstream tool name onto the body alphabet: each rejected
+ * code point becomes `_`; nothing else changes.
  */
 export function normaliseMcpToolBody(raw: string): string {
-  if (typeof raw !== "string") return "";
-  let out = trimUnderscores(raw.replace(/[^a-zA-Z0-9_]+/g, "_").toLowerCase());
-  const separator = out.indexOf("__");
-  if (separator >= 0 && separator < out.length - 2) {
-    out = out.slice(separator + 2);
+  return raw.replace(/[^A-Za-z0-9_-]/gu, "_");
+}
+
+const MCP_TOOL_HASH_LENGTH = 8;
+
+/**
+ * Exposed name for an untrusted upstream tool: `{namespace}__{body}` when it
+ * fits and is free, else the body cut to fit plus a hash of the ORIGINAL
+ * upstream name, so two names that normalise to the same body (`a.b`, `a_b`)
+ * still get distinct names. Which of them keeps the plain form depends on
+ * registration order: the first one registered. One salted re-hash on
+ * collision, then it throws.
+ */
+export function allocateMcpToolName(
+  namespace: string,
+  upstreamName: string,
+  taken: (name: string) => boolean,
+): string {
+  const body = normaliseMcpToolBody(upstreamName);
+  const plain = `${namespace}__${body}`;
+  if (isValidMcpToolName(plain) && !taken(plain)) return plain;
+  const budget = MCP_TOOL_NAME_MAX_LENGTH - namespace.length - 2 - MCP_TOOL_HASH_LENGTH - 1;
+  const head = body.slice(0, Math.max(0, budget));
+  for (const seed of [upstreamName, `${upstreamName}\0`]) {
+    const hash = fnv1a64Hex(seed).slice(0, MCP_TOOL_HASH_LENGTH);
+    const candidate = head ? `${namespace}__${head}_${hash}` : `${namespace}__${hash}`;
+    if (!taken(candidate)) return candidate;
+  }
+  throw new Error(`MCP tool name ${JSON.stringify(upstreamName)} collides after re-hashing`);
+}
+
+/** 64-bit FNV-1a over the UTF-8 bytes, as 16 lowercase hex digits. */
+export function fnv1a64Hex(value: string): string {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+  for (const byte of new TextEncoder().encode(value)) {
+    hash ^= BigInt(byte);
+    hash = (hash * prime) & mask;
   }
-  return out;
+  return hash.toString(16).padStart(16, "0");
 }
 
 /** Trim underscore runs in linear time without a backtracking expression. */