@plurnk/plurnk-agui 3.0.0 → 4.0.0

package/.env.defaults

@@ -1,13 +1,22 @@
 # @plurnk/plurnk-agui — client protocol. Listener address: the shared PLURNK_HOST/PLURNK_PORT
-# (@plurnk/plurnk-contracts).
+# (@plurnk/plurnk-contracts). The posture, the operator's secret and the browser sign-in are the
+# shared PLURNK_AUTH, PLURNK_SECRET and PLURNK_PASS there ({§agui-oauth}).
 
-# Bearer required on non-preflight requests; empty = no module-level authentication. Empty is the
-# package floor, not the shipped posture: a fresh install mints its own token into the operator's
-# `.env` above this ({§agui-http-authorization}), and every client reads it from there. Emptying
-# that line is how an operator turns the perimeter off.
-PLURNK_AGUI_TOKEN=
-# The origin whose pages a browser lets read replies (CORS): * = any page; one origin = that page
-# only; empty = no CORS headers, so no page reads a reply. The bearer, not this, is the perimeter.
+# The authorization server's issuer, the public origin clients reach this daemon at
+# ({§agui-oauth-endpoints}). Empty = the address each request reached this daemon at, so a daemon on
+# every interface (PLURNK_HOST=0.0.0.0) answers each caller where it called; set it when a front the
+# daemon cannot see, such as a TLS proxy, serves another origin.
+PLURNK_AGUI_ISSUER=
+# Credential lifetimes ({§agui-oauth-tokens}), seconds. An access token is presented as the bearer and
+# renewed through the refresh token or the secret; a refresh token rotates on every use.
+PLURNK_AGUI_ACCESS_TTL_SEC=3600
+PLURNK_AGUI_REFRESH_TTL_SEC=2592000
+# Confidential clients beyond the operator's own, one line each ({§agui-oauth-clients}):
+# PLURNK_AGUI_CLIENT_<id>={"secret":"<its secret>","scopes":["agui"]}. Each holds its own
+# credentials; removing its line and restarting revokes them. "operator" is reserved.
+# The other origin whose pages a browser lets read replies (CORS): * = any page; one origin = that
+# page only; empty = no CORS headers, so no page of another origin reads a reply (a page this
+# daemon serves reads its own). The bearer, not this, is the perimeter.
 PLURNK_AGUI_ALLOW_ORIGIN=*
 # Default run turn cap: empty = no module default; -1 = unlimited; otherwise nonnegative integer.
 # Core's operator ceiling still applies.

package/README.md

@@ -7,34 +7,50 @@ interface and translates daemon lifecycle events into AG-UI events.
 
 `POST /agui` accepts `RunAgentInput` and returns an AG-UI event stream.
 
+A stock AG-UI client needs only the endpoint and, when enabled, authentication.
+Its first message creates a folderless workspace and worker; the same `threadId`
+reopens that conversation after reconnect or daemon restart. An existing worker
+is directly addressable as `<workspace ID>#<worker name>`, stable across workspace
+renames. Inspection creates nothing ({§agui-thread-binding}, {§agui-thread-address}).
+
 PLURNK uses standard AG-UI events for Runs, messages, steps, tool calls, state,
-and approval requests. Additional execution metadata uses namespaced
-`plurnk.*` custom events so generic AG-UI clients can ignore it safely.
+and approval requests. PLURNK's facts about those parts ride their standard
+`metadata` under `plurnk`; facts with no standard subject use namespaced
+`plurnk.*` custom events, so generic AG-UI clients can ignore them safely.
 
 Workspace selection and PLURNK-specific management actions use namespaced
 fields under `forwardedProps.plurnk`. `SPEC.md` defines those extensions.
 
-## Conversation projection
+## Event projection
 
-Each Run observes its bound Worker and, once known, its exact Loop. Sibling
-events do not become chat messages; child activity arrives only when Core
-delivers it into the parent's log ({§agui-topology-scope}).
+Each Run observes its bound worker and, once known, its exact loop. Delegated
+children have standard subagent identities rather than speaking as the parent;
+Core owns delivery of their replies and results into the parent's log
+({§agui-topology-scope}, {§agui-subagents}). Unrelated siblings stay outside the
+conversation.
 
 | Daemon evidence | Client projection |
 | --- | --- |
 | NOTE | Ordinary operation row containing literal working memory. |
-| WAIT / loop conclusion | Lifecycle signals; delivered SEND replies are assistant speech. |
+| WAIT | A tool call with its receipt; a WAIT that carries a body speaks it instead. |
+| Loop conclusion | Lifecycle signals; delivered SEND replies are assistant speech. |
 | Live provider reasoning | Standard `REASONING_*` deltas, immediately. Retries have separate identities. |
 | SEND | Assistant text; already-streamed reasoning is not repeated. |
+| A message to the worker | A user message, named by its source unless this client sent it. |
 | Other model operations | Standard tool calls and results. |
-| Log rows | `CUSTOM plurnk.row` for richer clients; not a second chat stream to render alongside standard messages. |
-| Harness activity | `CUSTOM plurnk.ambient`, without invented model speech. |
-| Packet and terminal usage | State updates and `plurnk.terminated`; daemon quantities pass through unchanged. |
+| A row's facts | `metadata.plurnk` on the message, tool call or result the row builds, live and on snapshot. |
+| Delegated child activity | Standard `SUBAGENT_*` lifecycle and attributed messages/tool calls; its conclusion answers the parent's delegation call. |
+| Non-conversation harness activity | `CUSTOM plurnk.ambient`, without invented model speech. |
+| Loop end | `RUN_FINISHED` completed with its result or cancelled, or `RUN_ERROR` for a failure; the end carries its token `usage`. |
+| Packet and terminal usage | State updates, and the loop's terminal record as the end's `metadata.plurnk.terminal`: the complete accounting with cost; daemon quantities pass through unchanged. |
 
 READ of `reasoning://<worker>/…` is an operation receipt, not another reasoning stream.
-On reattach, the durable conversation snapshot restores accepted reasoning and
-SENDs. `forwardedProps.plurnk.mode="sync"` obtains that state without a prompt
-or model inference ({§agui-conversation-sync}).
+
+A Run's `messages` are the client's copy of the conversation. A Run submits only a
+user message the conversation doesn't hold, and a Run with nothing new reattaches:
+the durable `MESSAGES_SNAPSHOT` restores the whole conversation without a prompt or
+model inference ({§agui-run-input}, {§agui-sync}). A stock `HttpAgent` therefore
+reattaches by running again with its history.
 
 Pending proposals and user interactions use standard AG-UI interrupts and
 resume Runs. Core decides their owner and disposition, including delegated
@@ -43,6 +59,10 @@ event schemas, and settlement rules live in [SPEC.md](./SPEC.md).
 
 ## Integration
 
+A browser client imports the state and action-outcome types from
+`@plurnk/plurnk-agui/client`, which needs no Node types ({§agui-client-types}); the
+package root is the server module.
+
 The daemon discovers this package as a module: its `package.json` declares
 `plurnk: { kind: "module", module: "./module" }`, and the service composes
 nothing by hand. The module mounts only `/agui` on the daemon's listener
@@ -61,3 +81,7 @@ terminal/editor behavior.
 ```sh
 npm run test -w @plurnk/plurnk-agui
 ```
+
+Deterministic tests use isolated configuration. The service's explicit
+`test:live` tier also includes the real-model AG-UI stories; its
+`test:live:specimen` selector can run either story by exact name.