@aivi/plugin 0.0.0-stage → 0.1.0

package/dist/forge.d.ts

@@ -0,0 +1,243 @@
+/**
+ * The **forge** contract: the seam between aivi and a repository host. A
+ * forge owns the *remote*: the repository a project's checkout came from, the
+ * pull requests over its branches, the review conversation on them, and the
+ * credential that lets aivi move bytes as its own app.
+ *
+ * The line between a forge and aivi is **remote, not git** (ruled
+ * 2026-09-29): any git operation that reaches `origin` authenticates to it,
+ * so it belongs to the forge — clone, fetch, the sync of a clean checkout,
+ * push. What only touches the local store is aivi's own machinery (the
+ * orchestrator creates and reaps worktrees, the worker commits in one) and
+ * never appears here. A forge uses its API for what git cannot see: pull
+ * requests and reviews.
+ *
+ * Types only — the machinery consuming them ships in the host. The exact
+ * member set is **provisional by design**
+ * ([forge-github.md](../../docs/plans/forge-github.md)): the orchestrator's
+ * wiring is what proves it, and more forges will move the details.
+ *
+ * A project **having no forge is not a failure** (ruled 2026-09-29): a ticket
+ * can be "research X, write it up" and complete without aivi ever asking a
+ * repository host anything. Nothing here may assume a worker touches a remote.
+ *
+ * Cloning is a forge's operation too, but it is not on this interface: it
+ * happens once, at project setup, through the plugin's `./setupProject`
+ * contributor ([setup-project.ts](setup-project.ts)), which is where a person
+ * is asked which repository they mean. By the time a `Forge` is speaking to
+ * aivi the checkout already exists.
+ */
+/** What a forge needs to know about a project to recognise it: the directory
+ *  aivi discovered the checkout in. Reading `origin` from it is a local git
+ *  read — reaching `origin` is the forge's own business, below. */
+export interface ForgeProject {
+    id: string;
+    directory: string;
+}
+/** One repository of this forge, in the forge's own terms. Opaque to aivi:
+ *  it is handed back to every other call and never inspected. */
+export interface RepoRef {
+    /** The forge's name for it (`owner/repo`); what logs and errors say. */
+    id: string;
+    /** The remote URL aivi would use to reach it — the forge's own to
+     *  authenticate; nothing outside the forge puts a credential in it. */
+    remote: string;
+}
+/** A pull request over a branch: the fact a tracker may also report from its
+ *  own knowledge, and the forge answers when it cannot. */
+export interface PrFacts {
+    /** The forge's id for the pull request; what `resolveThread` and friends
+     *  are called with. */
+    id: string;
+    url: string;
+    title: string;
+    /** The platform's own state word (`open`, `merged`, `closed`). */
+    state: string;
+    /** The branch it stands for — the one thing aivi correlates on. */
+    branch: string;
+    /** Whether the base branch could take this merge today, so "main moved,
+     *  you conflict" is in the worker's first prompt instead of a surprise at
+     *  push time. `unknown` is the honest answer where the platform has not
+     *  computed it (a REST list read never says); a forge that cannot say
+     *  leaves it absent rather than guessing clean. */
+    mergeable?: 'clean' | 'dirty' | 'unknown';
+}
+/** Who wrote a review comment. Aivi's own posts are *signed* — visibly, in
+ *  text a human reads — and the forge parses that signature back into
+ *  `worker`, so a wake can tell its own past comments from a human's. */
+export interface ReviewAuthor {
+    /** The platform's login (`octocat`, `aivi-agent[bot]`). */
+    login: string;
+    /** The worker role aivi posted as, read back out of the comment's own
+     *  signature; absent for a human and for anything aivi did not write. */
+    worker?: string;
+    /** True when the platform says the author is an app or bot. */
+    bot: boolean;
+}
+/** One review thread. Only **open threads** are ever handed to a worker
+ *  (ruled 2026-09-29): there is no `since` cursor, a wake takes what is open
+ *  and the worker must bring all of it to zero — by agree (commit, then the
+ *  forge pushes on the orchestrator's word) or by decline (comment and
+ *  resolve). */
+export interface ReviewThread {
+    /** The forge's id for the thread; what `resolveThread` is called with. */
+    id: string;
+    /** The file the thread speaks to, when it is anchored to one. */
+    path?: string;
+    /** The platform's own state word (`open`, `resolved`, `outdated`). */
+    state: string;
+    /** The thread's opening body — what the worker is being asked. */
+    question: string;
+    /** Everything said since, oldest first, each with its author. */
+    replies: {
+        author: ReviewAuthor;
+        body: string;
+    }[];
+}
+/** What a worker wake gathers about a pull request: the state of the review
+ *  in neutral terms, and the open threads it must answer. */
+export interface ReviewFacts {
+    pr: PrFacts;
+    /** Approvals in the platform's own words (`APPROVED`, `CHANGES_REQUESTED`). */
+    reviews: {
+        author: ReviewAuthor;
+        state: string;
+    }[];
+    /** The threads a worker still owes an answer on. Empty means a clean
+     *  review: nothing to resolve, nothing to reply to. */
+    threads: ReviewThread[];
+    /** The pull request's plain conversation comments — not review threads,
+     *  and the platform gives them **no resolved state**, so they are
+     *  context, never gate items (ruled 2026-10-02). Oldest first, capped
+     *  like the thread reads; the agent file's guidance says to answer them. */
+    comments: {
+        author: ReviewAuthor;
+        body: string;
+        createdAt: string;
+    }[];
+}
+/** What a forge answers and does. Everything here is either a **fact aivi
+ *  cannot compute from a clone** or a **remote operation only the forge may
+ *  authenticate for**. */
+export interface Forge {
+    /** The forge's name for the repository a project's `origin` names, or
+     *  undefined when the remote is not this forge's — another forge's turn,
+     *  or no forge at all. */
+    repoFor(project: ForgeProject): Promise<RepoRef | undefined>;
+    /** The pull request over a branch, if one exists. A tracker may answer
+     *  this from its own knowledge; the forge is the fallback that can say. */
+    prForBranch(repo: RepoRef, branch: string): Promise<PrFacts | undefined>;
+    /** The review conversation: the open threads and the state of the
+     *  approvals, gathered for a worker about to wake. */
+    reviewFeedback(repo: RepoRef, pr: PrFacts): Promise<ReviewFacts>;
+    /** Answer one open thread as aivi and resolve it. The orchestrator calls
+     *  this with the message from a validated resolution report; the worker
+     *  never holds forge credentials to write review traffic, and the comment
+     *  says which worker role it came from — visibly. */
+    resolveThread(repo: RepoRef, pr: PrFacts, threadId: string, reply: {
+        author: string;
+        text: string;
+    }): Promise<void>;
+    /** Post a plain conversation comment on the pull request — the non-thread
+     *  channel a worker uses to say something grounded when there is no
+     *  thread to answer. Signed like every aivi post. */
+    commentPr(repo: RepoRef, pr: PrFacts, comment: {
+        author: string;
+        text: string;
+    }): Promise<void>;
+    /** Say *on the pull request itself* what aivi's review found: a review
+     *  with inline findings, which the platform shows as review threads — the
+     *  only way agent feedback becomes gate-owed on the next round. APPROVE
+     *  is not offered: the app authored the pull request and GitHub refuses an
+     *  author's own approval, so the approve button stays human forever
+     *  (ruled 2026-10-02). */
+    submitReview(repo: RepoRef, pr: PrFacts, review: {
+        author: string;
+        body: string;
+        state: 'COMMENT' | 'REQUEST_CHANGES';
+        comments?: {
+            path: string;
+            line?: number;
+            body: string;
+        }[];
+    }): Promise<void>;
+    /** Bring a project's clean checkout up to date with `origin`: fetch, then
+     *  fast-forward the checked-out branch. Anything needing a decision (local
+     *  changes, a detached head, diverged history) is reported, never forced —
+     *  the checkout aivi indexes is not a working directory. */
+    syncSource(repo: RepoRef, directory: string): Promise<ForgeSync>;
+    /** Carry one branch's remote tip into the checkout's own remote refs
+     *  (`refs/remotes/origin/<branch>`) so the orchestrator can start a
+     *  worktree from it **without ever touching the remote itself** — every
+     *  external boundary is crossed by using the forge (ruled 2026-10-02),
+     *  and what aivi does with the ref afterwards is local git. A remote
+     *  without that branch — a ticket branch never pushed — says so, and
+     *  that is an answer, not a failure: it returns quietly. A transfer that
+     *  failed throws, because the caller cannot tell a stale tip from an
+     *  absent one. */
+    fetchBranch(repo: RepoRef, directory: string, branch: string): Promise<void>;
+    /** Move aivi's own commits to `origin`, as the app and never as the
+     *  person at the keyboard. The orchestrator's smart push decides *how*:
+     *  plain when the remote fast-forwards (or the branch is new), and with
+     *  `lease` — the commit it just fetched as the branch's tip — when the
+     *  divergence is only the worker's own rewrite, so the force replaces
+     *  exactly what the worker rebased over and nothing a person added
+     *  since. How the forge authenticates — mint once, cache to its TTL,
+     *  re-mint on a 401 — is the forge's own choice and never written into
+     *  the worktree's `.git/config`. A transfer the remote refuses throws
+     *  with git's words; a lease that no longer matches is exactly that. */
+    push(repo: RepoRef, worktree: string, branch: string, options?: {
+        lease?: string;
+    }): Promise<void>;
+    /** Open the pull request that stands for the branch, against the
+     *  repository's own default branch, and say which worker role asked —
+     *  visibly, in the body a human reads. The orchestrator asks only when
+     *  no open pull request stands for the branch (its `prForBranch` said
+     *  so, or the last one closed); opening a second is the platform's to
+     *  refuse, and its refusal is said, not smoothed over. */
+    openPr(repo: RepoRef, branch: string, pr: {
+        author: string;
+        title: string;
+        body: string;
+    }): Promise<PrFacts>;
+    /** Bring **all** the remote's refs into the checkout's own remote refs —
+     *  fetch with prune, refs only, nothing checked out (`aivi_sync`: the
+     *  worker looks before it rebases, and the push's fresh view of every
+     *  branch starts here). A failed transfer throws; there is nothing a
+     *  caller could safely do with a stale view. */
+    fetchRefs(repo: RepoRef, directory: string): Promise<void>;
+}
+/** The outcome of bringing a checkout up to date, in the forge's own words:
+ *  `updated` when it moved, `current` when it already matched, `held` with
+ *  the reason when only a human can decide. */
+export interface ForgeSync {
+    state: 'updated' | 'current' | 'held';
+    from?: string;
+    to?: string;
+    reason?: string;
+}
+/** The registry's answer: the forge that recognised the project's remote,
+ *  and the repository it recognised — handed straight to `syncSource`,
+ *  `push` and friends, never inspected outside the forge. */
+export interface ForgeOwner {
+    forge: Forge;
+    repo: RepoRef;
+}
+/** The host-side forge registry (built 2026-10-02, the first thing with the
+ *  question "who owns this project's remote?" to ask). Forge modules
+ *  register once at module start, the way channels register with the router
+ *  and tools claim on the tool surface; the host's machinery asks.
+ *
+ *  **The answer may be nobody** (ruled 2026-09-29: the forge is a
+ *  configurable path, not the spine): with no forge registered, or a remote
+ *  no registered forge recognises, `owner` answers undefined and the
+ *  machinery does the local-only thing it has always done. Nothing here
+ *  reaches a network: recognising is a read of `origin`, and reaching
+ *  `origin` is what the returned forge authenticates for. */
+export interface Forges {
+    /** Register once at module start; the returned function unregisters. */
+    register(forge: Forge): () => void;
+    /** Who owns this project's remote: the first registered forge whose
+     *  `repoFor` answers with a repository. Undefined when none does. */
+    owner(project: ForgeProject): Promise<ForgeOwner | undefined>;
+}

