@tomradex/agent 0.16.2 → 0.17.0

package/dist/engine-shape.d.ts

@@ -0,0 +1,10 @@
+import type { Engine, EngineRegistration } from "./engine.js";
+/**
+ * The engine in the grouped shape, whichever shape it was given in: plugins
+ * built before the grouping still register flat members. Everything past
+ * registration reads only the grouped ones.
+ */
+export declare function normalizeEngine(given: EngineRegistration): Engine;
+/** The engine in the flat names plugin scenarios read (`localAgents.engine`), as they were before the grouping. */
+export declare function flatEngineView(engine: Engine): Record<string, unknown>;
+//# sourceMappingURL=engine-shape.d.ts.map

package/dist/engine.d.ts

@@ -0,0 +1,332 @@
+import type { z } from "zod";
+import type { Author } from "@tomradex/domain";
+import type { TurnInput, TurnIO, TurnResult } from "./turn.js";
+/**
+ * What an engine can be trusted with. `backlog` talks to the app through its
+ * tools; `code` also edits files and runs commands in a repository — only a
+ * local coding agent (Claude Code, Codex…) declares it, and only such an engine
+ * is offered when a ticket is started.
+ */
+export type EngineCapability = "backlog" | "code" | "general";
+/**
+ * What stands between an engine and its first turn, so the app can say how to fix it in the person's language.
+ * `repair`: the CLI is there but does not run.
+ */
+export type EngineNeed = "install" | "repair" | "sign-in" | "model" | "service";
+/** Where a local CLI candidate came from, in the order they are tried. */
+export type CliSource = "manual" | "path" | "login-path" | "known";
+export interface CliAttempt {
+    path: string;
+    source: CliSource;
+    ok: boolean;
+    /** The version it printed, or why it did not run. */
+    detail: string;
+}
+/** How a local agent's CLI was looked for and what was found — enough to show its state and to report it. */
+export interface LocalCliStatus {
+    name: string;
+    state: "ready" | "missing" | "broken";
+    path?: string;
+    source?: CliSource;
+    version?: string;
+    /** Why the best candidate did not run, when none did. */
+    error?: string;
+    /** A path the person chose that no longer runs; detection carried on without it. */
+    manual?: {
+        path: string;
+        error: string;
+    };
+    /** Found only inside WSL, where a Windows app cannot run it. */
+    wsl?: string;
+    /** Not found, but this agent's desktop app is installed — which does not include the CLI. */
+    desktopApp?: string;
+    /** Not found, and this login shell did not answer in time: the folders its startup files add to PATH went unsearched. */
+    shellTimedOut?: string;
+    attempts: CliAttempt[];
+    /** Directories searched, in order. */
+    searched: string[];
+    platform: string;
+    arch: string;
+    /** The PATH the app itself runs with. */
+    pathEnv: string;
+}
+export interface EngineAvailability {
+    ok: boolean;
+    reason?: string;
+    need?: EngineNeed;
+    /** Present for engines that drive a CLI installed on this machine. */
+    cli?: LocalCliStatus;
+    /** What it can take on right now, when only part of it is ready; absent means all its capabilities. */
+    capabilities?: EngineCapability[];
+    /** How it installs on this machine, when that differs from the engine's declared setup — an installer that is not here is left out. */
+    setup?: EngineSetup;
+    /** The folder a local CLI reads its sign-in from, when it is not signed in (CODEX_HOME, CLAUDE_CONFIG_DIR). */
+    configDir?: string;
+}
+/**
+ * How a person makes a local agent ready on this machine, as commands: what
+ * setup screens show, copy and run in a terminal. Only what an engine declares
+ * here can be started in a terminal from the app.
+ */
+export interface EngineSetup {
+    /** Install commands, the recommended one first. */
+    install: string[];
+    signIn?: string;
+    /** Signing in starts the agent itself, which then asks (`/login`); otherwise the command signs in and returns. */
+    signInRuns?: boolean;
+    docs?: string;
+    /** Offered on setup screens before it is installed. */
+    suggested?: boolean;
+}
+/**
+ * Tomrade's MCP server in the agent's own user-level configuration, so a
+ * session the person opens anywhere outside Tomrade can reach it. Written only
+ * when the person asks.
+ */
+export interface EngineMcpLink {
+    status(): Promise<McpLinkView>;
+    /** `profile` names one of `status().profiles`; without it, the agent's own (the first). Answers as `status()` does. */
+    connect(profile?: string): Promise<McpLinkView>;
+    disconnect(profile?: string): Promise<McpLinkView>;
+    /** Whether the agent will load a `tomrade` server a repository's own config declares; some ask once per folder first. */
+    projectApproval?(dir: string): "approved" | "rejected" | "pending";
+    /** The same, for each of its profiles. */
+    projectApprovals?(dir: string): McpProjectApproval[];
+    /** A session of the agent started somewhere — its transcript names the profile it ran under. */
+    sawTranscript?(file: string): void;
+}
+export interface McpProjectApproval {
+    profile: string;
+    state: "approved" | "rejected" | "pending";
+    /** How to start the agent under that profile, for the person to run in the checkout. */
+    command: string;
+}
+export interface McpLinkView {
+    /** `stale`: a `tomrade` server is configured but at another address (an old port, the other Tomrade). */
+    state: "connected" | "missing" | "stale" | "unavailable";
+    /** The address this Tomrade serves; null while its MCP server is not running. */
+    url: string | null;
+    /** The address the agent's configuration names, when it names one. */
+    configuredUrl: string | null;
+    /** Where the agent keeps it, for the person to look at. */
+    file: string | null;
+    /** Commands that do the same by hand, for when the CLI cannot be run from here. */
+    manual: {
+        connect: string;
+        disconnect: string;
+    };
+    /** Why the last step could not be done or the state could not be read. */
+    error?: string;
+    /** The configuration folder this describes, for an agent that has several (CLAUDE_CONFIG_DIR per account). */
+    profile?: string;
+    /** Every profile, this one first, when there is more than one. */
+    profiles?: McpLinkView[];
+}
+/** A path the person typed or picked, run once to see whether it is the CLI. */
+export interface CliCheck {
+    ok: boolean;
+    path: string;
+    version?: string;
+    error?: string;
+}
+/** Anything that can take one turn on a thread. The conductor seam. */
+export interface Engine {
+    /** Actual formats supported by the selected transport/model; absent means text only. */
+    media?(options: unknown): {
+        input: string[];
+        output: string[];
+    };
+    id: string;
+    title: string;
+    author: Author;
+    /** Absent means `["backlog"]`. */
+    capabilities?: EngineCapability[];
+    /**
+     * Engines this one runs in their place: pickers list it alone, and a thread
+     * or setting naming one of them is answered by this engine.
+     */
+    includes?: string[];
+    /**
+     * No model judges what the user types: free text while a workflow waits is
+     * taken as that workflow's answer. A model engine instead reads the reply with
+     * the waiting question in its prompt and resumes or cancels the workflow itself.
+     */
+    literal?: boolean;
+    /**
+     * `fresh` looks again instead of answering from a recent probe — after the person installs or points at a CLI.
+     * `options`: whether it can run a turn with these engine options, such as the model a thread picked.
+     */
+    available(opts?: {
+        fresh?: boolean;
+        options?: unknown;
+    }): Promise<EngineAvailability>;
+    /** Engine settings, drawn by the settings UI from the schema. */
+    options?: z.ZodType<unknown>;
+    /** `default` is what a session starts in until the person picks another mode. */
+    permissionModes?: {
+        default: string;
+        choices: {
+            value: string;
+            label: string;
+        }[];
+    };
+    /** Whether a ticket can be handed to its CLI in a terminal. Absent: `{ mode: "handoff" }`. */
+    terminal?: EngineTerminal;
+    /** True: it runs on the model profiles set up in Tomrade, so a key or model error is fixed there — not in its own sign-in. */
+    usesModels?: boolean;
+    /** How it takes messages sent while a turn runs; absent, the panel queues them until the turn ends. */
+    steering?: EngineSteering;
+    /** The agent's own setup on this machine: its CLI, install, connection, permissions and knobs. */
+    local?: EngineLocal;
+    turn(input: TurnInput, io: TurnIO): Promise<TurnResult>;
+}
+export interface EngineTerminal {
+    /**
+     * `none`: it runs only inside Tomrade, with no CLI session a person can be handed in a terminal.
+     * `handoff`: a ticket can also be handed to its CLI in a terminal.
+     * `only`: a CLI Tomrade starts only in a terminal the person sees — handed the ticket, heard over MCP, never driven turn by turn.
+     */
+    mode: "none" | "handoff" | "only";
+    /** `link`: in a terminal it reaches Tomrade only through its own user-level connection (`local.mcpLink`), so that comes first. Absent: `session`. */
+    via?: "session" | "link";
+    /** That connection carries no session token, so the session's first act is claim_ticket, which joins it to the session Start made. */
+    claims?: boolean;
+}
+/**
+ * `queue`: Tomrade holds them and the engine takes them where its model reads next (`io.takeSteers`).
+ * `forward`: its agent keeps its own steering queue; each is handed over (`io.steerTo`) and placed when read (`io.steered`).
+ */
+export type EngineSteering = "queue" | "forward";
+export interface EngineLocal {
+    /** Whether this file is a CLI it can use. */
+    checkCli?(file: string): Promise<CliCheck>;
+    setup?: EngineSetup;
+    /** Quick-pick knobs the panel offers; each writes options[key]. Called per view, so lists can be live. */
+    picks?(): EnginePick[];
+    /** What the troubleshooter may read about this engine beyond `available()`. */
+    diagnostics?: EngineDiagnostics;
+    /** What the engine's own configuration lets its agent run; absent when Tomrade cannot read it. */
+    commands?: EngineCommands;
+    mcpLink?: EngineMcpLink;
+}
+/** The flat members an engine had before they were grouped; `Agent.engine` still maps them once, at registration. */
+export interface FlatEngineMembers {
+    /** @deprecated `terminal: { mode: "none" }` for false. */
+    terminal?: boolean;
+    /** @deprecated `terminal: { mode: "only" }`. */
+    terminalOnly?: boolean;
+    /** @deprecated `terminal: { via: "link" }`. */
+    terminalViaLink?: boolean;
+    /** @deprecated `terminal: { claims: true }`. */
+    terminalClaims?: boolean;
+    /** @deprecated `steering`; read as `"queue"`, and a turn's `io` offers both protocols either way. */
+    steers?: boolean;
+    /** @deprecated `local.checkCli`. */
+    checkCli?(file: string): Promise<CliCheck>;
+    /** @deprecated `local.setup`. */
+    setup?: EngineSetup;
+    /** @deprecated `local.picks`. */
+    picks?(): EnginePick[];
+    /** @deprecated `local.diagnostics`. */
+    diagnostics?: EngineDiagnostics;
+    /** @deprecated `local.commands`. */
+    commands?: EngineCommands;
+    /** @deprecated `local.mcpLink`. */
+    mcpLink?: EngineMcpLink;
+}
+/** What `Agent.engine` takes: an engine, or one still in the flat shape. */
+export type EngineRegistration = Engine | (Omit<Engine, "terminal"> & FlatEngineMembers);
+/**
+ * An engine's own evidence, for the troubleshooter and a report. Only what is
+ * named here is read: an agent investigating a failure gets no other files.
+ */
+export interface EngineDiagnostics {
+    /** The agent's own log files, newest first; their tails go into a report. */
+    logs?(): string[] | Promise<string[]>;
+    /** Short facts that tell one setup from another — edition, endpoint, models offered. */
+    facts?(): Record<string, string> | Promise<Record<string, string>>;
+}
+/**
+ * Whether the engine's own permission settings let one shell command through,
+ * read from its config files — not a promise: a safety check or the remote can
+ * still refuse it at run time.
+ */
+export interface EngineCommands {
+    check(command: string, opts: CommandCheckOptions): Promise<CommandCheck>;
+    /** Adds `check(...).fix.rule` to `fix.file`, then checks again. */
+    allow?(command: string, opts: CommandCheckOptions): Promise<CommandCheck>;
+}
+export interface CommandCheckOptions {
+    /** Where the agent will run, for project-level settings; null reads only the user's. */
+    cwd: string | null;
+    /** The run gets a fresh worktree of `cwd`: only checked-in project files reach it, not untracked local ones. */
+    worktree?: boolean;
+    /** The permission mode it will run under; absent, the one its settings default to. */
+    permissionMode?: string;
+}
+export interface CommandCheck {
+    /** `asks`: the person approves it when it comes up; `blocked`: refused, or likely to be, without a change. */
+    state: "allowed" | "asks" | "blocked";
+    /** Why, in a word a screen can name in its own language. */
+    why: "bypass" | "allow-rule" | "ask-rule" | "deny-rule" | "prompts" | "auto-mode" | "plan" | "dont-ask";
+    mode: string;
+    /** The rule that decided it, and the file it is in. */
+    rule?: {
+        rule: string;
+        file: string;
+    };
+    /** The one rule `allow` writes; absent when no added rule would help (a deny rule wins over it). */
+    fix?: {
+        rule: string;
+        file: string;
+    };
+}
+/** One quick-pick knob: "model" and "effort" keys get localized group labels; other keys show `title`. */
+export interface EnginePick {
+    key: string;
+    title: string;
+    /** `searchesWeb`: the model searches the web on its own, so needs no web search key. */
+    choices: {
+        value: string;
+        label?: string;
+        searchesWeb?: boolean;
+    }[];
+    /** Choices are suggestions only — settings may hold any string (e.g. a model id the CLI knows). */
+    freeText?: boolean;
+    /** The engine is still asking its agent for the choices; ask again shortly. */
+    pending?: boolean;
+}
+/** One real turn on an engine, asked for by the person: does it answer? */
+export interface EngineTry {
+    ok: boolean;
+    ms: number;
+    at: number;
+    /** What it said, cut short. */
+    reply?: string;
+    error?: string;
+    details?: string;
+}
+export interface EngineView {
+    id: string;
+    title: string;
+    capabilities: EngineCapability[];
+    ok: boolean;
+    reason?: string;
+    need?: EngineNeed;
+    cli?: LocalCliStatus;
+    configDir?: string;
+    /** The last try with the settings it has now; a change to its settings clears it. */
+    tried?: EngineTry;
+    picks?: EnginePick[];
+    permissionModes?: Engine["permissionModes"];
+    terminal?: boolean;
+    terminalOnly?: boolean;
+    usesModels?: boolean;
+    steers?: boolean;
+    setup?: EngineSetup;
+    /** Engines it answers for: a thread, run or setting may still name one of them. */
+    includes?: string[];
+    /** It can put Tomrade's MCP server in its own user-level configuration (`agent.mcpLink`). */
+    mcpLink?: boolean;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/evaluation.d.ts

@@ -1,4 +1,6 @@
-import type { Block, Engine, TurnInput, TurnIO, TurnResult } from "./types.js";
+import type { Engine } from "./engine.js";
+import type { Block } from "./thread.js";
+import type { TurnInput, TurnIO, TurnResult } from "./turn.js";
 /** Provider counters stay separate: cached tokens are context, not free input. */
 export interface TurnMetrics {
     transport: "sdk" | "app-server" | "rpc" | "acp" | "http";

package/dist/hooks.d.ts

@@ -0,0 +1,122 @@
+import type { Author } from "@tomradex/domain";
+import type { Message, ToolSpec } from "@tomradex/llm";
+import type { RunHandle } from "@tomradex/tools";
+import type { ParkView, RunView, ThreadSummary } from "./thread.js";
+import type { TurnInput, TurnPurpose } from "./turn.js";
+declare module "cordis" {
+    interface Events {
+        "agent/prepare-turn"(input: TurnInput): Promise<void> | void;
+        /** The brief a CLI agent starts a delivery from, before it is handed over. A plugin may add context an in-app turn would get from `agent/prepare-turn`. */
+        "agent/prepare-brief"(brief: {
+            projectId: string;
+            itemId: string;
+            filesIndex?: string;
+        }): Promise<void> | void;
+        /** A run began driving a thread. */
+        "agent/run-started"(run: RunView, thread: ThreadSummary): void;
+        /** A run settled, however it stopped; `run.stop` says how. */
+        "agent/run-ended"(run: RunView, thread: ThreadSummary): void;
+        /** A thread stopped on a usage limit and waits for it to lift. */
+        "agent/parked"(park: ParkView, thread: ThreadSummary): void;
+        /** A parked thread's limit lifted and nobody continues it on its own: the person may. */
+        "agent/limit-lifted"(park: ParkView, thread: ThreadSummary): void;
+        /** A project's rules file was written through Tomrade. */
+        "agent/rules-changed"(projectId: string): void;
+        /**
+         * Each model request an in-app engine (`engine-loop`) is about to send: a listener may change its
+         * system prompt, tools and messages, before or after `next()`; what comes back is sent. CLI agents
+         * run their own loop and send nothing through here.
+         */
+        "agent/request"(request: AgentRequest, next: () => Promise<AgentRequest>): Promise<AgentRequest>;
+        /** A model request an in-app engine sent failed. The first listener to answer decides what to try instead. */
+        "agent/request-error"(failure: AgentRequestFailure): Promise<AgentRetry | void> | AgentRetry | void;
+        /** An in-app turn is about to end. The first listener to answer keeps it going, with a message to the model. */
+        "agent/turn-stopping"(ending: TurnEnding): Promise<{
+            continue: string;
+        } | void> | {
+            continue: string;
+        } | void;
+        /**
+         * A CLI agent's hook reached Tomrade — Claude Code, Codex, dsh and the rest. The first listener to
+         * answer decides; the answer reaches the agent only when `answerable` (a session Tomrade started).
+         */
+        "agent/cli-hook"(call: CliHookCall): Promise<CliHookAnswer | void> | CliHookAnswer | void;
+    }
+}
+/** What a CLI agent's hook says happened, in one set of names whichever agent sent it. */
+export type CliHookEvent = "session-start" | "prompt" | "pre-tool" | "post-tool" | "stop" | "session-end";
+export interface CliHookCall {
+    event: CliHookEvent;
+    /** The agent that sent it: `claude-code`, `codex`, `dsh`, `pi`, `workbuddy`, `cursor`, `opencode`, `hermes`… */
+    agent: string;
+    /** Whether an answer reaches the agent: true in a session Tomrade started, false for a connected repository's hooks. */
+    answerable: boolean;
+    projectId: string;
+    /** Tomrade's code session the hook belongs to. */
+    sessionId: string;
+    /** The ticket the session works, when it has one. */
+    ticket: string | null;
+    cwd: string | null;
+    tool?: {
+        name: string;
+        input: unknown;
+        output?: string;
+        error?: string;
+    };
+    /** What the model said last, at `stop`. */
+    text?: string;
+    /** The hook's own payload, as the agent sent it. */
+    raw: Record<string, unknown>;
+}
+/** Refuse the tool (`pre-tool`), add context for the model, or keep the turn going (`stop`). */
+export interface CliHookAnswer {
+    deny?: string;
+    context?: string;
+    continue?: string;
+}
+/** Which turn, step and model profile a request belongs to: read, never changed. */
+export interface AgentTurnInfo {
+    runId: string;
+    threadId: string;
+    projectId: string;
+    purpose: TurnPurpose;
+    profile: string;
+    step: number;
+}
+/** One model request as an in-app engine is about to send it. */
+export interface AgentRequest {
+    system: string;
+    tools: ToolSpec[];
+    messages: Message[];
+    turn: AgentTurnInfo;
+}
+export interface AgentRequestFailure {
+    error: unknown;
+    request: AgentRequest;
+    /** How many times this step was already tried again on a listener's answer. */
+    attempt: number;
+}
+/** Send the request again: changed, on another model profile, or both. */
+export interface AgentRetry {
+    request?: Partial<Pick<AgentRequest, "system" | "tools" | "messages">>;
+    profile?: string;
+}
+export interface TurnEnding {
+    /** What the model said last. */
+    text: string;
+    turn: AgentTurnInfo;
+    /** How many times this turn was already kept going. */
+    continued: number;
+}
+export interface AgentPolicy {
+    id: string;
+    /** Runs on tools/pre-execute for calls that belong to an agent run. Throw to refuse; the message reaches the model. */
+    before(call: {
+        name: string;
+        args: unknown;
+        by: Author;
+        projectId?: string;
+        run: RunHandle;
+    }, next: () => Promise<unknown>): Promise<unknown>;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/index.d.ts

@@ -12,5 +12,10 @@ export { HOUSE_RULES, RULES_INSTRUCTIONS_MAX, RULES_MAX_CHARS, rulesInstructions
 export { evaluateTurn, summarizeEvaluation, type TurnMetrics, type EvaluationObservation } from "./evaluation.js";
 export { NO_TOKENS, addTokens, runTokens, type TokenBreakdown } from "./tokens.js";
 export { carriedKits, deferredTools, kitLines } from "./kits.js";
-export { isSuspended, PANEL_SURFACES, type AgentEvent, type AgentPolicy, type AgentRequest, type AgentRequestFailure, type AgentRetry, type AgentTurnInfo, type Block, type CardAction, type CardView, type ChecklistCard, type CliAttempt, type CliHookAnswer, type CliHookCall, type CliHookEvent, type CliCheck, type EngineMcpLink, type McpLinkView, type McpProjectApproval, type CliSource, type Engine, type EngineAvailability, type EngineCapability, type EngineDiagnostics, type EngineCommands, type CommandCheck, type CommandCheckOptions, type EngineNeed, type EnginePick, type EngineView, type EngineTry, type EngineSetup, type FindingCard, type FocusRef, type FollowUpStart, type GeneralExecution, type LocalCliStatus, type OpenDependency, type ParkView, type PendingView, type Playbook, type PlaybookIndexEntry, type PlaybookSource, type RunStatus, type RunView, type Suspended, type ThreadMessage, type ThreadSummary, type ThreadSurface, type TurnEnding, type TurnInput, type TurnFollowUp, type TurnIO, type RetryState, type TurnPurpose, type TurnResult, type UserInput, type WorkflowInfo, type WorkflowIO, type WorkflowQuestion, type WorkflowSpec, type WorkflowTransition } from "./types.js";
+export { type AgentEvent, type Block, type CardAction, type CardView, type ChecklistCard, type FindingCard, type FocusRef, PANEL_SURFACES, type ParkView, type PendingView, type RunStatus, type RunView, type ThreadMessage, type ThreadSummary, type ThreadSurface, type UserInput } from "./thread.js";
+export { type OpenDependency, type RetryState, type TurnInput, type TurnIO, type TurnPurpose, type TurnResult } from "./turn.js";
+export { type FollowUpStart, type GeneralExecution, isSuspended, type Playbook, type PlaybookIndexEntry, type PlaybookSource, type Suspended, type TurnFollowUp, type WorkflowInfo, type WorkflowIO, type WorkflowQuestion, type WorkflowSpec, type WorkflowTransition } from "./workflow.js";
+export { type CliAttempt, type CliCheck, type CliSource, type CommandCheck, type CommandCheckOptions, type Engine, type EngineAvailability, type EngineCapability, type EngineCommands, type EngineDiagnostics, type EngineLocal, type EngineMcpLink, type EngineNeed, type EnginePick, type EngineRegistration, type EngineSetup, type EngineSteering, type EngineTerminal, type EngineTry, type EngineView, type FlatEngineMembers, type LocalCliStatus, type McpLinkView, type McpProjectApproval } from "./engine.js";
+export { type AgentPolicy, type AgentRequest, type AgentRequestFailure, type AgentRetry, type AgentTurnInfo, type CliHookAnswer, type CliHookCall, type CliHookEvent, type TurnEnding } from "./hooks.js";
+export { flatEngineView, normalizeEngine } from "./engine-shape.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/kits.d.ts

@@ -1,5 +1,6 @@
 import type { ToolDescriptor } from "@tomradex/tools";
-import type { ThreadMessage, TurnPurpose } from "./types.js";
+import type { ThreadMessage } from "./thread.js";
+import type { TurnPurpose } from "./turn.js";
 /** Kits a conversation carries from its first request: a coding session needs its ticket's tools; the rest wait until asked for. */
 export declare function carriedKits(purpose: TurnPurpose): string[];
 /**

package/dist/native-media.d.ts

@@ -1,4 +1,4 @@
-import type { TurnIO, TurnInput } from "./types.js";
+import type { TurnIO, TurnInput } from "./turn.js";
 export declare function attachedMedia(input: TurnInput, io: TurnIO): import("./media.js").MediaContent[];
 export declare function claudeMediaInput(input: TurnInput, io: TurnIO, text: string): ({
     type: "document" | "image";

package/dist/playbooks.d.ts

@@ -1,4 +1,4 @@
-import type { Playbook, PlaybookIndexEntry, PlaybookSource } from "./types.js";
+import type { Playbook, PlaybookIndexEntry, PlaybookSource } from "./workflow.js";
 /** Missing capabilities are visible to the caller; recommendations never hide a method. */
 export declare function missingPlaybookCapabilities(playbook: Pick<Playbook, "requires">, available: readonly string[]): string[];
 export declare const frontmatter: (raw: string) => {

package/dist/prompt.d.ts

@@ -1,4 +1,6 @@
-import type { FocusRef, GeneralExecution, OpenDependency, TurnInput, TurnIO } from "./types.js";
+import type { FocusRef } from "./thread.js";
+import type { OpenDependency, TurnInput, TurnIO } from "./turn.js";
+import type { GeneralExecution } from "./workflow.js";
 /**
  * The house rules every model-driven engine puts in its system prompt. One
  * copy on the platform, so a rule changed here reaches loop and CLI engines
@@ -52,13 +54,6 @@ export declare function generalPrompt(input: {
     filesIndex?: string;
     rules?: string;
 }): string;
-/**
- * The shared tail of a system prompt: the playbook index, the project brief,
- * the durable cards, and the waiting workflow. Engines prepend their identity
- * and the house rules, then join these with blank lines.
- */
-/** What the main conversation can do with the code, and where that code is, so a limit is named instead of mistaken for an empty folder. */
-export declare function mainConversationSection(repositories: TurnInput["repositories"]): string;
 export declare function promptSections(input: TurnInput, io: TurnIO, opts?: {
     playbooks?: boolean;
     filesIndex?: boolean;

package/dist/recap.d.ts

@@ -1,4 +1,4 @@
-import type { ThreadMessage } from "./types.js";
+import type { ThreadMessage } from "./thread.js";
 /**
  * The conversation so far, for an engine that keeps its own session and is
  * starting a new one on a thread that already has history: its old session is

package/dist/service.d.ts

@@ -4,8 +4,12 @@ import { type UndoRunResult } from "@tomradex/domain";
 import type { SettingsSection } from "@tomradex/settings";
 import { AgentStore } from "./store.js";
 import { type MediaRef, type MediaUpload, type MediaContent } from "./media.js";
-import { type AgentEvent, type AgentPolicy, type CardView, type Engine, type CliCheck, type McpLinkView, type EngineTry, type EngineView, type FocusRef, type GeneralExecution, type ParkView, type PendingView, type Playbook, type PlaybookIndexEntry, type PlaybookSource, type RunView, type ThreadMessage, type ThreadSummary, type TurnFollowUp, type UserInput, type WorkflowSpec, type ThreadSurface } from "./types.js";
+import type { AgentPolicy } from "./hooks.js";
+import type { CliCheck, Engine, EngineRegistration, EngineTry, EngineView, McpLinkView } from "./engine.js";
+import { type AgentEvent, type CardView, type FocusRef, type ParkView, type PendingView, type RunView, type ThreadMessage, type ThreadSummary, type ThreadSurface, type UserInput } from "./thread.js";
+import { type GeneralExecution, type Playbook, type PlaybookIndexEntry, type PlaybookSource, type TurnFollowUp, type WorkflowSpec } from "./workflow.js";
 import { type TokenBreakdown } from "./tokens.js";
+import { type AgentReader } from "@tomradex/contracts";
 /** Where a thread's engine would run, or the one reason it cannot yet. `code` is stable for the renderer to translate. */
 /** Which of these threads a plugin opened, and what to call that: thread id → label. */
 export type ThreadOrigins = (projectId: string, threads: ThreadSummary[]) => Iterable<[string, string]>;
@@ -200,7 +204,7 @@ export interface AgentSettings {
     playbookChoices: Record<string, PlaybookSource>;
 }
 export declare const AGENT_SECTION: SettingsSection<AgentSettings>;
-export declare class Agent extends Service {
+export declare class Agent extends Service implements AgentReader {
     readonly config: AgentConfig;
     static provide: string;
     static inject: string[];
@@ -237,7 +241,7 @@ export declare class Agent extends Service {
     answering(id: string): string;
     /** The engines a person chooses between: none that another engine took in. */
     allEngines(): Engine[];
-    engine(engine: Engine): () => void;
+    engine(given: EngineRegistration): () => void;
     /** A plugin names the conversations it opened (thread id → a short label in the person's language). */
     threadOrigins(provider: ThreadOrigins): () => void;
     /** The threads with what each plugin says opened them. */

package/dist/store.d.ts

@@ -1,6 +1,7 @@
 import type { Db } from "@tomradex/db";
 import type { Author } from "@tomradex/domain";
-import type { Block, CardView, GeneralExecution, ParkView, PendingView, RunStatus, RunView, ThreadMessage, ThreadSummary, ThreadSurface } from "./types.js";
+import type { Block, CardView, ParkView, PendingView, RunStatus, RunView, ThreadMessage, ThreadSummary, ThreadSurface } from "./thread.js";
+import type { GeneralExecution } from "./workflow.js";
 export declare const MIGRATIONS: {
     version: number;
     up: string;