esoul-sdk 0.3.0 → 0.4.0

package/README.md

@@ -47,7 +47,7 @@ that.
 | Entry | What it gives you |
 |---|---|
 | `esoul-sdk` | `ApplicationSchema`, `EventDefinition`, `EventTypes`, `ApplicationIdentifier`, `incompleteStateNotice`, `deterministicReducerId`, `stableStringify`, `timingSafeEqual`, `nanoid`, `callPluginOp`, the manifest schema |
-| `esoul-sdk/react` | `usePluginEventDispatch`, `useAppCanEdit`, `usePluginCurrentChatId`, `useWorkspaceTools`, file hooks |
+| `esoul-sdk/react` | `usePluginEventDispatch`, `useAppCanEdit`, `usePluginCurrentChatId`, `useWorkspaceTools`, `usePluginRealtime`, file hooks |
 | `esoul-sdk/server` | `PluginServerModule`, `readAppState`, `callWorkspaceTool`, `emitPluginAppEvent`, `getPluginConnectionCredentials`, file provider types |
 | `esoul-sdk/testing` | a mock OAuth server for connection tests |
 | `esoul-app validate <dir>` | validates a package folder against the manifest schema |

package/dist/helpers.d.ts

@@ -38,3 +38,23 @@ export declare function callPluginOp<T = unknown>(pluginId: string, op: string,
  * Pure JS (no node:crypto) so it is safe in any runtime the SDK reaches.
  */
 export declare function timingSafeEqual(a: string, b: string): boolean;
+/**
+ * Kick one of your app's background tasks (docs/07) from the browser OR from
+ * a tool's `execute` on the server. The task must be listed in the
+ * manifest's `kickableTasks`; the platform's send-event route refuses the
+ * rest. `data` rides on `ctx.eventData` — keep it small and JSON. The kick
+ * is fire-and-forget: the task's result lands as events, or on the channel.
+ */
+export declare function kickPluginTask(args: {
+    applicationType: string;
+    taskName: string;
+    identifier: {
+        workspaceId: string;
+        nodeId: string;
+        instanceName?: string;
+    };
+    data?: Record<string, unknown>;
+}): Promise<{
+    ok: boolean;
+    status: number;
+}>;

package/dist/helpers.js

@@ -91,3 +91,32 @@ export function timingSafeEqual(a, b) {
     }
     return diff === 0;
 }
+/**
+ * Kick one of your app's background tasks (docs/07) from the browser OR from
+ * a tool's `execute` on the server. The task must be listed in the
+ * manifest's `kickableTasks`; the platform's send-event route refuses the
+ * rest. `data` rides on `ctx.eventData` — keep it small and JSON. The kick
+ * is fire-and-forget: the task's result lands as events, or on the channel.
+ */
+export async function kickPluginTask(args) {
+    const onServer = typeof window === "undefined";
+    const base = onServer ? (process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000") : "";
+    const headers = { "Content-Type": "application/json" };
+    if (onServer && process.env.INTERNAL_TOOL_SECRET)
+        headers["x-esoul-internal-secret"] = process.env.INTERNAL_TOOL_SECRET;
+    const res = await fetch(`${base}/api/inngest/send-event`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            name: `${args.applicationType}/${args.taskName}`,
+            data: {
+                workspaceId: args.identifier.workspaceId,
+                nodeId: args.identifier.nodeId,
+                applicationType: args.applicationType,
+                instanceName: args.identifier.instanceName,
+                ...(args.data ?? {}),
+            },
+        }),
+    });
+    return { ok: res.ok, status: res.status };
+}

package/dist/index.d.ts

@@ -4,3 +4,22 @@ export * from "./helpers.js";
 export * from "./files.js";
 /** Id minting for dataCreators; an app depends on the SDK, not on nanoid. */
 export { nanoid } from "nanoid";
+/**
+ * Declare an app's realtime channel — one per instance. Inside the host this
+ * is the platform's real channel; outside it (tests, your editor) a
+ * descriptor of the same shape. Put it on the schema as `channel` and pass it
+ * to `usePluginRealtime`; a task publishes on it with `ctx.notify(topic, data)`.
+ */
+export declare function definePluginChannel<T extends Record<string, {
+    schema: unknown;
+}>>(args: {
+    applicationType: string;
+    topics: T;
+}): ((p: {
+    workspaceId: string;
+    nodeId: string;
+}) => Record<keyof T, unknown> & {
+    name: string;
+}) & {
+    topicNames: (keyof T & string)[];
+};

package/dist/index.js

@@ -4,3 +4,20 @@ export * from "./helpers.js";
 export * from "./files.js";
 /** Id minting for dataCreators; an app depends on the SDK, not on nanoid. */
 export { nanoid } from "nanoid";
