@yaklabs-ai/plugin-sdk 0.45.0 → 0.46.0

package/dist/artifact-provenance.js

@@ -0,0 +1,565 @@
+// packages/plugin-protocol/dist/artifact-provenance.js
+import { z as z2 } from "zod";
+
+// packages/plugin-protocol/dist/session-provenance.js
+import { z } from "zod";
+var NonEmptyString = z.string().min(1);
+var SessionId = NonEmptyString;
+var SessionRelationship = z.discriminatedUnion("kind", [
+  /** Spawn lineage: this session is a subagent child of `sessionId`. */
+  z.strictObject({ kind: z.literal("child-of"), sessionId: SessionId }),
+  /**
+   * This session was forked from a point in `sessionId`'s transcript - `/fork`, and every
+   * hindsight followup. `atEntryId` pins the fork point when one was given.
+   */
+  z.strictObject({
+    kind: z.literal("forked-from"),
+    sessionId: SessionId,
+    atEntryId: NonEmptyString.optional()
+  })
+]);
+var SdkSessionDoor = z.enum([
+  "sessions.create",
+  "sessions.run",
+  "hindsight.runFollowup",
+  "agents.run"
+]);
+var SessionCreator = z.discriminatedUnion("kind", [
+  /** A person, at the keyboard. `surface` names a scripted experience when one minted it. */
+  z.strictObject({
+    kind: z.literal("human"),
+    surface: NonEmptyString.optional()
+  }),
+  /** Another session's agent, through a tool call. */
+  z.strictObject({
+    kind: z.literal("agent"),
+    sessionId: SessionId,
+    tool: NonEmptyString,
+    /**
+     * The PARENT SESSION RUN that was driving when this session was minted
+     * (R2 provenance). Optional at parse so old rows stay readable; required
+     * of new agent producers. Absence on a new row is reported as a
+     * `legacy-run-id-missing` gap, never synthesized.
+     */
+    runId: NonEmptyString.optional(),
+    /**
+     * Correlation only; never part of identity. A missing or reused
+     * `toolCallId` must not block the exact parent-run link and never
+     * participates in mutation-result identity.
+     */
+    toolCallId: NonEmptyString.optional()
+  }),
+  /** A plugin, through one of its SDK doors. */
+  z.strictObject({
+    kind: z.literal("plugin"),
+    pluginId: NonEmptyString,
+    door: SdkSessionDoor,
+    callerSessionId: SessionId.optional()
+  }),
+  /** An automation binding that fired; the run id links its durable execution. */
+  z.strictObject({
+    kind: z.literal("trigger"),
+    automationId: NonEmptyString,
+    /**
+     * The AUTOMATION RUN that fired the binding (R2 provenance). Optional at
+     * parse so old rows stay readable; required of new automation producers.
+     * Absence on a new row is reported as a `legacy-run-id-missing` gap,
+     * never synthesized from the binding or a timestamp.
+     */
+    runId: NonEmptyString.optional(),
+    bindingName: NonEmptyString,
+    triggerKind: z.enum([
+      "cron",
+      "time",
+      "occurrence",
+      "uri-change",
+      "plugin-event",
+      "manual"
+    ])
+  }),
+  /** The daemon itself, for one of its own capabilities. */
+  z.strictObject({ kind: z.literal("daemon"), capability: NonEmptyString })
+]);
+var SessionDefiner = z.discriminatedUnion("layer", [
+  z.strictObject({
+    layer: z.literal("plugin"),
+    pluginId: NonEmptyString,
+    capability: NonEmptyString,
+    /** See the type docblock: unpopulated by design until #5230's children land. */
+    version: NonEmptyString.optional()
+  }),
+  z.strictObject({ layer: z.literal("host"), capability: NonEmptyString })
+]);
+var SessionIntent = z.enum(["interactive", "headless"]);
+var SessionCausedByEventShape = z.strictObject({
+  /** The plugin's own name for the subscribe handler that made this run, e.g. `"work-record"`. */
+  handler: NonEmptyString,
+  /** Absent reads as `"session-event"` - see this type's own doc comment. */
+  kind: z.enum(["session-event", "backfill"]).optional(),
+  /** Required when `kind` is `"session-event"` or absent; must be omitted when `kind` is `"backfill"`. */
+  event: z.strictObject({
+    /** {@link KayAppSessionEventType} in `@bonsai/plugin-sdk`, mirrored: a closed, extensible union. */
+    type: z.enum([
+      "turn-settled",
+      "phase-shift",
+      "human-message",
+      "assistant-message",
+      "ui-action"
+    ]),
+    entryId: NonEmptyString,
+    /** The source run captured at the event boundary; absence remains unresolved. */
+    runId: NonEmptyString.optional(),
+    /** Exact prior persisted boundary for a projected human-message event; null means empty history. */
+    throughEntryId: NonEmptyString.nullable().optional()
+  }).optional(),
+  /**
+   * The plugin-supplied exact-match dedupe key, when it gave one. Absent when the handler chose
+   * not to dedupe this run (every call is admitted). Carried here (not just checked and
+   * discarded) so a later reader can explain WHY the host refused a same-keyed second run. A
+   * `"backfill"` cause always supplies one (`backfill:${sessionId}`) so a sweep can never
+   * double-run the same historical session, but that is a caller convention, not a schema rule.
+   */
+  dedupeKey: NonEmptyString.optional()
+});
+var SessionCausedByEvent = SessionCausedByEventShape.refine((value) => (value.kind ?? "session-event") === "backfill" || value.event !== void 0, {
+  message: 'event is required unless kind is "backfill"',
+  path: ["event"]
+}).refine((value) => value.kind !== "backfill" || value.event === void 0, {
+  message: 'event must be omitted when kind is "backfill"',
+  path: ["event"]
+});
+var SessionProvenanceRecord = z.strictObject({
+  relationships: z.array(SessionRelationship),
+  createdBy: SessionCreator,
+  definedBy: SessionDefiner,
+  intent: SessionIntent,
+  /** See {@link SessionCausedByEvent}. Present only alongside `createdBy.door === "agents.run"`. */
+  causedByEvent: SessionCausedByEvent.optional()
+});
+
+// packages/plugin-protocol/dist/artifact-provenance.js
+var ARTIFACT_PROVENANCE_VERSION = "kay.artifact-provenance.v1";
+function hasControlCharacter(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 31 || code === 127)
+      return true;
+  }
+  return false;
+}
+function isProvenanceJson(input) {
+  const active = /* @__PURE__ */ new Set();
+  const stack = [{ value: input }];
+  while (stack.length > 0) {
+    const { value, leave } = stack.pop();
+    if (value === null || typeof value === "boolean")
+      continue;
+    if (typeof value === "string") {
+      if (hasControlCharacter(value))
+        return false;
+      continue;
+    }
+    if (typeof value === "number") {
+      if (!Number.isFinite(value) || Object.is(value, -0))
+        return false;
+      continue;
+    }
+    if (typeof value !== "object")
+      return false;
+    if (leave) {
+      active.delete(value);
+      continue;
+    }
+    if (active.has(value))
+      return false;
+    const array = Array.isArray(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (!array && prototype !== Object.prototype && prototype !== null)
+      return false;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const keys = Reflect.ownKeys(descriptors).filter((key) => !array || key !== "length");
+    if (array && (keys.length !== value.length || keys.some((key, index) => key !== String(index))))
+      return false;
+    active.add(value);
+    stack.push({ value, leave: true });
+    for (const key of keys) {
+      if (typeof key !== "string" || hasControlCharacter(key))
+        return false;
+      const descriptor = descriptors[key];
+      if (!descriptor.enumerable || !("value" in descriptor))
+        return false;
+      stack.push({ value: descriptor.value });
+    }
+  }
+  return true;
+}
+var Text = z2.string().min(1).refine((value) => !hasControlCharacter(value), {
+  message: "Provenance text must not contain control characters"
+});
+var ArtifactProvenanceRevision = z2.strictObject({
+  storeId: Text,
+  artifactId: Text,
+  uri: Text.optional(),
+  /** The enclosing commit is resolved by the reader, avoiding a self-referential commit hash. */
+  revision: z2.union([
+    Text,
+    z2.strictObject({ kind: z2.literal("enclosing-commit") }),
+    z2.null()
+  ]),
+  operationId: Text.nullable(),
+  /** Optional when the store identifies revisions without content addressing (including tombstones). */
+  digest: z2.strictObject({ algorithm: Text, value: Text }).optional()
+});
+var ArtifactProvenanceActor = z2.discriminatedUnion("kind", [
+  z2.strictObject({
+    kind: z2.literal("session"),
+    sessionId: Text,
+    runId: Text.nullable()
+  }),
+  z2.strictObject({
+    kind: z2.literal("human"),
+    userId: Text.optional(),
+    surface: Text
+  }),
+  z2.strictObject({
+    kind: z2.literal("plugin"),
+    pluginId: Text,
+    capability: Text
+  }),
+  z2.strictObject({ kind: z2.literal("host"), capability: Text }),
+  z2.strictObject({ kind: z2.literal("import"), source: Text }),
+  z2.strictObject({ kind: z2.literal("unknown") })
+]);
+var ArtifactProvenanceCause = z2.discriminatedUnion("kind", [
+  z2.strictObject({
+    kind: z2.literal("session"),
+    sessionId: Text,
+    runId: Text.nullable()
+  }),
+  z2.strictObject({
+    kind: z2.literal("session-event"),
+    sessionId: Text,
+    cause: SessionCausedByEvent
+  }),
+  z2.strictObject({
+    kind: z2.literal("automation"),
+    automationId: Text,
+    runId: Text.nullable()
+  }),
+  z2.strictObject({ kind: z2.literal("operation"), operationId: Text })
+]);
+var ArtifactProvenanceOperation = z2.strictObject({
+  id: Text.nullable(),
+  at: z2.iso.datetime().nullable(),
+  name: Text,
+  actor: ArtifactProvenanceActor,
+  /** Null means no tool invocation; a known invocation with an unknown id records a gap. */
+  invocation: z2.strictObject({
+    tool: Text,
+    toolCallId: Text.nullable(),
+    origin: z2.enum(["model", "host"])
+  }).nullable(),
+  /** Known causes only; unavailable cause capture requires a gap, never a guessed creation cause. */
+  causes: z2.array(ArtifactProvenanceCause)
+});
+var ArtifactProvenanceReference = z2.discriminatedUnion("kind", [
+  z2.strictObject({
+    kind: z2.literal("session"),
+    sessionId: Text,
+    runId: Text.optional()
+  }),
+  z2.strictObject({
+    kind: z2.literal("artifact"),
+    revision: ArtifactProvenanceRevision
+  }),
+  z2.strictObject({
+    kind: z2.literal("resource"),
+    uri: Text,
+    revision: Text.nullable()
+  })
+]);
+var ArtifactProvenanceGap = z2.strictObject({
+  code: z2.enum([
+    "unknown",
+    "capture-failed",
+    "legacy-derived",
+    "ambiguous-predecessor",
+    "unverified-index",
+    "missing-ancestor",
+    "cycle",
+    "truncated",
+    "metadata-write-failed",
+    "invalid-record"
+  ]),
+  /** JSON Pointer into this envelope; the empty pointer covers the whole capture. */
+  at: z2.string().regex(/^(?:\/(?:[^~/]|~[01])*)*$/).refine((value) => !hasControlCharacter(value)),
+  detail: Text.optional()
+}).refine((gap) => gap.at !== "" || gap.code === "capture-failed", {
+  message: "Only a whole-capture failure may cover the entire envelope"
+});
+var ArtifactProvenanceSession = z2.strictObject({
+  sessionId: Text,
+  basis: z2.enum(["recorded", "legacy-derived", "unverified-index", "missing"]),
+  record: SessionProvenanceRecord.nullable()
+});
+var ArtifactProvenanceSource = z2.strictObject({
+  relationship: z2.enum([
+    "revision-of",
+    "copied-from",
+    "harvested-from",
+    "restored-from",
+    "accepted-from",
+    "imported-from"
+  ]),
+  revision: ArtifactProvenanceRevision
+});
+var ArtifactProvenanceMutation = z2.strictObject({
+  kind: z2.enum([
+    "create",
+    "update",
+    "delete",
+    "copy",
+    "harvest",
+    "restore",
+    "accept",
+    "import"
+  ]),
+  target: ArtifactProvenanceRevision,
+  /** Retained from the source on copies/acceptance; operation.actor is the persistence actor. */
+  producer: ArtifactProvenanceOperation,
+  sources: z2.array(ArtifactProvenanceSource)
+});
+var Envelope = z2.strictObject({
+  version: z2.literal(ARTIFACT_PROVENANCE_VERSION),
+  operation: ArtifactProvenanceOperation,
+  artifacts: z2.array(ArtifactProvenanceMutation).min(1),
+  sessions: z2.array(ArtifactProvenanceSession),
+  subjects: z2.array(ArtifactProvenanceReference),
+  evidence: z2.array(ArtifactProvenanceReference),
+  gaps: z2.array(ArtifactProvenanceGap)
+});
+var UNKNOWN = [
+  "unknown",
+  "capture-failed",
+  "metadata-write-failed",
+  "invalid-record"
+];
+var MISSING = ["missing-ancestor", "truncated"];
+function checkOperation(operation, path, gap, session) {
+  if (operation.id === null)
+    gap(`${path}/id`, UNKNOWN);
+  if (operation.at === null)
+    gap(`${path}/at`, UNKNOWN);
+  if (operation.actor.kind === "unknown")
+    gap(`${path}/actor`, UNKNOWN);
+  if (operation.actor.kind === "session") {
+    session(operation.actor.sessionId, `${path}/actor/sessionId`);
+    if (operation.actor.runId === null)
+      gap(`${path}/actor/runId`, UNKNOWN);
+  }
+  if (operation.invocation?.toolCallId === null)
+    gap(`${path}/invocation/toolCallId`, UNKNOWN);
+  operation.causes.forEach((cause, index) => {
+    const causePath = `${path}/causes/${index}`;
+    if (cause.kind === "session" || cause.kind === "session-event")
+      session(cause.sessionId, `${causePath}/sessionId`);
+    if (cause.kind === "session-event" && (cause.cause.kind ?? "session-event") !== "backfill" && cause.cause.event?.runId === void 0) {
+      gap(`${causePath}/cause/event/runId`, UNKNOWN);
+    }
+    if ("runId" in cause && cause.runId === null)
+      gap(`${causePath}/runId`, UNKNOWN);
+  });
+}
+function checkRevision(revision, path, gap, issue, currentTarget = false) {
+  if (revision.revision === null)
+    gap(`${path}/revision`, UNKNOWN);
+  else if (typeof revision.revision === "object") {
+    if (!currentTarget)
+      issue(path.slice(1).split("/"), "Only the current target may refer to its enclosing commit");
+    if (revision.digest === void 0)
+      issue(path.slice(1).split("/"), "An enclosing-commit target must bind the exact content digest before commit");
+  }
+  if (revision.operationId === null)
+    gap(`${path}/operationId`, UNKNOWN);
+}
+function checkGraph(envelope, gap, issue) {
+  const nodes = new Map(envelope.sessions.map((node, index) => [node.sessionId, index]));
+  const edges = /* @__PURE__ */ new Map();
+  envelope.sessions.forEach((node, index) => {
+    const path = `/sessions/${index}`;
+    if (nodes.get(node.sessionId) !== index)
+      issue(["sessions", index, "sessionId"], "Session snapshots must be deduplicated by sessionId");
+    if (node.basis === "missing") {
+      if (node.record !== null)
+        issue(["sessions", index, "record"], "A missing snapshot cannot carry a creation record");
+      gap(path, MISSING);
+    } else if (node.record === null) {
+      issue(["sessions", index, "record"], "A non-missing snapshot requires its creation record");
+    }
+    if (node.basis === "legacy-derived")
+      gap(path, ["legacy-derived"]);
+    if (node.basis === "unverified-index")
+      gap(path, ["unverified-index"]);
+    const record = node.record;
+    if (record === null)
+      return;
+    const outgoing = record.relationships.map((relationship, edgeIndex) => ({
+      id: relationship.sessionId,
+      path: `${path}/record/relationships/${edgeIndex}/sessionId`
+    }));
+    const creator = record.createdBy;
+    if (creator.kind === "agent")
+      outgoing.push({
+        id: creator.sessionId,
+        path: `${path}/record/createdBy/sessionId`
+      });
+    if (creator.kind === "plugin" && creator.callerSessionId !== void 0)
+      outgoing.push({
+        id: creator.callerSessionId,
+        path: `${path}/record/createdBy/callerSessionId`
+      });
+    if ((creator.kind === "agent" || creator.kind === "trigger") && creator.runId === void 0 && node.basis === "recorded")
+      gap(`${path}/record/createdBy/runId`, UNKNOWN);
+    const eventCause = record.causedByEvent;
+    if (eventCause !== void 0 && (eventCause.kind ?? "session-event") !== "backfill" && eventCause.event?.runId === void 0 && node.basis === "recorded") {
+      gap(`${path}/record/causedByEvent/event/runId`, UNKNOWN);
+    }
+    edges.set(node.sessionId, outgoing);
+    outgoing.forEach((edge) => {
+      if (!nodes.has(edge.id))
+        gap(edge.path, MISSING);
+    });
+  });
+  const state = /* @__PURE__ */ new Map();
+  for (const node of envelope.sessions) {
+    if (state.has(node.sessionId))
+      continue;
+    const stack = [{ id: node.sessionId, next: 0 }];
+    state.set(node.sessionId, "active");
+    while (stack.length > 0) {
+      const current = stack[stack.length - 1];
+      const edge = edges.get(current.id)?.[current.next++];
+      if (edge === void 0) {
+        state.set(current.id, "done");
+        stack.pop();
+      } else if (state.get(edge.id) === "active") {
+        gap(edge.path, ["cycle"]);
+      } else if (nodes.has(edge.id) && !state.has(edge.id)) {
+        state.set(edge.id, "active");
+        stack.push({ id: edge.id, next: 0 });
+      }
+    }
+  }
+}
+function validateEnvelope(envelope, context) {
+  const issue = (path, message) => context.addIssue({ code: "custom", path, message });
+  const gap = (path, codes) => {
+    if (!envelope.gaps.some((entry) => entry.code === "capture-failed" && entry.at === "" || codes.includes(entry.code) && (path === entry.at || path.startsWith(`${entry.at}/`)))) {
+      issue(path.slice(1).split("/"), `Unresolved provenance requires an explicit ${codes.join(" or ")} gap`);
+    }
+  };
+  const nodes = new Set(envelope.sessions.map((node) => node.sessionId));
+  const session = (id, path) => {
+    if (!nodes.has(id))
+      gap(path, MISSING);
+  };
+  if (envelope.operation.id === null)
+    issue(["operation", "id"], "The current mutation requires a fresh operation identity");
+  checkOperation(envelope.operation, "/operation", gap, session);
+  const targets = /* @__PURE__ */ new Set();
+  envelope.artifacts.forEach((artifact, index) => {
+    const path = `/artifacts/${index}`;
+    const key = JSON.stringify([
+      artifact.target.storeId,
+      artifact.target.artifactId
+    ]);
+    if (targets.has(key))
+      issue(["artifacts", index, "target"], "One operation records each target artifact once");
+    targets.add(key);
+    if (artifact.target.operationId !== envelope.operation.id)
+      issue(["artifacts", index, "target", "operationId"], "The target must name the current persistence operation");
+    checkRevision(artifact.target, `${path}/target`, gap, issue, true);
+    checkOperation(artifact.producer, `${path}/producer`, gap, session);
+    artifact.sources.forEach((source, sourceIndex) => checkRevision(source.revision, `${path}/sources/${sourceIndex}/revision`, gap, issue));
+    const requiredSource = {
+      create: void 0,
+      update: "revision-of",
+      delete: "revision-of",
+      copy: "copied-from",
+      harvest: "harvested-from",
+      restore: "restored-from",
+      accept: "accepted-from",
+      import: "imported-from"
+    }[artifact.kind];
+    if (requiredSource !== void 0 && !artifact.sources.some((source) => source.relationship === requiredSource))
+      gap(`${path}/sources`, UNKNOWN);
+  });
+  for (const role of ["subjects", "evidence"]) {
+    envelope[role].forEach((reference, index) => {
+      const path = `/${role}/${index}`;
+      if (reference.kind === "session")
+        session(reference.sessionId, `${path}/sessionId`);
+      if (reference.kind === "artifact")
+        checkRevision(reference.revision, `${path}/revision`, gap, issue);
+      if (reference.kind === "resource" && reference.revision === null)
+        gap(`${path}/revision`, UNKNOWN);
+    });
+  }
+  checkGraph(envelope, gap, issue);
+}
+var ArtifactProvenanceEnvelopeV1 = z2.unknown().refine(isProvenanceJson, {
+  message: "Provenance must be plain, acyclic, lossless JSON without control characters"
+}).pipe(Envelope.superRefine(validateEnvelope));
+function parseArtifactProvenanceEnvelope(input) {
+  return ArtifactProvenanceEnvelopeV1.parse(input);
+}
+var ArtifactProvenanceCaptureContextSchema = z2.strictObject({
+  operation: ArtifactProvenanceOperation,
+  sessions: z2.array(ArtifactProvenanceSession),
+  subjects: z2.array(ArtifactProvenanceReference),
+  evidence: z2.array(ArtifactProvenanceReference),
+  gaps: z2.array(ArtifactProvenanceGap)
+});
+function parseArtifactProvenanceCaptureContext(input) {
+  return ArtifactProvenanceCaptureContextSchema.parse(input);
+}
+
+// packages/plugin-protocol/dist/artifact-provenance-capture.js
+function finalizeArtifactProvenanceEnvelope(capture, artifacts) {
+  const artifactGaps = [];
+  const blanket = capture.gaps.some((gap) => gap.code === "capture-failed" && gap.at === "");
+  if (!blanket) {
+    artifacts.forEach((artifact, index) => {
+      if (artifact.target.revision === null) {
+        artifactGaps.push({
+          code: "unknown",
+          at: `/artifacts/${index}/target/revision`
+        });
+      }
+      if (artifact.producer === capture.operation) {
+        for (const gap of capture.gaps) {
+          if (gap.at === "/operation" || gap.at.startsWith("/operation/")) {
+            artifactGaps.push({
+              ...gap,
+              at: `/artifacts/${index}/producer${gap.at.slice("/operation".length)}`
+            });
+          }
+        }
+      }
+    });
+  }
+  return parseArtifactProvenanceEnvelope({
+    version: ARTIFACT_PROVENANCE_VERSION,
+    operation: capture.operation,
+    artifacts,
+    sessions: capture.sessions,
+    subjects: capture.subjects,
+    evidence: capture.evidence,
+    gaps: [...capture.gaps, ...artifactGaps]
+  });
+}
+export {
+  finalizeArtifactProvenanceEnvelope,
+  parseArtifactProvenanceCaptureContext,
+  parseArtifactProvenanceEnvelope
+};

package/dist/canonical-transcript.js

@@ -543,11 +543,6 @@ function isKernelMessageRole(role) {
   return Object.hasOwn(KERNEL_MESSAGE_ROLES, role);
 }
 
-// packages/herd-transcript/dist/is-object.js
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 // packages/herd-transcript/dist/run-failure-classifier.js
 var MAX_FAILURE_TEXT_CHARS = 2e3;
 function boundedFailureText(text) {
@@ -625,6 +620,13 @@ function parsePresentationAnchor(value) {
 
 // packages/herd-transcript/dist/tool-call-failure.js
 import { z as z5 } from "zod";
+
+// packages/herd-transcript/dist/is-object.js
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/herd-transcript/dist/tool-call-failure.js
 var TOOL_CALL_FAILURE_DETAILS_KEY = "toolCallFailure";
 var TOOL_CALL_FAILURE_DOMAIN = "tool-call";
 var TOOL_CALL_FAILURE_CATEGORIES = [

package/dist/disclosure.d.ts

@@ -2431,9 +2431,19 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.44.0 adds `words.kinds` to a reference presentation (#15905): an ordered list of address patterns
  * and the kind each one names. Additive: a plugin that lists them declares ^0.44.0.
  *
- * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints.
+ * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints. It also
+ * lets a plugin declare what the window hardcoded about it (#15906). A reference presentation gains
+ * `accountLinks`, how a page opens under the account an address means, and a `local-app` open, for
+ * an item an app on this machine shows; a plugin the person installed can't declare that open. A
+ * `webSession` gains `signInFirst`. A URI module defines `lookupWebLink` and sets `looksUpWebLinks`
+ * to find a page when someone opens the address, and a preview field marks which `part` of a message
+ * it is. A claim's `brandIcon` is a file path and no longer inline markup, which only this repo's
+ * Microsoft plugin used. Otherwise additive: a plugin using any of these declares ^0.45.0.
+ *
+ * 0.46.0 adds `@bonsai/plugin-sdk/artifact-provenance`, so a plugin shipped as files can finalize
+ * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.45.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.46.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4703,6 +4713,7 @@ declare function refineWebSessionScopeConfined(webSession: {
     readonly probe: {
         readonly url: string;
     };
+    readonly signInFirst?: string | undefined;
 }, ctx: z.RefinementCtx): void;
 
 declare const RegistrableDomain: z.ZodString;
@@ -9521,6 +9532,11 @@ declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
  * - `base64`: unpadded base64 of the UTF-8 text (`{base64(:id :calendar)}`).
  * - `slackTimestamp`: a Slack archive message token as the API's timestamp
  *   (`p1783350000000100` becomes `1783350000.000100`).
+ * - `beforeColon`: the part of a `<team>:<user>` id before the colon. It fills nothing for an id
+ *   with no colon or nothing before it.
+ * - `beforeTilde`: the part of an id before its last `~`. It fills nothing with no `~`.
+ * - `encoded`: every reserved character escaped, `:` and `@` too, for a whole URL carried as a
+ *   query value (`continue={encoded(:url)}`).
  *
  * A transform that cannot read its input fills nothing. A claim whose `normalizeTo` fills nothing
  * does not match; a `sourceUrl` that fills nothing paints no link.
@@ -9779,6 +9795,13 @@ declare interface UriModule {
         readonly uri: string;
         readonly payload: unknown;
     }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    /**
+     * Find the web address of `uri` by asking the provider, for a resource whose address alone can't
+     * name its page. Called only when someone opens the address, under the account it means, and never
+     * to draw a reference. `undefined` means there's no page to open. A plugin module that defines
+     * this sets `looksUpWebLinks` in its manifest.
+     */
+    lookupWebLink?(uri: string, ctx: UriResolveContext): Promise<string | undefined>;
     readonly getCachePolicy?: UriCachePolicyResolver;
     /**
      * Code matching, for the host's own modules whose addresses no claim can describe (a bare file
@@ -9900,6 +9923,11 @@ declare interface UriOperationDescription {
             readonly editable?: true;
             /** Longest edited value, in UTF-16 code units. Meaningful only with `editable`. */
             readonly maxLength?: number;
+            /**
+             * Which part of a message this field is, when the call sends one. A preview with a `to` and
+             * a `text` is drawn as a message; without them it stays labelled rows.
+             */
+            readonly part?: "to" | "cc" | "bcc" | "subject" | "text";
         }[];
     };
     /** True only when every displayed fact comes from the input, independent of the executing account. */