@yaklabs-ai/plugin-sdk 0.15.0 → 0.15.2

package/dist/kay-app.d.ts

@@ -755,6 +755,7 @@ declare interface CustomAgentMessages {
     userInvoked: UserInvokedMessage;
     availabilityFacts: AvailabilityFactsMessage;
     midTurnCompactionOutcome: MidTurnCompactionOutcomeMessage;
+    runContinuationCarrier: RunContinuationCarrierMessage;
     subagentResult: SubagentResultMessage;
     backgroundTaskResult: BackgroundTaskResultMessage;
 }
@@ -921,6 +922,18 @@ declare interface DeferredHandle {
     data?: JsonValue_4;
 }
 
+/**
+ * Register an ordinary workflow that polls connected accounts with independent JSON cursors.
+ * First polls initialize silently. Failed or skipped accounts retain their cursor; removed
+ * accounts are pruned. Publication finishes before replacement state is returned.
+ *
+ * Credential resolution and provider reads share a step so credentials are never step outputs.
+ * Poll callbacks must keep secrets out of their returned cursor, events, and summary. Resolution
+ * errors fail the run with a sanitized message; provider poll errors isolate the account.
+ * Key events at their source: a step can repeat before its result commits or after an engine update.
+ */
+export declare function definePoller<Cursor extends JsonValue>(app: Pick<KayAppPluginApi, "workflows" | "auth" | "events">, localId: string, options: KayAppPollerOptions<Cursor>): void;
+
 /** Creates a Dependent type */
 declare function Dependent<If extends TSchema, Then extends TSchema, Else extends TSchema>(if_: If, then_: Then, else_: Else, options?: TSchemaOptions): TDependent<If, Then, Else>;
 
@@ -1397,6 +1410,14 @@ declare const Factor: (input: string) => [unknown, string] | [];
 
 declare function FactorMapping(input: [unknown, unknown, unknown, unknown, unknown]): unknown;
 
+/**
+ * The `ErrorOptions` for a workflow that fails BECAUSE this run failed: the run's retained
+ * failure ref as the error's `cause`, so the host reports that failure, with the same identity
+ * the session kept, instead of guessing from whichever run settled last. Empty when the run kept
+ * no failure: the throw is then the workflow's own.
+ */
+export declare function failedRunCause(outcome: KayAppSessionRunOutcome): ErrorOptions;
+
 declare type ForecastInterval = "step" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
 
 /** Creates a Function type. */
@@ -1850,7 +1871,7 @@ declare type JsonValue_4 = null | boolean | number | string | readonly JsonValue
  * the union and not to this list, so the next kind cannot repeat that bug
  * quietly.
  */
-export declare const KAY_APP_AUTOMATION_CONDITION_KINDS: readonly ["time", "uri-change", "occurrence", "delayed-occurrence"];
+export declare const KAY_APP_AUTOMATION_CONDITION_KINDS: readonly ["time", "uri-change", "plugin-event", "occurrence", "delayed-occurrence"];
 
 /** Maximum UTF-8 JSON size of one plugin app-data live change. */
 export declare const KAY_APP_DATA_CHANGE_MAX_BYTES: number;
@@ -2468,12 +2489,26 @@ export declare interface KayAppAutomationBinding {
     readonly nextDueAtMs?: number;
     readonly expiresAtMs?: number;
     readonly maxRuns?: number;
+    readonly concurrency?: KayAppAutomationConcurrency;
     readonly runCount: number;
     /** Why a script binding's last tick failed and paused it, when it did. */
     readonly scriptLastError?: string;
 }
 
