@ahpd/server 0.1.0

package/src/types/rpc.ts

@@ -0,0 +1,68 @@
+/** JSON-RPC 2.0 over a single connection. */
+
+/** One decoded JSON-RPC call: a method name and its parameters. */
+export interface Request {
+  /** The JSON-RPC `method` field, e.g. `subscribe`. */
+  readonly method: string;
+  /** The `params` object, or an empty object when the call carried none. */
+  readonly params: Record<string, unknown>;
+}
+
+/**
+ * The bytes end of one connection.
+ *
+ * Implemented per runtime, since Node, Bun and Deno expose different socket
+ * objects.
+ */
+export interface Wire {
+  /** Write one frame. */
+  send(text: string): void;
+  /** Close the connection. */
+  close(): void;
+  /** Whether a `send` would still reach the client. */
+  isOpen(): boolean;
+}
+
+/**
+ * The JSON-RPC end of one connection: messages rather than frames.
+ *
+ * Both directions. AHP is symmetrical - `ServerCommandMap` names ten methods
+ * a host may call on a client, and a client publishes resources a host is
+ * expected to be able to read - so a peer that could only answer was half a
+ * connection.
+ */
+export interface Peer {
+  /** Send a complete JSON-RPC message. Dropped if the connection has closed. */
+  send(message: Record<string, unknown>): void;
+  /** Send a server-to-client notification, which carries no id and gets no reply. */
+  notify(method: string, params: unknown): void;
+  /**
+   * Ask the client something, and wait for what it says.
+   *
+   * Rejects with an `RpcError` the client sent, an `RpcTimeout` when nothing
+   * came back inside `timeoutMs`, or an `RpcClosed` when the connection went
+   * away with the question still in flight. Three outcomes, three types: a
+   * caller that has to tell "the client refused" from "the client is gone"
+   * cannot do it by reading a message.
+   */
+  request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+  /**
+   * Take one JSON-RPC response off the wire and settle whatever asked for it.
+   *
+   * Called by `receive` for a message carrying `result` or `error` and no
+   * `method`. An id nothing here asked about is dropped: a response is not a
+   * request, and answering one is the violation this exists to stop.
+   */
+  answered(message: Record<string, unknown>): void;
+  /** Close the connection, rejecting every question still unanswered. */
+  close(): void;
+}
+
+/**
+ * Answers one request.
+ *
+ * The resolved value becomes the JSON-RPC `result`. Throwing an `RpcError`
+ * produces that error's code; any other throw becomes an internal error.
+ * Returning nothing for a notification is correct - notifications get no reply.
+ */
+export type Handler = (request: Request, peer: Peer) => Promise<unknown> | unknown;

package/src/types/session.ts

