@yaklabs-ai/plugin-sdk 0.15.3 → 0.26.3

package/dist/vendored-mcp.js

@@ -1,3 +1,74 @@
+// packages/vendored-mcp-integration/dist/facts.js
+var MAX_HINT_FLOWS = 3;
+var MAX_TRIGGER_KEYWORDS = 8;
+var ROUTE_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+function vendoredMcpUriModuleFacts(descriptor) {
+  const { namespace, displayName, summary } = descriptor;
+  const schemeRoot = `${namespace}://`;
+  return {
+    description: summary,
+    agentHint: {
+      summary,
+      commonFlows: descriptor.routes.slice(0, MAX_HINT_FLOWS).map((route) => ({
+        label: route.description,
+        example: `read(path: "${route.example}")`
+      })),
+      triggers: {
+        keywords: descriptor.triggerKeywords.slice(0, MAX_TRIGGER_KEYWORDS)
+      },
+      helpUri: schemeRoot,
+      skills: [...descriptor.skills]
+    },
+    verbs: {
+      readable: true,
+      writable: false,
+      editable: false,
+      listable: 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.`
+    },
+    templates: descriptor.routes.map((route) => ({
+      uri: route.uri,
+      description: route.description,
+      operations: ["read"]
+    })),
+    // 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`). It follows the route claims
+    // so a route's link is found first; the claim lookup reads the first match that declares one.
+    claims: [
+      ...descriptor.routes.map((route) => {
+        const [, authority = "", pathname = ""] = /^[^:]+:\/\/([^/?#]+)(\/[^?#]*)$/.exec(route.uri) ?? [];
+        return {
+          kind: "uriPattern",
+          pattern: { protocol: namespace, hostname: authority, pathname },
+          normalizeTo: route.uri,
+          route: routeId(route.uri),
+          sourceUrl: route.webUrl
+        };
+      }),
+      { kind: "scheme", scheme: namespace },
+      ...descriptor.claims.filter((claim) => claim.kind !== "scheme").map(copyClaim)
+    ]
+  };
+}
+function routeId(uri) {
+  const path = uri.replace(/^[^:]+:\/\//, "");
+  const segments = path.split("/");
+  const fixed = segments.filter((segment) => !segment.startsWith(":"));
+  const words = (fixed.length > 0 ? fixed : segments.map((s) => s.slice(1))).join("-").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const id = ROUTE_RE.test(words) ? words : `route-${words}`;
+  return id;
+}
+function copyClaim(claim) {
+  const { examples, ...rest } = claim;
+  return {
+    ...rest,
+    pattern: { ...rest.pattern },
+    ...examples !== void 0 ? { examples: [...examples] } : {}
+  };
+}
+
 // 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_]*$/;
@@ -18,57 +89,111 @@ function compileUriClaim(claim) {
     };
   }
   const pattern = compileRoutePattern(claim.pattern);
+  const normalizeTo = claim.normalizeTo === void 0 ? void 0 : compileTemplate(claim.normalizeTo);
+  const sourceUrl = claim.kind === "uriPattern" && claim.sourceUrl !== void 0 ? compileTemplate(claim.sourceUrl) : void 0;
+  const matchAt = (target, selector) => {
+    const parsed = parsePatternInput(target);
+    if (parsed === void 0)
+      return void 0;
+    const captures = matchRoute(pattern, parsed);
+    if (captures === void 0)
+      return void 0;
+    const restCaptures = pattern.restCaptures ?? [];
+    const normalized = normalizeTo === void 0 ? void 0 : fillTemplate(normalizeTo, captures, restCaptures);
+    if (normalizeTo !== void 0 && normalized === void 0)
+      return void 0;
+    const filledSourceUrl = sourceUrl === void 0 ? void 0 : fillTemplate(sourceUrl, captures, restCaptures);
+    return {
+      claimKind: claim.kind,
+      ...Object.keys(captures).length > 0 ? { captures } : {},
+      ...normalized !== void 0 ? {
+        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector)
+      } : {},
+      ...claim.route !== void 0 ? { route: claim.route } : {},
+      ...filledSourceUrl !== void 0 ? { sourceUrl: filledSourceUrl } : {},
+      ...claim.kind === "uriPattern" && claim.title !== void 0 ? { title: fillTitle(claim.title, captures) } : {}
+    };
+  };
   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 ?? []))
