@aivi/plugin 0.0.0-stage → 0.1.0

package/dist/tracker.d.ts

@@ -0,0 +1,473 @@
+/**
+ * The **tracker** contract, in the two seams a tracker module lives between.
+ *
+ * `Tracker` is the seam between the host's orchestrator and the module: the
+ * **stages** a run is walked through, keyed by the run. The orchestrator
+ * walks them in order and awaits only the lifecycle ones; it never learns
+ * what a ticket platform is. `Platform` is the seam between the module and
+ * its ticket platform: the conversation-keyed translator that turns the
+ * platform's events into neutral ones and aivi's neutral updates into the
+ * platform's mutations. A module registers one `Tracker` with the
+ * orchestrator and speaks its `Platform` to whomever on its platform; the
+ * stages that render are usually one-line forwards — the division is honest,
+ * not duplicated.
+ *
+ * The words here are platform-neutral by design: roughly seven trackers will
+ * move this contract, and every entry earns its place with a second
+ * tracker's need. The run shapes the stages carry are the shared run domain
+ * (`./run.ts`); the ticket shapes here are what the tracker reports and the
+ * orchestrator routes.
+ */
+import type { RunPlan, RunQuestion, RunView } from './run.ts';
+/**
+ * The work a tracker answers for: the **stages** the orchestrator walks a
+ * run through, and the board it walks for work. Division of labour, said as
+ * an interface: the orchestrator orchestrates and never learns what a ticket
+ * platform is; the tracker tracks and answers for its platform alone. A
+ * tracker module registers ONE of these at start; the orchestrator calls the
+ * stages in the documented order and awaits only the lifecycle ones
+ * (`initWork`, `endWork`): their failure is the run's failure, said visibly.
+ * The renders (`ready`, `startWork`, `question`, `plan`) are fire-and-forget
+ * — a platform that cannot show a thing loses nothing the orchestrator cares
+ * about, and a tracker retries its own renders in its own time. The order is
+ * owned by `docs/orchestrator.md` ("The tracker's stages").
+ *
+ * `initWork` is where a tracker does whatever its platform needs to open a
+ * ticket to work — Linear delegates the issue to its own app and Linear's
+ * answer carries the new agent session — and it hands back the ticket's
+ * **summary**: the words the worker is started with, composed around the
+ * directory and the lane by the orchestrator, which never reads a ticket
+ * itself. A tracker that needs nothing answers with the ticket's text alone.
+ */
+/** What `initWork` answers with: the words the worker is started with, and
+ *  the ticket's **branch name** where the platform names one. A lane that
+ *  writes (`worktree: true`) gets its worktree on this branch, and the
+ *  orchestrator never invents a name — such a lane whose tracker answers
+ *  without one fails the run visibly. A tracker whose platform has no
+ *  branch answers with the summary alone. */
+export interface WorkEntry {
+    summary: string;
+    branch?: string;
+}
+export interface Tracker {
+    /** The module id this tracker speaks for (`tracker-linear`): the key
+     *  the orchestrator records claims and queue places under. */
+    readonly id: string;
+    /** The projects this tracker speaks for, by core id: what a walk
+     *  visits. */
+    projects(): string[];
+    /** Tickets sitting in a lane, in the board's own top-to-bottom order.
+     *  `blocked` says a person's move is awaited, whatever the platform
+     *  calls it; blocked tickets wait and are never claimed. */
+    tickets(projectId: string, lane: string): Promise<{
+        id: string;
+        blocked: boolean;
+    }[]>;
+    /** Move a ticket into a lane: the queue pickup says it before the
+     *  worker starts, an ending moves the ticket where the lane order put
+     *  it. The orchestrator's decision; the tracker performs it. */
+    moveTo(projectId: string, ticketId: string, lane: string): Promise<void>;
+    /** Which lane the ticket sits in **right now**, by name; undefined when it
+     *  is gone from this board — deleted, or on a team the project does not
+     *  map. The orchestrator's validity check before an ending move (ruled
+     *  2026-10-02): a person may have moved the ticket out from under a live
+     *  run while a webhook was missed; their move wins, and the owed move is
+     *  spent rather than undone. */
+    ticketLane(projectId: string, ticketId: string): Promise<string | undefined>;
+    /** The **ticket desk**: a worker's hand on the ticket itself, with no
+     *  conversation to speak through. The host claims the `aivi_ticket_*` ids
+     *  exactly once and routes every call to the desk of the tracker that works
+     *  the calling run's ticket — so several trackers can run in one home and a
+     *  worker never names a ticket. Required of every tracker: the desk is
+     *  ticket work, and a tracker that cannot do ticket work is not a tracker.
+     *  Each method receives the run, never a bare id: the ticket is the run's,
+     *  and the ground truth of who may touch it is the ledger's. */
+    desk: TicketDesk;
+    /** The dispatcher's slot is in hand and the run is claimed: open the
+     *  ticket to work on the platform and answer with the **work entry**:
+     *  the summary the worker is started with, and the **branch the ticket
+     *  works on** when the platform names one (Linear's `Issue.branchName`).
+     *  A lane that writes gets its worktree on that branch, and the
+     *  orchestrator never invents a name — a worktree lane whose tracker
+     *  answers without one fails the run visibly. Linear's delegate
+     *  mutation creates the agent session and its answer serves as the
+     *  summary; the tracker stores the pair and may already post a first
+     *  word ("preparing the workspace"). Failure fails the run — visibly,
+     *  and the slot goes back. AWAITED. */
+    initWork(run: RunView): Promise<WorkEntry>;
+    /** The worker's session exists and its work environment is ready:
+     *  where a tracker attaches the run to the pair it opened at
+     *  `initWork`. A render. */
+    ready(run: RunView): void | Promise<void>;
+    /** The task went into the session and work is turning. Optional: a
+     *  platform whose session already shows life (Linear watches its own
+     *  agent sessions) says nothing here. */
+    startWork?(run: RunView): void | Promise<void>;
+    /** The worker asked a person a question and parked. **Required of
+     *  every tracker**: the OpenCode form is the durable record of the
+     *  wait, but only the tracker knows what a question looks like on its
+     *  platform. A render. */
+    question(run: RunView, question: RunQuestion): void | Promise<void>;
+    /** The worker's working plan, whole as it stands. Optional: a platform
+     *  without a plan surface drops it. A render. */
+    plan?(run: RunView, plan: RunPlan): void | Promise<void>;
+    /** The run ended: say so where people read — the closing words in the
+     *  shape the platform gives endings (Linear responds its agent
+     *  session, which ends it). The move to the next lane is the
+     *  orchestrator's and happens after this returns; the lease returns
+     *  last. A permanent failure here does not hold the ticket: the
+     *  ending failed is said and the person is asked for help (a tracker
+     *  marks its ticket for a human, in its platform's words), while the
+     *  closing stays owed to the tracker's own retries. AWAITED. */
+    endWork(run: RunView): Promise<void>;
+}
+/** One workflow state of a team, as the platform holds it. `type` is the
+ *  platform's own flavor word — Linear's `completed`/`canceled` are finished
+ *  work; the machinery asks the adapter what a finished state means and
+ *  never compares raw words of one platform. */
+export interface TrackerState {
+    id: string;
+    name: string;
+    type: string;
+}
+/** A ticket, in the neutral shape the machinery reads. Every field exists
+ *  because the routing decisions read it; `state` is the ticket's current
+ *  lane, `teamId` is what routes a ticket to a project. */
+export interface TrackerIssue {
+    id: string;
+    /** The human-facing id (`ENG-1`): what people read and comments quote. */
+    identifier: string;
+    title: string;
+    description: string | null;
+    /** The branch the platform suggests for this ticket; empty when it has no opinion. */
+    branchName: string;
+    url: string;
+    state: TrackerState;
+    teamId: string;
+    labels: {
+        id: string;
+        name: string;
+    }[];
+    /** Whose user id the ticket is delegated to; null when nobody's. */
+    delegateId: string | null;
+    assignee: {
+        id: string;
+        name: string;
+    } | null;
+    /** True once the platform has deleted the ticket as far as work goes;
+     *  a dead ticket gets nothing from aivi. */
+    archived: boolean;
+    /** Whether the ticket has finished as far as work goes — the adapter's
+     *  **verdict**, not a platform word: each tracker decides which of its
+     *  states mean closed (Linear's `completed` and `canceled` both do), and the
+     *  decision code never sees the words. */
+    completed: boolean;
+    /** The tickets blocking this one, each with the same verdict: a blocker
+     *  that has finished holds nothing back. */
+    blockedBy: {
+        id: string;
+        completed: boolean;
+    }[];
+}
+/** What changed on a ticket, in neutral words: only the things routing
+ *  keys on. `archive` is the platform's word for *deleted* — the ticket is
+ *  gone as work, which stops whatever still works it. Anything else a
+ *  platform reports is the adapter's to notice and drop. */
+export type TrackerChange = 'state' | 'labels' | 'delegate' | 'archive';
+/** One comment on a ticket, read back by the ticket-desk tools: who wrote
+ *  it (null when the platform hides the author), the text, and the moment
+ *  in the platform's own timestamp. */
+export interface TrackerComment {
+    author: string | null;
+    body: string;
+    at: string;
+}
+/** The ticket desk: the effective tool ids of a worker's hand on the ticket
+ *  itself. Named once here because three packages must speak the same words
+ *  without one importing another's world: a tracker module **claims** these
+ *  ids, `aivi setup` seeds a single `aivi_ticket_*` wildcard **deny** (the
+ *  CLI treats modules as opaque and imports nothing from them), and the
+ *  agent file that works tickets **allows** them by the same wildcard.
+ *  Tests hold the claims and the wildcard against this list — the prefix is
+ *  part of the contract, or the seeded deny stops covering a renamed id. */
+export declare const TICKET_TOOL_ACTIONS: readonly ['aivi_ticket_read', 'aivi_ticket_comments', 'aivi_ticket_labels', 'aivi_ticket_edit', 'aivi_ticket_comment', 'aivi_ticket_create', 'aivi_ticket_add_label', 'aivi_ticket_remove_label'];
+export type TicketToolAction = (typeof TICKET_TOOL_ACTIONS)[number];
+/**
+ * The ticket desk in the tracker's own words: what each `aivi_ticket_*` tool
+ * does to the ticket its run works. The host owns the tools — one claim of
+ * each id, the argument checks, and the guard that the call comes from a live
+ * run of this tracker — because that is run domain. What a ticket is on the
+ * platform is tracker domain: which conversation a plain comment lands on,
+ * which team a new ticket is born in, what "the label the team knows" means.
+ * Every method receives the run, whose `ticketId` is the only ticket it may
+ * touch; the answer shapes are what the worker reads, and they are the same
+ * on every platform.
+ */
+export interface TicketDesk {
+    /** Read the ticket: the words a worker starts from, as they now stand. */
+    read(run: RunView): Promise<{
+        identifier: string;
+        title: string;
+        description: string | null;
+        lane: string;
+        labels: string[];
+        url: string;
+    }>;
+    /** The comment trail, oldest first. */
+    comments(run: RunView): Promise<TrackerComment[]>;
+    /** The team's label catalogue and what stands on the ticket now. */
+    labels(run: RunView): Promise<{
+        team: string[];
+        on: string[];
+    }>;
+    /** Rewrite the ticket's own words; only what is named is touched. */
+    edit(run: RunView, changes: {
+        title?: string;
+        description?: string;
+    }): Promise<{
+        identifier: string;
+        title: string;
+        url: string;
+    }>;
+    /** A plain comment on the ticket, as aivi's own — what a person typed
+     *  lands as what a person reads. */
+    comment(run: RunView, text: string): Promise<void>;
+    /** Open a new ticket — the escape hatch for work this ticket should not
+     *  carry. Where it lands is the tracker's config, never the caller's word. */
+    create(run: RunView, input: {
+        title: string;
+        description: string;
+    }): Promise<{
+        identifier: string;
+        url: string;
+        lane: string;
+    }>;
+    /** Put one label on the ticket (`on`) or take it off. */
+    label(run: RunView, label: string, on: boolean): Promise<void>;
+}
+/**
+ * The normalized signals everything downstream keys off — never raw
+ * webhooks. `started` is a working session opened on a ticket (a
+ * delegation, a mention, whatever brought it); `prompted` is a message
+ * inside one, or a signal like a stop; `updated` is a ticket change with
+ * `changed` already narrowed to the routing-relevant parts.
+ */
+export type TrackerEvent = {
+    kind: 'started';
+    conversation: string;
+    issueId: string;
+    promptContext?: string;
+} | {
+    kind: 'prompted';
+    id: string;
+    conversation: string;
+    body?: string;
+    signal?: string | null;
+} | {
+    kind: 'updated';
+    conversation: string;
+    issueId: string;
+    changed: TrackerChange[];
+};
+/** How a message reads, in platform-neutral words; the adapter picks the
+ *  platform's own rendering (Linear maps these to agent-session activity
+ *  types). Adapters keep the distinction honest: a `progress` line is gone
+ *  when the work ends, an `answer` or `outcome` stays. */
+export type TrackerCommentKind = 
+/** A reply to what someone asked — the platform shows it as an answer. */
+'answer'
+/** An ephemeral line while work runs; replaced as work moves. */
+ | 'progress'
+/** A durable line about work in flight. */
+ | 'note'
+/** A terminal outcome: finished, stopped, or refused. */
+ | 'outcome';
+/** What the machinery asks of the platform, in neutral words. The adapter
+ *  translates and performs; *when* to act stays the machinery's decision. */
+export type TrackerUpdate = 
+/** Move the ticket to the named lane. */
+{
+    kind: 'move';
+    lane: string;
+}
+/** Add or remove one label. */
+ | {
+    kind: 'label';
+    label: string;
+    on: boolean;
+}
+/** Leave a visible comment on the ticket itself. */
+ | {
+    kind: 'comment';
+    text: string;
+};
+/** One moment of a worker's progress, in neutral words: the human-readable
+ *  status line as already rendered, and the tool the worker is running when
+ *  there is one. Rendered by the machinery (the same reducer a chat progress
+ *  placeholder reads), delivered the platform's way. */
+export interface TrackerProgressLine {
+    /** The status as text: "🔧 reading src/x.ts", "⏳ thinking…". */
+    text: string;
+    /** The running tool, when there is one and the platform shows tools. */
+    tool?: {
+        name: string;
+        detail?: string;
+    };
+}
+/**
+ * The tracker's **platform**: the ticket system behind a tracker module —
+ * Linear, Jira, GitHub Issues — seen as the conversation-keyed translator it
+ * is. A tracker owns tickets — lanes, delegation, what people write on them;
+ * the platform speaks its platform's voice: it turns the platform's events
+ * into the neutral ones above, aivi's neutral updates into the platform's
+ * mutations, and it is **required** to render a worker's question and a run's
+ * outcome the way its platform shows them (`ask`, and the answer/outcome
+ * kinds of `comment`) — the host's orchestrator owns the run itself: its
+ * durable record, its session, the two worker tools and the rule that only a
+ * tool call ends it. Channels use platforms, forges use platforms, and this
+ * is the same word for the same thing: the system aivi talks to over an API.
+ *
+ * The machinery consuming this ships in the host. The exact member set is
+ * **provisional by design**: roughly seven trackers will move it, and every
+ * entry earns its place with a second tracker's need.
+ */
+export interface Platform {
+    /** The module id this tracker speaks for (`tracker-linear`). */
+    readonly id: string;
+    /** The team's workflow states as the platform holds them, so a proposed
+     *  lane mapping can be validated against what exists. */
+    laneStates(conversation: string, teamId: string): Promise<TrackerState[]>;
+    /** Create the named states the mapping needs and none platform policy
+     *  refuses, returning the ones made. Opt-in with an explicit yes per
+     *  team, never silent. Absent means the tracker cannot create states. */
+    createStates?(conversation: string, teamId: string, missing: string[]): Promise<TrackerState[]>;
+    /** Ready issues in a lane, in the platform's own order, each with the
+     *  facts needed to build a worker's first message. Absent until a
+     *  pull-shaped tracker needs it. */
+    candidates?(conversation: string, lane: string): Promise<TrackerIssue[]>;
+    /** Apply one neutral outcome to a ticket (a lane move, one label, a plain
+     *  comment). Required: the machinery's asks all speak through it. */
+    apply(conversation: string, issueId: string, update: TrackerUpdate): Promise<void>;
+    /** The ticket, fresh from the platform — the only routing input, never
+     *  trusted from an event's own words. Delivered in the neutral shape;
+     *  the adapter's translation is where platform fields stop existing. */
+    issue(conversation: string, issueId: string): Promise<TrackerIssue>;
+    /** Make (with `null`: unmake) aivi the ticket's delegate — the neutral
+     *  word for whoever the platform names to work it. */
+    assign(conversation: string, issueId: string, userId: string): Promise<void>;
+    unassign(conversation: string, issueId: string): Promise<void>;
+    /** Open a working session on the ticket under aivi's own identity,
+     *  returning its conversation id; null when the platform made none.
+     *  Some platforms create the session as a side effect of `assign`;
+     *  hiding that is exactly the adapter's job. */
+    startSession(conversation: string, issueId: string): Promise<string | null>;
+    /** The conversation id for a session the platform names, in the
+     *  adapter's namespacing; what the store binds. */
+    idFor(sessionId: string): string;
+    /** The other direction, for what is named *from* a conversation: the
+     *  configured app within aivi that speaks it, and the platform's own
+     *  session id inside it (a worker's worktree is named from that). The
+     *  conversation string itself is the adapter's business, never parsed
+     *  by the machinery. */
+    parts(conversation: string): {
+        app: string;
+        session: string;
+    };
+    /** The workspace (organization) the conversation's app speaks in; what
+     *  routes a ticket to a project besides the team. */
+    orgOf(conversation: string): Promise<string>;
+    /** Whose user id aivi is in the conversation's workspace — the delegate
+     *  id `assign` and `startSession` use, and what a "delegate changed"
+     *  check compares against. */
+    ownerOf(conversation: string): string;
+    /** One message into the conversation, rendered the platform's way; the
+     *  platform's message id when it names them (the engine may edit by it). */
+    comment(conversation: string, text: string, kind: TrackerCommentKind): Promise<string | undefined>;
+    /**
+     * Show what a worker is doing **right now**, replacing whatever was shown
+     * before (ruled 2026-10-02: thoughts and actions, ephemeral — a working
+     * run says what it does without ever spamming the ticket). **Transient by
+     *  contract**: a replaced line must not linger as a permanent record.
+     *  Linear posts an ephemeral `action` activity when a tool runs and an
+     *  ephemeral `thought` otherwise. Absent means the platform has no
+     *  progress surface and hears nothing: a worker there works in silence,
+     *  and the follower never calls it.
+     */
+    progress?(conversation: string, line: TrackerProgressLine): Promise<void>;
+    /**
+     * A plain notice on the ticket **itself**, for a run that died before it
+     * had a conversation to speak through (ruled 2026-10-02 after seven silent
+     * early failures): silence is not an answer, and the ticket is the only
+     * board a person reads. The `conversation` is the app's own feed — there
+     * is no session yet.
+     */
+    notify(conversation: string, issueId: string, text: string): Promise<void>;
+    /** Whether this working session has already had its result rendered —
+     *  the follower's idempotence question, decided the platform's own way
+     *  (Linear: the agent session is ended; another: a result comment exists).
+     *  A catch-up that would say it twice says it once. */
+    resultShown(conversation: string): Promise<boolean>;
+    /** A closing note on the **ticket itself**, so an ending is readable
+     *  without opening the agent session (ruled 2026-10-02: the answer was
+     *  only visible inside the session — "hard to get to now"). Optional: a
+     *  platform with nothing standing outside the session posts no extra note
+     *  and loses nothing. **Idempotence is the adapter's** — the follower
+     *  retries this on every wake and boot like the rest of the ceremony, so
+     *  a note already standing must never be posted twice. */
+    closingNote?(conversation: string, issueId: string, text: string): Promise<void>;
+    /**
+     * Put a worker's question to the people, in the platform's own shape —
+     * the same `RunQuestion` the orchestrator recorded, rendered here.
+     * **Required of every tracker** (ruled 2026-09-30): the orchestrator
+     * records the question and does nothing else with it — only the adapter
+     * knows what a question looks like on its platform (Linear renders an
+     * elicitation activity, with its `select` signal when there are options;
+     * GitHub Issues would post a numbered comment). The answer arrives as an
+     * ordinary message event; the open OpenCode form is the discriminator,
+     * read from OpenCode, never a guess from texts.
+     */
+    ask(conversation: string, question: RunQuestion): Promise<void>;
+    /**
+     * Show the worker's working plan — the whole checklist, as it now stands.
+     * A forwarding like the orchestrator's own: the tracker renders it in its
+     * platform's shape (Linear replaces the session's agent plan wholesale)
+     * and nothing about a run waits on its delivery.
+     */
+    plan(conversation: string, plan: RunPlan): Promise<void>;
+    /**
+     * The ticket desk — what `aivi_ticket_*` tools do to tickets **directly**,
+     * with no agent session to speak through (the `conversation` is the app's
+     * own feed, as in `notify`). **Required as a set** (ruled 2026-10-07): the
+     * host claims the desk ids once for the whole home and routes each call to
+     * the tracker that works the run's ticket, so a tracker that skipped its
+     * desk would fail its own workers rather than nobody's. All of it is the
+     * **worker's hand on the ticket**, gated by OpenCode permissions (denied by
+     * default, allowed per agent); nothing here decides who may call.
+     */
+    ticketComments(conversation: string, issueId: string): Promise<TrackerComment[]>;
+    /** A plain comment on the ticket, as the app's own — no activity type,
+     *  no marker: what a person typed lands as what a person reads. */
+    addComment(conversation: string, issueId: string, text: string): Promise<void>;
+    /** Rewrite the ticket's own words: title and/or description. Returns the
+     *  ticket as it now stands, so the caller reports the truth it wrote. */
+    editIssue(conversation: string, issueId: string, changes: {
+        title?: string;
+        description?: string;
+    }): Promise<TrackerIssue>;
+    /** Open a new ticket in the named team, landing it in `lane` when a lane
+     *  is named (the adapter resolves the name against the team's states and
+     *  says so when none matches). */
+    createIssue(conversation: string, input: {
+        teamId: string;
+        title: string;
+        description?: string;
+        lane?: string;
+    }): Promise<TrackerIssue>;
+    /** The team's label catalogue — every name the team knows, so a worker
+     *  can pick honestly instead of guessing. */
+    teamLabels(conversation: string, teamId: string): Promise<string[]>;
+    /** Subscribe to the normalized events. The adapter owns the platform's
+     *  whole inbound surface — endpoints, signatures, acknowledgements;
+     *  registration happens at module start. Returns the unsubscribe. */
+    events(sink: (event: TrackerEvent) => Promise<void>): () => void;
+}