package/dist/forge.js

@@ -0,0 +1,30 @@
+/**
+ * The **forge** contract: the seam between aivi and a repository host. A
+ * forge owns the *remote*: the repository a project's checkout came from, the
+ * pull requests over its branches, the review conversation on them, and the
+ * credential that lets aivi move bytes as its own app.
+ *
+ * The line between a forge and aivi is **remote, not git** (ruled
+ * 2026-09-29): any git operation that reaches `origin` authenticates to it,
+ * so it belongs to the forge — clone, fetch, the sync of a clean checkout,
+ * push. What only touches the local store is aivi's own machinery (the
+ * orchestrator creates and reaps worktrees, the worker commits in one) and
+ * never appears here. A forge uses its API for what git cannot see: pull
+ * requests and reviews.
+ *
+ * Types only — the machinery consuming them ships in the host. The exact
+ * member set is **provisional by design**
+ * ([forge-github.md](../../docs/plans/forge-github.md)): the orchestrator's
+ * wiring is what proves it, and more forges will move the details.
+ *
+ * A project **having no forge is not a failure** (ruled 2026-09-29): a ticket
+ * can be "research X, write it up" and complete without aivi ever asking a
+ * repository host anything. Nothing here may assume a worker touches a remote.
+ *
+ * Cloning is a forge's operation too, but it is not on this interface: it
+ * happens once, at project setup, through the plugin's `./setupProject`
+ * contributor ([setup-project.ts](setup-project.ts)), which is where a person
+ * is asked which repository they mean. By the time a `Forge` is speaking to
+ * aivi the checkout already exists.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The kit: the contracts aivi is built on, in the package that owns them.
+ * The **run** domain (what a run is), the **tracker** contract (the stages
+ * the orchestrator walks and the platform behind them), the **channel**
+ * contract (conversations on chat platforms), and the **module** contract
+ * (what `runHost` composes and hands a module) are declared here; the host
+ * implements them and imports them from here, and plugin packages import
+ * them from here. One copy, owned by the package everyone already imports.
+ *
+ * This package depends on nothing above it: `@aivi/core` for the shared
+ * facts, `@opencode/client` to name the client plugins receive. The host is
+ * the one that depends on the kit, never the other way — at compile time or
+ * at runtime. Where a contract names a store or a registry, it names an
+ * interface here and the host's class is checked against it.
+ */
+export * from './cli.ts';
+export * from './module.ts';
+export * from './plugin.ts';
+export * from './run.ts';
+export * from './setup.ts';
+export * from './setup-project.ts';
+export * from './tracker.ts';

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * The kit: the contracts aivi is built on, in the package that owns them.
+ * The **run** domain (what a run is), the **tracker** contract (the stages
+ * the orchestrator walks and the platform behind them), the **channel**
+ * contract (conversations on chat platforms), and the **module** contract
+ * (what `runHost` composes and hands a module) are declared here; the host
+ * implements them and imports them from here, and plugin packages import
+ * them from here. One copy, owned by the package everyone already imports.
+ *
+ * This package depends on nothing above it: `@aivi/core` for the shared
+ * facts, `@opencode/client` to name the client plugins receive. The host is
+ * the one that depends on the kit, never the other way — at compile time or
+ * at runtime. Where a contract names a store or a registry, it names an
+ * interface here and the host's class is checked against it.
+ */
+export * from './cli.js';
+export * from './module.js';
+export * from './plugin.js';
+export * from './run.js';
+export * from './setup.js';
+export * from './setup-project.js';
+export * from './tracker.js';