-        } : {}
-      };
+      if (claim.kind === "uriPattern") {
+        const { selector, rest } = parseUriConnectionSelector(input);
+        if (selector !== void 0) {
+          const match = matchAt(rest, selector);
+          if (match !== void 0)
+            return match;
+        }
+      }
+      return matchAt(input, void 0);
     }
   };
 }
+function fillTitle(template, captures) {
+  return template.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (written, name) => captures[name] ?? written);
+}
+var CONNECTION_SELECTOR_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)@([^/]+)(?:\/(.*))?$/;
+function parseUriConnectionSelector(input) {
+  const match = CONNECTION_SELECTOR_RE.exec(input.trim());
+  if (match?.[1] === void 0 || match[2] === void 0) {
+    return { rest: input };
+  }
+  return { selector: match[2], rest: `${match[1]}${match[3] ?? ""}` };
+}
+function withSelector(normalized, inputProtocol, selector) {
+  if (selector === void 0)
+    return normalized;
+  if (templateProtocol(normalized) !== inputProtocol)
+    return normalized;
+  const schemeEnd = normalized.indexOf("://") + 3;
+  return `${normalized.slice(0, schemeEnd)}@${selector}/${normalized.slice(schemeEnd)}`;
+}
 function normalizeProtocol(value) {
   return value.replace(/:$/, "").toLowerCase();
 }
 function parsePatternInput(input) {
+  const trimmed = input.trim();
+  let url;
   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
-    };
+    url = new URL(trimmed);
   } catch {
-    return void 0;
+    if (!trimmed.includes(" "))
+      return void 0;
+    try {
+      url = new URL(trimmed.replaceAll(" ", "%20"));
+    } catch {
+      return void 0;
+    }
   }
+  return {
+    protocol: normalizeProtocol(url.protocol),
+    // A web host arrives lowercased; a custom scheme's keeps its case, so a capture of it
+    // (`projects://Acme`) names it as written. Literal host parts match either case.
+    hostname: url.hostname,
+    pathname: url.pathname,
+    search: url.search.startsWith("?") ? url.search.slice(1) : url.search
+  };
 }
 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(), ".") } : {},
+    ...pattern.hostname !== void 0 ? {
+      hostname: compileParts(pattern.hostname.toLowerCase(), LONE_CAPTURE_RE.test(pattern.hostname) ? void 0 : ".")
+    } : {},
     ...pathname !== void 0 ? { pathname } : {},
+    ...pattern.pathname?.endsWith("/") === true ? { pathnameEndsInSlash: true } : {},
     ...pathname !== void 0 ? {
       restCaptures: pathname.filter((part) => part.rest === true).map((part) => part.capture)
     } : {},
     ...pattern.search !== void 0 ? { search: compileParts(pattern.search.replace(/^\?/, ""), "&") } : {}
   };
 }
