@ahpd/server 0.1.0 → 0.3.0

package/src/terminals.ts

@@ -1,353 +0,0 @@
-import { spawn } from 'node:child_process';
-import type { Pty, SpawnPty, Terminal, TerminalOptions } from './types/terminals.js';
-import type { TerminalStore } from './types/host.js';
-
-/**
- * A shell on the host machine, as a terminal channel.
- *
- * Pipes, not a pseudoterminal: a PTY needs a native binding this daemon does
- * not depend on, and the protocol has `isPty: false` for exactly this - "output
- * is plain text and clients do not need to parse VT sequences". So a command
- * runs and its output arrives, and anything that draws itself with cursor
- * movement will not look right. Said in the state rather than discovered.
- *
- * `node:child_process` is used because all three supported runtimes provide it.
- */
-
-/** What runs, when nothing else was asked for. */
-const shellOf = (asked?: string): string => asked ?? process.env.SHELL ?? '/bin/sh';
-
-/**
- * What a shell says about itself, in the escape sequences it says it with.
- *
- * OSC 133 is the command-boundary convention every shell integration script
- * writes - `A` before the prompt, `B` where the command starts, `C` where its
- * output does, `D;<code>` when it finished - and OSC 7 is the directory. They
- * arrive mixed into the output, so this reads them out and leaves the rest
- * alone: the bytes still go to the client, which is drawing a terminal and
- * needs them.
- *
- * Only under a pseudoterminal, because only then is there a shell running its
- * own prompt to emit them.
- */
-const MARKS = /\u001b\](133|7);([^\u0007\u001b]*)(?:\u0007|\u001b\\)/g;
-
-export function createTerminal(options: TerminalOptions, pty?: SpawnPty): Terminal {
-  const { uri, cwd, emit } = options;
-  const shell = shellOf(options.shell);
-  let title = options.name ?? shell.slice(shell.lastIndexOf('/') + 1);
-  let claim = options.claim;
-  let cols = options.cols ?? 80;
-  let rows = options.rows ?? 24;
-  let exitCode: number | undefined;
-  /**
-   * Everything written so far, so a client that subscribes late sees it.
-   *
-   * Capped: a terminal left running `tail -f` for a day is a host holding a
-   * day of output for a client that may never come back.
-   */
-  let buffered = '';
-  const KEEP = 200_000;
-
-  const said = (data: string): void => {
-    buffered = (buffered + data).slice(-KEEP);
-    emit('terminal', { type: 'terminal/data', data });
-  };
-
-  /*
-   * `-c` when there is a command, and nothing when there is not.
-   *
-   * A shell given `-c` runs the one thing and exits. Under pipes that is the
-   * only completion signal there is; under a pseudoterminal the shell says so
-   * itself, in OSC 133.
-   */
-  const args = options.command === undefined ? [] : ['-c', options.command];
-  const environment = {
-    ...process.env,
-    // A real terminal under a pty, and an honest `dumb` without one.
-    TERM: pty ? (process.env.TERM ?? 'xterm-256color') : 'dumb',
-    COLUMNS: String(cols),
-    LINES: String(rows),
-  };
-
-  /** Where the shell says it is, once it has said. */
-  let where = cwd;
-  /** The command being run, from `C` until `D`. */
-  let command: { id: string; line: string; at: number } | undefined;
-  /** What has been typed since the prompt, so the command line can be read back. */
-  let typed = '';
-
-  /**
-   * Read the shell's own marks out of a chunk, and say what they meant.
-   *
-   * The chunk still reaches the client whole: this is a reader, not a filter,
-   * and a client drawing a terminal needs the bytes it was sent.
-   */
-  const marked = (data: string): void => {
-    for (const found of data.matchAll(MARKS)) {
-      const [, kind, body = ''] = found;
-      if (kind === '7') {
-        // `file://host/path`, per the convention. The host part is dropped:
-        // the path is on this machine, and that is what a client opens.
-        const path = body.replace(/^file:\/\/[^/]*/, '');
-        if (path !== '' && path !== where) {
-          where = path;
-          emit('terminal', { type: 'terminal/cwdChanged', cwd: `file://${path}` });
-        }
-        continue;
-      }
-      const mark = body.split(';')[0];
-      if (mark === 'A') { typed = ''; continue; }
-      if (mark === 'C') {
-        command = { id: `c${String(Date.now())}`, line: typed.trim(), at: Date.now() };
-        emit('terminal', {
-          type: 'terminal/commandExecuted',
-          commandId: command.id,
-          commandLine: command.line,
-          timestamp: command.at,
-        });
-        continue;
-      }
-      if (mark !== 'D' || command === undefined) continue;
-      const code = Number(body.split(';')[1]);
-      emit('terminal', {
-        type: 'terminal/commandFinished',
-        commandId: command.id,
-        ...(Number.isFinite(code) ? { exitCode: code } : {}),
-        durationMs: Date.now() - command.at,
-      });
-      command = undefined;
-    }
-  };
-
-  const terminal: Pty | undefined = pty?.(shell, args, {
-    ...(cwd !== undefined ? { cwd } : {}),
-    cols,
-    rows,
-    env: environment,
-  });
-  if (terminal !== undefined) {
-    terminal.onData((data) => { marked(data); said(data); });
-    terminal.onExit(({ exitCode: code }) => { exitCode = code; ended(); });
-    // Said once, at the start. A client MUST check this before relying on
-    // command boundaries, and the same fact is on the state.
-    emit('terminal', { type: 'terminal/commandDetectionAvailable' });
-  }
-
-  const child = terminal !== undefined ? undefined : spawn(shell, args, {
-    cwd,
-    /*
-     * Its own process group, so a signal reaches what it started.
-     *
-     * A shell reading from a pipe runs each command as its own child, and a
-     * signal sent to the shell alone leaves the command running. The group is
-     * what a terminal driver would have signalled, and this has no driver.
-     */
-    detached: true,
-    // A shell reading commands from a pipe. Without a pseudoterminal there is
-    // no point asking it to be interactive: it would print a prompt nobody
-    // can answer the way it expects.
-    stdio: ['pipe', 'pipe', 'pipe'],
-    env: environment,
-  });
-
-  child?.stdout.on('data', (chunk: Buffer) => said(chunk.toString('utf8')));
-  child?.stderr.on('data', (chunk: Buffer) => said(chunk.toString('utf8')));
-  /**
-   * Said once, whichever of the three got here first.
-   *
-   * `error` and `close` can both fire for one failed spawn, and a terminal
-   * that announced its own exit twice would be one every client draws as
-   * having died, come back, and died again.
-   */
-  let announced = false;
-  const ended = (): void => {
-    if (announced) return;
-    announced = true;
-    emit('terminal', { type: 'terminal/exited', exitCode });
-  };
-  child?.on('error', (error: Error) => {
-    said(`${error.message}\n`);
-    exitCode = 127;
-    ended();
-  });
-  child?.on('exit', (code: number | null, signal: string | null) => {
-    // A signal is not an exit code, and 128+n is the shell's own convention
-    // for one - better than reporting nothing, which reads as still running.
-    exitCode = code ?? (signal ? 128 : 0);
-  });
-  /*
-   * Announced on `close` rather than on `exit`, which is a race this lost.
-   *
-   * `exit` fires when the process goes; `close` fires once its pipes are
-   * drained. Between the two there is output already written and not yet
-   * read, so a host that reported the exit on `exit` reported a command's
-   * result before the result had arrived - which is exactly what a `!`
-   * command in the composer reads back.
-   */
-  child?.on('close', () => {
-    // A process that closed without an exit event was killed outright.
-    exitCode ??= 0;
-    ended();
-  });
-
-  return {
-    uri,
-    title: () => title,
-    claim: () => claim,
-    exitCode: () => exitCode,
-    lifecycle: () => (exitCode === undefined
-      ? { status: 'running' }
-      : { status: 'exited', exitCode }),
-
-    state: () => ({
-      title,
-      cwd: `file://${cwd}`,
-      cols,
-      rows,
-      // One part, because without command detection there are no boundaries
-      // to divide the output at. The protocol's shape, not a flat string.
-      content: buffered === '' ? [] : [{ type: 'unclassified', value: buffered }],
-      claim,
-      // Both true only under a pseudoterminal: without one there is no shell
-      // running its own prompt, so there are no boundaries to report and no
-      // VT sequences for a client to parse.
-      supportsCommandDetection: terminal !== undefined,
-      isPty: terminal !== undefined,
-      /*
-       * Both spellings, because this host speaks five versions.
-       *
-       * `lifecycle` is what 0.9.0 requires and is not optional there - a
-       * client reading `lifecycle.status` on a 0.8.0-shaped terminal gets
-       * `undefined`, which reads as a process that never exits. The flat
-       * `exitCode` is what every version before it reads, and this daemon
-       * negotiates down to 0.5.1.
-       */
-      lifecycle: exitCode === undefined
-        ? { status: 'running' }
-        : { status: 'exited', exitCode },
-      ...(exitCode !== undefined ? { exitCode } : {}),
-    }),
-
-    write: (data) => {
-      if (exitCode !== undefined)
-        return;
-      /*
-       * `^C` is a signal, and there is nothing here to turn it into one.
-       *
-       * A pseudoterminal has a line discipline that sees the byte and sends
-       * SIGINT to the foreground group. Pipes have none, so the byte arrives
-       * as input and the command runs on - which is a terminal a runaway
-       * command cannot be stopped in. Sending the signal is what the driver
-       * would have done.
-       */
-      /*
-       * Under a pseudoterminal the byte is the signal.
-       *
-       * A pty has a line discipline: `^C` reaches it as input and it sends
-       * SIGINT to the foreground group itself, which is the whole point of
-       * having one. So this writes it through and does nothing clever.
-       */
-      if (terminal !== undefined) {
-        terminal.write(data);
-        // Kept so a command line can be read back at the next `C` mark; the
-        // shell echoes what was typed, but the echo arrives as output and
-        // this is the only place the input itself is seen.
-        typed += data;
-        return;
-      }
-      const at = data.indexOf('\u0003');
-      if (at !== -1) {
-        const rest = data.slice(0, at) + data.slice(at + 1);
-        if (rest !== '' && child?.stdin.writable) child.stdin.write(rest);
-        /*
-         * The group, named by the child's own pid, and only when there is one.
-         *
-         * A spawn that failed leaves no pid, and `0` is not a safe stand-in:
-         * to `kill` it means every process in *this* process group, so a
-         * terminal whose shell never started would signal the host and
-         * whatever started the host.
-         */
-        const group = child?.pid;
-        if (group !== undefined) {
-          try { process.kill(-group, 'SIGINT'); }
-          // The group is gone, which is the outcome asked for.
-          catch { /* nothing left to interrupt */ }
-        }
-        return;
-      }
-      if (child?.stdin.writable) child.stdin.write(data);
-    },
-
-    // Told, when there is something to tell: a pseudoterminal gets the new
-    // size and sends SIGWINCH itself. Without one these are kept because the
-    // state reports them and a client draws to them.
-    resize: (nextCols, nextRows) => {
-      terminal?.resize(nextCols, nextRows);
-      cols = nextCols;
-      rows = nextRows;
-      emit('terminal', { type: 'terminal/resized', cols, rows });
-    },
-
-    // The scrollback and nothing else. `cols`, `rows`, `title` and `claim` are
-    // untouched, which is what the reference suite checks for.
-    clear: () => {
-      buffered = '';
-      emit('terminal', { type: 'terminal/cleared' });
-    },
-
-    setTitle: (next) => {
-      if (next === title) return;
-      title = next;
-      emit('terminal', { type: 'terminal/titleChanged', title });
-    },
-
-    setClaim: (next) => {
-      claim = next;
-      emit('terminal', { type: 'terminal/claimed', claim });
-    },
-
-    close: () => {
-      if (terminal !== undefined) {
-        terminal.kill();
-        return;
-      }
-      child?.stdin.end();
-      // The group, not the shell: detached, its children outlive it otherwise.
-      // Only when there is a pid to name it - see the interrupt above.
-      const group = child?.pid;
-      if (group === undefined) {
-        child?.kill();
-        return;
-      }
-      try { process.kill(-group, 'SIGKILL'); }
-      catch { child?.kill(); }
-    },
-  };
-}
-
-/**
- * A shell on this machine, as a host's `TerminalStore`.
- *
- * Kept out of `createHost` for the reason above: spawning is the runtime's
- * business, and a host that opens no terminal should not have to have one.
- *
- * ```ts
- * createHost({ path, agents, terminals: shellTerminals() });
- * ```
- *
- * Given a `pty` it runs shells under a pseudoterminal instead, which is what
- * makes shell integration possible: the shell prints its own OSC 133 marks, so
- * command boundaries and the working directory become facts rather than
- * guesses. The binding is handed in because it is native code - `node-pty` is
- * the daemon's dependency and never this library's, and a host on another
- * runtime passes whatever it has.
- *
- * ```ts
- * import { spawn } from 'node-pty';
- * createHost({ path, agents, terminals: shellTerminals({ pty: spawn }) });
- * ```
- */
-export const shellTerminals = (options: { pty?: SpawnPty } = {}): TerminalStore => ({
-  create: (asked) => createTerminal(asked, options.pty),
-});