-export declare type KayAppAutomationCondition = Extract<KayAppAutomationConditionInput, {
+/**
+ * How many of an automation's runs may be in progress at once. Absent means `sequential`: one at
+ * a time, in order. `parallel` runs up to `limit` at once (1 to 32, default 4), for an automation
+ * whose runs each handle their own event and can safely overlap, such as replying to separate
+ * emails.
+ */
+export declare type KayAppAutomationConcurrency = {
+    readonly mode: "sequential";
+} | {
+    readonly mode: "parallel";
+    readonly limit?: number;
+};
+
+export declare type KayAppAutomationCondition = KayAppAutomationPluginEventCondition | Extract<KayAppAutomationConditionInput, {
     readonly kind: "time";
 }> | KayAppAutomationUriChangeCondition | {
     readonly kind: "occurrence";
@@ -2495,7 +2530,7 @@ export declare type KayAppAutomationCondition = Extract<KayAppAutomationConditio
     readonly guard?: "session-idle";
 };
 
-export declare type KayAppAutomationConditionInput = {
+export declare type KayAppAutomationConditionInput = KayAppAutomationPluginEventCondition | {
     readonly kind: "time";
     readonly schedule: {
         readonly kind: "every";
@@ -2607,6 +2642,22 @@ export declare interface KayAppAutomationExternalResourceItem {
 export declare type KayAppAutomationFactSource = "run-settled" | "tool-used" | "tool-failed";
 
 export declare type KayAppAutomationMatch = {
+    readonly kind: "plugin-event";
+    readonly event: {
+        readonly id: string;
+        readonly type: string;
+        readonly version: number;
+        readonly uri: string;
+        readonly occurredAt: string;
+        readonly publishedAt: string;
+        readonly source: {
+            readonly layer: "runtime";
+            readonly pluginId: string;
+            readonly poller?: string | undefined;
+            readonly runId?: string | undefined;
+        };
+    };
+} | {
     readonly kind: "time";
     readonly scheduledAtMs: number;
 } | {
@@ -2648,6 +2699,16 @@ export declare type KayAppAutomationMatch = {
     readonly requestedBy?: "user" | "agent" | undefined;
 };
 
+/** Match any listed type; filters use strict equality or scalar-list containment. */
+export declare interface KayAppAutomationPluginEventCondition {
+    readonly kind: "plugin-event";
+    readonly events: readonly string[];
+    readonly where?: readonly {
+        readonly path: string;
+        readonly equals: string | number | boolean;
+    }[];
+}
+
 /**
  * One URI a run produced: every URI its successful `write` and `edit` calls
  * changed, every URI a tool declared it created or updated, and every row
@@ -2683,7 +2744,7 @@ export declare interface KayAppAutomationRun {
     readonly id: string;
     readonly bindingId: string;
     readonly logicalKey: string;
-    readonly status: "claimed" | "queued" | "running" | "succeeded" | "failed" | "skipped" | "abandoned";
+    readonly status: "claimed" | "queued" | "running" | "succeeded" | "failed" | "skipped";
     readonly match: KayAppAutomationMatch;
     readonly generation: string;
     readonly claimedAtMs: number;
@@ -2757,16 +2818,17 @@ export declare type KayAppAutomationRunOutcome = {
 } | {
     readonly status: "failed";
     readonly summary?: KayAppRunSummary | undefined;
-    readonly reason: "executor_failed" | "permission_denied" | "surface_unavailable" | "target_gone";
+    /**
+     * Which part of the lane refused or failed. Absent on a run an earlier build recorded with
+     * a reason this build no longer names; nothing is reconstructed.
+     */
+    readonly reason?: "executor_failed" | "permission_denied" | "surface_unavailable" | "owner_missing" | "target_missing" | "declaration_gone" | undefined;
     readonly message?: string | undefined;
     /** How many tries the run's effect took, when more than one. */
     readonly tries?: number | undefined;
 } | {
     readonly status: "skipped";
-    readonly reason: "already_running" | "binding_inactive" | "circuit_breaker" | "concurrency_capped" | "guard_not_satisfied" | "missed_window" | "timer_cancelled";
-} | {
-    readonly status: "abandoned";
-    readonly reason: "daemon_restart";
+    readonly reason: "already_running" | "binding_inactive" | "guard_not_satisfied" | "missed_window" | "timer_cancelled";
 };
 
 export declare interface KayAppAutomations {
@@ -2805,6 +2867,7 @@ export declare interface KayAppAutomations {
         readonly catchUpGraceMs?: number;
         readonly expiresAtMs?: number;
         readonly maxRuns?: number;
+        readonly concurrency?: KayAppAutomationConcurrency;
     }, ctx: KayAppAutomationContext): Promise<{
         readonly kind: "created";
         readonly binding: KayAppAutomationBinding;
@@ -3089,12 +3152,23 @@ export declare interface KayAppCorpus {
      */
     readEntries(sessionId: string): AsyncIterable<TranscriptEntry>;
     /**
-     * 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.
-     * A page can hold no entries at all (a run of storage lines) while more follows; a record
-     * longer than the page is stepped over and counted in `oversizedRecords`.
+     * Active-branch entries from the latest canonical human turn opener (send companions included)
+     * through the anchor, oldest first. Mid-turn steers and machine wakes remain inside that window;
+     * attachment-only openers and fresh card answers count. Missing sessions/anchors return [];
+     * unsupported hosts may omit it.
+     * Reads never fall back to materializing the full log.
+     */
+    readLatestHumanWindow?(sessionId: string, options?: {
+        readonly throughEntryId?: string;
+    }): Promise<readonly TranscriptEntry[]>;
+    /**
+     * Read one bounded page of a session's stored transcript. The host resolves `sessionId` to its
+     * authoritative indexed path and validates the opaque cursor before reading. When
+     * `throughEntryId` is supplied, the page ends at that entry and the cursor stays at the start of
+     * the commit holding it: the commit's other entries are returned for the caller to filter, and
+     * the next page replays that commit. A page can hold no entries at all (storage records with no
+     * entry) while more follows; a record longer than the page is stepped over and counted in
+     * `oversizedRecords`.
      */
     readEntryBatch?(sessionId: string, options?: {
         readonly cursor?: JsonValue;
@@ -3109,7 +3183,7 @@ export declare interface KayAppCorpus {
     readSessionSourceMark(sessionId: string): Promise<KayAppCorpusSourceMark | undefined>;
 }
 
-/** One bounded physical page from the host's incremental JSONL reader. */
+/** One bounded page from the host's stored transcript reader. */
 export declare interface KayAppCorpusEntryBatch {
     readonly entries: readonly TranscriptEntry[];
     /** Opaque JSON cursor after the physical page; only the host may interpret it or open its path. */
@@ -3759,11 +3833,9 @@ export declare interface KayAppPaths {
      *
      * Unlike `telemetryRoot`, this can be granted yet absent: compositions that spawn no log lane
      * (test and eval hosts) hand the daemon no logs directory, and the field is then omitted rather
-     * than guessed. Event content redaction differs by lane and configuration — the daemon lane
-     * omits tool content outright; the Desktop lane captures it when `observability.contentCapture`
-     * is on (off by default in packaged builds, on by default unpackaged — a packaged user CAN
-     * enable it, so never assume rows from a packaged install are content-free). Absent `content`
-     * on a row is the normal case.
+     * than guessed. Desktop and daemon logs contain the same diagnostic facts exported to
+     * PostHog; call content is never recorded. Historical files can contain private content
+     * from older builds, and diagnostic errors/stacks can contain file paths.
      */
     readonly logsRoot?: string;
 }
@@ -3900,7 +3972,7 @@ export declare interface KayAppPluginApi {
      */
     readonly sessionEvents: KayAppSessionEvents;
     /**
-     * Grant-gated time-triggered workflow registration. Present for a plugin the host has a workflow
+     * Grant-gated workflow registration, started on a time schedule or the plugin's own events. Present for a plugin the host has a workflow
      * namespace for; `undefined` otherwise. The first `define` asks for the `workflows.define` claim
      * in the user's grant ledger — no manifest request and no source-class gate — and it is decided
      * once `activate()` resolves: an ungranted plugin does not start until the user allows it. A
@@ -4013,6 +4085,36 @@ export declare interface KayAppPluginEvents {
     publish(localId: string, input: PluginEventPublishInput): void;
 }
 
+export declare interface KayAppPollerEvent {
+    readonly localId: string;
+    readonly input: PluginEventPublishInput;
+}
+
+export declare interface KayAppPollerOptions<Cursor extends JsonValue> {
+    readonly name: string;
+    readonly description: string;
+    /** Interval in milliseconds; the workflow engine enforces its scheduling floor. */
+    readonly every: number;
+    readonly serviceId: string;
+    readonly schemeId?: string;
+    readonly resolveCredential: (account: KayAppAccountSummary, runId: string) => Promise<KayAppBackgroundCredentialResult>;
+    /** Cursor, events, and summary must contain no credentials or other secrets. */
+    readonly poll: (input: {
+        readonly account: KayAppAccountSummary;
+        readonly cursor: Cursor | undefined;
+        readonly credential: Extract<KayAppBackgroundCredentialResult, {
+            readonly status: "resolved";
+        }>;
+        readonly runId: string;
+    }) => Promise<KayAppPollResult<Cursor>>;
+}
+
+export declare interface KayAppPollResult<Cursor extends JsonValue> {
+    readonly cursor: Cursor;
+    readonly events?: readonly KayAppPollerEvent[];
+    readonly summary?: string;
+}
+
 export declare type KayAppProcessingSpeed = "standard" | "fast";
 
 /**
@@ -4456,6 +4558,17 @@ export declare type KayAppSessionRunCompletion = {
 /** Provider-neutral recorded classification; an unclassified failure omits the field. */
 export declare type KayAppSessionRunFailureReason = Exclude<RunFailureReason, "unknown">;
 
+/**
+ * The identity of a failed run's retained failure: the same ref the runtime keeps on the
+ * session and the automation run. A workflow that fails BECAUSE this run failed passes it as
+ * its error's `cause` (`{ cause: { failureRef } }`), and the host reports that failure, not a
+ * guess from whichever run settled last.
+ */
+export declare interface KayAppSessionRunFailureRef {
+    readonly authority: string;
+    readonly id: string;
+}
+
 /** One host-tool name in a one-shot system run's explicit ceiling. */
 export declare type KayAppSessionRunHostToolName = string;
 
@@ -4542,6 +4655,8 @@ export declare interface KayAppSessionRunInput {
 
 export declare type KayAppSessionRunOutcome = (KayAppSessionRunBase & {
     readonly state: "failed";
+    /** The retained failure's identity, when the runtime kept one for this run. */
+    readonly failureRef?: KayAppSessionRunFailureRef | undefined;
     /** Present when the runtime could classify the failure. */
     readonly failureReason?: KayAppSessionRunFailureReason | undefined;
     /** Bounded provider-suggested delay before retrying this terminal failure. */
@@ -5983,14 +6098,13 @@ export declare interface KayAppWhiteboardTypes {
  * - **Do not hold state in module scope and expect it to survive.** A recovery may happen in a
  *   different process. Anything you need later belongs in a step's return value.
  */
-export declare interface KayAppWorkflowContext {
+export declare interface KayAppWorkflowContext<Trigger extends KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger> {
     /** State from the last successful run; undefined until a run saves it. */
     readonly state: JsonValue | undefined;
     readonly automationId: string;
     readonly runId: string;
-    readonly match: Extract<KayAppAutomationMatch, {
-        readonly kind: "time" | "manual";
-    }>;
+    /** What started this run; see {@link KayAppWorkflowMatch}. */
+    readonly match: KayAppWorkflowMatch<Trigger>;
     /**
      * Record a step's result for replay.
      *
@@ -6048,17 +6162,23 @@ export declare interface KayAppWorkflowContext {
     runAgent(agent: KayAppAgentDefinitionRef, input: Omit<KayAppSessionRunInput, "agent">): Promise<KayAppSessionRunOutcome>;
 }
 
-export declare interface KayAppWorkflowDefinition {
+export declare interface KayAppWorkflowDefinition<Trigger extends KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger> {
     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) => Promise<{
-        /** Replacement JSON state, at most 64 KiB; omission keeps the previous value. */
+    readonly trigger: Trigger;
+    /**
+     * How many runs may be in progress at once. Absent means `sequential`. A `parallel` workflow
+     * suits an event trigger whose runs each handle their own event; it cannot return `state`.
+     */
+    readonly concurrency?: KayAppAutomationConcurrency;
+    readonly run: (context: KayAppWorkflowContext<Trigger>) => Promise<{
+        /**
+         * Replacement JSON state, at most 64 KiB; omission keeps the previous value. Only a
+         * sequential workflow may return it: a `parallel` run that does fails.
+         */
         readonly state?: JsonValue | undefined;
         readonly summary: KayAppRunSummary;
         readonly produced?: KayAppRunProduced;
@@ -6066,6 +6186,16 @@ export declare interface KayAppWorkflowDefinition {
     }>;
 }
 
+/**
+ * The event that started a run, as the publisher sent it. The publishing session is withheld.
+ * This is the run's private input, so it carries `payload`, `related` and `key`, which the
+ * public run history's event identity leaves out.
+ */
+export declare type KayAppWorkflowEvent = Readonly<Omit<PluginEventEnvelope, "related" | "source">> & {
+    readonly related?: Readonly<Record<string, string | readonly string[]>> | undefined;
+    readonly source: Readonly<Omit<PluginEventEnvelope["source"], "sessionId">>;
+};
+
 /** Fail a workflow while retaining its own explanation beside this attempt. */
 export declare class KayAppWorkflowFailure extends Error {
     readonly summary: KayAppRunSummary;
@@ -6097,11 +6227,43 @@ export declare type KayAppWorkflowInstruction = {
     readonly ref: KayAppAutomationScriptRef;
 };
 
+/**
+ * What started a run, by trigger: a time workflow sees `time`, an event workflow sees
+ * `plugin-event`, and either sees `manual` for Run now and retries. A retry, even of an event run,
+ * arrives as `manual` without the event.
+ */
+export declare type KayAppWorkflowMatch<Trigger extends KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger> = Extract<KayAppAutomationMatch, {
+    readonly kind: "manual";
+}> | (Trigger extends {
+    readonly kind: "plugin-event";
+} ? {
+    readonly kind: "plugin-event";
+    readonly event: KayAppWorkflowEvent;
+} : Extract<KayAppAutomationMatch, {
+    readonly kind: "time";
+}>);
+
 export declare interface KayAppWorkflows {
-    define(localId: string, definition: KayAppWorkflowDefinition): void;
+    define<Trigger extends KayAppWorkflowTrigger>(localId: string, definition: KayAppWorkflowDefinition<Trigger>): void;
     inspect(localId: string, options?: KayAppWorkflowInspectOptions): Promise<KayAppWorkflowInspection>;
 }
 
+export declare type KayAppWorkflowTimeTrigger = Extract<KayAppAutomationConditionInput, {
+    readonly kind: "time";
+}>;
+
+/**
+ * What starts a workflow: a time schedule, or one or more of this plugin's own declared events.
+ *
+ * An event trigger names full event types (`google.gmail.message.received`) and takes the same
+ * filters as a `plugin-event` automation. Each matching event starts one run. Only events this
+ * plugin declares are accepted; another plugin's events are refused at `define`.
+ *
+ * A run is not started by an event that one of this workflow's own runs published, as long as the
+ * publish names the run: pass `source: { runId: ctx.runId }` (the Poller helper does).
+ */
+export declare type KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger | KayAppAutomationPluginEventCondition;
+
 /**
  * Read/arrange access to the live desktop workspace (tabs, panes, the shell chrome). Always
  * present. `snapshot` is ungated; `execute` is checked per call against the `workspace.command`
@@ -6508,13 +6670,7 @@ declare interface MessageEntry extends EntryBase {
 /** TypeBox instantiation metrics */
 declare const Metrics: TMetrics;
 
-/**
- * A hidden kernel statement delivered before resuming a tool-requested compaction stop.
- *
- * Module-local, unlike every sibling above it: this message is never rendered and never matched
- * by name outside this file, so exporting the string would only publish something no surface
- * consumes. It earns an export the day one needs to recognise it.
- */
+/** A hidden kernel statement delivered before resuming a tool-requested compaction stop. */
 declare const MID_TURN_COMPACTION_OUTCOME_CUSTOM_TYPE = "mid_turn_compaction_outcome";
 
 /**
@@ -7679,9 +7835,37 @@ declare function ReturnType_2<Type extends TSchema>(type: Type, options?: TSchem
 /** Creates a deferred ReturnType action. */
 declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?: TSchemaOptions): TReturnTypeDeferred<Type>;
 
+/**
+ * The hidden message a continued run rides as its admission ticket (a mid-turn compaction
+ * resume, a run-recovery re-drive). The engine writes it; this package's placement rows keep it
+ * out of the canonical transcript.
+ */
+declare const RUN_CONTINUATION_CARRIER_CUSTOM_TYPE = "herd_run_continuation";
+
 /** Observed cause of a failed request or interrupted run. */
 declare const RUN_FAILURE_REASONS: readonly ["auth", "cancelled", "content_blocked", "context_overflow", "invalid_request", "model_disabled", "model_unavailable", "network", "organization_unavailable", "overloaded", "quota_exhausted", "rate_limit", "runtime_interrupted", "safeguard_block", "seat_unpaid", "server_error", "sign_in_required", "stream_interrupted", "timeout", "unknown"];
 
+/**
+ * What a {@link RUN_CONTINUATION_CARRIER_CUSTOM_TYPE} carrier records about the failed turns it
+ * continues.
+ */
+declare interface RunContinuationCarrierDetails {
+    readonly provenance: {
+        readonly source: "core";
+    };
+    /**
+     * Visible text the failed turns since the previous carrier streamed before they died. Absent
+     * when they showed none (thinking, an unexecuted tool call, or a thrown attempt): such a
+     * carrier is plain.
+     */
+    readonly shownText?: string;
+}
+
+declare type RunContinuationCarrierMessage = CustomMessage<RunContinuationCarrierDetails> & {
+    readonly customType: typeof RUN_CONTINUATION_CARRIER_CUSTOM_TYPE;
+    readonly display: false;
+};
+
 declare type RunFailureReason = (typeof RUN_FAILURE_REASONS)[number];
 
 /**
@@ -8260,6 +8444,7 @@ declare const SessionCreator: z.ZodDiscriminatedUnion<[z.ZodObject<{
         cron: "cron";
         occurrence: "occurrence";
         "uri-change": "uri-change";
+        "plugin-event": "plugin-event";
         manual: "manual";
     }>;
 }, z.core.$strict>, z.ZodObject<{
@@ -8351,6 +8536,7 @@ declare const SessionProvenanceRecord: z.ZodObject<{
             cron: "cron";
             occurrence: "occurrence";
             "uri-change": "uri-change";
+            "plugin-event": "plugin-event";
             manual: "manual";
         }>;
     }, z.core.$strict>, z.ZodObject<{
@@ -11201,6 +11387,14 @@ export declare type ToolParametersWire = unknown;
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
 export declare interface ToolPermissionHint {
+    /**
+     * Names this exact call for the approval card, from its validated input: a title and optional
+     * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
+     * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
+     * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
+     * unsafe string costs the description and the call is asked about as before.
+     */
+    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -11327,6 +11521,16 @@ export declare interface ToolPermissionHint {
     readonly defaultPermission?: "allow" | "ask" | "never";
 }
 
+/** What {@link ToolPermissionHint.describePreview} answers. */
+declare interface ToolPreviewDescription {
+    readonly title: string;
+    readonly description?: string;
+    readonly fields?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+}
+
 declare interface ToolReference {
     name: string;
 }

package/dist/kay-app.js

@@ -444,10 +444,159 @@ function isRetryable(result) {
 var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "time",
   "uri-change",
+  "plugin-event",
   "occurrence",
   "delayed-occurrence"
 ];
 
+// packages/plugin-sdk/dist/kay-app/poller.js
+function accountCursors(state) {
+  if (state === void 0)
+    return [];
+  if (state === null || typeof state !== "object" || Array.isArray(state) || !Array.isArray(state.accounts)) {
+    throw new Error("Invalid Poller state");
+  }
+  return state.accounts.map((entry) => {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry) || typeof entry.schemeId !== "string" || typeof entry.accountId !== "string" || !("cursor" in entry)) {
+      throw new Error("Invalid Poller account cursor");
+    }
+    return {
+      schemeId: entry.schemeId,
+      accountId: entry.accountId,
+      cursor: entry.cursor
+    };
+  });
+}
+function ordinal(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function plainText(value, max) {
+  let text = "";
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    const printable = code < 32 || code === 127 ? " " : character;
+    if (text.length + printable.length > max)
+      break;
+    text += printable;
+  }
+  return text;
+}
+function definePoller(app, localId, options) {
+  const { workflows, auth, events } = app;
+  if (!workflows)
+    throw new Error("Poller requires workflows");
+  if (!Number.isSafeInteger(options.every) || options.every <= 0) {
+    throw new TypeError("Poller interval must be a positive integer in milliseconds");
+  }
+  workflows.define(localId, {
+    name: options.name,
+    description: options.description,
+    trigger: {
+      kind: "time",
+      schedule: { kind: "every", intervalMs: options.every, anchorAtMs: 0 }
+    },
+    async run(ctx) {
+      if (!auth)
+        throw new Error("Poller requires account listing");
+      const previous = accountCursors(ctx.state);
+      const accounts = await ctx.runStep(async () => {
+        const listed = await auth.listAccounts({
+          serviceId: options.serviceId,
+          ...options.schemeId === void 0 ? {} : { schemeId: options.schemeId }
+        });
+        return [...listed].sort((a, b) => ordinal(a.schemeId, b.schemeId) || ordinal(a.accountId, b.accountId));
+      }, { name: "list-poller-accounts" });
+      const next = [];
+      const details = [];
+      let published = 0;
+      let initialized = 0;
+      let skipped = 0;
+      let failed = 0;
+      for (const account of accounts) {
+        const saved = previous.find((entry) => entry.schemeId === account.schemeId && entry.accountId === account.accountId);
+        const outcome = await ctx.runStep(async () => {
+          if (account.status === "needs_reauth" || account.status === "refresh_failed" || account.status === "revoked") {
+            return {
+              status: "skipped",
+              summary: `Sign-in required (${account.status})`
+            };
+          }
+          let credential;
+          try {
+            credential = await options.resolveCredential(account, ctx.runId);
+          } catch {
+            throw new Error("Poller credential resolution failed");
+          }
+          if (credential.status !== "resolved") {
+            return {
+              status: "skipped",
+              summary: credential.status === "requires-auth" ? "Sign-in or required scope missing" : "Credential missing"
+            };
+          }
+          try {
+            const result = await options.poll({
+              account,
+              cursor: structuredClone(saved?.cursor),
+              credential,
+              runId: ctx.runId
+            });
+            return {
+              status: "polled",
+              result: {
+                cursor: result.cursor,
+                ...saved === void 0 || result.events === void 0 ? {} : { events: result.events },
+                ...result.summary === void 0 ? {} : { summary: plainText(result.summary, 600) }
+              }
+            };
+          } catch {
+            return {
+              status: "failed",
+              summary: "Provider poll failed; cursor retained"
+            };
+          }
+        }, { name: "poll-account" });
+        if (outcome.status !== "polled") {
+          if (saved !== void 0)
+            next.push(saved);
+          if (outcome.status === "skipped")
+            skipped++;
+          else
+            failed++;
+          details.push(`${account.schemeId}/${account.accountId}: ${outcome.summary}`);
+          continue;
+        }
+        await ctx.runStep(async () => {
+          for (const event of outcome.result.events ?? []) {
+            events.publish(event.localId, {
+              ...event.input,
+              source: { poller: localId, runId: ctx.runId }
+            });
+          }
+          return null;
+        }, { name: "publish-poller-events" });
+        published += outcome.result.events?.length ?? 0;
+        if (saved === void 0)
+          initialized++;
+        next.push({
+          schemeId: account.schemeId,
+          accountId: account.accountId,
+          cursor: outcome.result.cursor
+        });
+        if (outcome.result.summary)
+          details.push(`${account.schemeId}/${account.accountId}: ${outcome.result.summary}`);
+      }
+      return {
+        state: { accounts: next },
+        summary: {
+          headline: plainText(`${published} events; ${initialized} initialized; ${skipped} skipped; ${failed} failed`, 100),
+          ...details.length === 0 ? {} : { details: plainText(details.join("; "), 600) },
+          author: "automation"
+        }
+      };
+    }
+  });
+}
+
 // packages/plugin-sdk/dist/kay-app/skills.js
 function createUnavailableSkills(message) {
   const unavailable = {
@@ -505,6 +654,9 @@ function createUnavailableUsage(message) {
 }
 
 // packages/plugin-sdk/dist/kay-app/workflows.js
+function failedRunCause(outcome) {
+  return outcome.kind === "ran" && outcome.state === "failed" && outcome.failureRef !== void 0 ? { cause: { failureRef: outcome.failureRef } } : {};
+}
 var KayAppWorkflowFailure = class extends Error {
   summary;
   constructor(summary, options) {
@@ -537,6 +689,8 @@ export {
   createUnavailableSkills,
   createUnavailableTools,
   createUnavailableUsage,
+  definePoller,
+  failedRunCause,
   invalidObservation,
   isRetryable,
   parseLineSelector,