package/dist/module.d.ts

@@ -0,0 +1,306 @@
+/**
+ * The **module contract**: what aivi composes and hands a module at start,
+ * and what the module may do with it. Declared here because both sides
+ * follow it: the host's `runHost` builds the bag and the modules use it; the
+ * host's classes are checked against the interfaces below, so the contract
+ * and the machinery cannot drift apart silently.
+ *
+ * What a module receives is enough to serve and nothing to drive: the run
+ * vocabulary (`./run.ts`) is read-only from here, the tracker stages
+ * (`./tracker.ts`) are what a tracker hands *in*, and the OpenCode client
+ * arrives discovered on every call — a restarted service is picked up by the
+ * next unit of work without restarting aivi.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { AddJobOptions, AuditEntry, Config, ExecutionContext, ExecutionResult, Job, JobEntry, KnowledgeService, LoadedConfig, Logger, Person, PersonToken, Report, RequestLogEntry, Run, RunFilter, RunState, Task, ToolDescriptor } from '@aivi/core';
+import type { OpenCode } from '@opencode/client';
+import type { Channels } from './channel.ts';
+import type { Dispatcher } from './dispatcher.ts';
+import type { Forges } from './forge.ts';
+import type { RunView } from './run.ts';
+import type { Tracker } from './tracker.ts';
+import type { Voice } from './voice.ts';
+/** The OpenCode client a module receives from `services.opencode()`: the
+ *  SDK's own client, named here because this is where plugins meet it. */
+export type OpenCodeClient = ReturnType<typeof OpenCode.make>;
+/** A tool failed with an answer for the agent: this status and message reach the caller. */
+export declare class ToolError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * A module start that no retry can fix: a missing token, an id that does not
+ * match. Modules throw this for what the operator must change; everything else
+ * (a platform answering 503, a network blip) is retried.
+ */
+export declare class ConfigurationError extends Error {
+}
+/** What a module hands back at start: the one thing the host may do to it is stop it. */
+export interface RunningModule {
+    stop(): Promise<void>;
+}
+/** The module a plugin package builds: an id the operator configured, a start, and optional system jobs. */
+export interface AiviModule {
+    /** The module id — the package's short name (`channel-discord`), the same
+     *  word as `plugins.<id>`. It keys the supervisor, shows as the `/status`
+     *  id and owns task claims. Not the channel's platform id: that one is
+     *  `discord` and keys the database, and a module that registers a channel
+     *  carries both on purpose. */
+    id: string;
+    start(services: AiviServices): Promise<RunningModule>;
+    /**
+     * System jobs to seed beside the host's own while this module is composed.
+     * They carry `invocation` tasks for operations the module claims in its
+     * `start`; when the module leaves the composition, its jobs are removed
+     * with it.
+     */
+    jobs?(config: Config): Job[];
+}
+/** Everything the host composes and a module may use. */
+export interface AiviServices {
+    loaded: LoadedConfig;
+    store: Store;
+    knowledge: KnowledgeService;
+    /** Discovers the OpenCode service on every call. Call once per unit of work and hold the client for its duration. */
+    opencode: () => Promise<OpenCodeClient>;
+    /** The host's one OpenCode event stream, fanned out by session id; channel progress watches turns through it. */
+    events: SessionEvents;
+    signal: AbortSignal;
+    log: Logger;
+    /** Chat platform modules register here once; that makes them report destinations and session owners. */
+    channels: Channels;
+    /** Webhook routes a module exposes on the host listener, outside bearer auth; the platform's signature is the auth. */
+    routes: PublicRoutes;
+    /** What `kind: 'invocation'` tasks dispatch to: the host claims its own operations here, modules claim theirs. */
+    tasks: TaskClaims;
+    /** The tool surface the OpenCode plugin registers at load: the host claims its own tools here, modules claim theirs. */
+    tools: ToolClaims;
+    /** The forge registry: a forge module registers its `Forge` once at start;
+     *  the host's machinery asks who owns a project's remote. A project with no
+     *  forge is not a failure — the answer is simply nobody. */
+    forges: Forges;
+    /** The voice seat: the voice module provides its one adapter at start;
+     *  modules standing in a room (discord, meet, …) open `room` handles and
+     *  feed audio. No adapter loaded, no hearing: `room` throws VoiceNotLoaded
+     *  naming the fix — the plugin is optional and the failure is honest. */
+    voice: Voice;
+    /** Capacity as named pools: every service that works asks for a slot before
+     *  working (the ticket workers drew it first; voice rooms draw the same).
+     *  A pool is an endpoint — capacity, an optional model, an optional
+     *  fallback. Pools are how a local box and a remote endpoint stay apart. */
+    dispatcher: Dispatcher;
+    /** Ticket-to-run machinery: a tracker module registers its stages, stops
+     *  runs and reads run records here. The orchestrator owns the run's state
+     *  machine, the worker session, and the worker tools; it never calls back. */
+    orchestrator: Orchestrator;
+    /** Tell the scheduler and every channel engine that the queue or capacity changed; dispatch now. */
+    wake(): void;
+    /** Be told the same; a channel engine ticks on it instead of polling for capacity released elsewhere. */
+    onWake(listener: () => void): () => void;
+    /** Abort the whole host. Only for failures the module cannot recover from. */
+    fail(error: unknown): void;
+}
+/**
+ * The home store as a module meets it: the whole contract of the host's
+ * `Store` class, which is checked against this interface. A module gets the
+ * open database for its own tables (namespaced migrations), the job and run
+ * surface its commands report through, the leases it reads, the identity
+ * lookups the chat platforms redeem, and the request diary a setup flow
+ * watches. No module ever names the database file: the runner opens it and
+ * hands over the handle.
+ */
+export interface Store {
+    readonly db: DatabaseSync;
+    /** Open for the last time; closing it is the runner's, never a module's. */
+    close(): void;
+    /** Apply this namespace's migrations, once, in order; new tables belong to the module that named them. */
+    migrate(namespace: string, steps: readonly string[]): void;
+    /** Run one SQLite transaction; a throw rolls it back whole. */
+    transaction<T>(fn: () => T): T;
+    /** Leave one audit line on a run. */
+    note(id: string, action: string, reason: string, now?: number): void;
+    /** Run history: one job, one state, the newest few. */
+    runs(filter?: RunFilter): Run[];
+    /** One run by id; throws when it is not there. */
+    run(id: string): Run;
+    /** How many runs stand in each state. */
+    counts(): Record<RunState, number>;
+    /** One run of a task that should happen once now (a report, a re-entry). */
+    enqueue(task: Task, resource: string, dedupeKey: string, now?: number, report?: Report | null): Run;
+    /** Every job as the store holds it: definition, source, state, next instant. */
+    jobs(): JobEntry[];
+    /** The job defined under `id`; throws when it is not there. */
+    job(id: string): JobEntry;
+    /** Reconcile the definitions with `config.json` and the host's system jobs. */
+    syncJobs(config: Job[], system?: Job[], now?: number): void;
+    /** Define a job from an agent tool call or the operator CLI. */
+    addJob(spec: Job, source: 'agent' | 'operator', now?: number, options?: AddJobOptions): JobEntry;
+    setJobEnabled(id: string, enabled: boolean, now?: number): JobEntry;
+    removeJob(id: string, now?: number): void;
+    /** Run a job now, beside its schedule. */
+    runJob(id: string, now?: number): Run;
+    /** Materialize occurrences that came due while aivi slept; silence is a result. */
+    materializeDue(now?: number, graceMs?: number): {
+        created: number;
+        missed: Run[];
+    };
+    /** The next occurrence to materialize; null when nothing is due. */
+    nextDue(now?: number): number | null;
+    /** Name the session a claimed run opened, so reports can find their way back. */
+    attachSession(id: string, owner: string, sessionId: string): void;
+    /** Settle a claimed run: its result, its state, its reason. */
+    finish(id: string, owner: string, state: 'succeeded' | 'failed' | 'blocked', result: unknown, reason: string, now?: number): void;
+    cancelQueued(id: string, now?: number): void;
+    /** A person answered what a blocked run awaited; the run resumes its outcome. */
+    resolveBlocked(id: string, outcome: 'succeeded' | 'failed', reason: string, now?: number): void;
+    /** The one live host: a second serve finds the daemon held and steps back. */
+    acquireDaemon(owner: string, pid?: number, now?: number): void;
+    releaseDaemon(owner: string): void;
+    /** A run's audit trail, oldest first. */
+    history(id: string): AuditEntry[];
+    /** Runs that reached a final state since `since`, newest first. */
+    recent(since: number, limit?: number): Run[];
+    lastRun(jobId: string): Run | null;
+    /** Consecutive failed runs of a job; the streak a report's nudge reads. */
+    failureStreak(jobId: string): number;
+    /** Tell a running run a person asked it to stop. */
+    requestCancel(id: string, now?: number): void;
+    /** The runs this owner was told to stop and has not felt yet. */
+    cancelRequested(owner: string): string[];
+    /** Drop history older than the instant; the counts say what left. */
+    prune(olderThan: number): {
+        runs: number;
+        jobs: number;
+        linkCodes: number;
+    };
+    /** The people directory: `aivi people`, and the tokens they sign in with. */
+    createPerson(spec: {
+        name: string;
+        email?: string | null;
+        roles?: string[];
+    }, now?: number): Person;
+    person(id: string): Person | null;
+    people(): Person[];
+    mintToken(personId: string, label: string, now?: number): {
+        token: PersonToken;
+        secret: string;
+    };
+    personForToken(secret: string): {
+        person: Person;
+        token: PersonToken;
+    } | null;
+    /** A link code a person spends on a chat platform; the expiry is the answer. */
+    mintLinkCode(personId: string, ttlMs?: number, now?: number): {
+        code: string;
+        expiresAt: number;
+    };
+    redeemLinkCode(code: string, channel: string, userId: string, now?: number): {
+        reason: 'bound';
+        person: Person;
+    } | {
+        reason: 'already';
+        person: Person;
+    } | {
+        reason: 'expired';
+    } | {
+        reason: 'unknown';
+    };
+    /** The person behind a platform identity, if aivi knows one. */
+    identityFor(channel: string, userId: string): Person | null;
+    personLinkedIn(channel: string, personId: string): boolean;
+    /** Record one call the host answered; the diary a setup flow watches. */
+    logRequest(entry: Omit<RequestLogEntry, 'id'>): void;
+    requests(filter?: {
+        sinceId?: number;
+        method?: string;
+        path?: string;
+        limit?: number;
+    }): RequestLogEntry[];
+    clearRequests(olderThan: number): number;
+}
+/**
+ * The run machinery as a module meets it: a tracker registers its stages,
+ * wakes the walk, stops and answers runs, and reads run records. Work is
+ * never handed in here — the walk over the tracker's board is the only door
+ * for board work (ruled 2026-10-01). The orchestrator itself is the host's
+ * class, checked against this interface.
+ */
+export interface Orchestrator {
+    /** Register the one tracker a module speaks for. */
+    addTracker(tracker: Tracker): void;
+    /** Walk the board now: the whole set, or one project. */
+    wake(projectId?: string): Promise<void>;
+    /** Stop a running run; the run ends `cancelled` and says so where people read. */
+    stop(runId: string, reason: string): Promise<void>;
+    /** A person's answer to a parked run; `formId` is the OpenCode form it answers. */
+    answer(sessionId: string, text: string, formId?: string): Promise<{
+        resumed: true;
+    } | {
+        resumed: false;
+        queued?: string;
+        refused?: string;
+    }>;
+    /** The run working `ticketId` for `trackerId`, if one is in flight. */
+    activeRun(trackerId: string, ticketId: string): RunView | undefined;
+    /** The run a worker session belongs to, whatever tracker spoke for it. */
+    runBySession(sessionId: string): RunView | undefined;
+    /** Forget a waiting request: a person moved the ticket themselves. */
+    cancelWaiting(trackerId: string, ticketId: string): void;
+}
+/**
+ * What a public route sees: the request and its raw body (signatures are
+ * computed over bytes, never re-serialized JSON). Headers are the plain
+ * lower-cased view the API has always handed over.
+ */
+export interface PublicRequest {
+    method: string;
+    headers: Record<string, string | undefined>;
+    body: Buffer;
+}
+export type PublicRouteHandler = (request: PublicRequest) => Promise<{
+    status: number;
+    body?: unknown;
+}>;
+/**
+ * Routes a module exposes without the bearer token: webhooks from platforms
+ * that authenticate with their own signature. A path is owned by one handler;
+ * registering it twice is a programming error. `/health` and `/version` are
+ * the only other unauthenticated routes, and no module may take them. The
+ * registry is the host's class, checked against this interface.
+ */
+export interface PublicRoutes {
+    register(path: string, handler: PublicRouteHandler): () => void;
+}
+export type TaskHandler = (run: Run, context: ExecutionContext) => Promise<ExecutionResult>;
+/** What `kind: 'invocation'` tasks dispatch to: the host claims its own
+ *  operations here, modules claim theirs. */
+export interface TaskClaims {
+    claim(name: string, handler: TaskHandler): void;
+    release(name: string): void;
+}
+/** One call as the generic dispatch hands it over: the envelope's ids, the model's input. */
+export interface ToolCall {
+    sessionId: string;
+    messageId?: string;
+    input: Record<string, unknown>;
+}
+export type ToolHandler = (call: ToolCall) => Promise<unknown>;
+/** The tool surface the OpenCode plugin registers at load: the host claims
+ *  its own tools here, modules claim theirs. */
+export interface ToolClaims {
+    claim(descriptor: ToolDescriptor, handler: ToolHandler): void;
+    release(id: string): void;
+}
+/** The shape every OpenCode event shares; session events carry `data.sessionID`. */
+export interface SessionEvent {
+    type: string;
+    data?: {
+        sessionID?: string;
+    } & Record<string, unknown>;
+}
+export type SessionEventListener = (event: SessionEvent) => void;
+/** The host's one OpenCode event stream, fanned out by session id. */
+export interface SessionEvents {
+    /** Receive this session's events until the returned function is called. */
+    watch(sessionID: string, listener: SessionEventListener): () => void;
+}

package/dist/module.js

@@ -0,0 +1,28 @@
+/**
+ * The **module contract**: what aivi composes and hands a module at start,
+ * and what the module may do with it. Declared here because both sides
+ * follow it: the host's `runHost` builds the bag and the modules use it; the
+ * host's classes are checked against the interfaces below, so the contract
+ * and the machinery cannot drift apart silently.
+ *
+ * What a module receives is enough to serve and nothing to drive: the run
+ * vocabulary (`./run.ts`) is read-only from here, the tracker stages
+ * (`./tracker.ts`) are what a tracker hands *in*, and the OpenCode client
+ * arrives discovered on every call — a restarted service is picked up by the
+ * next unit of work without restarting aivi.
+ */
+/** A tool failed with an answer for the agent: this status and message reach the caller. */
+export class ToolError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * A module start that no retry can fix: a missing token, an id that does not
+ * match. Modules throw this for what the operator must change; everything else
+ * (a platform answering 503, a network blip) is retried.
+ */
+export class ConfigurationError extends Error {
+}