+/**
+ * Declare an app's realtime channel — one per instance. Inside the host this
+ * is the platform's real channel; outside it (tests, your editor) a
+ * descriptor of the same shape. Put it on the schema as `channel` and pass it
+ * to `usePluginRealtime`; a task publishes on it with `ctx.notify(topic, data)`.
+ */
+export function definePluginChannel(args) {
+    const type = args.applicationType.replace(/[^a-z0-9_]/gi, "_");
+    const factory = ((p) => {
+        const out = { name: `plugin:${type}:${p.workspaceId}:${p.nodeId}` };
+        for (const t of Object.keys(args.topics))
+            out[t] = { topic: t, channel: out.name };
+        return out;
+    });
+    factory.topicNames = Object.keys(args.topics);
+    return factory;
+}

package/dist/react.d.ts

@@ -83,3 +83,32 @@ export declare function usePluginFileUpload(_workspaceId: string): (file: File)
 export declare function useFileSources(_workspaceId: string | null): FileSourcesState;
 /** One mount's listing; a failing source reports error/errorKind, never []. */
 export declare function useFileSourceEntries(_workspaceId: string | null, _sourceId: string | null, _folderRef?: string): FileEntriesState;
+export interface PluginRealtimeMessage<T = unknown> {
+    topic: string;
+    data: T;
+}
+export interface PluginRealtime<T = unknown> {
+    /** Every message received this mount, oldest first. */
+    data: PluginRealtimeMessage<T>[];
+    latestData: PluginRealtimeMessage<T> | null;
+    error: Error | null;
+    /** "connecting" | "active" | "closed" | "error". */
+    state: string;
+}
+/**
+ * Subscribe to this instance's channel (the one you declared with
+ * `definePluginChannel` and put on the schema as `channel`). A task publishes
+ * with `ctx.notify(topic, data)`; each message arrives here as
+ * `{ topic, data }`. Realtime is a NUDGE, never the truth: anything that must
+ * survive a refresh goes on the timeline as an event as well.
+ */
+export declare function usePluginRealtime<T = unknown>(_args: {
+    channel: (p: {
+        workspaceId: string;
+        nodeId: string;
+    }) => unknown;
+    workspaceId: string;
+    nodeId: string;
+    topics: readonly string[];
+    enabled?: boolean;
+}): PluginRealtime<T>;

package/dist/react.js