+var LONE_CAPTURE_RE = /^:[A-Za-z_][A-Za-z0-9_]*(?:\([^()|]*\))?$/;
 function compileParts(value, separator, options = {}) {
   if (value === "")
     return [];
-  const parts = value.split(separator);
+  const parts = separator === void 0 ? [value] : value.split(separator);
   return parts.map((part, index) => {
     const restMatch = REST_CAPTURE_RE.exec(part);
     if (restMatch !== null) {
@@ -108,19 +233,30 @@ function matchRoute(pattern, input) {
     return void 0;
   }
   const captures = {};
-  if (pattern.hostname !== void 0 && !matchParts(pattern.hostname, input.hostname, ".", captures)) {
+  if (pattern.hostname !== void 0 && !matchParts(pattern.hostname, input.hostname, isLoneCapture(pattern.hostname) ? void 0 : ".", captures, true)) {
     return void 0;
   }
-  if (pattern.pathname !== void 0 && !matchParts(pattern.pathname, input.pathname, "/", captures)) {
+  if (pattern.pathname !== void 0 && !matchParts(pattern.pathname, pattern.pathnameEndsInSlash === true ? input.pathname : withoutTrailingSlash(input), "/", captures)) {
     return void 0;
   }
-  if (pattern.search !== void 0 && !matchParts(pattern.search, input.search, "&", captures)) {
+  if (pattern.search !== void 0 && (pattern.search.length === 0 ? input.search !== "" : !matchParts(pattern.search, input.search, "&", captures))) {
     return void 0;
   }
   return captures;
 }
-function matchParts(pattern, value, separator, captures) {
-  const parts = value.split(separator);
+function withoutTrailingSlash(input) {
+  const { hostname, pathname } = input;
+  if (!pathname.endsWith("/") || pathname.endsWith("//"))
+    return pathname;
+  if (pathname === "/" && hostname === "")
+    return pathname;
+  return pathname.slice(0, -1);
+}
+function isLoneCapture(pattern) {
+  return pattern.length === 1 && pattern[0].capture !== void 0 && pattern[0].rest !== true;
+}
+function matchParts(pattern, value, separator, captures, foldLiterals = false) {
+  const parts = separator === void 0 ? [value] : value.split(separator);
   let partIndex = 0;
   for (let i = 0; i < pattern.length; i += 1) {
     const expected = pattern[i];
@@ -128,7 +264,7 @@ function matchParts(pattern, value, separator, captures) {
       const remaining = parts.slice(partIndex);
       if (remaining.every((part) => part === ""))
         return false;
-      captures[expected.capture] = remaining.join(separator);
+      captures[expected.capture] = remaining.join(separator ?? "");
       return true;
     }
     if (partIndex >= parts.length)
@@ -143,8 +279,9 @@ function matchParts(pattern, value, separator, captures) {
       partIndex += 1;
       continue;
     }
-    if (expected.literal !== actual)
+    if (expected.literal !== (foldLiterals ? actual.toLowerCase() : actual)) {
       return false;
+    }
     partIndex += 1;
   }
   return partIndex === parts.length;
@@ -165,31 +302,116 @@ function withInputSearch(claim, pattern, input, normalized) {
 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)
-    });
-  });
+var TEMPLATE_TOKEN_RE = /\{([A-Za-z][A-Za-z0-9]*)\(([^)]*)\)\}|:([A-Za-z_][A-Za-z0-9_]*)/g;
+var TRANSFORMS = {
+  base64: (value) => {
+    const bytes = new TextEncoder().encode(value);
+    let binary = "";
+    for (const byte of bytes)
+      binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/=+$/, "");
+  },
+  slackTimestamp: (value) => {
+    const match = /^p(\d+)(\d{6})$/.exec(value);
+    return match === null ? void 0 : `${match[1]}.${match[2]}`;
+  }
+};
+function isTransform(name) {
+  return Object.prototype.hasOwnProperty.call(TRANSFORMS, name);
+}
+function compileTemplate(template) {
+  const parts = [];
+  let last = 0;
+  for (const token of template.matchAll(TEMPLATE_TOKEN_RE)) {
+    const offset = token.index;
+    if (offset > last)
+      parts.push({ literal: template.slice(last, offset) });
+    const position = templatePosition(template, offset);
+    const [full, transform = "", inner = "", capture] = token;
+    if (capture !== void 0) {
+      parts.push({ capture, position });
+    } else {
+      if (!isTransform(transform)) {
+        throw new Error(`Unknown URI claim template transform '${transform}'.`);
+      }
+      parts.push({
+        transform,
+        inner: compileTransformInput(inner),
+        position
+      });
+    }
+    last = offset + full.length;
+  }
+  if (last < template.length)
+    parts.push({ literal: template.slice(last) });
+  return parts;
 }
-function encodeCaptureValue({ template, offset, value, rest }) {
-  const normalized = isAuthorityCapture(template, offset) ? value.toLowerCase() : value;
-  if (!rest)
-    return encodeURIComponent(normalized);
-  return normalized.split("/").join("/");
+function compileTransformInput(text) {
+  const parts = [];
+  let last = 0;
+  for (const token of text.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
+    if (token.index > last)
+      parts.push({ literal: text.slice(last, token.index) });
+    parts.push({ capture: token[1] });
+    last = token.index + token[0].length;
+  }
+  if (last < text.length)
+    parts.push({ literal: text.slice(last) });
+  return parts;
+}
+function fillTemplate(parts, captures, restCaptures) {
+  let out = "";
+  for (const part of parts) {
+    if ("literal" in part) {
+      out += part.literal;
+      continue;
+    }
+    if ("capture" in part) {
+      const value = captures[part.capture];
+      if (value === void 0) {
+        out += `:${part.capture}`;
+        continue;
+      }
+      const escaped = restCaptures.includes(part.capture) ? escapeRestCapture(value) : escapeForPosition(value, part.position);
+      if (escaped === void 0)
+        return void 0;
+      out += escaped;
+      continue;
+    }
+    let raw = "";
+    for (const inner of part.inner) {
+      raw += "literal" in inner ? inner.literal : captures[inner.capture] ?? `:${inner.capture}`;
+    }
+    const transformed = TRANSFORMS[part.transform](raw);
+    if (transformed === void 0)
+      return void 0;
+    out += escapeForPosition(transformed, part.position);
+  }
+  return out;
 }
-function isAuthorityCapture(template, offset) {
+function templatePosition(template, offset) {
   const prefix = template.slice(0, offset);
+  if (prefix.includes("#"))
+    return "fragment";
+  if (prefix.includes("?"))
+    return "query";
   const schemeIndex = prefix.lastIndexOf("://");
-  if (schemeIndex === -1)
-    return false;
-  return !/[/?#]/.test(prefix.slice(schemeIndex + 3));
+  if (schemeIndex !== -1 && !prefix.slice(schemeIndex + 3).includes("/")) {
+    return "host";
+  }
+  return "path";
+}
+function escapeForPosition(value, position) {
+  if (position === "host")
+    return encodeURIComponent(value.toLowerCase());
+  return encodeURIComponent(value).replace(/%(?:3A|40)/gi, (code) => decodeURIComponent(code));
+}
+function escapeRestCapture(value) {
+  const segments = value.split("/").map(safeDecode);
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    return void 0;
+  }
+  return segments.map(encodeURIComponent).join("/");
 }
 
 // packages/herd-uri/dist/errors.js
@@ -378,52 +600,22 @@ function captureNames(template) {
 }
 
 // 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);
+  const facts = vendoredMcpUriModuleFacts(descriptor);
   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.`
-    },
+    ...facts,
     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"]
-        })),
+        templates: facts.templates,
         examples: descriptor.routes.map((route) => ({
           task: route.description,
           uri: route.example,
@@ -431,17 +623,6 @@ function createVendoredMcpUriModule(descriptor) {
         }))
       });
     },
-    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) {
@@ -461,11 +642,7 @@ function createVendoredMcpUriModule(descriptor) {
     }
   };
 }
-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
+  createVendoredMcpUriModule,
+  vendoredMcpUriModuleFacts
 };

package/dist/whiteboard.d.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+
+export declare const JsonSchema: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+
+export declare type JsonSchema = z.infer<typeof JsonSchema>;
+
+export declare type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+
+export declare const JsonValue: z.ZodType<JsonValue>;
+
+export declare const WhiteboardEntryEnvelope: z.ZodObject<{
+    id: z.ZodString;
+    typeId: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    title: z.ZodString;
+    authorSessionId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+
+export declare type WhiteboardEntryEnvelope = Readonly<z.infer<typeof WhiteboardEntryEnvelope>>;
+
+export declare const WhiteboardEntryInfo: z.ZodObject<{
+    name: z.ZodString;
+    revision: z.ZodString;
+    entry: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        typeId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        title: z.ZodString;
+        authorSessionId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        unavailable: "unavailable";
+        available: "available";
+        "unsupported-version": "unsupported-version";
+        invalid: "invalid";
+    }>;
+    mutable: z.ZodBoolean;
+    diagnostics: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+
+export declare type WhiteboardEntryInfo = Readonly<z.infer<typeof WhiteboardEntryInfo>>;
+
+export declare const WhiteboardEntryInspection: z.ZodObject<{
+    name: z.ZodString;
+    revision: z.ZodString;
+    entry: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        typeId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        title: z.ZodString;
+        authorSessionId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        unavailable: "unavailable";
+        available: "available";
+        "unsupported-version": "unsupported-version";
+        invalid: "invalid";
+    }>;
+    mutable: z.ZodBoolean;
+    diagnostics: z.ZodArray<z.ZodString>;
+    value: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+    text: z.ZodString;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+
+export declare type WhiteboardEntryInspection = Readonly<z.infer<typeof WhiteboardEntryInspection>>;
+
+export declare const WhiteboardTypeInfo: z.ZodObject<{
+    typeId: z.ZodString;
+    displayName: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    available: z.ZodBoolean;
+    presentation: z.ZodOptional<z.ZodObject<{
+        app: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;
+
+export { }