@@ -0,0 +1,415 @@
+/** One agent session: its lifecycle, its turns, and what it is waiting for. */
+
+import type { Bag } from './common.js';
+import type { BoundTool } from './agent.js';
+
+/**
+ * Emits one state action on a session's channel.
+ *
+ * `session` addresses the session channel, `chat` the chat channel beneath it,
+ * and `terminal` a terminal's own - the emitter knows which of its channels it
+ * is talking about and the host knows what each is called.
+ */
+export type Emit = (channel: 'session' | 'chat' | 'terminal', action: Bag) => void;
+
+/**
+ * The model a turn runs on.
+ *
+ * An object rather than a name, because a model that carries a `configSchema`
+ * is chosen by picking a row *and* answering its form: the protocol's
+ * `ModelSelection` is `{ id, config }`, and a host that read only the id would
+ * accept a form it then ignored.
+ */
+export interface Chosen {
+  /** The model, spelled as `RootState.agents[].models[].id` spells it. */
+  id: string;
+  /**
+   * What the client filled that model's own `configSchema` in with.
+   *
+   * JSON primitives, which is what the protocol carries here: most pickers
+   * produce strings and a numeric one produces a number.
+   */
+  config?: Record<string, string | number | boolean | null>;
+}
+
+/** How to construct a session. */
+export interface SessionOptions {
+  /** The session channel URI, `ahp-session:/<id>`. */
+  uri: string;
+  /** The chat channel URI beneath it, `ahp-chat:/<id>`. */
+  chatUri: string;
+  /**
+   * Directories beside the first the agent may also read and write.
+   *
+   * The first is `cwd` and is the process root; these are its peers. The
+   * protocol calls the whole set `workingDirectories` and fixes index 0 for
+   * the session's lifetime, which is what `immutablePrimary` means.
+   */
+  additional?: string[];
+  /** The directory the agent works in. */
+  cwd: string;
+  /** Config values chosen at creation, by key. */
+  settings?: Record<string, unknown>;
+  /** The config schema this session reports, shared with the root channel. */
+  schema?: () => Bag;
+  /** Customizations to report until the agent reports its own. */
+  seedCustomizations?: Bag[];
+  /** Where state actions go. */
+  emit: Emit;
+  /**
+   * Environment for the agent's own process.
+   *
+   * Merged over `process.env` by the session, never handed to the SDK alone:
+   * the SDK's `env` *replaces* the subprocess environment rather than adding
+   * to it, so passing only a credential is a subprocess with no `PATH`.
+   */
+  env?: Record<string, string>;
+  /** An existing agent session to continue, rather than starting a new one. */
+  resume?: string;
+  /**
+   * The prompt this session is resumed *at*, so the rest is left behind.
+   *
+   * A fork: the conversation continues from that turn as though the ones
+   * after it had not happened, under a new id of its own so the original is
+   * untouched. Meaningless without `resume`, which names what is being forked.
+   */
+  forkAt?: string;
+  /**
+   * The chain entry this session is resumed *at*, keeping it and everything
+   * before it.
+   *
+   * A rewind rather than a fork: the conversation carries on under the id it
+   * already had, with the turns after that point dropped. What
+   * `chat/truncated` asks for, and the id is the difference - a fork leaves
+   * the original for somebody else to find, a truncation means there is
+   * nothing left to find. Meaningless without `resume`, and ignored beside
+   * `forkAt`, which asks for the other thing.
+   */
+  rewindAt?: string;
+  /**
+   * Context the first turn carries without showing it.
+   *
+   * A side chat is started from a turn somewhere else and needs to know what
+   * that turn said, but the protocol is explicit that the source transcript is
+   * not copied into this chat's visible history - so this reaches the model
+   * and never the wire.
+   */
+  context?: string;
+
+  /**
+   * MCP servers this session declares, by name.
+   *
+   * Declared by the host rather than left to the backend's own discovery,
+   * because a server the SDK was given is one it can be told about again -
+   * which is what applying a token a client signed in with requires.
+   */
+  mcpServers?: Record<string, Bag>;
+  /**
+   * Tools the host contributes to this session.
+   *
+   * Offered to the model as an MCP server that runs in this process, so a
+   * call is a function call rather than a subprocess. What they are is the
+   * host's business; this only runs them.
+   */
+  tools?: BoundTool[];
+  /** Turns already known, so a resumed session does not open empty. */
+  seed?: Bag[];
+  /**
+   * A file a tool is about to change, and the same file once it has.
+   *
+   * Off the agent's own message stream rather than out of a hook: the SDK's
+   * `PreToolUse` and `PostToolUse` are bypassable from a person's settings,
+   * and the stream is the signal that cannot be turned off. Called with
+   * `before` as the tool is announced and `after` when its result arrives,
+   * which is what makes a turn's changeset the turn's rather than the
+   * working tree's at the time somebody asked.
+   *
+   * The path only. Reading it is the host's business, because reading a file
+   * is a filesystem and a session has none.
+   */
+  onFileEdit?(turnId: string, path: string, phase: 'before' | 'after'): void;
+  /** Called once the agent has reported what it can do. */
+  onHandshake?(): void;
+}
+
+/** What a host-run command did, once it has finished doing it. */
+export interface Ran {
+  /** Whether it exited cleanly. */
+  success: boolean;
+  /** One line about how it went, in the past tense, for the finished call. */
+  said: string;
+  /** Everything it printed. Empty when it printed nothing. */
+  output: string;
+  /** The terminal it ran in, so a client can watch it while it runs. */
+  terminal?: string;
+  /** What it exited with, where the runtime reported one. */
+  code?: number;
+}
+
+/** A live session. */
+export interface Session {
+  /** The session channel URI. */
+  readonly uri: string;
+  /** The chat channel URI. */
+  readonly chatUri: string;
+
+  /** Models this session can run a turn on. Empty until the agent has answered. */
+  models(): { id: string; name: string }[];
+  /**
+   * The id the agent gave this session, if it has said one yet.
+   *
+   * Not the same as `uri`: the client names the channel, the agent names the
+   * transcript it writes. The catalogue needs both to tell that the row on
+   * disk and this session are one conversation.
+   */
+  agentId(): string | undefined;
+
+  /**
+   * The backend's own name for the prompt that began a turn, if it has one.
+   *
+   * What a fork is cut at. A turn has an id this host chose and the backend
+   * has an id of its own for the same prompt, and only the backend's means
+   * anything when it is asked to resume at one.
+   *
+   * Optional, and its absence is what makes forking unavailable: a backend
+   * that cannot name a prompt cannot be asked to continue from one, and the
+   * host advertises no `fork` capability for it rather than offering a control
+   * that fails when it is used.
+   */
+  forkPoint?(turnId: string): string | undefined;
+  /**
+   * The backend's own name for the *last* thing a turn did, if it has one.
+   *
+   * Where a rewind cuts. `forkPoint` names the prompt a turn began with and
+   * `endPoint` names the last entry it left behind, and the two are different
+   * questions: a fork re-asks the turn, a truncation keeps it whole and drops
+   * what came after.
+   *
+   * Optional and, like `forkPoint`, only ever answered for a turn this process
+   * watched run: the backend's names for a turn read back off a transcript are
+   * not recorded, so a session resumed from disk can be truncated no further
+   * back than its own first turn.
+   */
+  endPoint?(turnId: string): string | undefined;
+  /** Skills, commands, subagents and MCP servers this session was given. */
+  customizations(): Bag[];
+  /** Every completed turn. Snapshots carry only the newest page of these. */
+  allTurns(): Bag[];
+
+  /** `SessionStatus` bitset, derived from what the session is doing now. */
+  status(): number;
+  /** What it is doing now, in one line, or nothing when it is idle. */
+  activity(): string | undefined;
+  /** Display title. */
+  title(): string;
+  /** ISO 8601 timestamp of the last change. */
+  modifiedAt(): string;
+  /**
+   * Where the agent is actually working, as `file://` URIs.
+   *
+   * Asked rather than assumed: the host knows what directory it was started
+   * in and a session may have been created in another, so a host that
+   * answered with its own reported the wrong one for exactly the sessions
+   * somebody chose a directory for.
+   */
+  workingDirectories(): string[];
+
+  /** The session channel's state, for a subscription snapshot. */
+  sessionState(): Bag;
+  /** The chat channel's state, for a subscription snapshot. */
+  chatState(): Bag;
+
+  /**
+   * Run one command as a turn of this chat's, without asking the agent.
+   *
+   * What the composer's `!` prefix means: the person typed a command rather
+   * than a question, and the answer is a shell's. The turn is still the
+   * chat's - a host that emitted one this session did not know about would
+   * serve a snapshot without it the moment anybody re-subscribed - so the
+   * session opens it, reports the tool call, and closes it when `run`
+   * settles.
+   *
+   * `run` is the host's half: it is handed the id of the tool call this turn
+   * is about and answers with what happened. The terminal is the host's
+   * because the shell is - a session has no port to spawn one through - and
+   * naming it back is what lets a client watch the output arrive rather than
+   * only read it afterwards.
+   *
+   * Optional. A backend that leaves it out is one this host advertises no
+   * `terminalCommandPrefix` for, which is the protocol's own way of saying the
+   * shorthand is unavailable.
+   */
+  ran?(turnId: string, command: string, run: (toolCallId: string) => Promise<Ran>): void;
+
+  /**
+   * Put a message into the turn that is already running.
+   *
+   * Steering, in the protocol's word: somebody correcting an agent halfway
+   * rather than waiting for it to finish doing the thing they are trying to
+   * stop. Answers whether there was a turn to steer - a chat with nothing
+   * running has nothing to inject into, and the caller says so rather than
+   * quietly turning it into an ordinary message.
+   *
+   * Optional. A backend that cannot take a message mid-turn leaves it out,
+   * and this host refuses steering for that backend with that as the reason.
+   */
+  steer?(id: string, text: string): boolean;
+
+  /** Start a turn with what the person said, optionally naming a model. */
+  begin(turnId: string, text: string, model?: Chosen): void;
+  /**
+   * Run the latest turn again, without adding a message.
+   *
+   * What `chat/turnResume` asks for: the turn errored, its message and its
+   * parts are intact, and the client wants the same prompt tried again rather
+   * than typed again. Answers whether there was such a turn to resume.
+   *
+   * Optional. A backend that cannot re-run a turn leaves it out, and the host
+   * refuses the action with that as the reason.
+   */
+  resume?(turnId: string): boolean;
+
+  /** Stop the running turn, and answer anything it was blocked on. */
+  cancel(turnId: string): void;
+
+  /**
+   * Hold a message, and make it the next turn when the running one ends.
+   *
+   * The queue is the session's, not a client's: a client that held a message
+   * would be the only thing that could ever send it, and nothing in a client
+   * watches for a turn to end. The same `id` twice edits what is waiting.
+   */
+  queue(id: string, text: string, model?: Chosen): void;
+  /** Take one back, while it is still waiting. */
+  unqueue(id: string): void;
+  /**
+   * What somebody is part-way through typing.
+   *
+   * Held by the session so two people on one chat see each other's - a client
+   * that kept its own would need nothing from a host for this.
+   */
+  setDraft(draft: Bag | undefined): void;
+  /** Reorder what is waiting. Anything not named keeps its place behind what is. */
+  reorder(order: string[]): void;
+
+  /** Answer a tool call the agent is waiting on. */
+  confirm(toolCallId: string, approved: boolean): void;
+
+  /**
+   * Replace the tools this session offers the model.
+   *
+   * The host's own are fixed at creation; a client's come and go with the
+   * client, which is what this is for. Replaces rather than merges, because
+   * a tool taken away has to be able to go.
+   *
+   * False when the backend could not re-declare them - a session whose agent
+   * has gone, or one whose backend cannot change its tools once it is running.
+   *
+   * Optional. A backend that leaves it out is one this host offers no
+   * client-provided tools through, and it says so rather than accepting an
+   * announcement it will not act on.
+   */
+  setTools?(tools: BoundTool[]): Promise<boolean>;
+  /**
+   * The client running a tool call, for a call that is one client's to run.
+   *
+   * Nothing for a call the agent is running itself, which is what makes this
+   * the check for whether a client may write into one: the protocol says a
+   * host should refuse `chat/toolCallContentChanged` from anybody but the
+   * call's own contributor.
+   */
+  toolCallOwner?(toolCallId: string): string | undefined;
+  /**
+   * What a client says one of its own tool calls did.
+   *
+   * False when no call by that id is waiting, or when it is waiting on a
+   * different client - both are a client out of step rather than a no-op, and
+   * the host refuses rather than dropping it.
+   */
+  completeToolCall?(
+    toolCallId: string,
+    clientId: string,
+    result: { text: string; ok: boolean },
+  ): boolean;
+  /**
+   * A client that was running tool calls here has gone.
+   *
+   * Its outstanding calls are failed rather than left open: the agent is
+   * waiting on a promise that nothing can settle any more, and a turn that
+   * hangs for ever is worse than a tool that says it could not run.
+   */
+  clientGone?(clientId: string): void;
+  /** Answer a question the agent asked, keyed by question id. */
+  answer(requestId: string, accepted: boolean, answers: Bag): void;
+  /**
+   * One question of an open request, as somebody types the answer.
+   *
+   * The protocol calls the result the request's synced answer state, and it is
+   * what a `chat/inputCompleted` carrying no answers of its own is completed
+   * with. Held by the session for the same reason a draft message is: two
+   * people on one chat are answering one form.
+   *
+   * False when nothing here is waiting on that request, or when what is
+   * waiting is a tool confirmation rather than a question.
+   *
+   * Optional. A backend that keeps no drafts leaves it out, and the host
+   * refuses the action with that as the reason.
+   */
+  setAnswer?(requestId: string, questionId: string, answer: Bag | undefined): boolean;
+
+  /**
+   * Take one config value, or say why not.
+   *
+   * Every key a client sets goes through here, including the ones a backend
+   * advertises in its own schema: the host reads that schema for how a key
+   * behaves - whether it can move on a running session, whether it belongs to
+   * the session or to one chat - and knows nothing about what any key means.
+   *
+   * `true` when it was taken. A string is the refusal, in the backend's own
+   * words, and it is a string rather than `false` because only the backend
+   * knows which of the two things went wrong: a key it does not serve, or a
+   * value it will not take for a key it does. A host that answered both with
+   * one sentence would be telling a client its control does not exist when
+   * the truth is that the value was wrong.
+   */
+  setConfig?(key: string, value: unknown): true | string | Promise<true | string>;
+  /** The config in force, by key. */
+  settings(): Record<string, unknown>;
+
+  /**
+   * Turn a customization on or off. False when this backend cannot.
+   *
+   * False is a real answer and the one to give for anything with no runtime
+   * switch: a control that reports success and changes nothing is worse than
+   * one that refuses.
+   */
+  setCustomizationEnabled(id: string, enabled: boolean): Promise<boolean>;
+  /** Start an MCP server, which is also how one that needs signing into is. */
+  startMcpServer(id: string): Promise<boolean>;
+  /** Stop one. */
+  stopMcpServer(id: string): Promise<boolean>;
+
+  /**
+   * A token for one of this session's MCP servers, as the client signed in.
+   *
+   * Answers whether the server it names is one of this session's. The token
+   * becomes that server's `Authorization` header and the server is asked to
+   * connect again; nothing else in the session is told.
+   *
+   * Optional: a backend that cannot re-declare a server leaves it out, and the
+   * host then advertises no resource for one to be signed into.
+   */
+  authenticated?(resource: string, token: string): Promise<boolean>;
+
+  /**
+   * The OAuth resources this session's MCP servers need signing into.
+   *
+   * What `authenticate` is checked against: the protocol says a client's
+   * `resource` MUST match one the server advertised, and these are advertised
+   * on the servers' own `authRequired` states.
+   */
+  awaiting?(): string[];
+
+  /** End the session and stop its agent. */
+  close(): void;
+}