package/dist/tracker.js

@@ -0,0 +1,38 @@
+/**
+ * The **tracker** contract, in the two seams a tracker module lives between.
+ *
+ * `Tracker` is the seam between the host's orchestrator and the module: the
+ * **stages** a run is walked through, keyed by the run. The orchestrator
+ * walks them in order and awaits only the lifecycle ones; it never learns
+ * what a ticket platform is. `Platform` is the seam between the module and
+ * its ticket platform: the conversation-keyed translator that turns the
+ * platform's events into neutral ones and aivi's neutral updates into the
+ * platform's mutations. A module registers one `Tracker` with the
+ * orchestrator and speaks its `Platform` to whomever on its platform; the
+ * stages that render are usually one-line forwards — the division is honest,
+ * not duplicated.
+ *
+ * The words here are platform-neutral by design: roughly seven trackers will
+ * move this contract, and every entry earns its place with a second
+ * tracker's need. The run shapes the stages carry are the shared run domain
+ * (`./run.ts`); the ticket shapes here are what the tracker reports and the
+ * orchestrator routes.
+ */
+/** The ticket desk: the effective tool ids of a worker's hand on the ticket
+ *  itself. Named once here because three packages must speak the same words
+ *  without one importing another's world: a tracker module **claims** these
+ *  ids, `aivi setup` seeds a single `aivi_ticket_*` wildcard **deny** (the
+ *  CLI treats modules as opaque and imports nothing from them), and the
+ *  agent file that works tickets **allows** them by the same wildcard.
+ *  Tests hold the claims and the wildcard against this list — the prefix is
+ *  part of the contract, or the seeded deny stops covering a renamed id. */
+export const TICKET_TOOL_ACTIONS = [
+    'aivi_ticket_read',
+    'aivi_ticket_comments',
+    'aivi_ticket_labels',
+    'aivi_ticket_edit',
+    'aivi_ticket_comment',
+    'aivi_ticket_create',
+    'aivi_ticket_add_label',
+    'aivi_ticket_remove_label',
+];

