@yaklabs-ai/plugin-sdk 0.8.5 → 0.9.1

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.8.5"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.9.1"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.8.5",
+  "version": "0.9.1",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -2700,6 +2700,24 @@ declare interface UriModule {
     readonly authActions?: UriAuthActionPolicy;
     /** Pure route/payload validation applied before a consequential permission ask. */
     readonly preflight?: UriOperationPreflightPolicy;
+    /**
+     * Structured facts naming the WHOLE consequence of this call, or `undefined` when
+     * the route cannot honestly be described on a one-line approval surface. The module
+     * owns the static action phrase, target resolution, payload decoding and declaration
+     * of covered payload fields and query parameters. Unknown fields cost the summary.
+     * The host owns framing, the whole-quote fit (no elision) and display-safety admission.
+     *
+     * Unlike preflight, this hook is async and may do I/O. Resolve names through `ctx`,
+     * the same dispatch context used by execution, never an ambient or cached account.
+     * The host calls it once before raising the ask, enforces the short `ctx.signal`
+     * deadline and discards late answers. A throw yields no summary and a module-attributed
+     * diagnostic; declining costs a click into the app, never an under-described approval.
+     */
+    describeOperation?(request: {
+        readonly operation: UriOperation;
+        readonly uri: string;
+        readonly payload: unknown;
+    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
     /**
      * Per-resource observability: does a `format: "observation"` read of THIS
      * uri render source-native material ({@link UriResolveContext.format})?
@@ -2813,6 +2831,22 @@ declare interface UriNormalizeResult {
 
 declare type UriOperation = "help" | "read" | "write" | "edit" | "list" | "search" | "delete";
 
+declare interface UriOperationDescription {
+    /** Static verb phrase authored by the module. Never interpolated from input. */
+    readonly action: string;
+    /** Human name resolved through the connection that will execute the call. */
+    readonly target: string;
+    /** Model-authored content; the host flattens, budgets, elides and bounds it. */
+    readonly quote?: string;
+    /** What this description accounts for; the host refuses undeclared input. */
+    readonly accounts: {
+        /** The payload actually read by the module, after its own decoding. */
+        readonly payload: unknown;
+        readonly payloadFields: readonly string[];
+        readonly queryParams?: readonly string[];
+    };
+}
+
 /**
  * Pure, route-aware validation that runs before permission policy can surface an ask.
  *

package/dist/kay-agent-testing.d.ts

@@ -2563,6 +2563,24 @@ declare interface UriModule {
     readonly authActions?: UriAuthActionPolicy;
     /** Pure route/payload validation applied before a consequential permission ask. */
     readonly preflight?: UriOperationPreflightPolicy;
+    /**
+     * Structured facts naming the WHOLE consequence of this call, or `undefined` when
+     * the route cannot honestly be described on a one-line approval surface. The module
+     * owns the static action phrase, target resolution, payload decoding and declaration
+     * of covered payload fields and query parameters. Unknown fields cost the summary.
+     * The host owns framing, the whole-quote fit (no elision) and display-safety admission.
+     *
+     * Unlike preflight, this hook is async and may do I/O. Resolve names through `ctx`,
+     * the same dispatch context used by execution, never an ambient or cached account.
+     * The host calls it once before raising the ask, enforces the short `ctx.signal`
+     * deadline and discards late answers. A throw yields no summary and a module-attributed
+     * diagnostic; declining costs a click into the app, never an under-described approval.
+     */
+    describeOperation?(request: {
+        readonly operation: UriOperation;
+        readonly uri: string;
+        readonly payload: unknown;
+    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
     /**
      * Per-resource observability: does a `format: "observation"` read of THIS
      * uri render source-native material ({@link UriResolveContext.format})?
@@ -2676,6 +2694,22 @@ declare interface UriNormalizeResult {
 
 declare type UriOperation = "help" | "read" | "write" | "edit" | "list" | "search" | "delete";
 
+declare interface UriOperationDescription {
+    /** Static verb phrase authored by the module. Never interpolated from input. */
+    readonly action: string;
+    /** Human name resolved through the connection that will execute the call. */
+    readonly target: string;
+    /** Model-authored content; the host flattens, budgets, elides and bounds it. */
+    readonly quote?: string;
+    /** What this description accounts for; the host refuses undeclared input. */
+    readonly accounts: {
+        /** The payload actually read by the module, after its own decoding. */
+        readonly payload: unknown;
+        readonly payloadFields: readonly string[];
+        readonly queryParams?: readonly string[];
+    };
+}
+
 /**
  * Pure, route-aware validation that runs before permission policy can surface an ask.
  *

package/dist/kay-agent.d.ts

@@ -4323,6 +4323,24 @@ export declare interface UriModule {
     readonly authActions?: UriAuthActionPolicy;
     /** Pure route/payload validation applied before a consequential permission ask. */
     readonly preflight?: UriOperationPreflightPolicy;
+    /**
+     * Structured facts naming the WHOLE consequence of this call, or `undefined` when
+     * the route cannot honestly be described on a one-line approval surface. The module
+     * owns the static action phrase, target resolution, payload decoding and declaration
+     * of covered payload fields and query parameters. Unknown fields cost the summary.
+     * The host owns framing, the whole-quote fit (no elision) and display-safety admission.
+     *
+     * Unlike preflight, this hook is async and may do I/O. Resolve names through `ctx`,
+     * the same dispatch context used by execution, never an ambient or cached account.
+     * The host calls it once before raising the ask, enforces the short `ctx.signal`
+     * deadline and discards late answers. A throw yields no summary and a module-attributed
+     * diagnostic; declining costs a click into the app, never an under-described approval.
+     */
+    describeOperation?(request: {
+        readonly operation: UriOperation;
+        readonly uri: string;
+        readonly payload: unknown;
+    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
     /**
      * Per-resource observability: does a `format: "observation"` read of THIS
      * uri render source-native material ({@link UriResolveContext.format})?
@@ -4453,6 +4471,22 @@ export declare class UriNotFoundError extends UriError {
 
 export declare type UriOperation = "help" | "read" | "write" | "edit" | "list" | "search" | "delete";
 
+export declare interface UriOperationDescription {
+    /** Static verb phrase authored by the module. Never interpolated from input. */
+    readonly action: string;
+    /** Human name resolved through the connection that will execute the call. */
+    readonly target: string;
+    /** Model-authored content; the host flattens, budgets, elides and bounds it. */
+    readonly quote?: string;
+    /** What this description accounts for; the host refuses undeclared input. */
+    readonly accounts: {
+        /** The payload actually read by the module, after its own decoding. */
+        readonly payload: unknown;
+        readonly payloadFields: readonly string[];
+        readonly queryParams?: readonly string[];
+    };
+}
+
 /**
  * Pure, route-aware validation that runs before permission policy can surface an ask.
  *

package/dist/kay-app.d.ts

@@ -299,6 +299,93 @@ declare type ConstrainedSamplingConfig = {
     variants: GrammarVariants;
 };
 
+export declare interface CorpusResourceInvocation {
+    readonly eventId: string;
+    /** Envelope recording time, never a run/message/incident identifier. */
+    readonly at: string;
+    readonly kind: CorpusResourceKind;
+    readonly sessionId: string;
+    /** Falls back to sessionId for legacy events without a recorded root. */
+    readonly rootSessionId: string;
+    readonly name: string;
+    readonly sourceId?: string;
+    /** Absent on unresolved legacy rows; names/aliases are not a substitute. */
+    readonly resourceId?: string;
+    readonly version?: string;
+    readonly variantId?: string;
+    readonly rootProvenance: SessionProvenanceRecord;
+    /** Current index hints, not the session's historical context at invocation. */
+    readonly currentContext: {
+        readonly cwd: string;
+        readonly projectId?: string;
+    };
+}
+
+/** Exclusive keyset position; preserve timestamp precision when returning it. */
+export declare const CorpusResourceInvocationCursor: z.ZodObject<{
+    at: z.ZodISODateTime;
+    eventId: z.ZodString;
+}, z.core.$strict>;
+
+export declare type CorpusResourceInvocationCursor = z.infer<typeof CorpusResourceInvocationCursor>;
+
+export declare interface CorpusResourceInvocationExclusion {
+    readonly eventId: string;
+    readonly sessionId: string;
+    readonly rootSessionId: string;
+    readonly reason: "session-missing" | "root-missing" | "root-provenance-unverified" | "root-creator-filtered";
+}
+
+export declare type CorpusResourceInvocationPage = {
+    readonly state: "available";
+    readonly items: readonly CorpusResourceInvocation[];
+    /** Absent only when this recording-time window is exhausted. */
+    readonly next?: CorpusResourceInvocationCursor;
+    /** Telemetry import succeeded; exclusions still describe missing or filtered index facts. */
+    readonly coverage: {
+        readonly scanned: number;
+        readonly exclusions: readonly CorpusResourceInvocationExclusion[];
+    };
+} | {
+    readonly state: "unavailable";
+    readonly reason: "not-wired" | "telemetry-unavailable" | "telemetry-incomplete" | "index-unavailable" | "invalid-record";
+    readonly message: string;
+};
+
+/** Half-open recording-time window. Limits bound scanned rows, including exclusions. */
+export declare const CorpusResourceInvocationQuery: z.ZodObject<{
+    kind: z.ZodEnum<{
+        skill: "skill";
+        "context-file": "context-file";
+        "prompt-command": "prompt-command";
+    }>;
+    since: z.ZodISODateTime;
+    until: z.ZodISODateTime;
+    after: z.ZodOptional<z.ZodObject<{
+        at: z.ZodISODateTime;
+        eventId: z.ZodString;
+    }, z.core.$strict>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    rootCreatedByKind: z.ZodOptional<z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+        plugin: "plugin";
+        trigger: "trigger";
+        daemon: "daemon";
+    }>>;
+}, z.core.$strict>;
+
+export declare type CorpusResourceInvocationQuery = z.infer<typeof CorpusResourceInvocationQuery>;
+
+/** Roster invocation facts, not evidence that a read completed successfully. */
+export declare const CorpusResourceKind: z.ZodEnum<{
+    skill: "skill";
+    "context-file": "context-file";
+    "prompt-command": "prompt-command";
+}>;
+
+export declare type CorpusResourceKind = z.infer<typeof CorpusResourceKind>;
+
 /**
  * The `signals` a host with no Jev lane or no signals store binds: `observe` never touches the
  * network, answers `invalid` for an input that breaks the recorded-name grammar exactly as a
@@ -1083,18 +1170,15 @@ export declare interface KayAppAutomationArtifactItem {
     readonly moduleId: string;
     /**
      * The authoring session. Required on the wire, and load-bearing rather than
-     * decorative: it is the identity a reverse `explainArtifactRevision` call
-     * resolves back to, and the session an `app:artifact:output` uri must be
+     * decorative: it is the session an `app:artifact:output` uri must be
      * resolved against to open at all.
      */
     readonly sessionId: string;
     /** Collapsed by precedence: `deleted` > `created` > `updated`. */
     readonly action: "created" | "updated" | "deleted";
     /**
-     * One real revision of the group, carrying the action above, so a reverse
-     * `explainArtifactRevision` read still resolves from this row. Not
-     * necessarily the newest: the projection stores no ordering for the several
-     * revisions of one target.
+     * One real revision of the group, carrying the action above. Not
+     * necessarily the newest revision of the target.
      */
     readonly revision: string;
     /** How many revisions this row collapsed. Always at least 1. */
@@ -1238,7 +1322,7 @@ export declare type KayAppAutomationEffectInput = {
  * widening of it: an external resource has no revision, no Kay uri module, and
  * nothing on this machine to re-read.
  *
- * `kind` mirrors the projection's closed external-resource vocabulary and names
+ * `kind` is the run-detail wire's closed external-resource vocabulary and names
  * the host as well as the thing. There is deliberately no `offBranch`: an
  * abandoned transcript branch does not un-open a pull request, so branch
  * membership is never consulted for these facts.
@@ -1361,6 +1445,7 @@ export declare interface KayAppAutomationRunOptions {
 
 export declare type KayAppAutomationRunOutcome = {
     readonly status: "succeeded";
+    readonly summary?: KayAppRunSummary | undefined;
     readonly daemonRunId?: string | undefined;
     /** Present on a script run: which source this run actually executed. */
     readonly script?: {
@@ -1369,11 +1454,12 @@ export declare type KayAppAutomationRunOutcome = {
     } | undefined;
 } | {
     readonly status: "failed";
+    readonly summary?: KayAppRunSummary | undefined;
     readonly reason: "executor_failed" | "permission_denied" | "surface_unavailable" | "target_gone";
     readonly message?: string | undefined;
 } | {
     readonly status: "skipped";
-    readonly reason: "already_running" | "binding_inactive" | "circuit_breaker" | "concurrency_capped" | "guard_not_satisfied" | "missed_window";
+    readonly reason: "already_running" | "binding_inactive" | "circuit_breaker" | "concurrency_capped" | "guard_not_satisfied" | "missed_window" | "timer_cancelled";
 } | {
     readonly status: "abandoned";
     readonly reason: "daemon_restart";
@@ -1407,6 +1493,7 @@ export declare interface KayAppAutomations {
     get(id: string, ctx: KayAppAutomationContext): Promise<KayAppAutomationBinding | undefined>;
     create(input: {
         readonly name: string;
+        readonly description?: string;
         readonly condition: KayAppAutomationConditionInput;
         readonly effect: KayAppAutomationEffectInput;
         readonly enabled?: boolean;
@@ -1468,13 +1555,13 @@ export declare interface KayAppAutomations {
         readonly nextCursor?: string;
     }>;
     /**
-     * One run's provenance detail (RFC Release 2): the sessions that run drove
-     * (direct and child, shared-run marked) and the Git-backed artifact
-     * revisions those sessions produced, with explicit projection coverage and
-     * gaps. A PUBLIC read like {@link listRuns}: it resolves the binding's
-     * actual owner rather than the caller's. Null when no retained run matches
-     * `bindingId` + `runId`. Coverage reports `rebuilding`/`partial` honestly
-     * while the projection catches up — it never blocks or fabricates.
+     * One run's detail (RFC Release 2): the sessions that run drove (direct and
+     * child, shared-run marked), the artifacts, external resources and skill
+     * suggestions those sessions produced, and explicit coverage and gaps. A
+     * PUBLIC read like {@link listRuns}: it resolves the binding's actual owner
+     * rather than the caller's. Null when no retained run matches `bindingId` +
+     * `runId`. Coverage reports `partial` honestly when some of the run's work
+     * cannot be read — it never blocks or fabricates.
      */
     getRun(bindingId: string, runId: string, ctx: KayAppAutomationContext, options?: KayAppAutomationRunDetailOptions): Promise<KayAppAutomationRunDetail | null>;
 }
@@ -1495,6 +1582,8 @@ export declare type KayAppAutomationScriptRef = {
 
 /** A receipt-attributed skill candidate, with live status only for that exact revision. */
 export declare type KayAppAutomationSuggestionItem = {
+    /** Only literal 1 proves physical addressing; other historical values remain uninterpreted. */
+    readonly locatorVersion?: unknown;
     readonly sourceId: string;
     readonly skillName: string;
     readonly suggestionId: string;
@@ -1613,10 +1702,15 @@ export declare interface KayAppConfig {
  * path of the winning file. A JSON-safe twin of the runtime's `KayConfigValueOrigin`
  * (`@kay/product-catalog`) — this SDK cannot import that package, so the shape is re-declared
  * here and an assignability test in `@kay/agent-runtime` pins the two together. The level union
- * is the closed, protocol-owned fold precedence stack (`learned < global < project`).
+ * is the closed, protocol-owned fold precedence stack (`baseline < learned < global < project`).
+ * `"baseline"` names a host-composed, in-memory, build/channel-scoped default with no file
+ * behind it (`KayConfigStoreOptions.baselineDefaults`) — a plugin can still be handed one as a
+ * winner for a FIELD within its own declared section that neither it nor the user ever set
+ * (e.g. hindsight's `handlers.signals`, defaulted on by the host for this release channel), so
+ * `path` for that level is a synthetic label, never a real file path.
  */
 export declare interface KayAppConfigOrigin {
-    readonly level: "learned" | "global" | "project";
+    readonly level: "baseline" | "learned" | "global" | "project";
     readonly path: string;
 }
 
@@ -1677,14 +1771,31 @@ export declare interface KayAppContextContributor {
  * Raw read access to every stored session's transcript. Always present on
  * {@link KayAppPluginApi}; each read is checked against the `corpus.read` claim, and refused
  * unless the user has granted it. Data is raw and un-redacted — the plugin filters to what it
- * needs. Both reads are async iterables so a corpus pass never loads the whole corpus into memory
- * at once (the bound is one session at a time).
+ * needs. Invocation queries are bounded pages. Transcript reads materialize a whole session
+ * before yielding; the iterable does not promise per-entry streaming or an allocation bound.
  */
 export declare interface KayAppCorpus {
+    /** Page invocation leads under the live grant; inspect exclusions even on available empty pages. */
+    listResourceInvocations(query: CorpusResourceInvocationQuery): Promise<CorpusResourceInvocationPage>;
     /** Enumerate every stored session, newest-first. */
     listSessions(): AsyncIterable<KayAppCorpusSession>;
-    /** Stream one session's full entry log oldest→newest; an unknown id yields nothing. */
+    /**
+     * Yield one session's full entry log oldest→newest; an unknown id yields nothing. Treat the
+     * entries as read-only: for a session the daemon holds in memory they are its live objects.
+     */
     readEntries(sessionId: string): AsyncIterable<SessionTreeEntry>;
+    /**
+     * Read one bounded physical JSONL page. The host resolves `sessionId` to its authoritative
+     * indexed path and validates the opaque cursor before opening it. When `throughEntryId` is
+     * supplied, the cursor stops at that entry's transaction line; a V4 line may carry later
+     * entries, which are returned for the caller to filter and are replayed on the next page.
+     */
+    readEntryBatch?(sessionId: string, options?: {
+        readonly cursor?: JsonValue_4;
+        readonly throughEntryId?: string;
+        /** Host-only cancellation for the bounded physical read. */
+        readonly signal?: AbortSignal;
+    }): Promise<KayAppCorpusEntryBatch>;
     /**
      * Read a cheap transcript change marker without loading the entry log. Unknown or deleted
      * sessions yield `undefined`.
@@ -1692,6 +1803,20 @@ export declare interface KayAppCorpus {
     readSessionSourceMark(sessionId: string): Promise<KayAppCorpusSourceMark | undefined>;
 }
 
+/** One bounded physical page from the host's incremental JSONL reader. */
+export declare interface KayAppCorpusEntryBatch {
+    readonly entries: readonly SessionTreeEntry[];
+    /** Opaque JSON cursor after the physical page; only the host may interpret it or open its path. */
+    readonly cursor: JsonValue_4;
+    /** Opaque cursor at the physical page start, for a partial logical chunk. */
+    readonly pageStartCursor?: JsonValue_4;
+    readonly mode: "replace" | "append";
+    readonly status: "complete" | "more" | "awaiting-append" | "record-too-large";
+    /** Present when a caller supplied `throughEntryId`. */
+    readonly anchorFound?: boolean;
+    readonly malformedRecords: number;
+}
+
 /** One stored session, as the granted corpus enumerates them. Keyed by its stable `sessionId`. */
 export declare interface KayAppCorpusSession {
     readonly sessionId: string;
@@ -1954,6 +2079,13 @@ export declare interface KayAppEndpoints {
     register(name: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
 }
 
+/** A real human carrier projected into the source session's transcript. */
+export declare interface KayAppHumanMessageSessionEvent extends KayAppSessionEventBase {
+    readonly type: "human-message";
+    /** Exact prior persisted boundary captured by the host at projection time; `null` means empty history. */
+    readonly throughEntryId: string | null;
+}
+
 /**
  * A provider's nominated image model, resolved now: what a session on one of that
  * provider's text-only models spawns to read images. `resolved` absent = nothing
@@ -2452,9 +2584,9 @@ export declare interface KayAppPluginEvents {
 export declare type KayAppProcessingSpeed = "standard" | "fast";
 
 /**
- * A gap reason on the run-detail wire. Adapter-determined codes come from the
- * projection's stored gap vocabulary; the remaining four are derived at query
- * time from current evidence and checkpoint coverage.
+ * A gap reason on the run-detail wire: something about the run's work the
+ * daemon could not establish from its session transcripts. The vocabulary is
+ * closed; a daemon may emit only some of these codes.
  */
 export declare type KayAppProvenanceGapCode = "legacy-run-id-missing" | "mutation-revision-missing" | "partial-git-provenance" | "git-session-stamp-missing"
 /** A run created something off this machine that the transcript cannot name. */
@@ -2537,6 +2669,14 @@ export declare interface KayAppResolvedCredential {
     readonly fields?: Readonly<Record<string, string>>;
 }
 
+export declare interface KayAppRunSummary {
+    /** One plain-text line, at most 100 characters. */
+    readonly headline: string;
+    /** Optional plain-text explanation, at most 600 characters. */
+    readonly details?: string | undefined;
+    readonly author: "automation" | "kay";
+}
+
 /**
  * The session provenance vocabulary, as the plugin protocol declares it. These used to be spelled
  * out here because the canonical schemas lived in `@kay/agent-runtime-protocol`, which this
@@ -2568,17 +2708,16 @@ export declare type KayAppSessionCreator = SessionCreator;
 
 export declare type KayAppSessionDefiner = SessionDefiner;
 
-export declare type KayAppSessionEvent = KayAppTurnSettledSessionEvent | KayAppPhaseShiftSessionEvent;
+export declare type KayAppSessionEvent = KayAppHumanMessageSessionEvent | KayAppTurnSettledSessionEvent | KayAppPhaseShiftSessionEvent;
 
 declare interface KayAppSessionEventBase {
     readonly sessionId: string;
     /**
-     * The event's own anchor entry: the settled turn's own last entry, or the phase-shift
-     * observation's `observationEntryId`. A handler bounds its OWN corpus read using this id (via
-     * whatever packet-building helpers the plugin already owns); the door hands out no
-     * `readEntries()` closure, and re-validating what was read against the CURRENT branch — a
-     * rewind can race between publish and read — is the handler's own job, exactly as
-     * `resolveClosedPhase` already does today for the phase extractor.
+     * The event's own anchor entry: the projected human carrier, the settled turn's own last
+     * entry, or the phase-shift observation's `observationEntryId`. A handler bounds its OWN logical
+     * corpus interval using this id (via whatever packet-building helpers the plugin already owns);
+     * the door hands out no `readEntries()` closure, and re-validating what was read against the
+     * CURRENT branch — a rewind can race between publish and read — is the handler's own job.
      */
     readonly entryId: string;
     /** ISO-8601 publish time. */
@@ -2615,6 +2754,8 @@ export declare type KayAppSessionEventCause = {
          * substitute a run id resolved another way.
          */
         readonly runId?: string;
+        /** Exact prior persisted boundary for a projected human-message event; null means empty history. */
+        readonly throughEntryId?: string | null;
     };
     /**
      * Exact-match dedupe key. The host REFUSES a second run carrying the same key outright (a
@@ -2677,12 +2818,12 @@ export declare interface KayAppSessionEventsSubscribeOptions {
 }
 
 /**
- * A closed, extensible union: today's two root events a lane could fire on
- * (`turn-settled`) and react to (`phase-shift`), collapsed onto one subscribable set now that
- * there is no dispatcher chaining one lane's completion into another's `when`. Adding a third
- * type is additive, never breaking.
+ * A closed, extensible union: a projected human message, a settled turn, or an accepted
+ * phase-shift observation. They share one subscribable set now that there is no dispatcher
+ * chaining one job's completion into another's `when`. Adding a fourth type is additive, never
+ * breaking.
  */
-export declare type KayAppSessionEventType = "turn-settled" | "phase-shift";
+export declare type KayAppSessionEventType = "human-message" | "turn-settled" | "phase-shift";
 
 export declare type KayAppSessionIntent = SessionIntent;
 
@@ -3006,8 +3147,9 @@ export declare interface KayAppSignalDetector {
  * - `classified`: Jev answered; `answers`, `model`, and `usage` are the vendor's verbatim
  *   response, and `stored` says whether the row landed in the durable store.
  * - `unavailable`: Jev could not answer (no key, refused grant, timeout, vendor error, or a
- *   malformed response). `reason` names the host's classification; no row is written, so the
- *   same input can be observed again later without a conflict.
+ *   malformed response), or the host has no signals store at all (`reason: "no-store"`).
+ *   `reason` names the host's classification; no row is written, so the same input can be
+ *   observed again later without a conflict.
  * - `invalid`: the input breaks the recorded-name grammar (see {@link invalidObservation}), and
  *   `reason` says which name and why. The caller's mistake, not the environment's: Jev is never
  *   called, no row is written, and the same input is refused again. `detector` and `source`
@@ -3030,7 +3172,11 @@ export declare interface KayAppSignalObservation {
     } | undefined;
     readonly tookMs?: number | undefined;
     readonly reason?: string | undefined;
-    /** True when the row landed in the durable store; false when the host composed no store. */
+    /**
+     * True when the row landed in the durable store; false when a composed store's own write
+     * failed after Jev already answered (rare -- a host with no store at all instead answers
+     * `unavailable` with reason `"no-store"`, never reaching `classified`).
+     */
     readonly stored: boolean;
     /** True when this call returned an already-stored row instead of running inference. */
     readonly deduplicated: boolean;
@@ -3531,10 +3677,22 @@ export declare interface KayAppWorkflowContext {
 
 export declare interface KayAppWorkflowDefinition {
     readonly name: string;
+    /** Plain-text purpose, at most 280 characters. */
+    readonly description: string;
+    readonly instructions?: readonly KayAppWorkflowInstruction[];
+    readonly perRunNote?: string;
     readonly trigger: Extract<KayAppAutomationConditionInput, {
         readonly kind: "time";
     }>;
-    readonly run: (context: KayAppWorkflowContext) => void | Promise<void>;
+    readonly run: (context: KayAppWorkflowContext) => Promise<{
+        readonly summary: KayAppRunSummary;
+    }>;
+}
+
+/** Fail a workflow while retaining its own explanation beside this attempt. */
+export declare class KayAppWorkflowFailure extends Error {
+    readonly summary: KayAppRunSummary;
+    constructor(summary: Omit<KayAppRunSummary, "author">, options?: ErrorOptions);
 }
 
 export declare interface KayAppWorkflowInspection {
@@ -3548,6 +3706,20 @@ export declare interface KayAppWorkflowInspectOptions {
     readonly limit?: number;
 }
 
+export declare type KayAppWorkflowInstruction = {
+    readonly label: string;
+    readonly kind: "prompt";
+    readonly text: string;
+} | {
+    readonly label: string;
+    readonly kind: "agent";
+    readonly agent: KayAppAgentDefinitionRef;
+} | {
+    readonly label: string;
+    readonly kind: "script";
+    readonly ref: KayAppAutomationScriptRef;
+};
+
 export declare interface KayAppWorkflows {
     define(localId: string, definition: KayAppWorkflowDefinition): void;
     inspect(localId: string, options?: KayAppWorkflowInspectOptions): Promise<KayAppWorkflowInspection>;
@@ -4454,9 +4626,11 @@ declare const SessionCausedByEvent: z.ZodObject<{
         type: z.ZodEnum<{
             "turn-settled": "turn-settled";
             "phase-shift": "phase-shift";
+            "human-message": "human-message";
         }>;
         entryId: z.ZodString;
         runId: z.ZodOptional<z.ZodString>;
+        throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strict>>;
     dedupeKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -4650,9 +4824,11 @@ declare const SessionProvenanceRecord: z.ZodObject<{
             type: z.ZodEnum<{
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
+                "human-message": "human-message";
             }>;
             entryId: z.ZodString;
             runId: z.ZodOptional<z.ZodString>;
+            throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strict>>;
         dedupeKey: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
@@ -5412,6 +5588,17 @@ export declare interface UriModule {
     readonly permission?: UriOperationPermissionPolicy;
     /** Pure route/payload validation applied before a consequential permission ask. */
     readonly preflight?: UriOperationPreflightPolicy;
+    /**
+     * Supply structured action facts and explicit input coverage for a one-line approval.
+     * The host composes and admits the line; see the protocol's UriModule contract.
+     * Names must be resolved through this call's dispatch context. The host enforces
+     * `ctx.signal`'s deadline and treats a throw or late answer as no summary.
+     */
+    describeOperation?(request: {
+        readonly operation: UriOperation;
+        readonly uri: string;
+        readonly payload: unknown;
+    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
     /**
      * Set false when the generic write tool must reject `source` copies before
      * fetching the source. Inline `content` writes remain available.
@@ -5584,6 +5771,22 @@ export declare class UriNotFoundError extends UriError {
 
 declare type UriOperation = "help" | "read" | "write" | "edit" | "list" | "search" | "delete";
 
+declare interface UriOperationDescription {
+    /** Static verb phrase authored by the module. Never interpolated from input. */
+    readonly action: string;
+    /** Human name resolved through the connection that will execute the call. */
+    readonly target: string;
+    /** Model-authored content; the host flattens, budgets, elides and bounds it. */
+    readonly quote?: string;
+    /** What this description accounts for; the host refuses undeclared input. */
+    readonly accounts: {
+        /** The payload actually read by the module, after its own decoding. */
+        readonly payload: unknown;
+        readonly payloadFields: readonly string[];
+        readonly queryParams?: readonly string[];
+    };
+}
+
 declare interface UriOperationPermissionClassification {
     /**
      * The operation's real effect. The permission classifier only accepts a

package/dist/kay-app.js

@@ -387,6 +387,16 @@ function transcriptRoleLabel(role) {
   return role === "user" ? "User" : "Assistant";
 }
 
+// packages/plugin-sdk/dist/kay-app/workflows.js
+var KayAppWorkflowFailure = class extends Error {
+  summary;
+  constructor(summary, options) {
+    super(summary.details ?? summary.headline, options);
+    this.name = "KayAppWorkflowFailure";
+    this.summary = { ...summary, author: "automation" };
+  }
+};
+
 // packages/plugin-protocol/dist/app-data.js
 var KAY_APP_DATA_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024;
 var KAY_APP_DATA_CHANGE_MAX_BYTES = 256 * 1024;
@@ -406,6 +416,7 @@ var KAY_APP_AUTOMATION_CONDITION_KINDS = [
 export {
   KAY_APP_AUTOMATION_CONDITION_KINDS,
   KAY_APP_DATA_CHANGE_MAX_BYTES,
+  KayAppWorkflowFailure,
   MAX_CHOICE_LABELS,
   SIGNAL_TIME_MAX_MS,
   UriConflictError,

package/dist/signals.d.ts

@@ -67,8 +67,9 @@ export declare interface KayAppSignalDetector {
  * - `classified`: Jev answered; `answers`, `model`, and `usage` are the vendor's verbatim
  *   response, and `stored` says whether the row landed in the durable store.
  * - `unavailable`: Jev could not answer (no key, refused grant, timeout, vendor error, or a
- *   malformed response). `reason` names the host's classification; no row is written, so the
- *   same input can be observed again later without a conflict.
+ *   malformed response), or the host has no signals store at all (`reason: "no-store"`).
+ *   `reason` names the host's classification; no row is written, so the same input can be
+ *   observed again later without a conflict.
  * - `invalid`: the input breaks the recorded-name grammar (see {@link invalidObservation}), and
  *   `reason` says which name and why. The caller's mistake, not the environment's: Jev is never
  *   called, no row is written, and the same input is refused again. `detector` and `source`
@@ -91,7 +92,11 @@ export declare interface KayAppSignalObservation {
     } | undefined;
     readonly tookMs?: number | undefined;
     readonly reason?: string | undefined;
-    /** True when the row landed in the durable store; false when the host composed no store. */
+    /**
+     * True when the row landed in the durable store; false when a composed store's own write
+     * failed after Jev already answered (rare -- a host with no store at all instead answers
+     * `unavailable` with reason `"no-store"`, never reaching `classified`).
+     */
     readonly stored: boolean;
     /** True when this call returned an already-stored row instead of running inference. */
     readonly deduplicated: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.8.5",
+  "version": "0.9.1",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",