@yaklabs-ai/plugin-sdk 0.8.4

package/dist/kay-agent.js

@@ -0,0 +1,1341 @@
+// packages/herd-uri/dist/errors.js
+var UriError = class extends Error {
+};
+var CONFLICT_MESSAGES = {
+  changed: "This resource changed since this session last read it. Read it again before modifying it.",
+  unwitnessed: "This resource was not read in this session. Read it before modifying it.",
+  unknown: "This resource changed or was not read in this session. Read it again before modifying it."
+};
+var UriConflictError = class extends UriError {
+  _tag = "UriConflictError";
+  reason;
+  constructor(reason) {
+    super(CONFLICT_MESSAGES[reason ?? "unknown"]);
+    this.name = "UriConflictError";
+    this.reason = reason;
+  }
+};
+var UriValidationError = class extends UriError {
+  _tag = "UriValidationError";
+  constructor(message) {
+    super(message);
+    this.name = "UriValidationError";
+  }
+};
+var UriProviderError = class extends UriError {
+  _tag = "UriProviderError";
+  moduleId;
+  operation;
+  uri;
+  status;
+  providerCode;
+  retryable;
+  /** Provider-directed delay before retrying, in milliseconds. */
+  retryAfterMs;
+  constructor(options) {
+    super(options.message);
+    this.name = "UriProviderError";
+    this.moduleId = options.moduleId;
+    this.operation = options.operation;
+    this.uri = options.uri;
+    if (options.status !== void 0)
+      this.status = options.status;
+    if (options.providerCode !== void 0)
+      this.providerCode = options.providerCode;
+    if (options.retryable !== void 0)
+      this.retryable = options.retryable;
+    if (options.retryAfterMs !== void 0) {
+      if (!Number.isInteger(options.retryAfterMs) || options.retryAfterMs < 0) {
+        throw new TypeError("retryAfterMs must be a nonnegative integer.");
+      }
+      this.retryAfterMs = options.retryAfterMs;
+    }
+  }
+};
+var UriNotFoundError = class extends UriError {
+  uri;
+  hint;
+  _tag = "UriNotFoundError";
+  constructor(uri, hint) {
+    super(hint !== void 0 ? `No resource found at '${uri}'. ${hint}` : `No resource found at '${uri}'.`);
+    this.uri = uri;
+    this.hint = hint;
+    this.name = "UriNotFoundError";
+  }
+};
+var UriUnsupportedOperationError = class extends UriError {
+  operation;
+  moduleId;
+  uri;
+  _tag = "UriUnsupportedOperationError";
+  constructor(operation, moduleId, uri, message) {
+    super(message ?? `URI module '${moduleId}' does not support '${operation}' for '${uri}'.`);
+    this.operation = operation;
+    this.moduleId = moduleId;
+    this.uri = uri;
+    this.name = "UriUnsupportedOperationError";
+  }
+};
+
+// packages/herd-uri/dist/connection.js
+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] ?? ""}` };
+}
+
+// packages/herd-uri/dist/resource-witness.js
+import { createHash } from "node:crypto";
+function contentDigest(content) {
+  const hash = createHash("sha256");
+  hash.update(typeof content === "string" ? new TextEncoder().encode(content) : content);
+  return `${DIGEST_PREFIX}${hash.digest("base64url")}`;
+}
+function assertResourceUnchanged(ctx, current) {
+  const expected = ctx.expectedRevision;
+  if (expected === void 0)
+    return;
+  if (current.revision !== void 0 && current.revision === expected)
+    return;
+  if (current.content !== void 0) {
+    const digest = contentDigest(current.content);
+    if (digest === expected)
+      return;
+    if (filesystemStampDigest(expected) === digest.slice(DIGEST_PREFIX.length))
+      return;
+  }
+  throw new UriConflictError("changed");
+}
+var DIGEST_PREFIX = "sha256:";
+function filesystemStampDigest(revision) {
+  const parts = revision.split(":");
+  return parts.length === 6 ? parts[5] : void 0;
+}
+
+// packages/herd-uri/dist/template-route.js
+var PLACEHOLDER_RE = /<([^<>]+)>/g;
+var REST_SUFFIX = "...";
+var SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):(?:\/\/)?(.*)$/s;
+function parseRoute(address) {
+  const trimmed = address.trim();
+  const match = SCHEME_RE.exec(trimmed);
+  const scheme = match?.[1]?.toLowerCase() ?? "";
+  const rest = match?.[2] ?? trimmed;
+  const [rawPath = "", rawQuery] = splitQuery(rest);
+  const path = rawPath.replace(/^\/+/, "").replace(/\/+$/, "");
+  const query = /* @__PURE__ */ new Map();
+  if (rawQuery !== void 0) {
+    for (const pair of rawQuery.split("&")) {
+      if (pair.length === 0)
+        continue;
+      const eq = pair.indexOf("=");
+      const key = eq === -1 ? pair : pair.slice(0, eq);
+      const value = eq === -1 ? "" : pair.slice(eq + 1);
+      if (key.length === 0)
+        continue;
+      if (!query.has(key) || isPlaceholder(value))
+        query.set(key, value);
+    }
+  }
+  return { scheme, path, query };
+}
+function splitQuery(rest) {
+  const hash = rest.indexOf("#");
+  const withoutFragment = hash === -1 ? rest : rest.slice(0, hash);
+  const q = withoutFragment.indexOf("?");
+  return q === -1 ? [withoutFragment, void 0] : [withoutFragment.slice(0, q), withoutFragment.slice(q + 1)];
+}
+function isPlaceholder(value) {
+  return /^<[^<>]+>$/.test(value);
+}
+function selectorPlaceholder(templateUri) {
+  const selector = parseUriConnectionSelector(templateUri).selector;
+  if (selector === void 0)
+    return void 0;
+  const match = /^<([^<>]+)>$/.exec(selector);
+  return match?.[1];
+}
+function isRestPlaceholder(name) {
+  return name.endsWith(REST_SUFFIX);
+}
+function placeholderParameterName(name) {
+  return isRestPlaceholder(name) ? name.slice(0, -REST_SUFFIX.length) : name;
+}
+function templateAddressProblem(templateUri) {
+  const parsed = parseRoute(stripUriSelector(templateUri));
+  for (const match of parsed.path.matchAll(PLACEHOLDER_RE)) {
+    const name = match[1] ?? "";
+    if (name.includes("/")) {
+      return `placeholder <${name}> contains a slash; use <${name.split("/")[0] ?? "path"}...> as the last segment for a rest-of-path placeholder`;
+    }
+    if (isRestPlaceholder(name) && match.index + match[0].length !== parsed.path.length) {
+      return `rest-of-path placeholder <${name}> must be the last path segment`;
+    }
+  }
+  return void 0;
+}
+function stripUriSelector(address) {
+  return parseUriConnectionSelector(address).rest;
+}
+function templatePlaceholders(templateUri) {
+  return deriveTemplateParameters({ uri: templateUri, description: "" }).map((parameter) => parameter.name);
+}
+function deriveTemplateParameters(template) {
+  const authored = new Map((template.parameters ?? []).map((parameter) => [parameter.name, parameter]));
+  const parsed = parseRoute(stripUriSelector(template.uri));
+  const derived = [];
+  const selector = selectorPlaceholder(template.uri);
+  if (selector !== void 0) {
+    derived.push(authored.get(selector) ?? {
+      name: selector,
+      in: "selector",
+      required: false,
+      schema: { type: "string" }
+    });
+  }
+  for (const match of parsed.path.matchAll(PLACEHOLDER_RE)) {
+    const name = placeholderParameterName(match[1] ?? "");
+    if (name.length === 0 || derived.some((p) => p.name === name))
+      continue;
+    derived.push(authored.get(name) ?? {
+      name,
+      in: "uri",
+      required: true,
+      schema: { type: "string" }
+    });
+  }
+  for (const [key, value] of parsed.query) {
+    if (derived.some((p) => p.name === key))
+      continue;
+    const schema = isPlaceholder(value) ? { type: "string" } : { type: "string", enum: value.split("|").filter((v) => v.length > 0) };
+    derived.push(authored.get(key) ?? {
+      name: key,
+      in: "query",
+      required: false,
+      schema
+    });
+  }
+  const derivedNames = new Set(derived.map((parameter) => parameter.name));
+  const extra = (template.parameters ?? []).filter((parameter) => !derivedNames.has(parameter.name));
+  return [...derived, ...extra];
+}
+
+// packages/herd-uri/dist/template-lint.js
+function lintUriTemplate(template) {
+  const findings = [];
+  const addressProblem = templateAddressProblem(template.uri);
+  if (addressProblem !== void 0) {
+    findings.push({
+      rule: "template-address-unmatchable",
+      uri: template.uri,
+      message: `${template.uri} can never be matched by help: ${addressProblem}.`
+    });
+  }
+  const operations = template.operations ?? [];
+  if (operations.filter((operation) => operation !== "help").length === 0) {
+    findings.push({
+      rule: "template-operations-missing",
+      uri: template.uri,
+      message: `${template.uri} lists no operations; a route must declare the verbs it supports.`
+    });
+  }
+  for (const operation of operations) {
+    if ((operation === "write" || operation === "edit") && template.accepts?.[operation] === void 0) {
+      findings.push({
+        rule: "template-accepts-missing",
+        uri: template.uri,
+        operation,
+        message: `${template.uri} lists ${operation} but declares no accepts.${operation} payload contract (use payload() from the handler's validator, or an explicit contract without a schema for an unstructured body).`
+      });
+    }
+    if (operation === "delete" && template.deleteEffect === void 0) {
+      findings.push({
+        rule: "template-delete-effect-missing",
+        uri: template.uri,
+        operation,
+        message: `${template.uri} lists delete but declares no deleteEffect (trash, permanent, or conditional).`
+      });
+    }
+    if (operation === "help")
+      continue;
+    const sentence = template.operationDocs?.[operation];
+    const soleVerb = operations.filter((candidate) => candidate !== "help").length === 1;
+    if (sentence === void 0 && !soleVerb) {
+      findings.push({
+        rule: "template-operation-docs-missing",
+        uri: template.uri,
+        operation,
+        message: `${template.uri} lists ${operation} alongside other verbs and has no operationDocs.${operation} sentence.`
+      });
+    }
+  }
+  const placeholders = new Set(templatePlaceholders(template.uri));
+  for (const parameter of template.parameters ?? []) {
+    if (placeholders.has(parameter.name))
+      continue;
+    findings.push({
+      rule: "template-parameter-unknown",
+      uri: template.uri,
+      parameter: parameter.name,
+      message: `${template.uri} authors parameter "${parameter.name}" but the address has no <${parameter.name}> placeholder.`
+    });
+  }
+  return findings;
+}
+function lintUriHelpContracts(help) {
+  return (help.templates ?? []).flatMap((template) => lintUriTemplate(template));
+}
+
+// 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/observation.js
+var OBSERVATION_MIME = "application/vnd.kay.observation+json";
+
+// 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)
+]);
+var uriTextEditPayloadSchema = uriTextEditPayloadArms;
+var URI_TEXT_EDIT_SHAPE_SUMMARY = `{"find": string, "replace": string, "all"?: boolean} (one exact-text replacement), or the edit tool's {"edits": [{"oldText", "newText"}, ...]}`;
+function parseUriTextEditPayload(payload2) {
+  const parsed = uriTextEditPayloadArms.safeParse(payload2);
+  if (!parsed.success)
+    return { ok: false };
+  const data = parsed.data;
+  if (!Array.isArray(data) && "find" in data) {
+    return {
+      ok: true,
+      grammar: "find",
+      edits: [
+        { find: data.find, replace: data.replace, all: data.all ?? false }
+      ]
+    };
+  }
+  const entries = Array.isArray(data) ? data : "edits" in data ? data.edits : [data];
+  return {
+    ok: true,
+    grammar: "edits",
+    edits: entries.map((entry) => ({
+      find: entry.oldText,
+      replace: entry.newText,
+      all: false
+    }))
+  };
+}
+function occurrencePositions(content, find) {
+  const positions = [];
+  let cursor = content.indexOf(find);
+  while (cursor !== -1) {
+    positions.push(cursor);
+    cursor = content.indexOf(find, cursor + find.length);
+  }
+  return positions;
+}
+function applyUriTextEdits(content, edits) {
+  const ranges = [];
+  for (const [index, edit] of edits.entries()) {
+    const positions = occurrencePositions(content, edit.find);
+    if (positions.length === 0) {
+      return { ok: false, failure: { kind: "no-match", index } };
+    }
+    if (positions.length > 1 && !edit.all) {
+      return {
+        ok: false,
+        failure: { kind: "ambiguous", index, occurrences: positions.length }
+      };
+    }
+    const applied = edit.all ? positions : positions.slice(0, 1);
+    for (const start of applied) {
+      ranges.push({
+        start,
+        end: start + edit.find.length,
+        replace: edit.replace,
+        editIndex: index
+      });
+    }
+  }
+  ranges.sort((a, b) => a.start - b.start || a.editIndex - b.editIndex);
+  for (let i = 1; i < ranges.length; i++) {
+    if (ranges[i].start < ranges[i - 1].end) {
+      return {
+        ok: false,
+        failure: {
+          kind: "overlap",
+          index: Math.max(ranges[i].editIndex, ranges[i - 1].editIndex)
+        }
+      };
+    }
+  }
+  let text = "";
+  let cursor = 0;
+  for (const range of ranges) {
+    text += content.slice(cursor, range.start) + range.replace;
+    cursor = range.end;
+  }
+  text += content.slice(cursor);
+  if (text === content) {
+    return { ok: false, failure: { kind: "no-change" } };
+  }
+  return { ok: true, text, replaced: ranges.length };
+}
+function describeUriTextEditTarget(grammar, index, count) {
+  if (grammar === "find")
+    return "The find text";
+  return count === 1 ? "The oldText" : `edits[${String(index)}].oldText`;
+}
+
+// packages/herd-uri/dist/line-selector.js
+var RAW_TOKEN = /^raw$/i;
+function parseRangeListToken(token) {
+  if (token.length === 0)
+    return void 0;
+  const ranges = [];
+  for (const part of token.split(",")) {
+    const range = parseSingleRange(part);
+    if (range === void 0)
+      return void 0;
+    ranges.push(range);
+  }
+  return ranges;
+}
+function toInt(value) {
+  if (!/^\d+$/.test(value))
+    return void 0;
+  const n = Number.parseInt(value, 10);
+  return Number.isSafeInteger(n) && n >= 1 ? n : void 0;
+}
+function parseSingleRange(part) {
+  const plus = part.indexOf("+");
+  if (plus >= 0) {
+    const start2 = toInt(part.slice(0, plus));
+    const count = toInt(part.slice(plus + 1));
+    if (start2 === void 0 || count === void 0)
+      return void 0;
+    return { start: start2, end: start2 + count - 1 };
+  }
+  const dash = part.indexOf("-");
+  if (dash >= 0) {
+    const start2 = toInt(part.slice(0, dash));
+    const endRaw = part.slice(dash + 1);
+    if (start2 === void 0)
+      return void 0;
+    if (endRaw.length === 0)
+      return { start: start2, end: Number.POSITIVE_INFINITY };
+    const end = toInt(endRaw);
+    if (end === void 0 || end < start2)
+      return void 0;
+    return { start: start2, end };
+  }
+  const start = toInt(part);
+  if (start === void 0)
+    return void 0;
+  return { start, end: Number.POSITIVE_INFINITY };
+}
+function mergeRanges(ranges) {
+  const sorted = [...ranges].sort((a, b) => a.start - b.start);
+  const merged = [];
+  for (const range of sorted) {
+    const last = merged[merged.length - 1];
+    if (last !== void 0 && range.start <= last.end) {
+      if (range.end > last.end) {
+        merged[merged.length - 1] = { start: last.start, end: range.end };
+      }
+      continue;
+    }
+    merged.push(range);
+  }
+  return merged;
+}
+function parseLineSelector(input) {
+  let address = input;
+  let raw = false;
+  let ranges;
+  for (let i = 0; i < 2; i += 1) {
+    const colon = address.lastIndexOf(":");
+    if (colon < 0)
+      break;
+    const token = address.slice(colon + 1);
+    if (RAW_TOKEN.test(token)) {
+      if (raw)
+        break;
+      raw = true;
+      address = address.slice(0, colon);
+      continue;
+    }
+    const parsed = parseRangeListToken(token);
+    if (parsed === void 0)
+      break;
+    if (ranges !== void 0)
+      break;
+    ranges = parsed;
+    address = address.slice(0, colon);
+  }
+  return {
+    address,
+    selector: { ranges: ranges ? mergeRanges(ranges) : [], raw }
+  };
+}
+
+// packages/herd-uri/dist/schema/to-json-schema.js
+import { z as z4 } from "zod";
+function toJsonSchema(schema) {
+  if (schema instanceof z4.ZodType) {
+    const { $schema: _dialect, ...value } = z4.toJSONSchema(schema, {
+      // `io: "input"` describes what a caller may SEND, which is what a parameter and an
+      // `accepts` payload advertise: a field with a Zod default is optional on the wire even
+      // though the parsed value always carries it. Strictness still survives where the validator
+      // really enforces it — `z.strictObject` emits `additionalProperties: false`, while a plain
+      // `z.object` correctly does not, because it TOLERATES unknown keys and silently strips
+      // them. A `returns` payload derived from a Zod schema is described in the same input terms;
+      // no module does that today, and a faithful output projection would need its own seam.
+      io: "input",
+      // Inline every reused sub-schema rather than emitting `$ref`s into a `$defs` block. A
+      // contract schema is a FRAGMENT: it gets embedded in a payload contract, and callers
+      // legitimately lift one arm of a union out of it. A `$ref` only resolves relative to the
+      // root that carries `$defs`, so the moment the fragment moves, the reference dangles.
+      // Self-contained is worth the repetition at these sizes.
+      reused: "inline",
+      // Recursion (`z.lazy`) has no self-contained form: zod's default is to emit a
+      // `$defs` block with `$ref` pointers, which dangle the moment the fragment is
+      // embedded. Throw instead, so a contract that needs recursion has to disclose a
+      // non-recursive shape (see skill-module's metadata disclosure) rather than ship a
+      // reference nothing can resolve.
+      cycles: "throw"
+    });
+    return value;
+  }
+  return structuredClone(schema);
+}
+
+// packages/herd-uri/dist/schema/helpers.js
+function uriParam(name, schema, description, options = {}) {
+  return {
+    name,
+    in: "uri",
+    required: options.required ?? true,
+    ...description === void 0 ? {} : { description },
+    schema: toJsonSchema(schema),
+    ...options.examples === void 0 ? {} : { examples: options.examples }
+  };
+}
+function payload(name, schema, options = {}) {
+  return {
+    name,
+    ...options.mediaType === void 0 ? {} : { mediaType: options.mediaType },
+    ...options.description === void 0 ? {} : { description: options.description },
+    schema: toJsonSchema(schema),
+    ...options.semanticConstraints === void 0 ? {} : { semanticConstraints: options.semanticConstraints },
+    ...options.examples === void 0 ? {} : { examples: options.examples }
+  };
+}
+function capability(spec) {
+  return { ...spec };
+}
+
+// packages/plugin-sdk/dist/jev.js
+function createFallbackOnlyWithJev() {
+  return async (_use, fallback, options = {}) => {
+    if (typeof fallback !== "function") {
+      throw new TypeError("withJev requires a `fallback` function as its second argument.");
+    }
+    const { signal, deadlineAt } = options;
+    if (deadlineAt !== void 0 && !Number.isFinite(deadlineAt)) {
+      throw new TypeError("withJev's `deadlineAt` must be a finite epoch-ms timestamp.");
+    }
+    const assertWithinBoundaries = () => {
+      if (signal?.aborted === true) {
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+      }
+      if (deadlineAt !== void 0 && Date.now() >= deadlineAt) {
+        throw new Error("withJev's deadline has passed.");
+      }
+    };
+    assertWithinBoundaries();
+    let timer;
+    let onAbort;
+    const stopped = new Promise((_resolve, reject) => {
+      if (signal !== void 0) {
+        onAbort = () => reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      if (deadlineAt !== void 0) {
+        const checkDeadline = () => {
+          const remaining = deadlineAt - Date.now();
+          if (remaining <= 0) {
+            reject(new Error("withJev's deadline has passed."));
+          } else {
+            timer = setTimeout(checkDeadline, Math.min(remaining, 2147483647));
+          }
+        };
+        checkDeadline();
+      }
+    });
+    try {
+      const result = await Promise.race([
+        Promise.resolve().then(() => {
+          assertWithinBoundaries();
+          return fallback();
+        }),
+        stopped
+      ]);
+      assertWithinBoundaries();
+      return result;
+    } catch (error) {
+      assertWithinBoundaries();
+      throw error;
+    } finally {
+      if (timer !== void 0)
+        clearTimeout(timer);
+      if (signal !== void 0 && onAbort !== void 0) {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+  };
+}
+
+// packages/herd-uri-extensions/dist/limits.js
+var MAX_BYTES = 50 * 1024 * 1024;
+var MAX_OUTPUT_CHARS = 5e5;
+
+// packages/herd-uri-extensions/dist/markdown.js
+function finalizeOutput(content, maxChars = MAX_OUTPUT_CHARS) {
+  const cleaned = content.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+  const truncated = cleaned.length > maxChars;
+  return {
+    content: truncated ? cleaned.slice(0, maxChars) : cleaned,
+    truncated
+  };
+}
+
+// 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 tryParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function formatNumber(n) {
+  if (n >= 1e6)
+    return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3)
+    return `${(n / 1e3).toFixed(1)}K`;
+  return String(n);
+}
+function formatIsoDate(value) {
+  if (value == null)
+    return "";
+  try {
+    return new Date(value).toISOString().split("T")[0] ?? "";
+  } catch {
+    return "";
+  }
+}
+function jsonResource(uri, value) {
+  return {
+    uri,
+    content: JSON.stringify(value, null, 2),
+    mimeType: "application/json"
+  };
+}
+function markdownResource(uri, md, notes = []) {
+  const capped = finalizeOutput(md);
+  if (capped.truncated)
+    notes.push("Output truncated to size limit.");
+  const content = capped.content;
+  return {
+    uri,
+    content: content.length === 0 ? "(empty)" : content,
+    mimeType: "text/markdown",
+    ...notes.length > 0 ? { metadata: { notes } } : {}
+  };
+}
+function observationResource(uri, material) {
+  return {
+    uri,
+    content: JSON.stringify(material, null, 2),
+    mimeType: OBSERVATION_MIME
+  };
+}
+function accountQualifiedUri(scheme, accountId, path) {
+  if (accountId.length === 0 || accountId.includes("/")) {
+    throw new Error(`accountQualifiedUri: accountId must be non-empty and contain no "/" (selector-parse would truncate it), got ${JSON.stringify(accountId)}`);
+  }
+  return `${scheme}://@${accountId}/${path}`;
+}
+function isOptionalString(value) {
+  return value === void 0 || typeof value === "string";
+}
+function isOptionalStringArray(value) {
+  return value === void 0 || Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function observationFromResource(resource) {
+  if (resource.mimeType !== OBSERVATION_MIME)
+    return void 0;
+  if (typeof resource.content !== "string")
+    return void 0;
+  const parsed = tryParseJson(resource.content);
+  if (parsed === void 0 || typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return void 0;
+  }
+  const value = parsed;
+  if (typeof value.uri !== "string" || typeof value.kind !== "string") {
+    return void 0;
+  }
+  if (!isOptionalString(value.title) || !isOptionalStringArray(value.text) || !isOptionalString(value.createdAt) || !isOptionalString(value.updatedAt) || !isOptionalString(value.version)) {
+    return void 0;
+  }
+  return value;
+}
+
+// packages/herd-agent/dist/core/extensions/auth/scheme.js
+var ACCOUNT_ID_PARAM = "accountId";
+function authContextOf(ctx) {
+  return ctx.auth;
+}
+function authFailureResult(failure) {
+  return {
+    content: [{ type: "text", text: failure.message }],
+    details: void 0
+  };
+}
+function withAccountIdParam(parameters) {
+  if (parameters === null || typeof parameters !== "object" || parameters.type !== "object") {
+    return parameters;
+  }
+  const schema = parameters;
+  if (schema.properties?.[ACCOUNT_ID_PARAM] !== void 0) {
+    return parameters;
+  }
+  return {
+    ...schema,
+    properties: {
+      ...schema.properties,
+      [ACCOUNT_ID_PARAM]: {
+        type: "string",
+        description: "Optional account id to use for this call instead of the session-active account."
+      }
+    }
+  };
+}
+function withResolvedAuth(definition, binding, body) {
+  return {
+    ...definition,
+    requiresAuth: binding,
+    parameters: withAccountIdParam(definition.parameters),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const auth = authContextOf(ctx);
+      if (auth === void 0) {
+        return authFailureResult({
+          ok: false,
+          reason: "no-connection",
+          message: `Auth is not available in this context for ${binding.serviceId}.`
+        });
+      }
+      const override = params?.[ACCOUNT_ID_PARAM];
+      const result = await auth.resolveToken({
+        serviceId: binding.serviceId,
+        ...binding.schemeId === void 0 ? {} : { schemeId: binding.schemeId },
+        ...typeof override === "string" && override.length > 0 ? { accountId: override } : {},
+        ...binding.requiredScopes === void 0 ? {} : { requiredScopes: binding.requiredScopes },
+        ...binding.scopeRequirement === void 0 ? {} : { scopeRequirement: binding.scopeRequirement },
+        ...binding.connectServiceId === void 0 ? {} : { connectServiceId: binding.connectServiceId }
+      });
+      if (!result.ok) {
+        return authFailureResult(result);
+      }
+      return body(toolCallId, params, signal, onUpdate, ctx, result.auth);
+    }
+  };
+}
+
+// packages/herd-agent/dist/core/web/search/types.js
+var SearchProviderError = class extends Error {
+  provider;
+  status;
+  constructor(provider, message, status) {
+    super(message);
+    this.provider = provider;
+    this.status = status;
+    this.name = "SearchProviderError";
+  }
+};
+
+// packages/herd-agent/dist/core/web/search/with-resolved-search-provider.js
+function withResolvedSearchProvider(definition, binding, body) {
+  return {
+    id: definition.id,
+    label: definition.label,
+    providerId: definition.providerId ?? "",
+    requiresAuth: binding,
+    async isAvailable(ctx) {
+      const auth = ctx?.auth;
+      if (auth === void 0)
+        return false;
+      const result = await auth.resolveToken(binding);
+      return result.ok;
+    },
+    async search(params, signal, ctx) {
+      const auth = ctx?.auth;
+      if (auth === void 0) {
+        throw new SearchProviderError(definition.id, `Auth is not available in this context for ${binding.serviceId}.`);
+      }
+      const result = await auth.resolveToken(binding);
+      if (!result.ok) {
+        throw new SearchProviderError(definition.id, result.message);
+      }
+      return body(params, signal, result.auth);
+    }
+  };
+}
+
+// packages/herd-agent/dist/core/tools/tool-parameters.js
+import { z as z5 } from "zod";
+var URI_PAYLOAD_MARKER = "x-kay-uri-payload";
+var URI_PAYLOAD_WIRE_TYPES = [
+  "string",
+  "object",
+  "array",
+  "number",
+  "boolean",
+  "null"
+];
+var uriPayloadSchema = z5.union([
+  z5.string(),
+  z5.record(z5.string(), z5.unknown()),
+  z5.array(z5.unknown()),
+  z5.number(),
+  z5.boolean(),
+  z5.null()
+]).meta({ [URI_PAYLOAD_MARKER]: true });
+function toToolParameters(schema) {
+  const jsonSchema = z5.toJSONSchema(schema, {
+    io: "input",
+    override(ctx) {
+      const node = ctx.jsonSchema;
+      if (node[URI_PAYLOAD_MARKER] === true) {
+        delete node[URI_PAYLOAD_MARKER];
+        delete node["anyOf"];
+        node["type"] = [...URI_PAYLOAD_WIRE_TYPES];
+      }
+    }
+  });
+  const { $schema: _schema, $id: _id, ...rest } = jsonSchema;
+  return rest;
+}
+
+// packages/plugin-primitives/dist/results.js
+function textResult(text, details) {
+  const content = [{ type: "text", text }];
+  return { content, details };
+}
+function contentResult(content, details) {
+  return { content: [...content], details };
+}
+
+// packages/plugin-primitives/dist/transfer.js
+var MAX_BYTES2 = 50 * 1024 * 1024;
+async function readBodyWithByteCap(response, maxBytes) {
+  const reader = response.body?.getReader();
+  if (!reader)
+    return void 0;
+  const chunks = [];
+  let totalSize = 0;
+  let capped = false;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    if (value) {
+      chunks.push(value);
+      totalSize += value.length;
+      if (totalSize > maxBytes) {
+        capped = true;
+        await reader.cancel();
+        break;
+      }
+    }
+  }
+  const bodyBuffer = Buffer.concat(chunks);
+  const bytes = new Uint8Array(bodyBuffer.buffer, bodyBuffer.byteOffset, bodyBuffer.byteLength);
+  return { bytes, capped };
+}
+
+// packages/plugin-sdk/dist/kay-agent/index.js
+import { z as z6 } from "zod";
+
+// packages/plugin-sdk/dist/kay-agent/http-client.js
+var PluginApiError = class extends Error {
+  status;
+  url;
+  bodyText;
+  constructor(init) {
+    super(`Request to ${init.url} failed with status ${init.status}`);
+    this.name = "PluginApiError";
+    this.status = init.status;
+    this.url = init.url;
+    this.bodyText = init.bodyText;
+  }
+};
+async function readErrorBodyText(response) {
+  return response.text().catch(() => "");
+}
+async function readCappedErrorBodyText(response, maxBytes) {
+  const result = await readBodyWithByteCap(response, maxBytes).catch(() => void 0);
+  return result === void 0 ? "" : new TextDecoder().decode(result.bytes.slice(0, maxBytes));
+}
+function mergeHeaders(defaults, overrides) {
+  const headers = new Headers(defaults);
+  if (overrides !== void 0) {
+    for (const [key, value] of Object.entries(overrides))
+      headers.set(key, value);
+  }
+  return headers;
+}
+function withQueryParams(url, params) {
+  if (params === void 0)
+    return url;
+  const target = new URL(url);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0)
+      target.searchParams.set(key, String(value));
+  }
+  return target.toString();
+}
+async function getBytes(url, options, fetchImpl = globalThis.fetch) {
+  const response = await fetchImpl(url, {
+    headers: mergeHeaders(void 0, options.headers),
+    ...options.signal !== void 0 ? { signal: options.signal } : {}
+  });
+  if (!response.ok) {
+    throw new PluginApiError({
+      status: response.status,
+      url,
+      bodyText: await readCappedErrorBodyText(response, options.maxBytes)
+    });
+  }
+  const capRead = await readBodyWithByteCap(response, options.maxBytes);
+  return {
+    status: response.status,
+    headers: response.headers,
+    bytes: capRead?.bytes ?? new Uint8Array(0),
+    capped: capRead?.capped ?? false
+  };
+}
+function createJsonApiClient(options = {}) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  async function requestJson(url, init) {
+    const response = await fetchImpl(url, init);
+    if (!response.ok) {
+      throw new PluginApiError({
+        status: response.status,
+        url,
+        bodyText: await readErrorBodyText(response)
+      });
+    }
+    const body = await response.json();
+    return { status: response.status, headers: response.headers, body };
+  }
+  return {
+    getJson: (url, callOptions) => requestJson(withQueryParams(url, callOptions?.params), {
+      method: "GET",
+      headers: mergeHeaders(void 0, callOptions?.headers),
+      ...callOptions?.signal !== void 0 ? { signal: callOptions.signal } : {}
+    }),
+    postJson: (url, payload2, callOptions) => requestJson(withQueryParams(url, callOptions?.params), {
+      method: "POST",
+      headers: mergeHeaders({ "content-type": "application/json" }, callOptions?.headers),
+      body: JSON.stringify(payload2),
+      ...callOptions?.signal !== void 0 ? { signal: callOptions.signal } : {}
+    }),
+    getBytes: (url, byteOptions) => getBytes(url, byteOptions, fetchImpl)
+  };
+}
+
+// packages/plugin-sdk/dist/kay-agent/readers.js
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function str(record, key) {
+  const value = record?.[key];
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function num(record, key) {
+  const value = record?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function numLike(record, key) {
+  const value = record?.[key];
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : void 0;
+  }
+  return void 0;
+}
+
+// packages/plugin-sdk/dist/kay-agent/base64.js
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function bytesToBase64(bytes) {
+  let output = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] ?? 0;
+    const b1 = bytes[i + 1] ?? 0;
+    const b2 = bytes[i + 2] ?? 0;
+    const triple = b0 << 16 | b1 << 8 | b2;
+    output += BASE64_ALPHABET.charAt(triple >> 18 & 63);
+    output += BASE64_ALPHABET.charAt(triple >> 12 & 63);
+    output += i + 1 < bytes.length ? BASE64_ALPHABET.charAt(triple >> 6 & 63) : "=";
+    output += i + 2 < bytes.length ? BASE64_ALPHABET.charAt(triple & 63) : "=";
+  }
+  return output;
+}
+
+// packages/plugin-sdk/dist/kay-agent/advertisement.js
+function defineKayAgentAdvertisement(advertisement) {
+  return advertisement;
+}
+function rejectDuplicate(category, id, seen) {
+  if (seen.has(id)) {
+    throw new Error(`Duplicate advertised ${category} '${id}'.`);
+  }
+  seen.add(id);
+}
+function rejectImplementationFields(category, value, fields) {
+  for (const field of fields) {
+    if (field in value) {
+      throw new Error(`Advertised ${category} cannot include implementation field '${field}'.`);
+    }
+  }
+}
+function snapshotAdvertisementValue(value, seen = /* @__PURE__ */ new WeakMap()) {
+  if ((typeof value !== "object" || value === null) && typeof value !== "function") {
+    return value;
+  }
+  if (typeof value === "function") {
+    return value;
+  }
+  const existing = seen.get(value);
+  if (existing !== void 0)
+    return existing;
+  if (Array.isArray(value)) {
+    const copy2 = [];
+    seen.set(value, copy2);
+    for (const entry of value) {
+      copy2.push(snapshotAdvertisementValue(entry, seen));
+    }
+    return Object.freeze(copy2);
+  }
+  const copy = /* @__PURE__ */ Object.create(null);
+  seen.set(value, copy);
+  const copiedKeys = /* @__PURE__ */ new Set();
+  let source = value;
+  while (source !== null && source !== Object.prototype) {
+    for (const key of Reflect.ownKeys(source)) {
+      if (key === "constructor" || copiedKeys.has(key))
+        continue;
+      copiedKeys.add(key);
+      copy[key] = snapshotAdvertisementValue(Reflect.get(value, key), seen);
+    }
+    source = Object.getPrototypeOf(source);
+  }
+  return Object.freeze(copy);
+}
+function snapshotDelegatedServiceSource(source) {
+  return () => {
+    const entries = source();
+    if (!Array.isArray(entries)) {
+      throw new Error("An advertised delegated service source must return an array synchronously.");
+    }
+    return Object.freeze(entries.map((entry) => {
+      rejectImplementationFields("delegated service source scheme", entry.scheme, ["connect", "refresh"]);
+      return snapshotAdvertisementValue(entry);
+    }));
+  };
+}
+function collectKayAgentAdvertisement(advertisement) {
+  const tools = [];
+  const uriModules = [];
+  const searchProviders = [];
+  const converters = [];
+  const services = [];
+  const oauthPkceSchemes = [];
+  const apiKeySchemes = [];
+  const externalCliSchemes = [];
+  const delegatedSchemes = [];
+  const delegatedServiceSources = [];
+  const toolNames = /* @__PURE__ */ new Set();
+  const moduleIds = /* @__PURE__ */ new Set();
+  const providerIds = /* @__PURE__ */ new Set();
+  const converterIds = /* @__PURE__ */ new Set();
+  let collecting = true;
+  const assertCollecting = () => {
+    if (!collecting) {
+      throw new Error("The kay.agent advertisement API cannot be used after advertise() returns.");
+    }
+  };
+  const auth = {
+    advertiseService: (descriptor) => {
+      assertCollecting();
+      services.push(snapshotAdvertisementValue(descriptor));
+    },
+    declareOAuthPkceScheme: (serviceId, scheme) => {
+      assertCollecting();
+      rejectImplementationFields("OAuth PKCE scheme", scheme, [
+        "resolveAccountId",
+        "resolveAccounts"
+      ]);
+      oauthPkceSchemes.push(snapshotAdvertisementValue({ serviceId, scheme }));
+    },
+    declareApiKeyScheme: (serviceId, scheme) => {
+      assertCollecting();
+      rejectImplementationFields("API key scheme", scheme, ["validate"]);
+      apiKeySchemes.push(snapshotAdvertisementValue({ serviceId, scheme }));
+    },
+    declareExternalCliScheme: (serviceId, scheme) => {
+      assertCollecting();
+      externalCliSchemes.push(snapshotAdvertisementValue({ serviceId, scheme }));
+    },
+    declareDelegatedScheme: (serviceId, scheme) => {
+      assertCollecting();
+      rejectImplementationFields("delegated scheme", scheme, [
+        "connect",
+        "refresh"
+      ]);
+      delegatedSchemes.push(snapshotAdvertisementValue({ serviceId, scheme }));
+    },
+    registerDelegatedServiceSource: (source) => {
+      assertCollecting();
+      delegatedServiceSources.push(Object.freeze({ source: snapshotDelegatedServiceSource(source) }));
+    }
+  };
+  const api = {
+    uri: {
+      registerModule: (module) => {
+        assertCollecting();
+        rejectImplementationFields("URI module", module, [
+          "locate",
+          "read",
+          "help",
+          "write",
+          "edit",
+          "list",
+          "search",
+          "delete"
+        ]);
+        const snapshot = snapshotAdvertisementValue(module);
+        rejectDuplicate("URI module id", snapshot.id, moduleIds);
+        uriModules.push(snapshot);
+      }
+    },
+    registerTool: (definition) => {
+      assertCollecting();
+      rejectImplementationFields("tool", definition, ["execute"]);
+      const snapshot = snapshotAdvertisementValue(definition);
+      rejectDuplicate("tool name", snapshot.name, toolNames);
+      tools.push(snapshot);
+    },
+    registerSearchProvider: (provider) => {
+      assertCollecting();
+      rejectImplementationFields("search provider", provider, [
+        "isAvailable",
+        "search"
+      ]);
+      const snapshot = snapshotAdvertisementValue(provider);
+      rejectDuplicate("search provider id", snapshot.id, providerIds);
+      searchProviders.push(snapshot);
+    },
+    registerConverter: (converter) => {
+      assertCollecting();
+      rejectImplementationFields("converter", converter, ["convert"]);
+      const snapshot = snapshotAdvertisementValue(converter);
+      rejectDuplicate("converter id", snapshot.id, converterIds);
+      converters.push(snapshot);
+    },
+    auth
+  };
+  let result;
+  try {
+    result = advertisement.advertise(api);
+  } finally {
+    collecting = false;
+  }
+  if (result !== void 0) {
+    void Promise.resolve(result).catch(() => void 0);
+    throw new Error("A kay.agent advertisement must finish synchronously and return undefined.");
+  }
+  return Object.freeze({
+    tools: Object.freeze([...tools]),
+    uriModules: Object.freeze([...uriModules]),
+    searchProviders: Object.freeze([...searchProviders]),
+    converters: Object.freeze([...converters]),
+    auth: Object.freeze({
+      services: Object.freeze([...services]),
+      oauthPkceSchemes: Object.freeze([...oauthPkceSchemes]),
+      apiKeySchemes: Object.freeze([...apiKeySchemes]),
+      externalCliSchemes: Object.freeze([...externalCliSchemes]),
+      delegatedSchemes: Object.freeze([...delegatedSchemes]),
+      delegatedServiceSources: Object.freeze([...delegatedServiceSources])
+    })
+  });
+}
+
+// packages/plugin-sdk/dist/kay-agent/index.js
+function toolParameters(schema) {
+  return toToolParameters(schema);
+}
+function defineTool(definition) {
+  return definition;
+}
+function defineAuthedTool(definition, schema, binding, body) {
+  return withResolvedAuth({ ...definition, parameters: toolParameters(schema) }, binding, (toolCallId, rawParams, signal, onUpdate, ctx, resolvedAuth) => body(toolCallId, schema.parse(rawParams), signal, onUpdate, ctx, resolvedAuth));
+}
+var KayAgentFilesystemError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "KayAgentFilesystemError";
+    this.code = code;
+  }
+};
+var KayAgentCapabilityError = class extends Error {
+  refusal;
+  constructor(refusal, message) {
+    super(message ?? refusal.message);
+    this.name = "KayAgentCapabilityError";
+    this.refusal = refusal;
+  }
+};
+var KayAgentWebSessionError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "KayAgentWebSessionError";
+  }
+};
+export {
+  KayAgentCapabilityError,
+  KayAgentFilesystemError,
+  KayAgentWebSessionError,
+  OBSERVATION_MIME,
+  PluginApiError,
+  SearchProviderError,
+  URI_TEXT_EDIT_SHAPE_SUMMARY,
+  UriConflictError,
+  UriNotFoundError,
+  UriProviderError,
+  UriUnsupportedOperationError,
+  UriValidationError,
+  accountQualifiedUri,
+  applyUriTextEdits,
+  asArray,
+  asRecord,
+  assertResourceUnchanged,
+  basicUriHelp,
+  bytesToBase64,
+  capability,
+  collectKayAgentAdvertisement,
+  contentDigest,
+  contentResult,
+  createFallbackOnlyWithJev,
+  createJsonApiClient,
+  defineAuthedTool,
+  defineKayAgentAdvertisement,
+  defineTool,
+  describeUriTextEditTarget,
+  formatIsoDate,
+  formatNumber,
+  getBytes,
+  jsonResource,
+  lintUriHelpContracts,
+  lintUriTemplate,
+  markdownResource,
+  num,
+  numLike,
+  observationFromResource,
+  observationResource,
+  parseLineSelector,
+  parseUriConnectionSelector,
+  parseUriTextEditPayload,
+  payload,
+  readBodyWithByteCap,
+  str,
+  textResult,
+  toJsonSchema,
+  toolParameters,
+  uriParam,
+  uriTextEditPayloadSchema,
+  withResolvedAuth,
+  withResolvedSearchProvider,
+  z6 as z
+};