package/src/types/terminals.ts

@@ -0,0 +1,133 @@
+/** A shell on the host machine, as a terminal channel. */
+
+import type { TerminalClaim, TerminalLifecycleState, TerminalState } from '@microsoft/agent-host-protocol';
+import type { OnWire } from './wire.js';
+import type { Bag } from './common.js';
+import type { Emit } from './session.js';
+
+/** Who currently holds a terminal: a connected client, or a session. */
+/**
+ * Who is holding a terminal, in the protocol's own type.
+ *
+ * A client, or a session and the chat inside it. Was `Bag`, which meant a
+ * claim missing the fields its own kind requires compiled perfectly.
+ */
+export type Claim = OnWire<TerminalClaim>;
+
+/** How to start one. */
+export interface TerminalOptions {
+  /** The terminal channel URI, chosen by the client that asked for it. */
+  uri: string;
+  /** The directory it starts in. Already checked against what the host serves. */
+  cwd: string;
+  /** Who is holding it. */
+  claim: Claim;
+  /** Display name. The shell's own if none is given. */
+  name?: string;
+  /**
+   * The shell to run, absolute. The store's own choice if none is given.
+   *
+   * A connected client pushes this: VS Code sends `defaultShell` on the root
+   * channel out of `terminal.integrated.agentHostProfile.<os>`, because the
+   * shell somebody wants a host-managed terminal to open is a preference of
+   * theirs rather than a fact about the machine.
+   */
+  shell?: string;
+  /**
+   * One command to run instead of a shell to sit in.
+   *
+   * The terminal runs it and exits, so `terminal/exited` is what says the
+   * command finished and its code is what says how. Without this the shell
+   * reads from a pipe and stays open, which is right for a terminal somebody
+   * is typing into and wrong for one opened to answer a single question -
+   * there is no shell integration here to tell where one command ends.
+   */
+  command?: string;
+  /** Width in columns, as the client draws it. */
+  cols?: number;
+  /** Height in rows. */
+  rows?: number;
+  /** Where state actions go. The host routes them to the terminal's channel. */
+  emit: Emit;
+}
+
+/** A running terminal. */
+export interface Terminal {
+  /** Its channel URI. */
+  readonly uri: string;
+  /** Display title. */
+  title(): string;
+  /** Who is holding it. */
+  claim(): Claim;
+  /** The process's exit code, once it has one. Undefined while it runs. */
+  exitCode(): number | undefined;
+  /**
+   * Running, or exited and with what.
+   *
+   * 0.9.0 moved the exit code in here and made this required, so a terminal
+   * described without it is a terminal a client cannot ask about. `exitCode`
+   * above stays for the versions this host still negotiates down to.
+   */
+  lifecycle(): OnWire<TerminalLifecycleState>;
+  /** The channel's state, for a subscription snapshot. */
+  /**
+   * The terminal channel's snapshot, in the protocol's own type.
+   *
+   * Typed against the package rather than as a `Bag`, which is the point:
+   * `Bag` is why 0.9.0 moved the exit code inside `lifecycle` and this host
+   * went on sending the old shape with a clean compile. A field removed or
+   * renamed upstream is a type error here now, at the one place the payload
+   * is built.
+   *
+   * The intersection is the deliberate part. This host negotiates down to
+   * 0.5.1 and every version before 0.9.0 reads a flat `exitCode`, so it sends
+   * both - and saying so in the type is the difference between a divergence
+   * somebody chose and one nobody noticed.
+   */
+  state(): OnWire<TerminalState> & { exitCode?: number };
+
+  /** Send input. Ignored once the process has exited. */
+  write(data: string): void;
+  /** Record a new size. Nothing is signalled: there is no pseudoterminal. */
+  resize(cols: number, rows: number): void;
+  /**
+   * Throw away the scrollback, keeping everything else.
+   *
+   * The size, the title and the claim survive: a client clears a terminal to
+   * stop reading what is already there, not to give it up. Nothing reaches
+   * the process - there is no pseudoterminal to send anything to, and a shell
+   * has no notion of its own output having been discarded.
+   */
+  clear(): void;
+  /** Rename it. */
+  setTitle(title: string): void;
+  /** Hand it to somebody else. */
+  setClaim(claim: Claim): void;
+  /** Kill the process and let go. */
+  close(): void;
+}
+
+/**
+ * A pseudoterminal, as this host needs one.
+ *
+ * Handed in rather than imported: a PTY is a native binding, and a library
+ * that depended on one would not load under a runtime it was not built for.
+ * The daemon passes `node-pty` when it has it; a host on another runtime
+ * passes its own, and one that passes none keeps pipes and says `isPty: false`.
+ */
+export interface Pty {
+  /** Everything the terminal writes, VT sequences included. */
+  onData(listen: (data: string) => void): void;
+  /** Called once, when the process goes. */
+  onExit(listen: (exit: { exitCode: number }) => void): void;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+
+/** Start one. The shape `node-pty`'s own `spawn` already has. */
+export type SpawnPty = (
+  file: string,
+  args: string[],
+  options: { cwd?: string; cols: number; rows: number; env: Record<string, string | undefined> },
+) => Pty;

package/src/types/wire.ts

@@ -0,0 +1,69 @@
+/** The protocol's own shapes, as they actually go down the socket. */
+
+import type { Bag } from './common.js';
+
+/**
+ * Why this exists at all.
+ *
+ * Every payload this host builds used to be a `Bag`, and that is how 0.9.0
+ * moved a terminal's exit code inside `lifecycle`, removed `Turn.error` and
+ * required an `ErrorInfo` on a failed MCP server without a single compile
+ * error here. Three shape defects in one afternoon's audit, each one a client
+ * behaving correctly and getting it wrong. Typing the construction sites
+ * against the package turns the next one into a build failure.
+ *
+ * The conversion is needed because the protocol types its discriminants as
+ * `const enum`, and this project compiles with `verbatimModuleSyntax`, which
+ * refuses to import an ambient const enum as a value. That is not a problem
+ * worth casting past: what travels on the wire *is* the string, and
+ * `` `${SomeEnum}` `` is the set of strings that enum can be - checked, so a
+ * value renamed upstream stops matching here exactly as a field would.
+ */
+
+/** One value, with string enums widened to the strings they are. */
+type WireValue<V> =
+  // A function is not a payload. Left alone so a shape carrying one - which
+  // none of these do - does not silently become something else.
+  V extends (...args: never[]) => unknown ? V
+    : V extends string ? `${V}`
+      : V extends readonly (infer E)[] ? WireValue<E>[]
+        : V extends object ? OnWire<V>
+          : V;
+
+/**
+ * A protocol shape as this host builds it.
+ *
+ * Optional keys stay optional, which matters under `exactOptionalPropertyTypes`:
+ * a field the protocol allows to be absent must not become one that has to be
+ * present and `undefined`.
+ */
+export type OnWire<T> = { [K in keyof T]: WireValue<T[K]> };
+
+/**
+ * A turn, whose parts are checked where they are built rather than here.
+ *
+ * `responseParts` is seven kinds and an eight-state tool call, assembled piece
+ * by piece as an agent talks - so the array cannot carry a union the way a
+ * finished value can: a call is `running` when it is pushed and `completed`
+ * three frames later, and a variable declared as either fights the other.
+ *
+ * The gap this used to leave is where the worst of it hid. A rebuilt
+ * transcript wrote a tool-call `status` that is not one of the seven, left off
+ * three fields the completed state requires, and gave its content blocks no
+ * `type` - four defects in one object, none of them a compile error, and every
+ * one of them a conversation that would not draw. So each part is now checked
+ * against the state it claims, at the moment it is built, with `satisfies` on
+ * the literal; what stays loose here is only the mutation that follows.
+ */
+export type WireTurn<T> = Omit<OnWire<T>, 'responseParts'> & { responseParts: Bag[] };
+
+/**
+ * On `satisfies` rather than annotation, where you see it.
+ *
+ * A turn is built as an `ActiveTurn` and then *mutated* into a `Turn` - a
+ * state and a duration are set on the same object when it ends. Declaring the
+ * variable as either one fights the other, so the literal is checked with
+ * `satisfies` at the moment it is built and the variable stays a `Bag` for the
+ * mutation that follows. The construction is what the protocol changes under,
+ * and the construction is what is checked.
+ */