@ekanos/cli 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test a Fusion integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ekanos/integration-schema": "0.1.3",
+    "@ekanos/integration-schema": "0.1.4",
     "esbuild": "0.28.1"
   },
   "peerDependencies": {

package/templates/AGENTS.md.tmpl

@@ -29,6 +29,7 @@ export const integration = defineIntegration<MyStorage>({
   tools: [ /* assistant-callable functions */ ],
   webhooks: [ /* inbound deliveries */ ],
   schedules: [ /* cron runs */ ],
+  onActivate: async (ctx) => { /* seed caches, sanity-check credentials */ },
   storage: { account: { /* key → zod schema */ } },
   egress: ['https://api.example.com'],
 });
@@ -45,7 +46,7 @@ lives in both files; `ekanos validate` reports a finding if they disagree.
 ## The capability context (`ctx`) — the ONLY platform surface
 
 Every server-side handler (tool `run`, webhook `handler`, schedule `handler`,
-`oauth.onTokens`) receives one `ctx` object, already scoped to
+`oauth.onTokens`, `onActivate`) receives one `ctx` object, already scoped to
 `{account, integration}` before your code runs.
 
 **Hard rule: NEVER use global `fetch`, `process.env`, or `node:fs` in
@@ -148,6 +149,27 @@ failure). Schedule results: `{ status: 'completed' }` / `{ status: 'skipped' }`
 (`invocation.trigger` distinguishes them). Cron is 5-field numeric only — no
 names, no `@daily`, no seconds.
 
+### `onActivate`
+
+Runs once after an activation is first persisted, and again after
+activationData is updated — **seed the cache in `onActivate`; the schedule
+keeps it fresh.** Without it, a cache-backed widget is empty until the first
+schedule tick. v1 errors are non-fatal: a throw is logged as a warning and the
+activation stays connected, so this is for cache seeding and eager
+validation, never a connect gate. Seed BEST-EFFORT: catch transient upstream
+failures (timeouts, 5xx), log, and return — a throw surfaces a scary warning
+on a brand-new connection that the schedule will heal within one tick anyway.
+Reserve the throw for misconfiguration the user can actually fix.
+
+A cache invalidated only by age still serves the *previous* activation's data
+for a while even with `onActivate` wired up. Close that gap with a
+fingerprint: store a hash of the activation fields a cached value's **values**
+depended on (not just the ones that pick which data to fetch — currency, units
+and locale change the numbers without changing the cache key) alongside the
+value, and treat a mismatch or an absent fingerprint on read as a miss.
+Declare that field `.optional()` on the storage schema, or every pre-existing
+row throws `StorageValidationError` on read.
+
 ## Widgets
 
 Dashboard widgets are client components (`'use client'`) declared at