package/src/tools.ts

@@ -1,64 +0,0 @@
-import type { HostTool } from './types/host.js';
-
-/**
- * The tools this package contributes to every session, as a host's `tools`.
- *
- * The protocol's `serverTools` are the *host's* own - not a backend's and not
- * a client's - and what makes one worth contributing is that the host knows
- * something the agent inside a session cannot: the other sessions running
- * beside it, and the terminals the person is watching. Both are read-only.
- *
- * ```ts
- * createHost({ path, agents, tools: hostTools() });
- * ```
- *
- * A host that wants its own passes its own; a host that passes none
- * contributes none, and its sessions report no `serverTools` at all.
- */
-export const hostTools = (): HostTool[] => [
-  {
-    definition: {
-      name: 'ahp_sessions',
-      title: 'Sessions on this host',
-      description: 'The other agent sessions running on this host, with the directories each works in. '
-        + 'Use it before touching a file to find out whether another agent is already working there.',
-      inputSchema: { type: 'object', properties: {} },
-      annotations: { title: 'Sessions on this host', readOnlyHint: true, openWorldHint: false },
-    },
-    run: (_input, at) => {
-      const others = at.sessions().filter((one) => one.uri !== at.session);
-      if (others.length === 0) return 'No other session is running on this host.';
-      return others
-        .map((one) => `${one.uri}\t${one.provider}\t${one.title}\t${one.workingDirectories.join(' ')}`)
-        .join('\n');
-    },
-  },
-  {
-    definition: {
-      name: 'ahp_resource',
-      title: 'Read a resource this host serves',
-      description: 'Read a resource by URI, including one a connected client publishes and this machine has no copy of '
-        + '- a plugin\u2019s virtual files, an editor\u2019s unsaved buffers. Addressed as <scheme>://<client>/<path>.',
-      inputSchema: { type: 'object', properties: { uri: { type: 'string' } }, required: ['uri'] },
-      annotations: { title: 'Read a resource this host serves', readOnlyHint: true },
-    },
-    run: async (input, at) => await at.read(String(input.uri ?? '')),
-  },
-  {
-    definition: {
-      name: 'ahp_terminals',
-      title: 'Terminals on this host',
-      description: 'The terminals this host has open, with what each is running and where. '
-        + 'These are the terminals the person can see, which is not the same as a shell run from a tool.',
-      inputSchema: { type: 'object', properties: {} },
-      annotations: { title: 'Terminals on this host', readOnlyHint: true, openWorldHint: false },
-    },
-    run: (_input, at) => {
-      const open = at.terminals();
-      if (open.length === 0) return 'This host has no terminal open.';
-      return open
-        .map((one) => `${one.uri}\t${one.title}\t${one.cwd}\t${one.running ? 'running' : 'exited'}`)
-        .join('\n');
-    },
-  },
-];

