@yaklabs-ai/plugin-sdk 0.15.1 → 0.15.3

package/dist/kay-app.js

@@ -449,6 +449,154 @@ var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "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 = {
@@ -506,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) {
@@ -538,6 +689,8 @@ export {
   createUnavailableSkills,
   createUnavailableTools,
   createUnavailableUsage,
+  definePoller,
+  failedRunCause,
   invalidObservation,
   isRetryable,
   parseLineSelector,

package/dist/phase-shift.d.ts

@@ -114,14 +114,13 @@ declare interface TranscriptSourceEntryLike extends TranscriptTreeEntryLike {
 
 /**
  * A session entry as {@link branchEntryIds} reads it: the fields above plus the
- * tree links the walk follows to find the active branch. No timestamp: the walk
- * never reads one, and a live v2 entry carries epoch milliseconds where a raw
- * v3 log carries an ISO string, so requiring either shape here would force one
+ * parent link the walk follows to find the active branch. No timestamp: the walk
+ * never reads one, and callers hold entries whose timestamp is epoch
+ * milliseconds or an ISO string, so requiring either shape here would force one
  * class of caller to convert entries it only wants walked.
  */
 declare interface TranscriptTreeEntryLike extends TranscriptEntryLike {
     readonly parentId?: string | null;
-    readonly targetId?: string | null;
 }
 
 export { }

package/dist/phase-shift.js

@@ -14,7 +14,7 @@ function branchEntryIds(entries) {
     return EMPTY_BRANCH_IDS;
   const byId = new Map(entries.map((entry) => [entry.id, entry]));
   const onBranch = /* @__PURE__ */ new Set();
-  let cursor = last.type === "leaf" ? last.targetId ?? null : last.id;
+  let cursor = last.id;
   while (cursor !== null && !onBranch.has(cursor)) {
     onBranch.add(cursor);
     cursor = byId.get(cursor)?.parentId ?? null;

package/dist/transcript.d.ts

@@ -3,8 +3,8 @@ import { z } from 'zod';
 export declare const ATTACHMENTS_CUSTOM_TYPE = "attachments";
 
 /**
- * The ids on a session's active branch: the leaf chain walked parent-ward from
- * the tip, which a trailing `leaf` marker moves. Empty for an empty log.
+ * The ids on a session's active branch: the parent chain walked from the tip,
+ * the last entry. Empty for an empty log.
  *
  * One walk shared by every reader of "is this entry still live", so a rewind
  * means the same thing to every projection that calls it. Self-guarding
@@ -106,14 +106,13 @@ export declare interface TranscriptSourceEntryLike extends TranscriptTreeEntryLi
 
 /**
  * A session entry as {@link branchEntryIds} reads it: the fields above plus the
- * tree links the walk follows to find the active branch. No timestamp: the walk
- * never reads one, and a live v2 entry carries epoch milliseconds where a raw
- * v3 log carries an ISO string, so requiring either shape here would force one
+ * parent link the walk follows to find the active branch. No timestamp: the walk
+ * never reads one, and callers hold entries whose timestamp is epoch
+ * milliseconds or an ISO string, so requiring either shape here would force one
  * class of caller to convert entries it only wants walked.
  */
 declare interface TranscriptTreeEntryLike extends TranscriptEntryLike {
     readonly parentId?: string | null;
-    readonly targetId?: string | null;
 }
 
 /**

package/dist/transcript.js

@@ -27,7 +27,7 @@ function branchEntryIds(entries) {
     return EMPTY_BRANCH_IDS;
   const byId = new Map(entries.map((entry) => [entry.id, entry]));
   const onBranch = /* @__PURE__ */ new Set();
-  let cursor = last.type === "leaf" ? last.targetId ?? null : last.id;
+  let cursor = last.id;
   while (cursor !== null && !onBranch.has(cursor)) {
     onBranch.add(cursor);
     cursor = byId.get(cursor)?.parentId ?? null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -45,6 +45,10 @@
       "types": "./dist/transcript.d.ts",
       "default": "./dist/transcript.js"
     },
+    "./canonical-transcript": {
+      "types": "./dist/canonical-transcript.d.ts",
+      "default": "./dist/canonical-transcript.js"
+    },
     "./time": {
       "types": "./dist/time.d.ts",
       "default": "./dist/time.js"