@ekanos/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.3.0",
-  "private": false,
+  "version": "0.3.1",
   "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",
@@ -34,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@ekanos/integration-schema": "0.2.0",
+    "@ekanos/integration-schema": "0.3.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },

package/templates/AGENTS.md.tmpl

@@ -27,6 +27,7 @@ export const integration = defineIntegration<MyStorage>({
   permissions: [ /* disclosure of what you read/write */ ],
   components: { widgets: [ /* … */ ] },
   tools: [ /* assistant-callable functions */ ],
+  actions: { /* deterministic, widget-invoked server handlers */ },
   webhooks: [ /* inbound deliveries */ ],
   schedules: [ /* cron runs */ ],
   onActivate: async (ctx) => { /* seed caches, sanity-check credentials */ },
@@ -172,6 +173,76 @@ failure). Schedule results: `{ status: 'completed' }` / `{ status: 'skipped' }`
 (`invocation.trigger` distinguishes them). Cron is 5-field numeric only — no
 names, no `@daily`, no seconds.
 
+### Actions
+
+`actions` is a record — keyed by kebab-case action name (`'create-record'`,
+not `tools`' `snake_case`) — of deterministic, widget-invoked server
+handlers. It is a **parallel surface to `tools`, not a flag on it**: a
+widget's Save button already has fully-typed, user-entered values, so it
+calls your handler directly instead of routing a natural-language prompt
+through the assistant and hoping the model picks the right tool with the
+right arguments.
+
+```ts
+actions: {
+  'create-record': {
+    description: 'Create a record in the base.',
+    input: CreateRecordInput,             // a real zod schema
+    output: CreateRecordOutput,           // optional — validates what handler resolves to
+    handler: async (ctx, input) => {
+      // Same ctx every tool/webhook/schedule handler gets: ctx.fetch,
+      // ctx.secrets, ctx.storage — runs server-side, never in the browser.
+      return createRecordViaApi(ctx, input);
+    },
+  },
+},
+```
+
+`input` (and the optional `output`) are real `z.ZodTypeAny` instances, not
+the JSON-schema-shaped `parameters` a tool declares for LLM argument
+synthesis — an action is only ever parsed in-process, never serialized to a
+model. Export the inferred types alongside the declaration
+(`export type CreateRecordInput = z.infer<typeof CreateRecordInput>`) so the
+widget importing them gets real autocomplete, per the SDK typing note below.
+
+**Invoke it from a widget with `useIntegrationAction()`** (`@ekanos/sdk/hooks`)
+— never `useAskAssistant()` for this. `useAskAssistant()` sends a
+conversational question to the assistant dock (`Widget.AskFooter`'s "ask
+anything about this widget"); it is not a write path and does not call your
+handler deterministically. A form's Save button calls the handler you
+declared, with the exact values the user typed:
+
+```tsx
+const createRecord = useIntegrationAction<CreateRecordInput, CreateRecordOutput>(
+  '__SLUG__',
+  'create-record',
+  { accountId },
+);
+
+<Button onClick={() => createRecord.mutate(formValues)} disabled={createRecord.isPending}>
+  Save
+</Button>
+```
+
+A rejected mutation's `error` is always an `IntegrationActionError`
+(`status`, `code`, and — for a 400 — your own declared zod `issues`), never a
+raw fetch exception. The route answers a fixed set of `code`s your widget can
+branch on without string-matching: `action_not_found`, `invalid_input`,
+`rate_limited`, `handler_error` (plus the client-assigned `network_error` /
+`invalid_response` for a request that never reached a valid envelope).
+
+A handler that wants its OWN message shown to the end user verbatim (e.g.
+"That record already exists") throws `PublicActionError`
+(`@ekanos/sdk/integration`) — the one escape hatch from the route's default
+opaque `handler_error` message. Every other throw collapses to a generic
+"Action failed." on the wire, though the real error is always logged
+server-side.
+
+Reuse one handler as both an action and a tool without double-declaring
+logic — export the handler once and reference it from both declarations
+(`run: (ctx, args) => createRecord.handler(ctx, CreateRecordInput.parse(args))`)
+if you also want the assistant able to call it.
+
 ### `onActivate`
 
 Runs once after an activation is first persisted, and again after
@@ -222,6 +293,12 @@ harness and in production. A widget reads declared `clientReadable`
 account-scope storage back with `fetchIntegrationStorage()` from
 `@ekanos/sdk/hooks`.
 
+For a widget that WRITES — a form's Save button, not a read — reach for
+`useIntegrationAction()` (see "Actions" above), not `useAskAssistant()`.
+`useAskAssistant()` sends a conversational question to the assistant dock;
+it is not a deterministic write path and gives no guarantee the model calls
+your handler with the values the user actually typed.
+
 Build widget UI from `@ekanos/ui` — the published slice of the host design
 system. Available modules (import individually, e.g. `@ekanos/ui/button`):
 `alert`, `badge`, `button`, `card`, `dialog`, `dropdown-menu`, `form`, `icon`,
@@ -307,14 +384,18 @@ what the live context is for.
 
 Two different fetches, two different guarantees:
 
-- **`ctx.fetch` (handlers — `onActivate`/webhooks/schedules/tools).** Real
-  enforcement, in the harness AND in production: your `egress` allowlist,
-  redirect re-vetting, IP pinning. Locally it depends on the toolbar: in
-  fixtures mode handlers run in the browser against the mock context and
-  `ctx.fetch` answers from your fixtures, never the network; in live mode
-  they run on the dev server's live context and `ctx.fetch` reaches the real
-  vendor, egress-checked first — which is how the OAuth code exchange and a
-  post-connect sync work locally at all.
+- **`ctx.fetch` (handlers — `onActivate`/webhooks/schedules/tools/actions).**
+  Real enforcement, in the harness AND in production: your `egress`
+  allowlist, redirect re-vetting, IP pinning. Locally it depends on the
+  toolbar: in fixtures mode handlers run in the browser against the mock
+  context and `ctx.fetch` answers from your fixtures, never the network; in
+  live mode they run on the dev server's live context and `ctx.fetch` reaches
+  the real vendor, egress-checked first — which is how the OAuth code
+  exchange and a post-connect sync work locally at all. An `actions[name]`
+  handler is executed exactly the same way as a tool or webhook handler — a
+  widget's `useIntegrationAction()` call never reaches the vendor directly;
+  it always crosses through your server-side handler and `ctx.fetch` first,
+  in the harness and in production alike.
 - **`useIntegrationFetch()` (widgets, browser-side).** In the harness, live
   mode routes it through the same egress check as a convenience, enforced
   centrally rather than something you configure per widget. **That check
@@ -328,7 +409,14 @@ Two different fetches, two different guarantees:
 In short: widgets get real network in Live API mode, gated by convenience in
 the harness and by nothing in production; handlers get fixtures in fixtures
 mode and the real, enforced thing in live mode — locally on the dev server,
-then on the host after publish.
+then on the host after publish. `actions` handlers follow the handler rule:
+`useIntegrationAction()` in the harness runs your handler against fixtures
+by default, same as `invokeWebhook`/`invokeSchedule` — live execution is an
+explicit, per-session opt-in from the dev toolbar (a confirmation the first
+time a call would touch the real vendor that session, not a per-call
+prompt), never the default. In production there is only one mode: the
+handler always runs server-side with the real `IntegrationContext` and real
+`ctx.fetch` egress enforcement.
 
 ## Testing
 

package/templates/package.json.tmpl

@@ -15,8 +15,8 @@
     "@ekanos/ui": "^0.2.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.2.2",
-    "@ekanos/harness": "^0.1.5",
+    "@ekanos/cli": "^0.3.0",
+    "@ekanos/harness": "^0.2.0",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/postcss": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",

package/templates/skills/build-integration/SKILL.md

@@ -52,8 +52,10 @@ otherwise ask in plain prose with lettered options.
 3. **The outcomes** (free text): "What should a team see on their dashboard,
    and what should the integration be able to do?" Push for 1–3 concrete
    outcomes ("show open invoices", "alert on new disputes", "let the
-   assistant create a customer"). Each SEE-outcome becomes a widget; each
-   DO-outcome becomes a tool, webhook, or schedule.
+   assistant create a customer", "let someone create a record from a
+   dashboard form"). Each SEE-outcome becomes a widget; each DO-outcome
+   becomes a tool (assistant-invoked), a webhook/schedule (event-driven), or
+   an action (a widget's own deterministic write — a form's Save button).
 4. **Auth** (choice): API key / Bearer / OAuth 2.0 / Basic / not sure
    (research will settle it). This decides the activation-form fields — and
    every string field name on that form IS a secret name (see AGENTS.md).
@@ -134,7 +136,9 @@ notes, update `docs/api-notes.md` in the same commit as the code fix.
 
 Order: activation form (field names = secret names, keep them in exported
 constants) → server handlers using `ctx.fetch` / `ctx.storage` /
-`ctx.secrets` only → tools → webhooks/schedules. For an OAuth integration,
+`ctx.secrets` only → tools → webhooks/schedules → actions (deterministic
+widget writes — a form's Save button, invoked with `useIntegrationAction()`,
+never routed through the assistant). For an OAuth integration,
 also read `references/oauth-setup.md`: it tells you what to put on the
 harness entry so the harness walks the user through their provider's console,
 and how to hand the user off to the Local OAuth panel — the user's secrets

package/templates/skills/build-integration/references/api-wiring.md

@@ -30,6 +30,15 @@ code. This file is the order of work and the traps.
    `fetchIntegrationStorage()` from `@ekanos/sdk/hooks`. Cache freshness in
    the stored value (`fetchedAt`) and show it in the UI when staleness
    matters.
+6. **Widget writes** — the read path's mirror. A form's Save button declares
+   an `actions[name]` handler (zod `input`, optional `output`, `handler(ctx,
+   input)`) and calls it with `useIntegrationAction()` from
+   `@ekanos/sdk/hooks` — deterministic, with the values the user actually
+   typed, never a natural-language hand-off to the assistant. A handler that
+   wants its own message shown to the user verbatim throws
+   `PublicActionError` from `@ekanos/sdk/integration`; every other throw
+   collapses to a generic error on the wire (still logged in full
+   server-side). See "Actions" in AGENTS.md.
 
 ## Traps, each one earned
 
@@ -94,4 +103,8 @@ on its `harness.config.ts` entry — see AGENTS.md "Live mode") and the
 toolbar's fixtures ⇄ live switch runs real widget queries against the real
 API, gated only by the declared `egress`. Use fixtures for the Fusion-side
 state widgets need first, and for webhook/schedule handlers (the Triggers
-surface runs those against the mock context by design).
+surface runs those against the mock context by design). `actions[name]`
+handlers follow the same rule: `useIntegrationAction()` calls run against
+fixtures by default, and only reach the real vendor after an explicit,
+per-session live-mode confirmation from the toolbar — never on the first
+call by accident.

package/templates/skills/build-integration/references/widget-design.md

@@ -35,6 +35,14 @@ name the question for is a widget you cannot design.
 | Chart               | "Which way is it going?"           | The chart + current value; axes and legends muted                     |
 | Action / connection | "What can I do / who's connected?" | One clear CTA or the identity + status                                |
 
+A widget whose CTA WRITES something (a form, a "Create record" button) calls
+a declared `actions[name]` handler via `useIntegrationAction()` — a
+deterministic RPC with the values the user actually typed, not a
+conversational hand-off. Reach for `useAskAssistant()` only for an actual
+"ask about this" affordance (`Widget.AskFooter`); it is not a write path and
+gives no guarantee the assistant calls anything with the right arguments.
+See "Actions" in `AGENTS.md`.
+
 The default failure is uniform weight: everything `text-sm`, values dressed
 like labels. Squint at the render — if nothing reads first, there is no
 hierarchy, and no amount of padding will save it.
@@ -74,8 +82,10 @@ Every widget: `'use client'`, `Widget.DataState` wrapping `Widget.Card` →
 fetching on `ctx?.state.state === 'active'` from `WidgetContext`, and fetch
 with `useIntegrationFetch()` from `@ekanos/sdk/hooks` — never global
 `fetch` — reaching for `useActivationData()` (same module) if the widget
-needs a client-visible credential. Copy the canonical example from the SDK
-README rather than improvising the tree.
+needs a client-visible credential. For a write (a form submit), call
+`useIntegrationAction()` (same module) instead — it posts to your declared
+`actions[name]` handler, not the vendor directly. Copy the canonical example
+from the SDK README rather than improvising the tree.
 
 `Widget.Active` itself renders flush (no padding) so full-bleed charts and
 tables can run edge-to-edge. For ordinary content — text, rows, a KPI

package/templates/src/integration.ts.tmpl

@@ -80,4 +80,20 @@ export const integration = defineIntegration({
       },
     },
   ],
+
+  // `actions` is the deterministic counterpart to `tools`: a widget's own
+  // Save button calls a declared handler directly (via `useIntegrationAction()`
+  // from `@ekanos/sdk/hooks`), with the exact values the user typed — never a
+  // natural-language hand-off to the assistant. Uncomment and adapt once a
+  // widget needs to write something; see "Actions" in AGENTS.md.
+  //
+  // actions: {
+  //   'create-record': {
+  //     description: 'Create a record in the base.',
+  //     input: z.object({ name: z.string().min(1) }),
+  //     handler: async (_ctx, input) => {
+  //       return { id: 'rec_123', name: input.name };
+  //     },
+  //   },
+  // },
 });