package/src/types/agent.ts

@@ -1,255 +0,0 @@
-/** An agent backend, and everything the host asks one for. */
-
-import type { Turn } from '@microsoft/agent-host-protocol';
-import type { Bag } from './common.js';
-import type { WireTurn } from './wire.js';
-import type { Emit, Session } from './session.js';
-import type { ToolDefinition } from '@microsoft/agent-host-protocol';
-import type { Offered } from './probe.js';
-
-/**
- * A tool the host contributes, with the session it was contributed to
- * already bound.
- *
- * The host's `HostTool` takes a `ToolCall` saying where it was called from;
- * by the time a backend sees one that is answered, so what is left is a
- * definition to offer the model and a function to call.
- */
-export interface BoundTool {
-  /** What the model is offered. `name` is the id it calls. */
-  definition: ToolDefinition;
-  /**
-   * What running it does. Absent for a tool a client runs - see `owner`.
-   */
-  run?(input: Record<string, unknown>): Promise<string> | string;
-  /**
-   * The client that runs this one, when it is a client's rather than the host's.
-   *
-   * A client announces what it provides on `SessionActiveClient.tools`, and
-   * the protocol makes that client responsible for executing the call and
-   * dispatching its result. So there is nothing to run here: the backend
-   * offers the tool to the model, reports the call against that client, and
-   * waits for it to say what happened.
-   */
-  owner?: string;
-}
-
-/**
- * One session a backend already has, before the host has named it.
- *
- * Deliberately not a `Summary`: the resource URI, the provider and the status
- * bits are the host's to decide - `IsRead` and `IsArchived` in particular are
- * kept per client and a backend has never heard of them.
- */
-export interface Listed {
-  /** The backend's own id for it. The host serves it as `<provider>:/<id>`. */
-  id: string;
-  /** Display title. */
-  title: string;
-  /** ISO 8601 timestamp of creation. */
-  createdAt: string;
-  /** ISO 8601 timestamp of the last change. */
-  modifiedAt: string;
-  /** Directories the agent has tool access to, as `file://` URIs. */
-  workingDirectories: string[];
-}
-
-/** How the host asks a backend to start a session. */
-export interface Start {
-  /** The session channel URI the client chose. */
-  uri: string;
-  /** The chat channel URI beneath it. */
-  chatUri: string;
-  /** Config values in force, by key: this agent's defaults with the client's on top. */
-  settings: Record<string, unknown>;
-  /**
-   * The directory the client asked the agent to work in, if it named one.
-   *
-   * A path, not a `file://` URI. Absent means the client named none and the
-   * backend picks. A backend that will not work there should throw saying so:
-   * a directory accepted and then ignored is a session running somewhere
-   * nobody asked for, and nothing on screen says which.
-   */
-  workingDirectory?: string;
-  /** Directories beside it the agent may also work in. */
-  additional?: string[];
-  /**
-   * Tools the host contributes to this session, for the backend to offer.
-   *
-   * The host's own, not this backend's: a backend that cannot take tools from
-   * anywhere ignores them, and the host still reports them on the session so
-   * a client knows they exist.
-   */
-  tools?: BoundTool[];
-  /** The config schema to report on the session channel. This agent's own. */
-  schema(): Bag;
-  /** What to report as customizations until the backend reports its own. */
-  seedCustomizations?: Bag[];
-  /** Where state actions go. The host routes them to the right channel. */
-  emit: Emit;
-  /** A session of this backend's to continue, rather than starting a new one. */
-  resume?: string;
-  /** The prompt to resume *at*, so a fork leaves the turns after it behind. */
-  forkAt?: string;
-  /**
-   * The chain entry to resume *at*, keeping the id the session already had.
-   *
-   * A truncation rather than a fork: the turns after that point are dropped
-   * and the conversation carries on as itself, which is what `chat/truncated`
-   * asks for.
-   */
-  rewindAt?: string;
-  /** Context the first turn carries to the backend without showing it. */
-  context?: string;
-  /** 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.
-   *
-   * Optional both ways: a backend that cannot see its own tools does not call
-   * it, and a host with no changeset source does not pass one.
-   */
-  onFileEdit?(turnId: string, path: string, phase: 'before' | 'after'): void;
-  /** Called once the backend has reported what it can do. */
-  onHandshake?(): void;
-  /**
-   * Tokens for this backend's protected resources, by resource identifier.
-   *
-   * Only resources this agent advertised, and only what the connection
-   * asking for the session pushed - authentication is per connection, so a
-   * token one client offered is never spent on another's session. Absent for
-   * a session nobody asked for: an automation firing at nine in the morning
-   * has no connection behind it and runs on the daemon's own credentials.
-   *
-   * What to *do* with one is the backend's business. The host knows a token
-   * belongs to a resource and nothing else about it.
-   */
-  credentials?: Record<string, string>;
-}
-
-/**
- * A backend the host can run sessions on.
- *
- * One host serves several. `provider` is what a client names in
- * `createSession` and what every session of this kind reports, so it has to
- * be unique across the agents a host was given.
- *
- * Everything but `provider`, `displayName`, `schema`, `defaults` and `create`
- * is optional, and what is left out is a real answer rather than a gap: a
- * backend with no `list` has no sessions to browse, one with no `probe`
- * offers no models and no commands until a session of its own reports them.
- */
-export interface Agent {
-  /** The id clients name. Unique among a host's agents. */
-  provider: string;
-  /** What a person reads instead of the id. */
-  displayName: string;
-  /** One line about what this backend is. */
-  description?: string;
-
-  /**
-   * What a second chat in one session can be made from.
-   *
-   * Multi-chat itself is the host's doing - a second chat is `create` called
-   * twice - but these two are the backend's: a fork continues a conversation
-   * from one of its turns, and a side chat starts a fresh one that knows what
-   * a turn elsewhere said. A backend that declares neither still gets several
-   * chats; it just cannot be asked to make one out of another.
-   */
-  chats?: { fork?: boolean; sideChat?: boolean };
-
-  /**
-   * Whether a session of this backend can work in more than one directory.
-   *
-   * The first is the process root and never moves; the rest are its peers.
-   * A backend that leaves this out gets one directory per session, which is
-   * what a client is told when the capability is absent.
-   */
-  multipleDirectories?: boolean;
-
-  /**
-   * OAuth protected resources this backend can be given a token for.
-   *
-   * RFC 9728 metadata, served on `AgentInfo.protectedResources`, and the only
-   * thing that makes `authenticate` callable: the protocol says a client's
-   * `resource` MUST match one the server has itself advertised, so a host that
-   * advertises none can be sent no token at all.
-   *
-   * `required: false` on an entry is a backend saying it works without one -
-   * this daemon runs as whoever started it and inherits their credentials, so
-   * a token is an override rather than a precondition.
-   */
-  protectedResources?: Bag[];
-
-  /**
-   * What a session of this kind can be told to do differently.
-   *
-   * A JSON-Schema-shaped `{ properties }`. Each property may carry `title`,
-   * `description`, `enum`, `enumLabels`, `enumDescriptions`, `default`,
-   * `sessionMutable` and `scope`.
-   *
-   * The last two are what the *host* reads, and they are the only two things
-   * it needs to know about a key it otherwise knows nothing about.
-   * `sessionMutable: false` is refused on a running session rather than
-   * accepted and dropped. `scope` is `'session'` - the default - for a key the
-   * chats of one session share, and `'chat'` for one each chat answers for
-   * itself: a permission mode is the session's, and a model is the chat's.
-   * `scope` is this library's, not the protocol's, whose config schema is
-   * deliberately generic and says nothing about either.
-   *
-   * Everything else is between the backend and whatever client draws it.
-   *
-   * One schema, used before a session exists and by every session that does.
-   * Two copies drift, and a composer then offers one set of controls on the
-   * new-session screen and a different set the moment a session opens.
-   */
-  schema(): Bag;
-  /** What each schema key sits at when nothing has been chosen. */
-  defaults(): Record<string, unknown>;
-
-  /**
-   * What the backend offers, asked once at startup.
-   *
-   * Before any session exists, because that is when a client asks: the models
-   * to pick from and the commands behind a slash are what a composer needs to
-   * draw itself, and waiting for the first session means offering them only
-   * once the conversation has started.
-   */
-  probe?(): Promise<Offered>;
-
-  /**
-   * The directories this backend will work in.
-   *
-   * The host's answer to "may this client read that file": a resource outside
-   * every backend's directories is refused, because a host that served the
-   * whole filesystem is one that anybody who can reach the port can read
-   * `~/.ssh` through.
-   *
-   * Left out means this backend claims no directories, and contributes
-   * nothing to what may be browsed.
-   */
-  directories?(): string[];
-
-  /** Sessions this backend already has. Ordering is the host's business. */
-  list?(): Promise<Listed[]>;
-
-  /**
-   * One past session's turns, read without starting anything.
-   *
-   * What makes a catalogue row openable: the host serves it from here, and
-   * starts nothing until somebody sends a turn to it. Undefined means this
-   * backend has no such session.
-   *
-   * A `WireTurn` rather than a `Bag[]`: everything around the parts is checked
-   * here, and each part is checked where it is built - a part is assembled by
-   * mutation as an agent talks, so the literal is what can be held to a shape
-   * and the variable after it cannot. This was a `Bag[]`, and inside it 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`.
-   */
-  transcript?(id: string): Promise<WireTurn<Turn>[] | undefined>;
-
-  /** Start one. */
-  create(start: Start): Session;
-}