diff --git a/packages/client/README.md b/packages/client/README.md index 841295396..39b150198 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -1,6 +1,6 @@ # @earendil-works/pi-client -Transport-neutral client for the initial Pi `list` and `attach` protocol slice. +Transport-neutral client for Pi Session discovery, attachment, and prompting. ```ts import { PiClient, type ByteTransportFactory } from "@earendil-works/pi-client"; @@ -21,11 +21,12 @@ const client = await PiClient.connect({ }); const sessions = await client.listSessions(); const attachment = await client.attachSession(sessions[0].id); +const result = await client.promptSession(attachment.sessionId, "Summarize this session"); ``` -The client verifies that the physical endpoint reports the expected logical `serverId`. Every list and attach request carries that ID again so the final server can reject misdelivery. +The client verifies that the physical endpoint reports the expected logical `serverId`. Every Session request carries that ID again so the final server can reject misdelivery. -`attachSession()` currently returns only `{ sessionId }`. The attachment is exclusive to that client connection and is released on disconnect or disposal. Remote Session and Harness methods will be added directly from the new shared interfaces in a later slice. The client does not reconnect or replay requests automatically. After disconnection, call `reconnect()` and explicitly repeat safe control-plane actions. +`attachSession()` returns only `{ sessionId }`. The attachment is exclusive to that client connection. `promptSession()` accepts the protocol's serializable Harness prompt overloads and returns a structural `RunResult`. On disconnect or disposal, pending prompts reject locally, but accepted work may still complete remotely before the attachment is released. The client never reconnects or replays requests automatically. After disconnection, call `reconnect()` and explicitly repeat only operations known to be safe. The experimental local coordinator only provides a stable endpoint and relays traffic. Replaceable server processes own session and worker lifecycle outside the public client protocol. diff --git a/packages/protocol/README.md b/packages/protocol/README.md index f357e25a4..f71f22613 100644 --- a/packages/protocol/README.md +++ b/packages/protocol/README.md @@ -2,15 +2,15 @@ Runtime-neutral schemas, types, CBOR encoding, and byte-stream framing for the experimental Pi protocol. -Protocol version `1` currently contains the first control-plane slice: +Protocol version `1` currently contains the first Session-operation slice: - a version handshake that identifies the logical `serverId`; -- a service RPC manifest with `list()` and `attach(sessionId)`; +- a service RPC manifest with `list()`, `attach(sessionId)`, and `prompt(sessionId, arguments)`; - correlated responses and bounded protocol errors. -The manifest generates typed client methods and validated server dispatch. The wire uses generic `{ serverId, method, args }` calls rather than a hand-written command union. `list()` returns the durable `SessionMetadata` values from `SessionRepo.list()`. `attach()` exclusively binds that Session to the client connection and returns only its `sessionId`; the real `Session` and `AgentHarness` remain hosted by the server. Disconnecting releases the attachment. +The manifest generates typed client methods and validated server dispatch. The wire uses generic `{ serverId, method, args }` calls rather than a hand-written command union. `list()` returns durable `SessionMetadata`. `attach()` exclusively binds that Session to the client connection and returns only its `sessionId`. `prompt()` targets an explicitly identified Session attached to the requesting connection. The real `Session` and `AgentHarness` remain hosted by the server. Disconnecting releases the attachment after accepted work settles. -The package also defines `PromptArguments`, a tuple containing a serializable `AgentLane.prompt()` overload. `PromptMessage` is the protocol's closed set of built-in message DTOs; application-defined `AgentMessage` extensions are not accepted implicitly. `RunResult` is the wire-safe structural equivalent of the Harness result and contains no JavaScript `Error` instances. These DTOs are not yet exposed through the service RPC manifest. +`PromptArguments` contains one serializable `AgentLane.prompt()` overload. `PromptMessage` is the protocol's closed set of built-in message DTOs; application-defined `AgentMessage` extensions are not accepted implicitly. `RunResult` is the wire-safe structural equivalent of the Harness result and contains no JavaScript `Error` instances. Server and worker lifecycle is intentionally outside this public protocol. The experimental local coordinator is only an opaque message router; each replaceable server process owns the private lifecycle protocol. diff --git a/packages/server/README.md b/packages/server/README.md index 2799beb59..dab615c04 100644 --- a/packages/server/README.md +++ b/packages/server/README.md @@ -2,12 +2,13 @@ Experimental local server for the new durable Session and Agent Harness interfaces. -The current slice supports two client operations: +The current slice supports three client operations: - `list` calls `SessionRepo.list()` without opening sessions. - `attach` finds the requested metadata, passes it to the host, and retains the returned Harness handle in the server. +- `prompt` executes one serializable Harness prompt through the requesting client's attached handle. -A Session permits one attached client connection at a time. Repeating `attach` from that connection is idempotent; another connection receives `session_in_use`. Losing the connection releases its attachment lease. The host decides when zero client demand and Harness activity permit worker retirement. Server shutdown closes every hosted Harness, releasing its Session writer ownership. +A Session permits one attached client connection at a time. Repeating `attach` from that connection is idempotent; another connection receives `session_in_use`. Prompting requires that exact connection to own the targeted attachment. Losing the connection rejects the local response but releases its attachment lease only after accepted prompts settle. The host decides when zero client demand and Harness activity permit worker retirement. Server shutdown closes every hosted Harness, releasing its Session writer ownership. ```ts import { randomUUID } from "node:crypto";