esoul-sdk 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 Releases before 0.20.0 are recorded in the repository history only.
 
+## 0.24.0
+
+### Added
+
+- `questions(ctx)` (esoul-sdk/server): a question your app needs the person to answer reaches the
+  platform's questions bell on every workspace — options as buttons, an Open button that lands on
+  the place inside your app (`useAppNav`), and the answer delivered to your own op as the person who
+  answered. `settle(key, …)` closes it when your own screen took the answer (docs/06-server.md,
+  "Asking the person").
+- `mailWaitDirective(runCtx, …)`: an app tool pauses an agent network run until mail arrives at this
+  inbox on a thread or from a sender — the platform's own wait kernel (docs/04-tools.md, "Waiting
+  inside a network run").
+
+## 0.23.0
+
+### Added
+
+- `useAppNav(nodeId, onTarget)` (esoul-sdk/react): the platform opens a place INSIDE your app —
+  the tasks pane lands on a conversation or a campaign, not just the app (docs/05-ui.md, "Opened
+  from outside").
+- `origin: "server"` on an event definition: only the app's own server code (ops, routes, tasks,
+  webhooks) may append it; the browser's append and offline-queue doors and the PAT / SDK / MCP
+  dispatch routes refuse it (docs/03-events-and-state.md, "Events only the server emits").
+
+### Changed
+
+- `readAppState(nodeId)` reads only for the call the platform is running: your app and its own
+  type in your workspace, another type only with a `workspaceTools` grant for it (refused with the
+  line to add), null for an app in another workspace, own type only from a webhook, and a throw
+  outside an op, route, task or webhook. `callWorkspaceTool` refuses a `pluginId`/`nodeId` that is
+  not the running call's own. The Forge box applies the same read rule.
+
+### Fixed
+
+- `pluginServer.fileProducers` takes a producer with its own key type: `PluginFileProducer<MyKey>`
+  with `MyKey` declared as an `interface` no longer fails to typecheck against the map.
+
 ## 0.22.0
 
 ### Added

package/api-reference.md

@@ -7,11 +7,11 @@ the complete list it teaches from. In a Forge workbench the source itself is rea
 Regenerate: `npm run docs:api`.
 
 ==============================================================================
-## `esoul-sdk` — 250 exports
+## `esoul-sdk` — 252 exports
 
 Manifest, events, tools, ops, bindings, contracts, charts, access words — what app.tsx and the shared modules import.
 
-### Functions and values (150)
+### Functions and values (151)
 
 #### `ASSET_APP_MAX_BYTES` — const · src/assets.ts
 
@@ -621,6 +621,14 @@ A gateway model id: `provider/model` ("deepseek/deepseek-v3.2").
 const LLM_MODEL_ID_RE: RegExp
 ```
 
+#### `mailWaitDirective` — function · src/agent-wait.ts
+
+The wait's event, for the toolkit's `eventCallback`. Throws on a malformed wait.
+
+```ts
+function mailWaitDirective(runCtx: AgentRunToolContext, a: MailWaitArgs): Record<string, unknown>
+```
+
 #### `makeOpTool` — function · src/ops.ts
 
 `opTool`, bound to a caller. The package binds its own `callPluginOp`; the platform binds the one that carries the acting viewer and targets this deployment — same tool, different wire, decided once at the index.
@@ -1213,7 +1221,7 @@ A manifest with one entry removed (the bytes stay; they may be shared). Pure.
 function withoutAsset(assets: AssetsManifest | null | undefined, pluginId: string, name: string): AssetsManifest
 ```
 
-### Types (100)
+### Types (101)
 
 #### `AgentRunToolContext` — interface · src/types.ts
 
