@ahpd/server 0.1.0

package/dist/types/session.d.ts

@@ -0,0 +1,395 @@
+/** 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;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/types/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":"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"}

package/dist/types/session.js

@@ -0,0 +1,3 @@
+/** One agent session: its lifecycle, its turns, and what it is waiting for. */
+export {};
+//# sourceMappingURL=session.js.map

package/dist/types/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":"AAAA,+EAA+E"}

package/dist/types/terminals.d.ts

@@ -0,0 +1,131 @@
+/** 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 { 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;
+//# sourceMappingURL=terminals.d.ts.map

package/dist/types/terminals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminals.d.ts","sourceRoot":"","sources":["../../src/types/terminals.ts"],"names":[],"mappings":"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"}

package/dist/types/terminals.js

@@ -0,0 +1,3 @@
+/** A shell on the host machine, as a terminal channel. */
+export {};
+//# sourceMappingURL=terminals.js.map

package/dist/types/terminals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminals.js","sourceRoot":"","sources":["../../src/types/terminals.ts"],"names":[],"mappings":"AAAA,0DAA0D"}

package/dist/types/wire.d.ts

@@ -0,0 +1,62 @@
+/** 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> = 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[];
+};
+export {};
+/**
+ * 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.
+ */
+//# sourceMappingURL=wire.d.ts.map

package/dist/types/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/types/wire.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;;;GAgBG;AAEH,oEAAoE;AACpE,KAAK,SAAS,CAAC,CAAC,IAGd,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAAG,CAAC,GACvC,CAAC,SAAS,MAAM,GAAG,GAAG,CAAC,EAAE,GACvB,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,GAC7C,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,GAC1B,CAAC,CAAC;AAEd;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAE5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,GAAG;IAAE,aAAa,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC;;AAEtF;;;;;;;;;GASG"}

package/dist/types/wire.js

@@ -0,0 +1,13 @@
+/** The protocol's own shapes, as they actually go down the socket. */
+export {};
+/**
+ * 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.
+ */
+//# sourceMappingURL=wire.js.map

package/dist/types/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../src/types/wire.ts"],"names":[],"mappings":"AAAA,sEAAsE;;AA2DtE;;;;;;;;;GASG"}