@@ -41,3 +41,13 @@ export function useFileSources(_workspaceId) {
 export function useFileSourceEntries(_workspaceId, _sourceId, _folderRef) {
     return hostOnly("useFileSourceEntries");
 }
+/**
+ * Subscribe to this instance's channel (the one you declared with
+ * `definePluginChannel` and put on the schema as `channel`). A task publishes
+ * with `ctx.notify(topic, data)`; each message arrives here as
+ * `{ topic, data }`. Realtime is a NUDGE, never the truth: anything that must
+ * survive a refresh goes on the timeline as an event as well.
+ */
+export function usePluginRealtime(_args) {
+    return hostOnly("usePluginRealtime");
+}

package/docs/05-ui.md

@@ -63,6 +63,36 @@ The app renders inside the platform frame at any size: a desktop window, a maxim
 `look_at_app` in the workbench screenshots desktop-light, desktop-dark and phone-light. Open the
 images; a phone shot with a horizontal scrollbar is a bug.
 
+## Live data from a background task
+
+```tsx
+import { usePluginRealtime } from "esoul-sdk/react";
+import { kickPluginTask } from "esoul-sdk";
+import { stopwatchChannel } from "./channel";
+
+const live = usePluginRealtime<{ runId: string; elapsedMs: number; serverNow: number }>({
+  channel: stopwatchChannel,
+  workspaceId: state.workspaceId,
+  nodeId: state.nodeId,
+  topics: stopwatchChannel.topicNames,
+});
+// live.latestData → { topic: "tick", data: {...} } — the newest message, or null.
+// live.data       → everything received this mount, oldest first.
+
+const start = () =>
+  kickPluginTask({
+    applicationType: "plugin_stopwatch",
+    taskName: "tick",
+    identifier: state,
+    data: { runId, kickedAt: Date.now() },
+  });
+```
+
+The subscription is per instance and read-only; the token the platform mints for it carries only
+the topics your schema declares. Treat messages as nudges: what the UI must still show after a
+refresh comes from state, so a task that changes anything durable dispatches an event as well
+(docs/07 has the whole loop, including the stop).
+
 ## Cross-app from the UI
 
 ```ts

package/docs/07-background-tasks.md

@@ -28,7 +28,8 @@ tasks: [
 - `ctx.getState()` — the app's state, fresh.
 - `ctx.dispatchEvent(eventName, eventData)` — through the full pipeline (append, fold, watermark),
   using YOUR processors, so a task's mutation is identical to a tap's.
-- `ctx.notify(topic, data)` — a realtime nudge to the app's channel; the UI refetches.
+- `ctx.notify(topic, data)` — publish on the app's realtime channel (see *Live tasks* below). A
+  nudge, never the truth: the UI hears it while mounted; a refresh only sees the timeline.
 - `ctx.logger`.
 
 ## The replay model — read this twice
@@ -42,8 +43,10 @@ replay; mint them inside. Step names are unique per logical operation; loops inc
 ## How a task gets kicked
 
 - **From a webhook**: `ctx.sendInngestEvent("<applicationType>/<task>", payload)` (docs/06).
-- **From the browser**: list the task in `kickableTasks`; the UI posts the event through the
-  platform's send-event route, which allows only listed tasks.
+- **From the browser or a tool**: list the task in `kickableTasks`, then
+  `kickPluginTask({ applicationType, taskName, identifier, data })` (from `esoul-sdk`; works in
+  a component and in a tool's `execute`). The platform's send-event route allows only listed
+  tasks and stamps nothing — `data` is exactly what `ctx.eventData` sees.
 - **On a cadence**: `pollTasks: [{ task, everyMinutes }]` — one shared platform sweep kicks each
   live instance at 5-minute granularity (minimum 5). This is your cron. There are deliberately
   no per-app Inngest functions: function ids are fixed at module load, and the plan caps

package/llms-full.txt

@@ -51,7 +51,7 @@ that.
 | Entry | What it gives you |
 |---|---|
 | `esoul-sdk` | `ApplicationSchema`, `EventDefinition`, `EventTypes`, `ApplicationIdentifier`, `incompleteStateNotice`, `deterministicReducerId`, `stableStringify`, `timingSafeEqual`, `nanoid`, `callPluginOp`, the manifest schema |
-| `esoul-sdk/react` | `usePluginEventDispatch`, `useAppCanEdit`, `usePluginCurrentChatId`, `useWorkspaceTools`, file hooks |
+| `esoul-sdk/react` | `usePluginEventDispatch`, `useAppCanEdit`, `usePluginCurrentChatId`, `useWorkspaceTools`, `usePluginRealtime`, file hooks |
 | `esoul-sdk/server` | `PluginServerModule`, `readAppState`, `callWorkspaceTool`, `emitPluginAppEvent`, `getPluginConnectionCredentials`, file provider types |
 | `esoul-sdk/testing` | a mock OAuth server for connection tests |
 | `esoul-app validate <dir>` | validates a package folder against the manifest schema |
@@ -491,6 +491,36 @@ The app renders inside the platform frame at any size: a desktop window, a maxim
 `look_at_app` in the workbench screenshots desktop-light, desktop-dark and phone-light. Open the
 images; a phone shot with a horizontal scrollbar is a bug.
 
+## Live data from a background task
+
+```tsx
+import { usePluginRealtime } from "esoul-sdk/react";
+import { kickPluginTask } from "esoul-sdk";
+import { stopwatchChannel } from "./channel";
+
+const live = usePluginRealtime<{ runId: string; elapsedMs: number; serverNow: number }>({
+  channel: stopwatchChannel,
+  workspaceId: state.workspaceId,
+  nodeId: state.nodeId,
+  topics: stopwatchChannel.topicNames,
+});
+// live.latestData → { topic: "tick", data: {...} } — the newest message, or null.
+// live.data       → everything received this mount, oldest first.
+
+const start = () =>
+  kickPluginTask({
+    applicationType: "plugin_stopwatch",
+    taskName: "tick",
+    identifier: state,
+    data: { runId, kickedAt: Date.now() },
+  });
+```
+
+The subscription is per instance and read-only; the token the platform mints for it carries only
+the topics your schema declares. Treat messages as nudges: what the UI must still show after a
+refresh comes from state, so a task that changes anything durable dispatches an event as well
+(docs/07 has the whole loop, including the stop).
+
 ## Cross-app from the UI
 
 ```ts
@@ -628,7 +658,8 @@ tasks: [
 - `ctx.getState()` — the app's state, fresh.
 - `ctx.dispatchEvent(eventName, eventData)` — through the full pipeline (append, fold, watermark),
   using YOUR processors, so a task's mutation is identical to a tap's.
-- `ctx.notify(topic, data)` — a realtime nudge to the app's channel; the UI refetches.
+- `ctx.notify(topic, data)` — publish on the app's realtime channel (see *Live tasks* below). A
+  nudge, never the truth: the UI hears it while mounted; a refresh only sees the timeline.
 - `ctx.logger`.
 
 ## The replay model — read this twice
@@ -642,8 +673,10 @@ replay; mint them inside. Step names are unique per logical operation; loops inc
 ## How a task gets kicked
 
 - **From a webhook**: `ctx.sendInngestEvent("<applicationType>/<task>", payload)` (docs/06).
-- **From the browser**: list the task in `kickableTasks`; the UI posts the event through the
-  platform's send-event route, which allows only listed tasks.
+- **From the browser or a tool**: list the task in `kickableTasks`, then
+  `kickPluginTask({ applicationType, taskName, identifier, data })` (from `esoul-sdk`; works in
+  a component and in a tool's `execute`). The platform's send-event route allows only listed
+  tasks and stamps nothing — `data` is exactly what `ctx.eventData` sees.
 - **On a cadence**: `pollTasks: [{ task, everyMinutes }]` — one shared platform sweep kicks each
   live instance at 5-minute granularity (minimum 5). This is your cron. There are deliberately
   no per-app Inngest functions: function ids are fixed at module load, and the plan caps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esoul-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Build ExternalSoul apps: event-sourced state, agent tools, server ops, background tasks, OAuth connections, files — the contract the Forge compiles against.",
   "license": "UNLICENSED",
   "type": "module",