@@ -1723,6 +1731,7 @@ interface EventDefinition<StateType extends ApplicationIdentifier> {
   triggerMeta?: TriggerMeta;
   sideEffect?: EventSideEffect;
   permission?: "user_exclusive";
+  origin?: "server";
   conflictPolicy?: "mark" | "silent";
   conflictScope?: (eventData: any) => string[] | null | undefined;
   merge?: MergeDescription;
@@ -1975,6 +1984,25 @@ interface LabelShape {
 }
 ```
 
+#### `MailWaitArgs` — interface · src/agent-wait.ts
+
+```ts
+interface MailWaitArgs {
+  workspaceId: string;
+  inboxNodeId: string;
+  inboxName: string;
+  toolName: string;
+  threadId?: string;
+  fromEmail?: string;
+  subject?: string;
+  afterTimestamp: number;
+  timeoutSeconds?: number;
+  directiveId: string;
+  onResume?: string;
+  onTimeout?: string;
+}
+```
+
 #### `MergeDescription` — interface · src/types.ts
 
 ```ts
@@ -2393,11 +2421,11 @@ interface UsesDecl {
 ```
 
 ==============================================================================
-## `esoul-sdk/server` — 112 exports
+## `esoul-sdk/server` — 115 exports
 
 Server code only (server.ts, ops, routes, tasks): the viewer, the app's database, files, connections, machines, charts, route tokens.
 
-### Functions and values (35)
+### Functions and values (36)
 
 #### `APPROVAL_WAIT` — const · src/computer.ts
 
@@ -2631,9 +2659,17 @@ The consent-enforcing files API for plugin server code. Every call re-checks you
 function pluginFiles(_ctx: PluginFilesCtx): Promise<FilesApi>
 ```
 
+#### `questions` — function · src/server.ts
+
+THE PLATFORM'S QUESTIONS BELL. A question an app needs the person to answer (an agent waiting on a decision) reaches them wherever they are — the bell, on every workspace — not only when they open the app:
+
+```ts
+function questions(_ctx: { pluginId: string; workspaceId: string; nodeId: string; viewer?: { userId: string | null } }): Questions
+```
+
 #### `readAppState` — function · src/server.ts
 
-Read one app's state folded to head, by nodeId — server truth for an op or a task. Null when no such app exists. HOST-ONLY.
+Read one app's state folded to head, by nodeId — server truth for an op, route, task or webhook. It reads for the app instance of the call the platform is running: your own app and other instances of its type in your workspace; another app type only when plugin.json `workspaceTools` grants a tool of that type (the refusal names the line to add). Null when no such app exists — an app in another workspace is null too. A webhook (it runs for no instance) finds only instances of its own type. Outside a running call it throws. HOST-ONLY.
 
 ```ts
 function readAppState( _nodeId: string, ): Promise<{ nodeId: string; workspaceId: string; applicationType: string; foldedSeq: number; state: Record<string, unknown> } | null>
@@ -2679,7 +2715,23 @@ WHO IS THIS, IN WORDS. The caller's own name and email, for an app with a reason
 function viewerProfile(_viewer: PluginViewer): Promise<ViewerProfile | null>
 ```
 
-### Types (77)
+### Types (79)
+
+#### `AppQuestion` — interface · src/server.ts
+
+A question for the person (questions(ctx).ask).
+
+```ts
+interface AppQuestion {
+  key: string;
+  question: string;
+  options?: string[];
+  details?: Record<string, unknown>;
+  open?: { kind: string; key: string; label?: string };
+  answer: { op: string; args?: Record<string, unknown> };
+  expiresInSeconds?: number;
+}
+```
 
 #### `AppRolePerson` — interface · src/server.ts
 
@@ -3387,7 +3439,7 @@ interface PluginServerModule {
   webhooks?: Record<string, PluginWebhookHandler>;
   ops?: Record<string, PluginOpHandler>;
   routes?: Record<string, PluginRouteHandler>;
-  fileProducers?: Record<string, PluginFileProducer>;
+  fileProducers?: Record<string, PluginFileProducer<any>>;
 }
 ```
 
@@ -3478,6 +3530,15 @@ interface ProgramStepState {
 }
 ```
 
+#### `Questions` — interface · src/server.ts
+
+```ts
+interface Questions {
+  ask(q: AppQuestion): Promise<{ questionId: string; created: boolean }>;
+  settle(key: string, outcome: { answer: string } | { cancelled: true }): Promise<void>;
+}
+```
+
 #### `RouteTokenGrant` — interface · src/server.ts
 
 ```ts
@@ -3689,11 +3750,11 @@ type WorkspaceGrant = { scope: "folder"; root: string } | { scope: "computer" };
 ```
 
 ==============================================================================
-## `esoul-sdk/react` — 69 exports
+## `esoul-sdk/react` — 71 exports
 
 The app's UI: hooks for the viewer, the app's state, realtime, workspace files and tools.
 
-### Functions and values (36)
+### Functions and values (37)
 
 #### `ConnectAccount` — function · src/react.ts
 
@@ -3815,6 +3876,14 @@ True when the current viewer may mutate this workspace.
 function useAppCanEdit(): boolean
 ```
 
+#### `useAppNav` — function · src/react.ts
+
+"Open THIS inside the app": the platform's tasks pane, a link chip or a recall hit asks for a place inside this app instance (the keys are the app's own — say which in your tool and task descriptions). `onTarget` runs with the target waiting when the app mounts, and with each one asked for while it is on screen. Open it and select it; an unknown key does nothing.
+
+```ts
+function useAppNav(_nodeId: string, _onTarget: (target: AppNavTarget) => void): void
+```
+
 #### `useCredential` — function · src/react.ts
 
 The state of one of your plugin.json `credentials` slots for the person looking at the app.
@@ -3983,7 +4052,15 @@ The account's computers as a panel: online, the apps each serves, Disconnect.
 function YourComputers(_props: { className?: string }): any
 ```
 
-### Types (33)
+### Types (34)
+
+#### `AppNavTarget` — type · src/react.ts
+
+A place inside an app, as named by whoever asks to open it: `{ thread: "…" }`, `{ campaign: "…" }`.
+
+```ts
+type AppNavTarget = Record<string, string>;
+```
 
 #### `DeviceRunStarted` — interface · src/device.ts
 

package/dist/agent-wait.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A DURABLE MAIL WAIT from an app's tool inside an agent network run: the run
+ * pauses — minutes or days, nothing running — until mail arrives at this inbox
+ * on a thread or from a sender, then resumes with the arrival in its history.
+ *
+ * The platform's agent runtime owns the wait (the same kernel `wait_for_reply`
+ * uses): it parks on `workspace/email.message_arrived`, checks the inbox's
+ * folded `messages` for an arrival newer than `afterTimestamp` before and
+ * after parking, and resumes with `onResume` (its `{{messageId}}`, `{{from}}`,
+ * `{{subject}}`, `{{threadId}}` filled in) or `onTimeout`.
+ *
+ *   toolkitCreator: (identifier, _chat, eventCallback, _msg, runCtx) => ({
+ *     [`wait_for_email_${base}`]: { …, execute: async (args) => {
+ *       if (!runCtx) return "Only inside an agent network run.";
+ *       eventCallback(mailWaitDirective(runCtx, { workspaceId, inboxNodeId, inboxName, toolName, threadId, afterTimestamp, directiveId }));
+ *       runCtx.setWaitDirectiveCreatedThisStep();
+ *       return "Waiting…";
+ *     } },
+ *   })
+ *
+ * The inbox's state must keep a `messages` map (`{ id, threadId, labelIds,
+ * from, subject, internalDate }`) and its app must announce arrivals as that
+ * event (the platform does it for the SDK Gmail app). Pure.
+ */
+import type { AgentRunToolContext } from "./types.js";
+export interface MailWaitArgs {
+    workspaceId: string;
+    /** The inbox app instance (the wait is scoped to it). */
+    inboxNodeId: string;
+    inboxName: string;
+    /** The tool's name as the model sees it (for the run's log). */
+    toolName: string;
+    /** Exactly one of: the next message on this thread, or from this sender (optionally with this subject). */
+    threadId?: string;
+    fromEmail?: string;
+    subject?: string;
+    /** Only mail newer than this counts (epoch ms) — the newest message the agent has already seen. */
+    afterTimestamp: number;
+    /** Default 7 days. */
+    timeoutSeconds?: number;
+    /** Unique per wait (the caller's id — keep it stable across a retried tool call). */
+    directiveId: string;
+    onResume?: string;
+    onTimeout?: string;
+}
+/** The wait's event, for the toolkit's `eventCallback`. Throws on a malformed wait. */
+export declare function mailWaitDirective(runCtx: AgentRunToolContext, a: MailWaitArgs): Record<string, unknown>;

package/dist/agent-wait.js

@@ -0,0 +1,47 @@
+const esc = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+/** The wait's event, for the toolkit's `eventCallback`. Throws on a malformed wait. */
+export function mailWaitDirective(runCtx, a) {
+    const threadId = a.threadId?.trim() || undefined;
+    const fromEmail = a.fromEmail?.trim() || undefined;
+    const subject = a.subject?.trim() || undefined;
+    if (!!threadId === !!fromEmail)
+        throw new Error("mailWaitDirective: give threadId OR fromEmail.");
+    const timeoutSeconds = Math.max(60, Math.min(30 * 86_400, Math.round(a.timeoutSeconds ?? 7 * 86_400)));
+    const scope = `async.data.workspaceId == "${esc(a.workspaceId)}" && async.data.nodeId == "${esc(a.inboxNodeId)}" && `;
+    const matchExpression = threadId
+        ? `${scope}async.data.threadId == "${esc(threadId)}" && !async.data.labelIds.exists(l, l == "SENT")`
+        : `${scope}async.data.fromEmail == "${esc(fromEmail.toLowerCase())}" && ` +
+            (subject ? `async.data.subject == "${esc(subject)}" && ` : "") +
+            `!async.data.labelIds.exists(l, l == "SENT")`;
+    const what = threadId ? `thread ${threadId}` : `sender ${fromEmail}${subject ? ` subject "${subject}"` : ""}`;
+    return {
+        eventName: "agent_wait_directive_created",
+        eventData: {
+            runId: runCtx.agentRunId,
+            directiveId: a.directiveId,
+            agentNodeId: runCtx.currentAgentNodeId ?? null,
+            toolName: a.toolName,
+            eventName: "workspace/email.message_arrived",
+            matchExpression,
+            timeoutSeconds,
+            templates: {
+                onResume: a.onResume ?? `[Email landed in "${a.inboxName}" (${what}): messageId={{messageId}}, from={{from}}, subject="{{subject}}", threadId={{threadId}}.]`,
+                onTimeout: a.onTimeout ?? `[No email in "${a.inboxName}" (${what}) within ${timeoutSeconds}s.]`,
+            },
+            reason: `Waiting for email in ${a.inboxName} (${what})`,
+            prewaitCheck: {
+                type: "workspace_email_arrival",
+                workspaceId: a.workspaceId,
+                nodeId: a.inboxNodeId,
+                ...(threadId ? { threadId } : { fromEmail }),
+                ...(subject && !threadId ? { subject } : {}),
+                afterTimestamp: a.afterTimestamp,
+            },
+        },
+        timestamp: Date.now(),
+        workspaceId: a.workspaceId,
+        applicationId: runCtx.agentBuilderNodeId,
+        instanceName: "",
+        chatIdSource: runCtx.agentRunId,
+    };
+}

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export * from "./chart.js";
  * the decision and the merges (records by id, fields, lines). The hook is `useRemoteReconcile` in esoul-sdk/react.
  */
 export * from "./editor-sync.js";
+export * from "./agent-wait.js";
 /**
  * The agent tool for one op, declared once: `opTool(ops.play, { say })` in app.tsx gives a tool whose
  * parameters ARE the op's zod input and whose call goes to `callPluginOp` — as the acting viewer on

package/dist/index.js

@@ -25,6 +25,7 @@ export * from "./chart.js";
  * the decision and the merges (records by id, fields, lines). The hook is `useRemoteReconcile` in esoul-sdk/react.
  */
 export * from "./editor-sync.js";
+export * from "./agent-wait.js";
 import { callPluginOp } from "./helpers.js";
 import { makeOpTool } from "./ops.js";
 /**

package/dist/manifest.d.ts

@@ -62,8 +62,8 @@ export declare const PluginConnectionSchema: z.ZodEffects<z.ZodObject<{
     /** apiKey: header NAMES the plugin will send (never values). */
     headerNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
-    label: string;
     kind: "oauth2" | "apiKey";
+    label: string;
     key: string;
     description?: string | undefined;
     authorizeUrl?: string | undefined;
@@ -73,8 +73,8 @@ export declare const PluginConnectionSchema: z.ZodEffects<z.ZodObject<{
     clientSecretEnv?: string | undefined;
     headerNames?: string[] | undefined;
 }, {
-    label: string;
     kind: "oauth2" | "apiKey";
+    label: string;
     key: string;
     description?: string | undefined;
     authorizeUrl?: string | undefined;
@@ -84,8 +84,8 @@ export declare const PluginConnectionSchema: z.ZodEffects<z.ZodObject<{
     clientSecretEnv?: string | undefined;
     headerNames?: string[] | undefined;
 }>, {
-    label: string;
     kind: "oauth2" | "apiKey";
+    label: string;
     key: string;
     description?: string | undefined;
     authorizeUrl?: string | undefined;
@@ -95,8 +95,8 @@ export declare const PluginConnectionSchema: z.ZodEffects<z.ZodObject<{
     clientSecretEnv?: string | undefined;
     headerNames?: string[] | undefined;
 }, {
-    label: string;
     kind: "oauth2" | "apiKey";
+    label: string;
     key: string;
     description?: string | undefined;
     authorizeUrl?: string | undefined;
@@ -809,12 +809,12 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 values: z.ZodArray<z.ZodString, "many">;
                 describe: z.ZodOptional<z.ZodString>;
             }, "strict", z.ZodTypeAny, {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             }, {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             }>, z.ZodObject<{
                 type: z.ZodLiteral<"bool">;
@@ -856,7 +856,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -869,13 +868,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -891,7 +891,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -904,13 +903,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -1004,7 +1004,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -1017,13 +1016,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -1063,7 +1063,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -1076,13 +1075,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -1122,7 +1122,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -1135,13 +1134,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -1181,7 +1181,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -1194,13 +1193,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -1255,8 +1255,8 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         /** apiKey: header NAMES the plugin will send (never values). */
         headerNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
-        label: string;
         kind: "oauth2" | "apiKey";
+        label: string;
         key: string;
         description?: string | undefined;
         authorizeUrl?: string | undefined;
@@ -1266,8 +1266,8 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         clientSecretEnv?: string | undefined;
         headerNames?: string[] | undefined;
     }, {
-        label: string;
         kind: "oauth2" | "apiKey";
+        label: string;
         key: string;
         description?: string | undefined;
         authorizeUrl?: string | undefined;
@@ -1277,8 +1277,8 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         clientSecretEnv?: string | undefined;
         headerNames?: string[] | undefined;
     }>, {
-        label: string;
         kind: "oauth2" | "apiKey";
+        label: string;
         key: string;
         description?: string | undefined;
         authorizeUrl?: string | undefined;
@@ -1288,8 +1288,8 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         clientSecretEnv?: string | undefined;
         headerNames?: string[] | undefined;
     }, {
-        label: string;
         kind: "oauth2" | "apiKey";
+        label: string;
         key: string;
         description?: string | undefined;
         authorizeUrl?: string | undefined;
@@ -1453,13 +1453,13 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         events: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         models: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
+        models?: string[] | undefined;
         tools?: string[] | undefined;
         events?: string[] | undefined;
-        models?: string[] | undefined;
     }, {
+        models?: string[] | undefined;
         tools?: string[] | undefined;
         events?: string[] | undefined;
-        models?: string[] | undefined;
     }>>>;
     /**
      * The app's realtime TOPICS, and who hears each (forge-sdk-spec-and-tests
@@ -1552,9 +1552,9 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
     }>>>;
 }, "strict", z.ZodTypeAny, {
     name: string;
+    id: string;
     version: string;
     applicationType: string;
-    id: string;
     description: string;
     scopes: string[];
     ops: string[] | Record<string, {
@@ -1578,8 +1578,8 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     workspaceTools: string[];
     connections: {
-        label: string;
         kind: "oauth2" | "apiKey";
+        label: string;
         key: string;
         description?: string | undefined;
         authorizeUrl?: string | undefined;
@@ -1603,7 +1603,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -1616,13 +1615,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -1716,9 +1716,9 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         optional?: boolean | undefined;
     }> | undefined;
     provides?: Record<string, {
+        models?: string[] | undefined;
         tools?: string[] | undefined;
         events?: string[] | undefined;
-        models?: string[] | undefined;
     }> | undefined;
     channel?: {
         topics: Record<string, {
@@ -1741,9 +1741,9 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
     }> | undefined;
 }, {
     name: string;
+    id: string;
     version: string;
     applicationType: string;
-    id: string;
     description: string;
     manifestVersion: 1;
     entry: string;
@@ -1752,7 +1752,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -1765,13 +1764,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -1874,8 +1874,8 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     workspaceTools?: string[] | undefined;
     connections?: {
-        label: string;
         kind: "oauth2" | "apiKey";
+        label: string;
         key: string;
         description?: string | undefined;
         authorizeUrl?: string | undefined;
@@ -1905,9 +1905,9 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         optional?: boolean | undefined;
     }> | undefined;
     provides?: Record<string, {
+        models?: string[] | undefined;
         tools?: string[] | undefined;
         events?: string[] | undefined;
-        models?: string[] | undefined;
     }> | undefined;
     channel?: {
         topics: Record<string, {
@@ -1930,9 +1930,9 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
     }> | undefined;
 }>, {
     name: string;
+    id: string;
     version: string;
     applicationType: string;
-    id: string;
     description: string;
     scopes: string[];
     ops: string[] | Record<string, {
@@ -1956,8 +1956,8 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     workspaceTools: string[];
     connections: {
-        label: string;
         kind: "oauth2" | "apiKey";
+        label: string;
         key: string;
         description?: string | undefined;
         authorizeUrl?: string | undefined;
@@ -1981,7 +1981,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -1994,13 +1993,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -2094,9 +2094,9 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         optional?: boolean | undefined;
     }> | undefined;
     provides?: Record<string, {
+        models?: string[] | undefined;
         tools?: string[] | undefined;
         events?: string[] | undefined;
-        models?: string[] | undefined;
     }> | undefined;
     channel?: {
         topics: Record<string, {
@@ -2119,9 +2119,9 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
     }> | undefined;
 }, {
     name: string;
+    id: string;
     version: string;
     applicationType: string;
-    id: string;
     description: string;
     manifestVersion: 1;
     entry: string;
@@ -2130,7 +2130,6 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
             argv: string[];
             timeoutSeconds?: number | undefined;
             cwd?: string | undefined;
-            result?: "json" | "text" | undefined;
             params?: Record<string, "string" | "number" | "int" | "bool" | {
                 type: "number" | "int";
                 min?: number | undefined;
@@ -2143,13 +2142,14 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
                 allowDash?: boolean | undefined;
                 describe?: string | undefined;
             } | {
-                type: "enum";
                 values: string[];
+                type: "enum";
                 describe?: string | undefined;
             } | {
                 type: "bool";
                 describe?: string | undefined;
             }> | undefined;
+            result?: "text" | "json" | undefined;
             config?: string[] | undefined;
             describe?: string | undefined;
             env?: Record<string, string> | undefined;
@@ -2252,8 +2252,8 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     workspaceTools?: string[] | undefined;
     connections?: {
-        label: string;
         kind: "oauth2" | "apiKey";
+        label: string;
         key: string;
         description?: string | undefined;
         authorizeUrl?: string | undefined;
@@ -2283,9 +2283,9 @@ export declare const PluginManifestSchema: z.ZodEffects<z.ZodObject<{
         optional?: boolean | undefined;
     }> | undefined;
     provides?: Record<string, {
+        models?: string[] | undefined;
         tools?: string[] | undefined;
         events?: string[] | undefined;
-        models?: string[] | undefined;
     }> | undefined;
     channel?: {
         topics: Record<string, {

package/dist/react.d.ts

@@ -67,6 +67,15 @@ export interface WorkspaceNav {
  * already on.
  */
 export declare function useWorkspaceNav(): WorkspaceNav;
+/** A place inside an app, as named by whoever asks to open it: `{ thread: "…" }`, `{ campaign: "…" }`. */
+export type AppNavTarget = Record<string, string>;
+/**
+ * "Open THIS inside the app": the platform's tasks pane, a link chip or a recall hit asks for a
+ * place inside this app instance (the keys are the app's own — say which in your tool and task
+ * descriptions). `onTarget` runs with the target waiting when the app mounts, and with each one
+ * asked for while it is on screen. Open it and select it; an unknown key does nothing.
+ */
+export declare function useAppNav(_nodeId: string, _onTarget: (target: AppNavTarget) => void): void;
 import type { FileEntry, FileListOptions, FileRef, FileSource } from "./files.js";
 import type { TransferSnapshot } from "./transfers.js";
 import type { LabelPoint, LabelShape } from "./labelme.js";

package/dist/react.js

@@ -33,6 +33,15 @@ export function useWorkspaceTools(_identity) {
 export function useWorkspaceNav() {
     return hostOnly("useWorkspaceNav");
 }
+/**
+ * "Open THIS inside the app": the platform's tasks pane, a link chip or a recall hit asks for a
+ * place inside this app instance (the keys are the app's own — say which in your tool and task
+ * descriptions). `onTarget` runs with the target waiting when the app mounts, and with each one
+ * asked for while it is on screen. Open it and select it; an unknown key does nothing.
+ */
+export function useAppNav(_nodeId, _onTarget) {
+    return hostOnly("useAppNav");
+}
 /** A files call from the UI refused — `kind` is the FileSourceErrorKind when the source said why. */
 export class FilesBrowseError extends Error {
     kind;

package/dist/server.d.ts

@@ -208,8 +208,12 @@ export interface PluginServerModule {
     ops?: Record<string, PluginOpHandler>;
     /** routeName → handler, for names declared in plugin.json `routes`. */
     routes?: Record<string, PluginRouteHandler>;
-    /** key → producer, for keys declared in plugin.json `fileProducers`: the app's own bytes as a transfer source. */
-    fileProducers?: Record<string, PluginFileProducer>;
+    /**
+     * key → producer, for keys declared in plugin.json `fileProducers`: the app's own bytes as a
+     * transfer source. Each producer keeps its own key type (`PluginFileProducer<MyKey>`, an
+     * interface or a type) — the platform hands `open` the key the transfer item named.
+     */
+    fileProducers?: Record<string, PluginFileProducer<any>>;
 }
 export type PluginConnectionCredentials = {
     kind: "oauth2";
@@ -578,8 +582,13 @@ export interface EmitPluginAppEventArgs {
     eventData: Record<string, unknown>;
 }
 /**
- * Read one app's state folded to head, by nodeId — server truth for an op or
- * a task. Null when no such app exists. HOST-ONLY.
+ * Read one app's state folded to head, by nodeId — server truth for an op, route,
+ * task or webhook. It reads for the app instance of the call the platform is
+ * running: your own app and other instances of its type in your workspace; another
+ * app type only when plugin.json `workspaceTools` grants a tool of that type (the
+ * refusal names the line to add). Null when no such app exists — an app in another
+ * workspace is null too. A webhook (it runs for no instance) finds only instances
+ * of its own type. Outside a running call it throws. HOST-ONLY.
  */
 export declare function readAppState(_nodeId: string): Promise<{
     nodeId: string;
@@ -658,6 +667,67 @@ export declare function mintRouteToken(_ctx: {
     ttlSeconds?: number;
     label?: string;
 }): Promise<RouteTokenGrant>;
+/** A question for the person (questions(ctx).ask). */
+export interface AppQuestion {
+    /** Stable per question within this app instance: asking twice with one key is one question. */
+    key: string;
+    question: string;
+    /** 1–4 answers the bell offers as buttons; without them the person types. */
+    options?: string[];
+    /** Context the bell shows under the question (≤1500 characters as JSON). */
+    details?: Record<string, unknown>;
+    /** Where the bell's Open button takes the person: the app hears `{ [kind]: key }` through useAppNav. */
+    open?: {
+        kind: string;
+        key: string;
+        label?: string;
+    };
+    /** The app's own op that takes the answer, called as the person answering with `{ ...args, answer }`. */
+    answer: {
+        op: string;
+        args?: Record<string, unknown>;
+    };
+    expiresInSeconds?: number;
+}
+export interface Questions {
+    ask(q: AppQuestion): Promise<{
+        questionId: string;
+        created: boolean;
+    }>;
+    /** The app settled it itself (answered on its own screen, the asker ended): the bell's row closes. */
+    settle(key: string, outcome: {
+        answer: string;
+    } | {
+        cancelled: true;
+    }): Promise<void>;
+}
+/**
+ * THE PLATFORM'S QUESTIONS BELL. A question an app needs the person to answer
+ * (an agent waiting on a decision) reaches them wherever they are — the bell,
+ * on every workspace — not only when they open the app:
+ *
+ *   await questions(ctx).ask({
+ *     key: `thread:${threadId}:${questionId}`,
+ *     question: "Accept 12 % off if they order 500?",
+ *     options: ["Yes", "No"],
+ *     open: { kind: "thread", key: threadId, label: "Open email thread" },
+ *     answer: { op: "answer_question", args: { threadId, questionId } },
+ *   });
+ *
+ * Answering in the bell calls `answer.op` with `{ ...args, answer }` as the
+ * person who answered (their access, the op's own rules); an `{ ok: false }`
+ * reply closes the row and shows the app's reason. When the app takes the
+ * answer on its own screen, `settle(key, { answer })` closes the row without a
+ * call back. HOST-ONLY; the Forge box keeps no bell (ask answers `created: false`).
+ */
+export declare function questions(_ctx: {
+    pluginId: string;
+    workspaceId: string;
+    nodeId: string;
+    viewer?: {
+        userId: string | null;
+    };
+}): Questions;
 /**
  * PARTS OF THE APP THAT RUN ON THE PERSON'S COMPUTER (plugin-device-arm.md).
  * The app declares its commands in plugin.json `device.commands`; the owner

package/dist/server.js

@@ -202,8 +202,13 @@ export function removeAppRole(_ctx, _name) {
     return hostOnly("removeAppRole");
 }
 /**
- * Read one app's state folded to head, by nodeId — server truth for an op or
- * a task. Null when no such app exists. HOST-ONLY.
+ * Read one app's state folded to head, by nodeId — server truth for an op, route,
+ * task or webhook. It reads for the app instance of the call the platform is
+ * running: your own app and other instances of its type in your workspace; another
+ * app type only when plugin.json `workspaceTools` grants a tool of that type (the
+ * refusal names the line to add). Null when no such app exists — an app in another
+ * workspace is null too. A webhook (it runs for no instance) finds only instances
+ * of its own type. Outside a running call it throws. HOST-ONLY.
  */
 export function readAppState(_nodeId) {
     return hostOnly("readAppState");
@@ -256,6 +261,28 @@ export function renderChartImage(_ctx, _args) {
 export function mintRouteToken(_ctx, _args) {
     return hostOnly("mintRouteToken");
 }
+/**
+ * THE PLATFORM'S QUESTIONS BELL. A question an app needs the person to answer
+ * (an agent waiting on a decision) reaches them wherever they are — the bell,
+ * on every workspace — not only when they open the app:
+ *
+ *   await questions(ctx).ask({
+ *     key: `thread:${threadId}:${questionId}`,
+ *     question: "Accept 12 % off if they order 500?",
+ *     options: ["Yes", "No"],
+ *     open: { kind: "thread", key: threadId, label: "Open email thread" },
+ *     answer: { op: "answer_question", args: { threadId, questionId } },
+ *   });
+ *
+ * Answering in the bell calls `answer.op` with `{ ...args, answer }` as the
+ * person who answered (their access, the op's own rules); an `{ ok: false }`
+ * reply closes the row and shows the app's reason. When the app takes the
+ * answer on its own screen, `settle(key, { answer })` closes the row without a
+ * call back. HOST-ONLY; the Forge box keeps no bell (ask answers `created: false`).
+ */
+export function questions(_ctx) {
+    return hostOnly("questions");
+}
 /**
  * PARTS OF THE APP THAT RUN ON THE PERSON'S COMPUTER (plugin-device-arm.md).
  * The app declares its commands in plugin.json `device.commands`; the owner

package/dist/types.d.ts

@@ -106,6 +106,15 @@ export interface EventDefinition<StateType extends ApplicationIdentifier> {
     triggerMeta?: TriggerMeta;
     sideEffect?: EventSideEffect;
     permission?: "user_exclusive";
+    /**
+     * WHO MAY APPEND IT. `"server"`: this event records something only the app's own server code
+     * knows — a message sent, a sync's result, a model's output, a payment. It is appended by the
+     * app's ops, routes, tasks and webhooks (and the platform), never by a client: the browser's
+     * append and WAL doors and the PAT/SDK dispatch routes refuse it, so nobody can plant a "sent"
+     * that was never sent or a sync that never ran (the platform's mail requirements, KD-120). Absent: any writer
+     * with access to the app may append it, as before.
+     */
+    origin?: "server";
     conflictPolicy?: "mark" | "silent";
     /** The sub-items (e.g. block ids) a partial write touches — two devices
      *  writing different sub-items of one item merge without a conflict. */

package/docs/03-events-and-state.md

@@ -88,13 +88,20 @@ snapshot baselines and the durability layers. Every shipped plugin and the scaff
 
 ## Events only the server emits
 
-There is no "server-only" event type: `EventTypes` has `Client` (what the UI and tools dispatch,
-and what a task's `dispatchEvent` or an op's `ctx.emit` writes through the same processors),
-`Workflow` and `Workspace` (the platform's own). An event that only a task or a webhook should
-produce is declared like any other; the guard is where its `dataCreator` is called — keep it out
-of the UI's reach and say so in a comment. (An earlier version of this page named
-`EventTypes.Server`, which does not exist: the Pantry's first type check in a box found it,
-2026-09-28.) The processor still obeys the three rules.
+An event that records something only your server code knows — a letter sent, a sync's result, a
+model's answer, a payment — says so with `origin: "server"`:
+
+```ts
+{ eventName: "mail_sent", type: EventTypes.Client, origin: "server", dataCreator, processor }
+```
+
+Your ops, routes, tasks and webhooks append it as usual (`ctx.emit`, a task's `dispatchEvent`).
+Every door a CLIENT's event enters by refuses it — the browser's appends and offline queue, and the
+PAT / SDK / MCP dispatch routes — so nobody with write access can plant a "sent" that was never
+sent or a sync that never ran. Your UI can still predict it for an optimistic click (run the
+processor locally); it just never dispatches it. `EventTypes` has no server type for this
+(`Client`, `Workflow`, `Workspace` only — an earlier version of this page named `EventTypes.Server`,
+which does not exist); `origin` is the switch. The processor still obeys the three rules.
 
 ## Durability you get for free
 

package/docs/04-tools.md

@@ -100,6 +100,33 @@ a `PluginCallError` carrying the platform's `code` (`forbidden`, `login-required
 pass it to `useSignInWall().raise(err)` in the UI and a `login-required` becomes the sign-in wall
 instead of an error. Relay any other error's message; never swallow it.
 
