esoul-sdk 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 Releases before 0.20.0 are recorded in the repository history only.
 
+## 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

@@ -1723,6 +1723,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;
@@ -2633,7 +2634,7 @@ function pluginFiles(_ctx: PluginFilesCtx): Promise<FilesApi>
 
 #### `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>
@@ -3387,7 +3388,7 @@ interface PluginServerModule {
   webhooks?: Record<string, PluginWebhookHandler>;
   ops?: Record<string, PluginOpHandler>;
   routes?: Record<string, PluginRouteHandler>;
-  fileProducers?: Record<string, PluginFileProducer>;
+  fileProducers?: Record<string, PluginFileProducer<any>>;
 }
 ```
 
@@ -3689,11 +3690,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 +3816,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 +3992,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/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;

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");

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/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/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
 
@@ -1190,6 +1197,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esoul-sdk",
-  "version": "0.22.0",
+  "version": "0.23.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",