@yaklabs-ai/plugin-sdk 0.13.6 → 0.13.8

package/dist/vendored-mcp.js

@@ -0,0 +1,471 @@
+// packages/herd-uri/dist/claims.js
+var SCHEME_RE = /^([a-z][a-z0-9+.-]*):\/\//i;
+var CAPTURE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var REST_CAPTURE_RE = /^:([A-Za-z_][A-Za-z0-9_]*)\*$/;
+var CONSTRAINED_CAPTURE_RE = /^([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+var MAX_CAPTURE_CONSTRAINT_LENGTH = 64;
+function compileUriClaim(claim) {
+  if (claim.kind === "scheme") {
+    const scheme = normalizeProtocol(claim.scheme);
+    return {
+      claim,
+      match(input) {
+        const actual = SCHEME_RE.exec(input.trim())?.[1]?.toLowerCase();
+        if (actual !== scheme)
+          return void 0;
+        return { claimKind: claim.kind };
+      }
+    };
+  }
+  const pattern = compileRoutePattern(claim.pattern);
+  return {
+    claim,
+    match(input) {
+      const parsed = parsePatternInput(input);
+      if (parsed === void 0)
+        return void 0;
+      const captures = matchRoute(pattern, parsed);
+      if (captures === void 0)
+        return void 0;
+      return {
+        claimKind: claim.kind,
+        ...Object.keys(captures).length > 0 ? { captures } : {},
+        ...claim.normalizeTo !== void 0 ? {
+          normalizedUri: withInputSearch(claim, pattern, parsed, interpolateNormalizeTo(claim.normalizeTo, captures, pattern.restCaptures ?? []))
+        } : {}
+      };
+    }
+  };
+}
+function normalizeProtocol(value) {
+  return value.replace(/:$/, "").toLowerCase();
+}
+function parsePatternInput(input) {
+  try {
+    const url = new URL(input.trim());
+    return {
+      protocol: normalizeProtocol(url.protocol),
+      hostname: url.hostname.toLowerCase(),
+      pathname: url.pathname,
+      search: url.search.startsWith("?") ? url.search.slice(1) : url.search
+    };
+  } catch {
+    return void 0;
+  }
+}
+function compileRoutePattern(pattern) {
+  const pathname = pattern.pathname !== void 0 ? compileParts(pattern.pathname, "/", { allowRest: true }) : void 0;
+  return {
+    ...pattern.protocol !== void 0 ? { protocol: normalizeProtocol(pattern.protocol) } : {},
+    ...pattern.hostname !== void 0 ? { hostname: compileParts(pattern.hostname.toLowerCase(), ".") } : {},
+    ...pathname !== void 0 ? { pathname } : {},
+    ...pathname !== void 0 ? {
+      restCaptures: pathname.filter((part) => part.rest === true).map((part) => part.capture)
+    } : {},
+    ...pattern.search !== void 0 ? { search: compileParts(pattern.search.replace(/^\?/, ""), "&") } : {}
+  };
+}
+function compileParts(value, separator, options = {}) {
+  if (value === "")
+    return [];
+  const parts = value.split(separator);
+  return parts.map((part, index) => {
+    const restMatch = REST_CAPTURE_RE.exec(part);
+    if (restMatch !== null) {
+      if (options.allowRest !== true || index !== parts.length - 1) {
+        throw new Error("URI claim rest captures must be final pathname segments.");
+      }
+      return { capture: restMatch[1], rest: true };
+    }
+    if (part.startsWith(":")) {
+      const rawCapture = part.slice(1);
+      const match = CONSTRAINED_CAPTURE_RE.exec(rawCapture);
+      if (match === null) {
+        throw new Error(`Invalid URI claim capture ':${rawCapture}'.`);
+      }
+      const capture = match[1];
+      if (!CAPTURE_RE.test(capture)) {
+        throw new Error(`Invalid URI claim capture ':${rawCapture}'.`);
+      }
+      const constraint = match[2];
+      if (constraint !== void 0)
+        assertSupportedConstraint(constraint);
+      return {
+        capture,
+        ...constraint !== void 0 ? { constraint: new RegExp(`^(?:${constraint})$`) } : {}
+      };
+    }
+    return { literal: part };
+  });
+}
+function assertSupportedConstraint(constraint) {
+  if (constraint.length > MAX_CAPTURE_CONSTRAINT_LENGTH || /[()|]/.test(constraint)) {
+    throw new Error("URI claim capture constraints must be short segment regexes without grouping or alternation.");
+  }
+}
+function matchRoute(pattern, input) {
+  if (pattern.protocol !== void 0 && pattern.protocol !== input.protocol) {
+    return void 0;
+  }
+  const captures = {};
+  if (pattern.hostname !== void 0 && !matchParts(pattern.hostname, input.hostname, ".", captures)) {
+    return void 0;
+  }
+  if (pattern.pathname !== void 0 && !matchParts(pattern.pathname, input.pathname, "/", captures)) {
+    return void 0;
+  }
+  if (pattern.search !== void 0 && !matchParts(pattern.search, input.search, "&", captures)) {
+    return void 0;
+  }
+  return captures;
+}
+function matchParts(pattern, value, separator, captures) {
+  const parts = value.split(separator);
+  let partIndex = 0;
+  for (let i = 0; i < pattern.length; i += 1) {
+    const expected = pattern[i];
+    if (expected.rest === true) {
+      const remaining = parts.slice(partIndex);
+      if (remaining.every((part) => part === ""))
+        return false;
+      captures[expected.capture] = remaining.join(separator);
+      return true;
+    }
+    if (partIndex >= parts.length)
+      return false;
+    const actual = parts[partIndex];
+    if (expected.capture !== void 0) {
+      const decoded = safeDecode(actual);
+      if (expected.constraint !== void 0 && !expected.constraint.test(decoded)) {
+        return false;
+      }
+      captures[expected.capture] = decoded;
+      partIndex += 1;
+      continue;
+    }
+    if (expected.literal !== actual)
+      return false;
+    partIndex += 1;
+  }
+  return partIndex === parts.length;
+}
+function safeDecode(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+function withInputSearch(claim, pattern, input, normalized) {
+  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || pattern.search !== void 0 || input.search.length === 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
+    return normalized;
+  }
+  return `${normalized}?${input.search}`;
+}
+function templateProtocol(template) {
+  return SCHEME_RE.exec(template)?.[1]?.toLowerCase();
+}
+function interpolateNormalizeTo(template, captures, restCaptures) {
+  return template.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (full, name, offset) => {
+    const value = captures[name];
+    if (value === void 0)
+      return full;
+    return encodeCaptureValue({
+      template,
+      offset,
+      value,
+      rest: restCaptures.includes(name)
+    });
+  });
+}
+function encodeCaptureValue({ template, offset, value, rest }) {
+  const normalized = isAuthorityCapture(template, offset) ? value.toLowerCase() : value;
+  if (!rest)
+    return encodeURIComponent(normalized);
+  return normalized.split("/").join("/");
+}
+function isAuthorityCapture(template, offset) {
+  const prefix = template.slice(0, offset);
+  const schemeIndex = prefix.lastIndexOf("://");
+  if (schemeIndex === -1)
+    return false;
+  return !/[/?#]/.test(prefix.slice(schemeIndex + 3));
+}
+
+// packages/herd-uri/dist/errors.js
+var UriError = class extends Error {
+};
+var UriValidationError = class extends UriError {
+  _tag = "UriValidationError";
+  constructor(message) {
+    super(message);
+    this.name = "UriValidationError";
+  }
+};
+
+// packages/herd-uri/dist/operations.js
+import { z } from "zod";
+var URI_OPERATIONS = [
+  "help",
+  "read",
+  "write",
+  "edit",
+  "list",
+  "search",
+  "delete"
+];
+var UriOperationSchema = z.enum(URI_OPERATIONS);
+
+// packages/herd-uri/dist/help-schema.js
+import { z as z2 } from "zod";
+var UriContractJsonSchema = z2.record(z2.string(), z2.unknown());
+var UriParameterSchema = z2.strictObject({
+  name: z2.string().min(1),
+  in: z2.enum(["uri", "query", "selector"]),
+  required: z2.boolean(),
+  description: z2.string().optional(),
+  schema: UriContractJsonSchema,
+  examples: z2.array(z2.unknown()).optional()
+});
+var UriPayloadContractSchema = z2.strictObject({
+  name: z2.string().min(1),
+  mediaType: z2.string().optional(),
+  description: z2.string().optional(),
+  schema: UriContractJsonSchema.optional(),
+  semanticConstraints: z2.array(z2.string().min(1)).min(1).optional(),
+  examples: z2.array(z2.unknown()).optional()
+});
+
+// packages/herd-uri/dist/text-edit.js
+import { z as z3 } from "zod";
+var findReplaceArm = z3.strictObject({
+  find: z3.string().min(1),
+  replace: z3.string(),
+  all: z3.boolean().optional()
+});
+var oldNewEntry = z3.strictObject({
+  oldText: z3.string().min(1),
+  newText: z3.string()
+});
+var uriTextEditPayloadArms = z3.union([
+  findReplaceArm,
+  z3.strictObject({ edits: z3.array(oldNewEntry).min(1) }),
+  oldNewEntry,
+  z3.array(oldNewEntry).min(1)
+]);
+
+// packages/herd-uri/dist/schema/to-json-schema.js
+import { z as z4 } from "zod";
+
+// packages/herd-uri-extensions/dist/limits.js
+var MAX_BYTES = 50 * 1024 * 1024;
+
+// packages/herd-uri-extensions/dist/help.js
+function basicUriHelp(options) {
+  return {
+    uri: options.uri,
+    title: options.title,
+    summary: options.summary,
+    capabilities: options.operations.map((operation) => ({
+      rel: operation,
+      operation,
+      uri: options.uri,
+      title: `${operation} ${options.uri}`
+    })),
+    ...options.templates !== void 0 ? { templates: options.templates } : {},
+    ...options.examples !== void 0 ? { examples: options.examples } : {},
+    ...options.notes !== void 0 ? { notes: options.notes } : {}
+  };
+}
+function jsonResource(uri, value) {
+  return {
+    uri,
+    content: JSON.stringify(value, null, 2),
+    mimeType: "application/json"
+  };
+}
+
+// packages/vendored-mcp-integration/dist/routes.js
+var CANONICAL_ROUTE_RE = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]+)(\/[^?#]*)$/i;
+var CAPTURE_RE2 = /:([A-Za-z_][A-Za-z0-9_]*)/g;
+var CONSTRAINED_CAPTURE_RE2 = /:[A-Za-z_][A-Za-z0-9_]*\(/;
+var REST_CAPTURE_RE2 = /:[A-Za-z_][A-Za-z0-9_]*\*(?=\/|$)/;
+function compileRoutes(namespace, routes) {
+  if (routes.length === 0) {
+    throw new Error(`Vendored MCP descriptor for '${namespace}' declares no routes; a module with no addressable shape can never resolve a link.`);
+  }
+  return routes.map((route) => {
+    const parts = CANONICAL_ROUTE_RE.exec(route.uri);
+    if (parts === null) {
+      throw new Error(`Vendored MCP route '${route.uri}' is not a '<scheme>://<segment>/<path>' template.`);
+    }
+    const [, protocol, authority, pathname] = parts;
+    if (protocol.toLowerCase() !== namespace.toLowerCase()) {
+      throw new Error(`Vendored MCP route '${route.uri}' uses scheme '${protocol}' but its plugin's namespace is '${namespace}'.`);
+    }
+    assertCaptureSymmetry(route);
+    assertPlainCaptures(route);
+    const pattern = { protocol, hostname: authority, pathname };
+    const compiled = {
+      route,
+      canonical: compileUriClaim({
+        kind: "uriPattern",
+        pattern,
+        normalizeTo: route.uri
+      }),
+      web: compileUriClaim({
+        kind: "uriPattern",
+        pattern,
+        normalizeTo: route.webUrl
+      })
+    };
+    assertExampleMatches(compiled);
+    return compiled;
+  });
+}
+function matchRoute2(compiled, input) {
+  const trimmed = input.trim().replace(/\/+$/, "");
+  for (const candidate of compiled) {
+    const canonical = candidate.canonical.match(trimmed);
+    if (canonical?.normalizedUri === void 0)
+      continue;
+    const web = candidate.web.match(trimmed);
+    if (web?.normalizedUri === void 0)
+      continue;
+    return {
+      route: candidate.route,
+      ids: canonical.captures ?? {},
+      canonicalUri: canonical.normalizedUri,
+      webUrl: web.normalizedUri
+    };
+  }
+  return void 0;
+}
+function assertCaptureSymmetry(route) {
+  const inUri = captureNames(route.uri);
+  const inWeb = captureNames(route.webUrl);
+  const missing = [...inUri].filter((name) => !inWeb.has(name));
+  const extra = [...inWeb].filter((name) => !inUri.has(name));
+  if (missing.length === 0 && extra.length === 0)
+    return;
+  throw new Error(`Vendored MCP route '${route.uri}' and its web URL '${route.webUrl}' do not capture the same ids${missing.length > 0 ? `; the web URL drops ${missing.join(", ")}` : ""}${extra.length > 0 ? `; the web URL names unknown ${extra.join(", ")}` : ""}.`);
+}
+function assertPlainCaptures(route) {
+  for (const template of [route.uri, route.webUrl]) {
+    if (CONSTRAINED_CAPTURE_RE2.test(template)) {
+      throw new Error(`Vendored MCP route '${route.uri}' carries an inline capture constraint in '${template}'; constrain ids in claims[], not routes[] (a route constraint would interpolate literally into the URL).`);
+    }
+    if (REST_CAPTURE_RE2.test(template)) {
+      throw new Error(`Vendored MCP route '${route.uri}' declares a rest capture in '${template}'; rest values interpolate unencoded into the web URL, so routes name fixed segment shapes.`);
+    }
+  }
+}
+function assertExampleMatches(compiled) {
+  const matched = compiled.canonical.match(compiled.route.example);
+  if (matched === void 0) {
+    throw new Error(`Vendored MCP route example '${compiled.route.example}' does not match its own template '${compiled.route.uri}'.`);
+  }
+  if (matched.normalizedUri === compiled.route.example)
+    return;
+  throw new Error(`Vendored MCP route example '${compiled.route.example}' is not canonical: its template '${compiled.route.uri}' rebuilds it as '${matched.normalizedUri}'. Write the example exactly as the pill would show it.`);
+}
+function captureNames(template) {
+  const names = /* @__PURE__ */ new Set();
+  for (const match of template.matchAll(CAPTURE_RE2)) {
+    names.add(match[1]);
+  }
+  return names;
+}
+
+// packages/vendored-mcp-integration/dist/uri-module.js
+var MAX_HINT_FLOWS = 3;
+var MAX_TRIGGER_KEYWORDS = 8;
+function createVendoredMcpUriModule(descriptor) {
+  const { namespace, displayName, resourceKind, summary, mcpServerName, mcpSummary } = descriptor;
+  const schemeRoot = `${namespace}://`;
+  const compiled = compileRoutes(namespace, descriptor.routes);
+  return {
+    id: descriptor.moduleId,
+    title: displayName,
+    description: summary,
+    // The scheme claim is added here rather than asked for: a module with no `{ kind: "scheme" }`
+    // claim fails the SDK's disclosure floor (`scheme-claim-missing`), and for a directory-origin
+    // plugin that is a load-time rejection. Every descriptor gets it right by construction.
+    claims: [{ kind: "scheme", scheme: namespace }, ...descriptor.claims],
+    agentHint: {
+      summary,
+      triggers: {
+        keywords: descriptor.triggerKeywords.slice(0, MAX_TRIGGER_KEYWORDS)
+      },
+      commonFlows: descriptor.routes.slice(0, MAX_HINT_FLOWS).map((route) => ({
+        label: route.description,
+        example: `read(path: "${route.example}")`
+      })),
+      helpUri: schemeRoot,
+      skills: [...descriptor.skills]
+    },
+    verbs: {
+      readable: true,
+      listable: false,
+      writable: false,
+      editable: false
+    },
+    verbDocs: {
+      read: `Returns a reference card for a ${displayName} resource: what it is, its ids, and the ${displayName} URL that opens it. Reading calls no ${displayName} API.`
+    },
+    async help(input) {
+      return basicUriHelp({
+        uri: input,
+        title: displayName,
+        summary: `${summary} Kay recognises ${displayName} web links and stores them as ${schemeRoot} URIs. Use the '${mcpServerName}' MCP server for anything beyond the reference card: ${mcpSummary}`,
+        operations: ["help", "read"],
+        templates: descriptor.routes.map((route) => ({
+          uri: route.uri,
+          description: route.description,
+          operations: ["read"]
+        })),
+        examples: descriptor.routes.map((route) => ({
+          task: route.description,
+          uri: route.example,
+          operation: "read"
+        }))
+      });
+    },
+    matches: (input) => input.trim().toLowerCase().startsWith(schemeRoot),
+    describe(input) {
+      const match = matchRoute2(compiled, input);
+      if (match === void 0)
+        return void 0;
+      return {
+        uri: match.canonicalUri,
+        title: referenceTitle(match, resourceKind),
+        sourceUrl: match.webUrl
+      };
+    },
+    async read(input) {
+      const match = matchRoute2(compiled, input);
+      if (match === void 0) {
+        throw new UriValidationError(`Unsupported ${displayName} URI: '${input}'. Expected one of: ${descriptor.routes.map((route) => route.uri).join(", ")}.`);
+      }
+      return jsonResource(match.canonicalUri, {
+        uri: match.canonicalUri,
+        vendor: displayName,
+        resourceKind,
+        resource: match.route.description,
+        ids: match.ids,
+        url: match.webUrl,
+        // The one line that keeps this card from being a dead end. An agent that needs the
+        // resource's contents needs the vendor's tools, and this names the exact server to call.
+        tools: `Kay reads ${displayName} links but does not fetch their contents. For details, changes, or anything beyond these ids, call the '${mcpServerName}' MCP server: ${mcpSummary}`
+      });
+    }
+  };
+}
+function referenceTitle(match, resourceKind) {
+  const values = Object.values(match.ids);
+  const last = values.at(-1);
+  return last === void 0 || last.length === 0 ? resourceKind : last;
+}
+export {
+  createVendoredMcpUriModule
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.13.6",
+  "version": "0.13.8",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -48,6 +48,26 @@
     "./time": {
       "types": "./dist/time.d.ts",
       "default": "./dist/time.js"
+    },
+    "./app-data": {
+      "types": "./dist/app-data.d.ts",
+      "default": "./dist/app-data.js"
+    },
+    "./transcript-review": {
+      "types": "./dist/transcript-review.d.ts",
+      "default": "./dist/transcript-review.js"
+    },
+    "./agent-conversation": {
+      "types": "./dist/agent-conversation.d.ts",
+      "default": "./dist/agent-conversation.js"
+    },
+    "./vendored-mcp": {
+      "types": "./dist/vendored-mcp.d.ts",
+      "default": "./dist/vendored-mcp.js"
+    },
+    "./system-one": {
+      "types": "./dist/system-one.d.ts",
+      "default": "./dist/system-one.js"
     }
   },
   "files": [

package/skills/directory-plugin-authoring/SKILL.md

@@ -95,8 +95,9 @@ claims all show only after enabling, in `read plugin://<id>`.
 ## The SDK resolution contract
 
 - Plugin source imports `@bonsai/plugin-sdk/<subpath>` as a **bare specifier**
-  (`@bonsai/plugin-sdk/kay-agent`, `/kay-agent/testing`, `/kay-app`, `/disclosure`, `/time` — only declared
-  exports exist).
+  (`@bonsai/plugin-sdk/kay-agent`, `/kay-agent/testing`, `/kay-app`, `/disclosure`, `/fs`, `/jev`,
+  `/signals`, `/phase-shift`, `/time`, `/transcript`, `/transcript-review`, `/agent-conversation`,
+  `/app-data`, `/vendored-mcp` — only declared exports exist).
 - The daemon's plugin loader bundles each declared TypeScript entrypoint and its relative imports.
   It keeps `@bonsai/plugin-sdk` imports external and resolves them to the running app's own built SDK.
   Multi-file plugins are supported, and no plugin-local build is needed for Bonsai to load them.