+## Waiting inside a network run — `mailWaitDirective`
+
+Inside an agent network run (`runCtx` is the fifth argument of `toolkitCreator`; absent in chat and
+voice) a tool can PAUSE the run until mail arrives — minutes or days, nothing running — with the
+platform's own wait kernel:
+
+```ts
+import { mailWaitDirective } from "esoul-sdk";
+
+execute: async (args) => {
+  if (!runCtx) return "Only inside an agent network run.";
+  if (runCtx.isWaitDirectiveAlreadyCreatedThisStep()) return "One wait per turn.";
+  eventCallback(mailWaitDirective(runCtx, {
+    workspaceId, inboxNodeId: identifier.nodeId, inboxName: identifier.instanceName,
+    toolName: `wait_for_email_${base}`, threadId: args.threadId,
+    afterTimestamp,                 // the newest message the agent has already seen
+    directiveId,                    // stable for a retried call
+  }));
+  runCtx.setWaitDirectiveCreatedThisStep();
+  return "Waiting…";
+}
+```
+
+The run wakes on `workspace/email.message_arrived` for this inbox (the platform sends it for the
+Gmail app's live mail) and first checks the inbox's folded `messages` for an arrival newer than
+`afterTimestamp`, so a reply that landed before the wait is not missed.
+
 ## Calling other apps
 
 From the UI: `useWorkspaceTools()` (docs/05). From server code: `callWorkspaceTool` (docs/06).

package/docs/05-ui.md

@@ -165,6 +165,26 @@ Reload in place, without a skeleton: a screen that flashes every time the assist
 reads as broken. Check it in the workbench: open the preview, call one of your write tools from the
 board (or `esoul-forge tool …`), and watch the view change within a few seconds, without a reload.
 
+## Opened from outside: a place inside your app
+
+The platform's tasks pane (and, as they adopt it, link chips and memory hits) can open a place
+INSIDE your app — a conversation, a campaign, a page — not just the app. It names the place with
+keys you choose; you hear it with `useAppNav`:
+
+```tsx
+import { useAppNav } from "esoul-sdk/react";
+
+useAppNav(nodeId, (target) => {
+  if (target.thread) openThread(target.thread);
+  else if (target.campaign) openCampaign(target.campaign);
+});
+```
+
+`onTarget` runs with the place waiting when the app mounts (declare it after any effect that
+restores a remembered view, so the request wins) and with each one asked for while the app is on
+screen. An unknown key does nothing. Name the keys in your task descriptions so the platform can
+point at them.
+
 ## Cross-app from the UI
 
 ```ts

package/docs/06-server.md

@@ -61,6 +61,31 @@ One app, folded to head: `{ nodeId, workspaceId, applicationType, foldedSeq, sta
 when absent. Use it for your own instance and, with care, for other apps in the same workspace.
 Never a raw database read — the import wall refuses `prisma` and the state column lags the log.
 
+## Asking the person — `questions(ctx)`
+
+A question your app needs answered (an agent waiting on a decision) goes to the platform's
+questions bell, which the person sees on every workspace — not only when your app is open:
+
+```ts
+import { questions } from "esoul-sdk/server";
+
+await questions(ctx).ask({
+  key: `thread:${threadId}:${questionId}`,   // one question per key: a replayed ask is the same one
+  question: "Accept 12 % off if they order 500?",
+  options: ["Yes", "No"],                     // 1–4 → buttons; without them the person types
+  open: { kind: "thread", key: threadId, label: "Open email thread" },
+  answer: { op: "answer_question", args: { threadId, questionId, via: "bell" } },
+});
+```
+
+- Answered in the bell, the platform calls **your own op** (`answer.op`, one of your declared ops)
+  with `{ ...args, answer }`, as the person who answered — their access, your op's rules. Reply
+  `{ ok: false, error }` when the question is gone: the bell closes it and shows your words.
+- `open` is where the bell's Open button lands: your app hears `{ [kind]: key }` through `useAppNav`.
+- Answered on your own screen instead, close the bell's copy: `questions(ctx).settle(key, { answer })`
+  (or `{ cancelled: true }`). The platform does not call you back for a settle.
+- In a Forge box there is no bell: `ask` answers `{ created: false }` and your screen still shows it.
+
 ## `callWorkspaceTool` — orchestrate other apps
 
 ```ts

package/llms-full.txt

@@ -880,13 +880,20 @@ snapshot baselines and the durability layers. Every shipped plugin and the scaff
 
 ## Events only the server emits
 
-There is no "server-only" event type: `EventTypes` has `Client` (what the UI and tools dispatch,
-and what a task's `dispatchEvent` or an op's `ctx.emit` writes through the same processors),
-`Workflow` and `Workspace` (the platform's own). An event that only a task or a webhook should
-produce is declared like any other; the guard is where its `dataCreator` is called — keep it out
-of the UI's reach and say so in a comment. (An earlier version of this page named
-`EventTypes.Server`, which does not exist: the Pantry's first type check in a box found it,
-2026-09-28.) The processor still obeys the three rules.
+An event that records something only your server code knows — a letter sent, a sync's result, a
+model's answer, a payment — says so with `origin: "server"`:
+
+```ts
+{ eventName: "mail_sent", type: EventTypes.Client, origin: "server", dataCreator, processor }
+```
+
+Your ops, routes, tasks and webhooks append it as usual (`ctx.emit`, a task's `dispatchEvent`).
+Every door a CLIENT's event enters by refuses it — the browser's appends and offline queue, and the
+PAT / SDK / MCP dispatch routes — so nobody with write access can plant a "sent" that was never
+sent or a sync that never ran. Your UI can still predict it for an optimistic click (run the
+processor locally); it just never dispatches it. `EventTypes` has no server type for this
+(`Client`, `Workflow`, `Workspace` only — an earlier version of this page named `EventTypes.Server`,
+which does not exist); `origin` is the switch. The processor still obeys the three rules.
 
 ## Durability you get for free
 
@@ -1001,6 +1008,33 @@ a `PluginCallError` carrying the platform's `code` (`forbidden`, `login-required
 pass it to `useSignInWall().raise(err)` in the UI and a `login-required` becomes the sign-in wall
 instead of an error. Relay any other error's message; never swallow it.
 
+## Waiting inside a network run — `mailWaitDirective`
+
+Inside an agent network run (`runCtx` is the fifth argument of `toolkitCreator`; absent in chat and
+voice) a tool can PAUSE the run until mail arrives — minutes or days, nothing running — with the
+platform's own wait kernel:
+
+```ts
+import { mailWaitDirective } from "esoul-sdk";
+
+execute: async (args) => {
+  if (!runCtx) return "Only inside an agent network run.";
+  if (runCtx.isWaitDirectiveAlreadyCreatedThisStep()) return "One wait per turn.";
+  eventCallback(mailWaitDirective(runCtx, {
+    workspaceId, inboxNodeId: identifier.nodeId, inboxName: identifier.instanceName,
+    toolName: `wait_for_email_${base}`, threadId: args.threadId,
+    afterTimestamp,                 // the newest message the agent has already seen
+    directiveId,                    // stable for a retried call
+  }));
+  runCtx.setWaitDirectiveCreatedThisStep();
+  return "Waiting…";
+}
+```
+
+The run wakes on `workspace/email.message_arrived` for this inbox (the platform sends it for the
+Gmail app's live mail) and first checks the inbox's folded `messages` for an arrival newer than
+`afterTimestamp`, so a reply that landed before the wait is not missed.
+
 ## Calling other apps
 
 From the UI: `useWorkspaceTools()` (docs/05). From server code: `callWorkspaceTool` (docs/06).
@@ -1190,6 +1224,26 @@ Reload in place, without a skeleton: a screen that flashes every time the assist
 reads as broken. Check it in the workbench: open the preview, call one of your write tools from the
 board (or `esoul-forge tool …`), and watch the view change within a few seconds, without a reload.
 
+## Opened from outside: a place inside your app
+
+The platform's tasks pane (and, as they adopt it, link chips and memory hits) can open a place
+INSIDE your app — a conversation, a campaign, a page — not just the app. It names the place with
+keys you choose; you hear it with `useAppNav`:
+
+```tsx
+import { useAppNav } from "esoul-sdk/react";
+
+useAppNav(nodeId, (target) => {
+  if (target.thread) openThread(target.thread);
+  else if (target.campaign) openCampaign(target.campaign);
+});
+```
+
+`onTarget` runs with the place waiting when the app mounts (declare it after any effect that
+restores a remembered view, so the request wins) and with each one asked for while the app is on
+screen. An unknown key does nothing. Name the keys in your task descriptions so the platform can
+point at them.
+
 ## Cross-app from the UI
 
 ```ts
@@ -1306,6 +1360,31 @@ One app, folded to head: `{ nodeId, workspaceId, applicationType, foldedSeq, sta
 when absent. Use it for your own instance and, with care, for other apps in the same workspace.
 Never a raw database read — the import wall refuses `prisma` and the state column lags the log.
 
+## Asking the person — `questions(ctx)`
+
+A question your app needs answered (an agent waiting on a decision) goes to the platform's
+questions bell, which the person sees on every workspace — not only when your app is open:
+
+```ts
+import { questions } from "esoul-sdk/server";
+
+await questions(ctx).ask({
+  key: `thread:${threadId}:${questionId}`,   // one question per key: a replayed ask is the same one
+  question: "Accept 12 % off if they order 500?",
+  options: ["Yes", "No"],                     // 1–4 → buttons; without them the person types
+  open: { kind: "thread", key: threadId, label: "Open email thread" },
+  answer: { op: "answer_question", args: { threadId, questionId, via: "bell" } },
+});
+```
+
+- Answered in the bell, the platform calls **your own op** (`answer.op`, one of your declared ops)
+  with `{ ...args, answer }`, as the person who answered — their access, your op's rules. Reply
+  `{ ok: false, error }` when the question is gone: the bell closes it and shows your words.
+- `open` is where the bell's Open button lands: your app hears `{ [kind]: key }` through `useAppNav`.
+- Answered on your own screen instead, close the bell's copy: `questions(ctx).settle(key, { answer })`
+  (or `{ cancelled: true }`). The platform does not call you back for a settle.
+- In a Forge box there is no bell: `ask` answers `{ created: false }` and your screen still shows it.
+
 ## `callWorkspaceTool` — orchestrate other apps
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esoul-sdk",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Build a full product on ExternalSoul: your own tables with per-person rules, a viewer on every seam, app roles, access levels, realtime with audiences, durable tasks, and bindings to other apps.",
   "license": "UNLICENSED",
   "type": "module",