@yaklabs-ai/plugin-sdk 0.8.5 → 0.9.0

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.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "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

@@ -1083,18 +1083,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 +1235,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 +1358,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 +1367,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 +1406,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 +1468,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>;
 }
@@ -1613,10 +1613,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;
 }
 
@@ -1683,7 +1688,10 @@ export declare interface KayAppContextContributor {
 export declare interface KayAppCorpus {
     /** Enumerate every stored session, newest-first. */
     listSessions(): AsyncIterable<KayAppCorpusSession>;
-    /** Stream one session's full entry log oldest→newest; an unknown id yields nothing. */
+    /**
+     * Stream 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 a cheap transcript change marker without loading the entry log. Unknown or deleted
@@ -2452,9 +2460,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 +2545,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
@@ -3006,8 +3022,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 +3047,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 +3552,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 +3581,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>;
@@ -5412,6 +5459,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 +5642,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.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",