@yaklabs-ai/plugin-sdk 0.48.0 → 0.49.0

package/dist/kay-app.js

@@ -1,3 +1,313 @@
+// 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";
+  }
+};
+function requireWriteContent(payload2, uri) {
+  if (payload2 === void 0) {
+    throw new UriValidationError(`Writing ${uri} needs \`content\` (or a \`source\` to copy from): pass the payload this address takes, which its help names.`);
+  }
+  if (payload2 instanceof Uint8Array) {
+    throw new UriValidationError(`${uri} stores text only, so it cannot take raw bytes. Copy the file to an address that accepts bytes.`);
+  }
+  return payload2;
+}
+var UriProviderError = class extends UriError {
+  _tag = "UriProviderError";
+  moduleId;
+  operation;
+  uri;
+  status;
+  providerCode;
+  retryable;
+  /** Provider-directed delay before retrying, in milliseconds. */
+  retryAfterMs;
+  /** See {@link UriProviderErrorOptions.effect}. */
+  effect;
+  /** See {@link UriProviderErrorOptions.refusalMessage}. */
+  refusalMessage;
+  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;
+    }
+    if (options.effect !== void 0)
+      this.effect = options.effect;
+    if (options.refusalMessage !== void 0) {
+      if (options.effect !== "none") {
+        throw new TypeError('refusalMessage requires effect: "none".');
+      }
+      this.refusalMessage = options.refusalMessage;
+    }
+  }
+};
+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/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")}`;
+}
+var DIGEST_PREFIX = "sha256:";
+
+// 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/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 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 }
+  };
+}
+
+// packages/plugin-sdk/dist/uri.js
+function createUnavailableUriCaller(message) {
+  const unavailable = async () => {
+    throw new Error(message);
+  };
+  return {
+    read: unavailable,
+    list: unavailable,
+    search: unavailable,
+    write: unavailable,
+    edit: unavailable,
+    delete: unavailable
+  };
+}
+
 // packages/plugin-protocol/dist/plugin-signal-limits.js
 var PLUGIN_EVENT_REFUSED_ERROR_NAME = "PluginEventRefusedError";
 var PLUGIN_SIGNAL_KINDS = [
@@ -58,17 +368,17 @@ function isCredentialShapedText(value) {
 }
 
 // packages/plugin-protocol/dist/json.js
-import { z } from "zod";
-var JsonValue = z.lazy(() => z.union([
-  z.string(),
-  z.number(),
-  z.boolean(),
-  z.null(),
-  z.array(JsonValue),
-  z.record(z.string(), JsonValue)
+import { z as z5 } from "zod";
+var JsonValue = z5.lazy(() => z5.union([
+  z5.string(),
+  z5.number(),
+  z5.boolean(),
+  z5.null(),
+  z5.array(JsonValue),
+  z5.record(z5.string(), JsonValue)
 ]));
-var JsonObject = z.record(z.string(), JsonValue);
-var JsonSchema = z.record(z.string(), JsonValue);
+var JsonObject = z5.record(z5.string(), JsonValue);
+var JsonSchema = z5.record(z5.string(), JsonValue);
 
 // packages/plugin-sdk/dist/kay-app/card-layout.js
 function element(type, props) {
@@ -104,559 +414,273 @@ function field(type, name, options) {
 function textField(name, options) {
   return field("Field", name, options);
 }
-function textArea(name, options) {
-  return field("TextArea", name, options);
-}
-function select(name, options) {
-  return field("Select", name, options);
-}
-function multiSelect(name, options) {
-  return field("MultiSelect", name, options);
-}
-function switchField(name, options) {
-  return field("Switch", name, options);
-}
-function submit(label) {
-  return {
-    root: "root",
-    elements: {
-      root: {
-        type: "Button",
-        props: { label },
-        on: { press: { action: "submit" } }
-      }
-    }
-  };
-}
-
-// packages/plugin-sdk/dist/signals.js
-import { z as z2 } from "zod";
-function createFallbackOnlySignals() {
-  const noStore = { status: "unavailable", reason: "no-store" };
-  return {
-    observe: (input) => Promise.resolve(invalidObservation(input) ?? {
-      status: "unavailable",
-      reason: "no-system-one",
-      detector: { ...input.detector, rubricDigest: "" },
-      source: input.source,
-      stored: false,
-      deduplicated: false,
-      inputDigest: "",
-      recordedAtMs: Date.now()
-    }),
-    listDetectors: () => Promise.resolve(noStore),
-    list: () => Promise.resolve(noStore)
-  };
-}
-var SIGNAL_TIME_MAX_MS = 864e13;
-var MAX_CHOICE_LABELS = 64;
-var MAX_NAME = 64;
-var MAX_POINTER = 256;
-var MAX_QUESTIONS = 64;
-var DETECTOR_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
-var VERSION = /^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/u;
-var QUESTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
-var POINTER = /^[^\s\p{C}/?#]+$/u;
-var LABEL = /^[^\s,@\p{C}]+(?: [^\s,@\p{C}]+)*$/u;
-var RUN_ID = /^\P{Cc}+$/u;
-var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
-var ObserveShape = z2.looseObject({
-  detector: z2.looseObject({ id: z2.string(), version: z2.string() }),
-  subject: z2.looseObject({ kind: z2.string(), key: z2.string().optional() }).optional(),
-  after: z2.looseObject({ observationId: z2.unknown() }).optional(),
-  reuse: z2.looseObject({ maxAgeMs: z2.unknown() }).optional(),
-  source: z2.looseObject({
-    sessionId: z2.string(),
-    entryId: z2.string(),
-    openerEntryId: z2.string().optional(),
-    runId: z2.string().optional(),
-    occurredAtMs: z2.unknown().optional()
-  }),
-  questions: z2.record(z2.string(), z2.unknown())
-});
-var ChoiceQuestion = z2.looseObject({
-  type: z2.literal("choice"),
-  criteria: z2.record(z2.string(), z2.unknown())
-});
-var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
-var isWhole = (value, min) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= SIGNAL_TIME_MAX_MS;
-var quoted = (value) => JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}\u2026` : value).replace(/(?! )[\s\p{C}]/gu, (char) => `\\u${char.codePointAt(0).toString(16).padStart(4, "0")}`);
-function grammarProblem(input) {
-  const shape = ObserveShape.safeParse(input);
-  if (!shape.success) {
-    const field2 = shape.error.issues[0]?.path.join(".") ?? "";
-    return field2 === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field2}\` is missing or has the wrong type.`;
-  }
-  const { detector, source, questions, subject, after, reuse } = shape.data;
-  const { state } = input;
-  if (typeof state !== "object" || state === null || Array.isArray(state)) {
-    return "`state` must be a JSON object.";
-  }
-  if (!fits(detector.id, DETECTOR_ID)) {
-    return "`detector.id` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
-  }
-  if (!fits(detector.version, VERSION)) {
-    return "`detector.version` must be at most 64 characters: letters and digits in parts joined by single `.`, `-`, or `_`.";
-  }
-  for (const [field2, grammar, rule] of [
-    ["sessionId", POINTER, POINTER_RULE],
-    ["entryId", POINTER, POINTER_RULE],
-    ["openerEntryId", POINTER, POINTER_RULE],
-    [
-      "runId",
-      RUN_ID,
-      `1 to ${MAX_POINTER} characters with no control character`
-    ]
-  ]) {
-    const id = source[field2];
-    if (id !== void 0 && !(id.length <= MAX_POINTER && grammar.test(id))) {
-      return `\`source.${field2}\` must be ${rule}.`;
-    }
-  }
-  const occurredAtMs = source.occurredAtMs;
-  if (occurredAtMs !== void 0 && !(typeof occurredAtMs === "number" && Number.isSafeInteger(occurredAtMs) && occurredAtMs >= 0 && occurredAtMs <= SIGNAL_TIME_MAX_MS)) {
-    return `\`source.occurredAtMs\` must be whole epoch milliseconds from 0 to ${SIGNAL_TIME_MAX_MS}.`;
-  }
-  if (subject !== void 0 && !fits(subject.kind, DETECTOR_ID)) {
-    return "`subject.kind` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
-  }
-  if (subject?.key !== void 0 && !(subject.key.length <= MAX_POINTER && POINTER.test(subject.key))) {
-    return `\`subject.key\` must be ${POINTER_RULE}.`;
-  }
-  if (after !== void 0 && !isWhole(after.observationId, 1)) {
-    return "`after.observationId` must be a positive whole number: the id of a stored signal.";
-  }
-  if (reuse !== void 0) {
-    if (!isWhole(reuse.maxAgeMs, 1)) {
-      return `\`reuse.maxAgeMs\` must be whole milliseconds from 1 to ${SIGNAL_TIME_MAX_MS}.`;
-    }
-    if (subject?.key === void 0) {
-      return "`reuse` needs `subject.key`: a stored answer is reused only for the same subject.";
-    }
-  }
-  const names = Object.keys(questions);
-  if (names.length === 0 || names.length > MAX_QUESTIONS) {
-    return `\`questions\` must ask 1 to ${MAX_QUESTIONS} questions.`;
-  }
-  for (const name of names) {
-    if (!fits(name, QUESTION_NAME)) {
-      return `The question name ${quoted(name)} must be an identifier of at most 64 characters: letters, digits, and \`_\`, not starting with a digit.`;
-    }
-    const choice = ChoiceQuestion.safeParse(questions[name]);
-    if (!choice.success)
-      continue;
-    const labels = Object.keys(choice.data.criteria);
-    if (labels.length > MAX_CHOICE_LABELS) {
-      return `The choice question \`${name}\` offers ${labels.length} labels; at most ${MAX_CHOICE_LABELS}.`;
-    }
-    const bad = labels.find((label) => !fits(label, LABEL));
-    if (bad !== void 0) {
-      return `The choice question \`${name}\` offers the label ${quoted(bad)}, which a \`where\` filter cannot name: a label is 1 to 64 characters with no \`,\`, \`@\`, or control or invisible character, and no whitespace but single spaces between words.`;
-    }
-  }
-  return void 0;
-}
-var EchoText = z2.string().catch("");
-var Echo = z2.object({
-  detector: z2.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
-  source: z2.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
-}).catch({
-  detector: { id: "", version: "" },
-  source: { sessionId: "", entryId: "" }
-});
-function invalidObservation(input) {
-  const reason = grammarProblem(input);
-  if (reason === void 0)
-    return void 0;
-  const { detector, source } = Echo.parse(input);
-  return {
-    status: "invalid",
-    reason,
-    detector: { ...detector, rubricDigest: "" },
-    source,
-    stored: false,
-    deduplicated: false,
-    inputDigest: "",
-    recordedAtMs: Date.now()
-  };
-}
-
-// packages/herd-transcript/dist/record-kinds.js
-var STORED_TRANSCRIPT_MESSAGE_KINDS = [
-  "user",
-  "assistant",
-  "tool_result",
-  "custom_message:*",
-  "compaction",
-  "branch_summary"
-];
-var NAMED_KINDS = /* @__PURE__ */ new Set([
-  "user",
-  "assistant",
-  "tool_result",
-  "compaction",
-  "branch_summary",
-  "other",
-  "unreadable"
-]);
-var ROLE_KINDS = {
-  user: "user",
-  assistant: "assistant",
-  toolResult: "tool_result"
-};
-function storedTranscriptKindOf(record) {
-  if (!("entry" in record))
-    return "unreadable";
-  const entry = record.entry;
-  switch (entry.type) {
-    case "message": {
-      const message = entry.message;
-      if (message.role === "custom") {
-        return `custom_message:${typeof message.customType === "string" ? message.customType : ""}`;
-      }
-      return (typeof message.role === "string" ? ROLE_KINDS[message.role] : void 0) ?? "other";
-    }
-    case "custom":
-      return `custom:${entry.customType}`;
-    case "compaction":
-      return "compaction";
-    case "branch_summary":
-      return "branch_summary";
-    default:
-      return "other";
-  }
+function textArea(name, options) {
+  return field("TextArea", name, options);
 }
-function parseStoredTranscriptKindFilter(tokens) {
-  const exact = /* @__PURE__ */ new Set();
-  const families = /* @__PURE__ */ new Set();
-  let all = false;
-  for (const raw of tokens) {
-    const token = raw.trim();
-    if (token === "all") {
-      all = true;
-    } else if (token === "messages") {
-      for (const kind of STORED_TRANSCRIPT_MESSAGE_KINDS)
-        addToken(kind);
-    } else if (!addToken(token)) {
-      return { ok: false, invalid: raw };
-    }
-  }
+function select(name, options) {
+  return field("Select", name, options);
+}
+function multiSelect(name, options) {
+  return field("MultiSelect", name, options);
+}
+function switchField(name, options) {
+  return field("Switch", name, options);
+}
+function submit(label) {
   return {
-    ok: true,
-    filter: {
-      includes: (kind) => all || exact.has(kind) || families.has(kind.slice(0, kind.indexOf(":") + 1))
+    root: "root",
+    elements: {
+      root: {
+        type: "Button",
+        props: { label },
+        on: { press: { action: "submit" } }
+      }
     }
   };
-  function addToken(token) {
-    if (NAMED_KINDS.has(token)) {
-      exact.add(token);
-      return true;
-    }
-    const family = /^(custom|custom_message):(.+)$/.exec(token);
-    if (family === null)
-      return false;
-    if (family[2] === "*")
-      families.add(`${family[1]}:`);
-    else
-      exact.add(token);
-    return true;
-  }
 }
-var STORED_TRANSCRIPT_MESSAGE_FILTER = (() => {
-  const parsed = parseStoredTranscriptKindFilter(STORED_TRANSCRIPT_MESSAGE_KINDS);
-  if (!parsed.ok)
-    throw new Error(`invalid default kinds: ${parsed.invalid}`);
-  return parsed.filter;
-})();
-
-// packages/plugin-sdk/dist/kay-app/index.js
-import { pathToFileURL } from "node:url";
 
-// 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;
+// packages/plugin-sdk/dist/signals.js
+import { z as z6 } from "zod";
+function createFallbackOnlySignals() {
+  const noStore = { status: "unavailable", reason: "no-store" };
+  return {
+    observe: (input) => Promise.resolve(invalidObservation(input) ?? {
+      status: "unavailable",
+      reason: "no-system-one",
+      detector: { ...input.detector, rubricDigest: "" },
+      source: input.source,
+      stored: false,
+      deduplicated: false,
+      inputDigest: "",
+      recordedAtMs: Date.now()
+    }),
+    listDetectors: () => Promise.resolve(noStore),
+    list: () => Promise.resolve(noStore)
+  };
+}
+var SIGNAL_TIME_MAX_MS = 864e13;
+var MAX_CHOICE_LABELS = 64;
+var MAX_NAME = 64;
+var MAX_POINTER = 256;
+var MAX_QUESTIONS = 64;
+var DETECTOR_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+var VERSION = /^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/u;
+var QUESTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+var POINTER = /^[^\s\p{C}/?#]+$/u;
+var LABEL = /^[^\s,@\p{C}]+(?: [^\s,@\p{C}]+)*$/u;
+var RUN_ID = /^\P{Cc}+$/u;
+var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
+var ObserveShape = z6.looseObject({
+  detector: z6.looseObject({ id: z6.string(), version: z6.string() }),
+  subject: z6.looseObject({ kind: z6.string(), key: z6.string().optional() }).optional(),
+  after: z6.looseObject({ observationId: z6.unknown() }).optional(),
+  reuse: z6.looseObject({ maxAgeMs: z6.unknown() }).optional(),
+  source: z6.looseObject({
+    sessionId: z6.string(),
+    entryId: z6.string(),
+    openerEntryId: z6.string().optional(),
+    runId: z6.string().optional(),
+    occurredAtMs: z6.unknown().optional()
+  }),
+  questions: z6.record(z6.string(), z6.unknown())
+});
+var ChoiceQuestion = z6.looseObject({
+  type: z6.literal("choice"),
+  criteria: z6.record(z6.string(), z6.unknown())
+});
+var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
+var isWhole = (value, min) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= SIGNAL_TIME_MAX_MS;
+var quoted = (value) => JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}\u2026` : value).replace(/(?! )[\s\p{C}]/gu, (char) => `\\u${char.codePointAt(0).toString(16).padStart(4, "0")}`);
+function grammarProblem(input) {
+  const shape = ObserveShape.safeParse(input);
+  if (!shape.success) {
+    const field2 = shape.error.issues[0]?.path.join(".") ?? "";
+    return field2 === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field2}\` is missing or has the wrong type.`;
   }
-};
-var UriValidationError = class extends UriError {
-  _tag = "UriValidationError";
-  constructor(message) {
-    super(message);
-    this.name = "UriValidationError";
+  const { detector, source, questions, subject, after, reuse } = shape.data;
+  const { state } = input;
+  if (typeof state !== "object" || state === null || Array.isArray(state)) {
+    return "`state` must be a JSON object.";
   }
-};
-function requireWriteContent(payload2, uri) {
-  if (payload2 === void 0) {
-    throw new UriValidationError(`Writing ${uri} needs \`content\` (or a \`source\` to copy from): pass the payload this address takes, which its help names.`);
+  if (!fits(detector.id, DETECTOR_ID)) {
+    return "`detector.id` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
   }
-  if (payload2 instanceof Uint8Array) {
-    throw new UriValidationError(`${uri} stores text only, so it cannot take raw bytes. Copy the file to an address that accepts bytes.`);
+  if (!fits(detector.version, VERSION)) {
+    return "`detector.version` must be at most 64 characters: letters and digits in parts joined by single `.`, `-`, or `_`.";
   }
-  return payload2;
-}
-var UriProviderError = class extends UriError {
-  _tag = "UriProviderError";
-  moduleId;
-  operation;
-  uri;
-  status;
-  providerCode;
-  retryable;
-  /** Provider-directed delay before retrying, in milliseconds. */
-  retryAfterMs;
-  /** See {@link UriProviderErrorOptions.effect}. */
-  effect;
-  /** See {@link UriProviderErrorOptions.refusalMessage}. */
-  refusalMessage;
-  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;
-    }
-    if (options.effect !== void 0)
-      this.effect = options.effect;
-    if (options.refusalMessage !== void 0) {
-      if (options.effect !== "none") {
-        throw new TypeError('refusalMessage requires effect: "none".');
-      }
-      this.refusalMessage = options.refusalMessage;
+  for (const [field2, grammar, rule] of [
+    ["sessionId", POINTER, POINTER_RULE],
+    ["entryId", POINTER, POINTER_RULE],
+    ["openerEntryId", POINTER, POINTER_RULE],
+    [
+      "runId",
+      RUN_ID,
+      `1 to ${MAX_POINTER} characters with no control character`
+    ]
+  ]) {
+    const id = source[field2];
+    if (id !== void 0 && !(id.length <= MAX_POINTER && grammar.test(id))) {
+      return `\`source.${field2}\` must be ${rule}.`;
     }
   }
-};
-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/operations.js
-import { z as z3 } from "zod";
-var URI_OPERATIONS = [
-  "help",
-  "read",
-  "write",
-  "edit",
-  "list",
-  "search",
-  "delete"
-];
-var UriOperationSchema = z3.enum(URI_OPERATIONS);
-
-// packages/herd-uri/dist/help-schema.js
-import { z as z4 } from "zod";
-var UriContractJsonSchema = z4.record(z4.string(), z4.unknown());
-var UriParameterSchema = z4.strictObject({
-  name: z4.string().min(1),
-  in: z4.enum(["uri", "query", "selector"]),
-  required: z4.boolean(),
-  description: z4.string().optional(),
-  schema: UriContractJsonSchema,
-  examples: z4.array(z4.unknown()).optional()
-});
-var UriPayloadContractSchema = z4.strictObject({
-  name: z4.string().min(1),
-  mediaType: z4.string().optional(),
-  description: z4.string().optional(),
-  schema: UriContractJsonSchema.optional(),
-  semanticConstraints: z4.array(z4.string().min(1)).min(1).optional(),
-  examples: z4.array(z4.unknown()).optional()
-});
-
-// packages/herd-uri/dist/text-edit.js
-import { z as z5 } from "zod";
-var findReplaceArm = z5.strictObject({
-  find: z5.string().min(1),
-  replace: z5.string(),
-  all: z5.boolean().optional()
-});
-var oldNewEntry = z5.strictObject({
-  oldText: z5.string().min(1),
-  newText: z5.string()
-});
-var uriTextEditPayloadArms = z5.union([
-  findReplaceArm,
-  z5.strictObject({ edits: z5.array(oldNewEntry).min(1) }),
-  oldNewEntry,
-  z5.array(oldNewEntry).min(1)
-]);
-
-// 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 occurredAtMs = source.occurredAtMs;
+  if (occurredAtMs !== void 0 && !(typeof occurredAtMs === "number" && Number.isSafeInteger(occurredAtMs) && occurredAtMs >= 0 && occurredAtMs <= SIGNAL_TIME_MAX_MS)) {
+    return `\`source.occurredAtMs\` must be whole epoch milliseconds from 0 to ${SIGNAL_TIME_MAX_MS}.`;
   }
-  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 };
+  if (subject !== void 0 && !fits(subject.kind, DETECTOR_ID)) {
+    return "`subject.kind` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
   }
-  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;
+  if (subject?.key !== void 0 && !(subject.key.length <= MAX_POINTER && POINTER.test(subject.key))) {
+    return `\`subject.key\` must be ${POINTER_RULE}.`;
+  }
+  if (after !== void 0 && !isWhole(after.observationId, 1)) {
+    return "`after.observationId` must be a positive whole number: the id of a stored signal.";
+  }
+  if (reuse !== void 0) {
+    if (!isWhole(reuse.maxAgeMs, 1)) {
+      return `\`reuse.maxAgeMs\` must be whole milliseconds from 1 to ${SIGNAL_TIME_MAX_MS}.`;
+    }
+    if (subject?.key === void 0) {
+      return "`reuse` needs `subject.key`: a stored answer is reused only for the same subject.";
     }
-    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);
+  const names = Object.keys(questions);
+  if (names.length === 0 || names.length > MAX_QUESTIONS) {
+    return `\`questions\` must ask 1 to ${MAX_QUESTIONS} questions.`;
+  }
+  for (const name of names) {
+    if (!fits(name, QUESTION_NAME)) {
+      return `The question name ${quoted(name)} must be an identifier of at most 64 characters: letters, digits, and \`_\`, not starting with a digit.`;
+    }
+    const choice = ChoiceQuestion.safeParse(questions[name]);
+    if (!choice.success)
       continue;
+    const labels = Object.keys(choice.data.criteria);
+    if (labels.length > MAX_CHOICE_LABELS) {
+      return `The choice question \`${name}\` offers ${labels.length} labels; at most ${MAX_CHOICE_LABELS}.`;
+    }
+    const bad = labels.find((label) => !fits(label, LABEL));
+    if (bad !== void 0) {
+      return `The choice question \`${name}\` offers the label ${quoted(bad)}, which a \`where\` filter cannot name: a label is 1 to 64 characters with no \`,\`, \`@\`, or control or invisible character, and no whitespace but single spaces between words.`;
     }
-    const parsed = parseRangeListToken(token);
-    if (parsed === void 0)
-      break;
-    if (ranges !== void 0)
-      break;
-    ranges = parsed;
-    address = address.slice(0, colon);
   }
+  return void 0;
+}
+var EchoText = z6.string().catch("");
+var Echo = z6.object({
+  detector: z6.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
+  source: z6.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
+}).catch({
+  detector: { id: "", version: "" },
+  source: { sessionId: "", entryId: "" }
+});
+function invalidObservation(input) {
+  const reason = grammarProblem(input);
+  if (reason === void 0)
+    return void 0;
+  const { detector, source } = Echo.parse(input);
   return {
-    address,
-    selector: { ranges: ranges ? mergeRanges(ranges) : [], raw }
+    status: "invalid",
+    reason,
+    detector: { ...detector, rubricDigest: "" },
+    source,
+    stored: false,
+    deduplicated: false,
+    inputDigest: "",
+    recordedAtMs: Date.now()
   };
 }
 
-// packages/herd-uri/dist/schema/to-json-schema.js
-import { z as z6 } from "zod";
-function toJsonSchema(schema) {
-  if (schema instanceof z6.ZodType) {
-    const { $schema: _dialect, ...value } = z6.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;
+// packages/herd-transcript/dist/record-kinds.js
+var STORED_TRANSCRIPT_MESSAGE_KINDS = [
+  "user",
+  "assistant",
+  "tool_result",
+  "custom_message:*",
+  "compaction",
+  "branch_summary"
+];
+var NAMED_KINDS = /* @__PURE__ */ new Set([
+  "user",
+  "assistant",
+  "tool_result",
+  "compaction",
+  "branch_summary",
+  "other",
+  "unreadable"
+]);
+var ROLE_KINDS = {
+  user: "user",
+  assistant: "assistant",
+  toolResult: "tool_result"
+};
+function storedTranscriptKindOf(record) {
+  if (!("entry" in record))
+    return "unreadable";
+  const entry = record.entry;
+  switch (entry.type) {
+    case "message": {
+      const message = entry.message;
+      if (message.role === "custom") {
+        return `custom_message:${typeof message.customType === "string" ? message.customType : ""}`;
+      }
+      return (typeof message.role === "string" ? ROLE_KINDS[message.role] : void 0) ?? "other";
+    }
+    case "custom":
+      return `custom:${entry.customType}`;
+    case "compaction":
+      return "compaction";
+    case "branch_summary":
+      return "branch_summary";
+    default:
+      return "other";
   }
-  return structuredClone(schema);
 }
-
-// packages/herd-uri/dist/schema/helpers.js
-function payload(name, schema, options = {}) {
+function parseStoredTranscriptKindFilter(tokens) {
+  const exact = /* @__PURE__ */ new Set();
+  const families = /* @__PURE__ */ new Set();
+  let all = false;
+  for (const raw of tokens) {
+    const token = raw.trim();
+    if (token === "all") {
+      all = true;
+    } else if (token === "messages") {
+      for (const kind of STORED_TRANSCRIPT_MESSAGE_KINDS)
+        addToken(kind);
+    } else if (!addToken(token)) {
+      return { ok: false, invalid: raw };
+    }
+  }
   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 }
+    ok: true,
+    filter: {
+      includes: (kind) => all || exact.has(kind) || families.has(kind.slice(0, kind.indexOf(":") + 1))
+    }
   };
+  function addToken(token) {
+    if (NAMED_KINDS.has(token)) {
+      exact.add(token);
+      return true;
+    }
+    const family = /^(custom|custom_message):(.+)$/.exec(token);
+    if (family === null)
+      return false;
+    if (family[2] === "*")
+      families.add(`${family[1]}:`);
+    else
+      exact.add(token);
+    return true;
+  }
 }
+var STORED_TRANSCRIPT_MESSAGE_FILTER = (() => {
+  const parsed = parseStoredTranscriptKindFilter(STORED_TRANSCRIPT_MESSAGE_KINDS);
+  if (!parsed.ok)
+    throw new Error(`invalid default kinds: ${parsed.invalid}`);
+  return parsed.filter;
+})();
+
+// packages/plugin-sdk/dist/kay-app/index.js
+import { pathToFileURL } from "node:url";
 
 // packages/plugin-sdk/dist/kay-app/auth.js
 var KayAppCredentialRejectedError = class extends Error {
@@ -880,6 +904,60 @@ function refusedCountOf(error) {
   return typeof count === "number" && Number.isSafeInteger(count) && count > 0 ? count : 1;
 }
 
+// packages/plugin-sdk/dist/kay-agent/declared-tool.js
+function declaredToolPermission(permission) {
+  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix, resourceTrim, defaultPermission, classificationRules } = permission;
+  return {
+    kind,
+    ...scheme === void 0 ? {} : { scheme },
+    ...ruleKey === void 0 ? {} : { ruleKey },
+    ...defaultPermission === void 0 ? {} : { defaultPermission },
+    ...classificationRules === void 0 ? {} : {
+      deriveClassification: (input) => {
+        const rule = classificationRules.find((candidate) => candidate.when.every((condition) => {
+          const value = Object.hasOwn(input, condition.arg) ? input[condition.arg] : void 0;
+          return "equals" in condition ? value === condition.equals : value !== void 0 === condition.present;
+        }));
+        return rule === void 0 ? void 0 : {
+          kind: rule.kind,
+          ...rule.ruleKey === void 0 ? {} : { ruleKey: rule.ruleKey }
+        };
+      }
+    },
+    ...resourceArgs === void 0 ? {} : {
+      deriveResources: (input) => resourceArgs.flatMap((arg) => {
+        const value = input[arg];
+        return typeof value === "string" ? [
+          `${resourcePrefix ?? ""}${resourceTrim === true ? value.trim() : value}`
+        ] : [];
+      })
+    }
+  };
+}
+
+// packages/plugin-sdk/dist/kay-app/declared-tool.js
+function declaredAppToolDefinition(tool, implementation) {
+  if (tool.parameters === void 0 || tool.description === void 0) {
+    throw new Error(`Tool '${tool.toolName}' declares no parameters or description.`);
+  }
+  const { permission: preview, label: _label, description: _description, parameters: _parameters, executionMode: _executionMode, promptSnippet: _promptSnippet, promptGuidelines: _promptGuidelines, ...callbacks } = implementation;
+  return {
+    ...callbacks,
+    label: tool.displayName ?? tool.toolName,
+    description: tool.description,
+    parameters: tool.parameters,
+    ...tool.executionMode === void 0 ? {} : { executionMode: tool.executionMode },
+    ...tool.promptSnippet === void 0 ? {} : { promptSnippet: tool.promptSnippet },
+    ...tool.promptGuidelines === void 0 ? {} : { promptGuidelines: tool.promptGuidelines },
+    ...tool.permission === void 0 ? {} : {
+      permission: {
+        ...declaredToolPermission(tool.permission),
+        ...preview?.describePreview === void 0 ? {} : { describePreview: preview.describePreview }
+      }
+    }
+  };
+}
+
 // packages/plugin-sdk/dist/kay-app/sealing.js
 var KAY_APP_SEALING_MAX_BYTES = 1048576;
 function createUnavailableSealing(message) {
@@ -1024,13 +1102,16 @@ export {
   UriUnsupportedOperationError,
   UriValidationError,
   card,
+  contentDigest,
   createConsoleKayPluginLog,
   createFallbackOnlySignals,
   createKayPluginLog,
   createUnavailableSealing,
   createUnavailableSkills,
   createUnavailableTools,
+  createUnavailableUriCaller,
   createUnavailableUsage,
+  declaredAppToolDefinition,
   definePoller,
   failedRunCause,
   invalidObservation,