package/dist/voice.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The voice contract: hearing as a capability. The voice plugin provides the
+ * one adapter (models, diarizer, person memory, wake, transcripts); modules
+ * that stand in a room — discord today, meet/teams/zoom tomorrow — open a
+ * `VoiceRoom` and feed it audio. When no adapter was provided, opening a
+ * room fails with `VoiceNotLoaded`: the plugin is optional, the failure is
+ * honest, and no ordering ceremony hides which module is missing.
+ *
+ * Who the speakers are is the room's business, not the contract's: a
+ * platform that names its speakers (Discord) says so per utterance; a room
+ * that only has mixed audio (a browser tab, a meeting bridge) pushes raw
+ * PCM and the adapter does ASR, diarization and person identification from
+ * the audio alone — when a diarizer is configured. Without one the cuts
+ * come from loudness and the lines carry no name: a guessed name would
+ * invent people (ruled 2026-10-14).
+ */
+/** No voice plugin, no hearing. The fix belongs in the message. */
+export declare class VoiceNotLoaded extends Error {
+    constructor();
+}
+export interface RoomOptions {
+    /** Platform the room is on (`discord`, `meet`): the origin on
+     *  everything it produces, never the package that speaks for it. */
+    id: string;
+    /** What this room is, for the transcript's source line. */
+    label: string;
+    /** True when the room will push raw mixed audio through `feed` and let
+     *  voice do everything — segmentation, speaker separation, person
+     *  identification. Rooms whose platform already demuxes named speakers
+     *  (Discord, through `lane()`) leave it out: mixed events are another
+     *  room's business. */
+    streaming?: boolean;
+    /** What this room IS: `call` (default — the conversation, not a record:
+     *  closed speech prompts aivi, barge-in lives here) or `meeting` (lines
+     *  append; the wake phrase activates, nothing else does). The module that
+     *  opens the room declares it (ruled 2026-10-13: mode belongs to the
+     *  room, not to the voice block; call is the default because the plain
+     *  voice system for a normal session is the common case — and loads the
+     *  least). */
+    mode?: 'call' | 'meeting';
+    /** The quiet after which the room's next exchange gets a FRESH OpenCode
+     *  session instead of the resumed one (0: fresh every join; false: the
+     *  same session forever). Absent: the voice block's `resumeMinutes` —
+     *  the global window. A meeting room may want a shorter memory than a
+     *  Discord channel (a call is a call: the next one starts clean). */
+    resumeMinutes?: number | false;
+    /** Dispatcher pool this room's sessions draw capacity from — a name in
+     *  `dispatcher.pools`. Absent: the voice block's `pool`. Openers keep
+     *  their categories apart this way: meeting rooms on a big local model,
+     *  calls on a snappy one, each with its own seats (operator, 2026-10-15:
+     *  voice capacity is per category, like LLM endpoints). */
+    pool?: string;
+    /** The OpenCode agent the room's sessions run as. The opener names it —
+     *  a channel's own agent is the natural filling (a Discord room speaks as
+     *  the Discord agent unless told otherwise); absent: `assistant`. */
+    agent?: string;
+}
+/** One finished piece of speech. `speaker` is the platform's own answer —
+ *  when it has none, leave it out and the adapter identifies from audio. */
+export interface Utterance {
+    speaker?: string;
+    /** Platform user id, kept with the line when the platform has one. */
+    user?: string;
+    /** Platform channel/room id, kept with the line when it varies per line. */
+    channel?: string;
+    /** This speaker is a known person of aivi (a linked account), not a bot or
+     *  a stranger: only their words may interrupt a live answer (barge-in). */
+    person?: boolean;
+    /** 16 kHz mono float PCM. */
+    pcm: Float32Array;
+}
+/** A named speaker's LIVE lane: their audio streams in while they speak and
+ *  words come back out as they are heard — the platform (Discord) already
+ *  demuxes speakers, so the adapter streams ASR without diarizing. One lane
+ *  is one utterance. */
+export interface VoiceLane {
+    /** Live 16 kHz mono float PCM, in real time, as the platform's packets land. */
+    push(pcm: Float32Array): void;
+    /** The utterance is over (the platform's own silence rule closed it):
+     *  flush the tail, then the line is committed with the streamed text —
+     *  or, if no live lane ever came up, batch-transcribed from the buffered
+     *  audio. Resolves with the text, or null when the utterance was lost. */
+    end(): Promise<string | null>;
+    /** Throw the utterance away (too short to be speech): no line, the live
+     *  lane is closed unheard. */
+    abort(): void;
+}
+/** A handle on one room. Audio goes in; lines, events and aivi's spoken
+ *  replies come out. Everything the handle does that needs a model either
+ *  works or says so in the log — a lost utterance is a logged loss. */
+export interface VoiceRoom {
+    /** Streaming room audio: s16le 16 kHz mono chunks, real time, anonymous.
+     *  The adapter streams ASR, identifies, scans for the wake phrase and
+     *  appends transcript lines. Diarizes only in meeting mode — call mode
+     *  reads voice activity off the waveform. Fire-and-forget by nature. */
+    feed(pcm: Buffer): void;
+    /** Open a live lane for one named speaker's utterance. In a call room the
+     *  first recognized WORD from a linked person is the interruption
+     *  (barge-in) — not the speaking start, which carries no content. */
+    lane(init: {
+        speaker: string;
+        user: string;
+        person?: boolean;
+        channel?: string;
+    }): VoiceLane;
+    /** A finished utterance a platform already segmented and named (platforms
+     *  that get a live stream per speaker use `lane()` instead): transcribe
+     *  it, append the line under that speaker. Resolves with the text, or null
+     *  when the utterance was lost. */
+    heard(utt: Utterance): Promise<string | null>;
+    /** Be the room's mouth: called with a wav whenever aivi's answer should be
+     *  spoken there (the room's microphone *is* this audio) — once per audio
+     *  chunk, in order; a sentence spoken while it synthesizes lands as
+     *  several wavs. Return false when nothing played. A mouth that queues
+     *  the audio returns a promise that settles when THIS wav is done with —
+     *  played, dropped by a barge, or failed: the room holds the answer's
+     *  speaking window open until every chunk settles, and interrupting words
+     *  are verified against that window. Resolving at enqueue means aivi
+     *  talks through the interruption unheard. `stop` (optional) silences the
+     *  mouth NOW — barge-in calls it: the playing answer stops mid-sentence,
+     *  nothing new starts (and every queued promise settles). `flush`
+     *  (optional) says the answer is over — the room calls it once the last
+     *  chunk has been handed over (never on the barge path, where `stop`
+     *  already closed everything): a mouth playing one continuous stream per
+     *  answer ends its stream here so the player drains back to Idle. Returns
+     *  the unregister. */
+    mouth(play: (wav: Buffer) => boolean | Promise<boolean>, stop?: () => void, flush?: () => void): () => void;
+    /** Stop talking and listen (the conversation interrupting): silence the
+     *  playing answer and drop the answers still queued to be spoken. The
+     *  interrupting speech arrives as speech and is heard like any other —
+     *  call rooms put it to the session, which gets to reconsider. Meeting
+     *  rooms are polite: this does nothing there. */
+    bargeIn(): void;
+    /** Watch what the room produces for display: fusion events
+     *  (`{ev:"delta"…}`, `{ev:"line"…}`, `{ev:"session_reset"…}`). */
+    onEvent(listener: (event: Record<string, unknown>) => void): () => void;
+    stop(): Promise<void>;
+}
+/** What the voice plugin provides at start — exactly one, host-wide. */
+export interface VoiceAdapter {
+    room(options: RoomOptions): VoiceRoom;
+}
+/** The service on `AiviServices`: the provider speaks once, every room
+ *  holder asks the same question — is there an adapter, and if so open one. */
+export interface Voice {
+    provide(adapter: VoiceAdapter): () => void;
+    room(options: RoomOptions): VoiceRoom;
+}