@bakers-build/conductor 0.0.0-stage → 0.1.0-next.42

package/dist/src/plugins/agent.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Per-agent effort footprint parsed from that agent's run transcript
+ * (BB-132). The metrics are transcript-derived and therefore
+ * **agent-specific** (each agent's transcript has its own format), so parsing
+ * lives behind the agent abstraction (see {@link BbAgent.parseFootprint}) —
+ * the conductor stays agent-agnostic and writes the footprint verbatim.
+ * `duration_s` is likewise derived from the transcript (its first→last entry
+ * timestamps), NOT recomputed by the conductor from a re-read `started_at`
+ * (BB-151): the log is the single source of the run's wall-clock length, so
+ * there is no timestamp round-trip through JSON:API to mis-parse.
+ */
+export interface AgentFootprint {
+    /** Total tokens across every usage bucket of every assistant turn. */
+    tokens: number;
+    /**
+     * Wall-clock run length in seconds, derived from the transcript's first→last
+     * entry timestamps (BB-151). 0 when the transcript has fewer than two
+     * timestamped entries (empty/absent log).
+     */
+    duration_s: number;
+    /** Number of assistant turns in the transcript. */
+    agent_turns: number;
+    /** Number of tool-use calls across all assistant turns. */
+    tool_calls: number;
+    /** Number of user-submitted prompts. */
+    user_prompts: number;
+    /** Total words across those user prompts. */
+    user_prompt_words: number;
+    /**
+     * Active agent time in seconds: `duration_s` minus the time spent waiting on
+     * the human, so the wait is `duration_s - active_s`. 0 means not measured,
+     * which is also what harnesses without a net-time parser report.
+     */
+    active_s: number;
+    /** Model of the last assistant turn, when present (informational). */
+    model?: string;
+}
+/** An all-zero footprint — the honest result for an empty/absent transcript. */
+export declare function emptyAgentFootprint(): AgentFootprint;
+/**
+ * A bakers.build agent: the program the conductor runs to work a ticket (e.g. claude).
+ * It knows how it is launched (CLI + model + flags) and where its per-run
+ * transcript/log lives — so the conductor stays agent-agnostic and the CLI can
+ * attach the run log on release without agent-specific knowledge.
+ */
+/**
+ * Identity of the run a transcript lookup is scoped to (BB-473): the run's
+ * own UUID (usable as a session id by agents that support pinning one) and,
+ * optionally, when the run started (a lower bound for agents with no session
+ * mechanism at all, so a stale transcript from a prior run in the same
+ * worktree/cwd can never be selected). Both fields are optional so a call
+ * site or addon that predates BB-473 keeps compiling and behaving exactly
+ * as before (today's mtime/cwd-scan fallback).
+ */
+export interface AgentRunIdentity {
+    sessionId: string;
+    startedAt?: string | number | Date;
+    /**
+     * The run's full deterministic attempt-id family (BB-473 review round 4,
+     * Critical 2), attempt 0 (== `sessionId`) first. When present, `getRunLog`
+     * should select the transcript of the HIGHEST-numbered attempt whose file
+     * actually exists, instead of the `startedAt` time window — a window
+     * selects by *when*, which a sibling session newer than the bound can
+     * still beat; a family selects by *which attempt*, which nothing outside
+     * this run can collide with. Omitted, callers keep the pre-round-4
+     * single-`sessionId` behaviour.
+     */
+    attemptFamily?: string[];
+}
+export interface BbAgent {
+    /** Stable id, e.g. 'claude'. */
+    readonly id: string;
+    /**
+     * Informational notes the conductor logs once per dispatch, before
+     * `startRun`. Unsupported effort on a harness that cannot express it is
+     * the current producer. Omitted when there is nothing to say.
+     */
+    readonly launchWarnings?: readonly string[];
+    /**
+     * Build the full agent CLI invocation for a bakers.build prompt. With an empty
+     * prompt, returns the bare launch command (no prompt argument).
+     *
+     * `run`, when given (BB-473), lets an agent that supports pinning its own
+     * session/transcript id do so at launch (e.g. `claude --session-id
+     * <uuid>`), so `getRunLog` can read that one file directly instead of
+     * scanning a worktree-keyed directory by mtime — the mtime scan is what let
+     * a resumed/re-dispatched/reused worktree finalise a FOREIGN transcript.
+     */
+    launchCommand(prompt: string, run?: AgentRunIdentity): string;
+    /**
+     * Locate and read this agent's run transcript for a run that executed in
+     * `worktreePath`. MUST return '' (never throw) when nothing is found.
+     *
+     * `run`, when given (BB-473), scopes the lookup to that run's own
+     * transcript — by direct filename lookup for agents that support pinning a
+     * session id at launch, or (for agents with no such mechanism) by
+     * discarding any transcript older than `run.startedAt`. Omitted, the call
+     * preserves today's directory-scan-by-mtime behaviour.
+     */
+    getRunLog(worktreePath: string, run?: AgentRunIdentity): Promise<string>;
+    /**
+     * Whether this agent already owns a transcript/session named `sessionId`
+     * under `worktreePath` (BB-473). Some CLIs refuse to start when a
+     * `--session-id` they are handed is already in use (`claude`, `grok`), so
+     * the conductor calls this **before** pinning the run's own UUID into
+     * `launchCommand` — a live re-dispatch of the same run must still be able
+     * to launch, even though the UUID it would pin already names a transcript
+     * from the run's first attempt. Optional: an agent whose launch mechanism
+     * cannot collide (no pinning at all, or a CLI that creates-if-missing like
+     * `pi`) declares none, and the conductor always pins for it.
+     */
+    sessionExists?(worktreePath: string, sessionId: string): Promise<boolean>;
+    /**
+     * Parse this agent's run transcript (as returned by {@link getRunLog}) into
+     * a footprint of effort metrics (BB-132). The transcript format is
+     * agent-specific, so each agent owns its own parser. MUST be tolerant of
+     * blank/partial/absent input (never throw) — an empty log yields
+     * {@link emptyAgentFootprint}.
+     */
+    parseFootprint(log: string): AgentFootprint;
+}

package/dist/src/plugins/agent.js

@@ -0,0 +1,12 @@
+/** An all-zero footprint — the honest result for an empty/absent transcript. */
+export function emptyAgentFootprint() {
+    return {
+        tokens: 0,
+        duration_s: 0,
+        agent_turns: 0,
+        tool_calls: 0,
+        user_prompts: 0,
+        user_prompt_words: 0,
+        active_s: 0,
+    };
+}

package/dist/src/plugins/executor.d.ts

@@ -0,0 +1,182 @@
+import type { Ticket } from './remote.js';
+export interface SpawnedSession {
+    sessionRef: string;
+}
+export interface ExecutorCapabilities {
+    persistent: boolean;
+}
+export interface SpawnRunInput {
+    ticket: {
+        uuid: string;
+        identifier: string;
+        title: string;
+        branchName: string;
+        state: string;
+        url?: string;
+    };
+    run: {
+        uuid: string;
+        id: number;
+        handler: string;
+    };
+    workspacePath: string;
+    instructions: {
+        path: string;
+        sha256: string;
+        text: string;
+    } | null;
+    command?: string;
+    env?: Record<string, string>;
+}
+/** The lifecycle-hook slots, keyed exactly like `config.hooks`. */
+export type HookName = 'after_create' | 'before_run' | 'after_run' | 'after_done' | 'on_freeze' | 'on_resume';
+/**
+ * What an addon hook listener receives (BB-599). One context object is
+ * shared by every listener of one dispatch, so a key a `before_run` listener
+ * adds to `env` reaches the next listener, that slot's shell hook and the
+ * agent launch. Reserved keys (`BB_*`, `WORKSPACE_ROOT`, `TICKET_URL`) and
+ * invalid entries are restored after each listener. `env` values may be
+ * secret: never log them.
+ *
+ * At `after_run` and `after_done` the context is rebuilt from the current
+ * ticket and the durable run record, not from a launch-time snapshot — a
+ * listener must find what it started by `run.uuid`, not by a captured value.
+ */
+export interface HookListenerContext {
+    /** Absolute path of the ticket's worktree (the hook's cwd). */
+    worktreePath: string;
+    ticket: Ticket;
+    /** The run's state at start; at `after_done` the ticket's current state. */
+    state: string;
+    env: Record<string, string>;
+    /** The run this slot belongs to; absent at `after_done` without a run. */
+    run?: {
+        uuid: string;
+        id?: number;
+    };
+}
+/** A listener's callback for one slot. Awaited; a failure is logged, never fatal. */
+export type HookListenerFn = (ctx: HookListenerContext) => void | Promise<void>;
+/**
+ * One addon contribution to the conductor `hooks` accumulator (BB-599): an
+ * object with an optional function per lifecycle slot. Listeners run in
+ * accumulator order, each before the slot's project shell hook.
+ */
+export type HookListener = {
+    [K in HookName]?: HookListenerFn;
+} & {
+    /** Names the listener in conductor logs. */
+    id?: string;
+};
+/** Context for a hook invocation — carries the ticket for observable logging. */
+export interface HookContext {
+    /** The ticket identifier/uuid the hook is running for (log context). */
+    ticket: string;
+}
+/**
+ * What a lifecycle hook invocation DID (BB-237). `runHook` still never throws,
+ * but it no longer swallows the outcome silently: it reports it, so a caller can
+ * record a failed provisioning hook against the run it is about to dispatch
+ * instead of relying on a log line to survive (AC-6). Reporting — rather than
+ * throwing — keeps the never-wedge property that the never-throw contract exists
+ * for; boundedness stays with the conductor's circuit breaker.
+ */
+export interface HookResult {
+    /** The hook slot that was invoked. */
+    hook: HookName;
+    /** false when no command is configured for the slot — nothing ran. */
+    ran: boolean;
+    /** false ONLY when a configured command actually failed. */
+    ok: boolean;
+    /** The stringified failure; present iff `ok` is false. */
+    error?: string;
+}
+/**
+ * Outcome of a worktree teardown (BB-293).
+ *
+ * - `removed`        — the worktree was torn down on this host, or the prunable
+ *                      admin entry it left behind was swept.
+ * - `already_absent` — nothing to tear down: neither git nor the filesystem
+ *                      still has it. A FINISHED teardown, not a failure.
+ * - `unverified`     — it could not be resolved or removed and may still be on
+ *                      disk; the reaper leaves the ticket on its work list.
+ *
+ * Replaces the former `boolean`, which could not distinguish "gone because we
+ * removed it" from "gone before we got here" — the distinction the reaper needs
+ * in order to record the absence rather than swallow it. The mapping preserves
+ * the old semantics exactly: `removed` is the old `true`, `unverified` the old
+ * `false`.
+ */
+export type WorktreeTeardown = 'removed' | 'already_absent' | 'unverified';
+export interface BbExecutor {
+    id: string;
+    capabilities(): ExecutorCapabilities;
+    /**
+     * Run the lifecycle hook `name` (command from `config.hooks[name]`) in `cwd`,
+     * best-effort. This is the SINGLE catch point for all lifecycle hooks:
+     *
+     * - MUST NEVER throw. No configured command → silent no-op. A failing command
+     *   → `logger.error({hook,worktree,ticket,err}, 'lifecycle hook failed')` then
+     *   return. So a hook failure never aborts dispatch or wedges a run in
+     *   `claimed`.
+     * - The underlying shell command still fails honestly (a non-zero exit
+     *   rejects); only the executor catches + logs + continues.
+     * - MUST report the outcome as a {@link HookResult} (BB-237): never throwing
+     *   is not the same as never telling. The caller decides what a failure means
+     *   for the run it is dispatching; the executor only refuses to abort.
+     *
+     * `env`, when given, is the run's resolved environment (per-ticket env_vars
+     * merged with the core BB_* vars, BB-99), merged over the hook process's
+     * inherited env. Values may be sensitive — implementations must never log
+     * them (log key names only).
+     */
+    runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<HookResult>;
+    startRun(input: SpawnRunInput): Promise<SpawnedSession>;
+    /**
+     * Signal the run's agent to stop. Called by the conductor's run-finalise pass
+     * BEFORE it captures the agent transcript (BB-132), so a stop must not
+     * destroy the log. For herdr this is a NO-OP: at finalise time the agent is
+     * idle and its jsonl transcript is already fully written to disk, and the
+     * subsequent {@link cleanupRun} tab-close kills the PTY (the agent dies with
+     * it). The seam exists for executors whose agent outlives its UI surface.
+     * Best-effort; gated by the conductor on `capabilities().persistent`.
+     */
+    stopRun(branch: string): Promise<void>;
+    /**
+     * Tear down ONE run's hosted UI surface — for herdr, close only the tab whose
+     * label carries the `#<runId>` token (`startRun` labels every tab
+     * `<identifier> · <state> #<run.id>`), via `herdr tab close <tab_id>` (killing
+     * that PTY). Run-scoped by design (BB-183): a sibling run's tab in the same
+     * branch workspace — a still-open prior-state run or a concurrent re-claim —
+     * and any non-run tab are left untouched. Called as the LAST finalisation step,
+     * strictly after the transcript is captured, and again at dispatch to clear a
+     * reused workspace's leftover tab for the run being (re-)started. No matching
+     * tab → a quiet no-op. Does NOT touch the branch worktree (that is the
+     * reap/{@link removeWorktree} lifecycle). Best-effort: a failing tab-close is
+     * swallowed and never aborts finalisation or dispatch. A no-op for
+     * non-persistent executors.
+     */
+    cleanupRun(branch: string, runId: number): Promise<void>;
+    /**
+     * Tear down the branch's entire worktree (git worktree + hosted workspace),
+     * reclaiming its disk. Called by the conductor's ticket-cleanup pass once a
+     * ticket is done. A no-op for non-persistent executors (no hosted workspace);
+     * the conductor gates the call on `capabilities().persistent`.
+     *
+     * `worktreePath` is the stable, identifier-derived worktree path (from the
+     * ticket's latest run). Prefer it over `branch` to resolve the worktree: the
+     * checked-out branch is mutable (the coding agent may rename/switch it), the
+     * path is not.
+     *
+     * Reports what the teardown DID as a {@link WorktreeTeardown} (BB-293):
+     * `removed` when the worktree was present on this host and torn down (or its
+     * prunable admin entry swept), `already_absent` when there was nothing to
+     * tear down at all, and `unverified` when nothing matched here and the
+     * worktree may still be on disk (another conductor's host, or a path that
+     * could not be resolved). The reaper flags a ticket `cleaned_up` for the
+     * first two and leaves it on the work list for `unverified`, so it never
+     * false-teardowns a worktree another host physically holds. A genuine
+     * failure still throws (surfaced as a teardown miss).
+     */
+    removeWorktree(branch: string, worktreePath?: string): Promise<WorktreeTeardown>;
+}

package/dist/src/plugins/executor.js

@@ -0,0 +1 @@
+export {};

package/dist/src/plugins/message.d.ts

@@ -0,0 +1,61 @@
+import type { ConductorLogger } from '@bakers-build/core';
+import { type MessageDefinition, type MessageResult } from '@bakers-build/message';
+import type { Ticket } from './remote.js';
+/** What a handler gets: its own request identity plus the ticket's worktree. */
+export interface InboxMessageRequest {
+    /** The bb_inbox_message entity UUID; the request's own identity, never the message type. */
+    id: string;
+    /** The namespaced message type, e.g. `ports.tunnel`. */
+    messageType: string;
+    addonVersion: string;
+    requestedBy: string;
+    ticket: Ticket;
+    payload?: Record<string, unknown>;
+    worktreePath: string;
+    env: Record<string, string>;
+    logger: ConductorLogger;
+    /** Aborts when the handler runs past its timeout. */
+    signal: AbortSignal;
+}
+export type InboxMessageHandler = (request: InboxMessageRequest) => Promise<MessageResult>;
+/** An addon preset's `inbox` export. */
+export interface InboxMessages {
+    contract: 2;
+    label?: string;
+    /** Inline SVG markup, at most 8192 characters; shown as an image only. */
+    icon?: string;
+    messages: Record<string, MessageDefinition>;
+    /** Lazy: imported only when the conductor loads the addon. */
+    handlers: (options?: unknown) => Promise<Record<string, InboxMessageHandler>>;
+}
+/** One `inbox` export as discovery found it. */
+export interface DiscoveredInbox {
+    name: string;
+    version: string;
+    inbox: InboxMessages;
+    /** The addon entry's `with` options, handed to `inbox.handlers`. */
+    options?: unknown;
+}
+/** A validated inbox addon with its handlers resolved. */
+export interface LoadedInbox {
+    name: string;
+    version: string;
+    label: string | undefined;
+    icon?: string;
+    messages: Record<string, MessageDefinition>;
+    handlers: Record<string, InboxMessageHandler>;
+}
+/**
+ * Validates every declared message definition, checks that handlers and
+ * declared message types match one to one, and rejects a contract other than
+ * 2. `handlers` gets `options` (the addon entry's `with`). Throws an Error naming
+ * the addon on any violation.
+ */
+export declare function loadInbox(found: DiscoveredInbox, options?: unknown): Promise<LoadedInbox>;
+/** Validates a request's payload against its message's input schema. */
+export declare function validateRequestPayload(messages: Record<string, MessageDefinition>, messageType: string, payload: unknown): {
+    ok: true;
+} | {
+    ok: false;
+    errors: string[];
+};

package/dist/src/plugins/message.js

@@ -0,0 +1,47 @@
+// The InboxMessageHandler contract on the conductor surface: an addon's
+// preset may export `inbox` — a map of message types plus LAZY handlers, so
+// a command-only load never imports them. Contract 2 replaces the retired
+// `actions`/views/rows contract (BB-661): this is the only live inbox
+// contract.
+import { MESSAGE_CONTRACT_VERSION, validateArgs, validateMessageDefinition, } from '@bakers-build/message';
+/**
+ * Validates every declared message definition, checks that handlers and
+ * declared message types match one to one, and rejects a contract other than
+ * 2. `handlers` gets `options` (the addon entry's `with`). Throws an Error naming
+ * the addon on any violation.
+ */
+export async function loadInbox(found, options) {
+    const fail = (msg) => new Error(`addon ${found.name}: ${msg}`);
+    if (found.inbox.contract !== MESSAGE_CONTRACT_VERSION)
+        throw fail(`unsupported inbox contract ${found.inbox.contract}`);
+    for (const [key, def] of Object.entries(found.inbox.messages)) {
+        const valid = validateMessageDefinition(def);
+        if (!valid.ok)
+            throw fail(`messages.${key}: ${valid.errors.join('; ')}`);
+    }
+    const handlers = await found.inbox.handlers(options);
+    const declared = Object.keys(found.inbox.messages);
+    for (const key of declared) {
+        if (typeof handlers[key] !== 'function')
+            throw fail(`no handler for message ${key}`);
+    }
+    for (const key of Object.keys(handlers)) {
+        if (!declared.includes(key))
+            throw fail(`handler ${key} is not declared`);
+    }
+    return {
+        name: found.name,
+        version: found.version,
+        label: found.inbox.label,
+        ...(found.inbox.icon !== undefined ? { icon: found.inbox.icon } : {}),
+        messages: found.inbox.messages,
+        handlers,
+    };
+}
+/** Validates a request's payload against its message's input schema. */
+export function validateRequestPayload(messages, messageType, payload) {
+    const def = messages[messageType];
+    if (!def)
+        return { ok: false, errors: [`unknown message type ${messageType}`] };
+    return validateArgs(def.input, payload);
+}

package/dist/src/plugins/plugins.d.ts

@@ -0,0 +1,96 @@
+import type { AgentRoutes, ConductorLogger } from '@bakers-build/core';
+import type { DropSHPlugin } from 'dropsh/plugin';
+import type { ConductorFileConfig } from '../types.js';
+import type { BbAgent } from './agent.js';
+import type { BbExecutor } from './executor.js';
+import type { BbRemote, Ticket } from './remote.js';
+import type { BbWorkspace } from './workspace.js';
+/** Runtime dependencies handed to a plugin factory at selection time. */
+export interface ExecutorDeps {
+    /** The in-scope conductor logger — the executor logs hook failures through it. */
+    logger: ConductorLogger;
+}
+export interface RemotePlugin extends DropSHPlugin {
+    readonly kind: 'remote';
+    readonly id: string;
+    readonly requiredModules: string[];
+    createRemote(config: ConductorFileConfig): Promise<BbRemote>;
+}
+export interface ExecutorPlugin extends DropSHPlugin {
+    readonly kind: 'executor';
+    readonly id: string;
+    readonly requiredModules: string[];
+    createExecutor(config: ConductorFileConfig, deps: ExecutorDeps): Promise<BbExecutor>;
+}
+export interface WorkspacePlugin extends DropSHPlugin {
+    readonly kind: 'workspace';
+    readonly id: string;
+    readonly requiredModules: string[];
+    /**
+     * BB-234: `deps` is **optional** so every existing workspace plugin
+     * (`addon-workspace-git`, `addon-fake`) keeps compiling untouched — a
+     * workspace that logs nothing simply ignores it. It reuses {@link ExecutorDeps}
+     * rather than minting a `WorkspaceDeps` alias: that interface is already the
+     * contract's name for "runtime deps handed to a plugin factory", and a second
+     * identical shape would be two names for one thing.
+     */
+    createWorkspace(config: ConductorFileConfig, deps?: ExecutorDeps): Promise<BbWorkspace>;
+}
+export interface AgentPlugin extends DropSHPlugin {
+    readonly kind: 'agent';
+    readonly id: string;
+    readonly requiredModules: string[];
+    createAgent(config: ConductorFileConfig): Promise<BbAgent>;
+}
+/** Resolves the remote from its named config slot. */
+export declare function selectRemote(config: ConductorFileConfig): Promise<BbRemote>;
+/** Resolves the executor from its named config slot, injecting the logger. */
+export declare function selectExecutor(config: ConductorFileConfig, logger: ConductorLogger): Promise<BbExecutor>;
+/**
+ * Resolves the workspace from its named config slot, injecting the logger when
+ * the caller has one — mirroring {@link selectExecutor}. Without it the herdr
+ * workspace's best-effort open-layout warn would land on a noop logger
+ * (BB-234).
+ */
+export declare function selectWorkspace(config: ConductorFileConfig, logger?: ConductorLogger): Promise<BbWorkspace>;
+/** A config-side agent choice: an agent plugin + an optional static priority over the ticket. */
+export interface AgentCandidate {
+    alias?: string;
+    description?: string;
+    model?: string;
+    modelVersion?: string;
+    agent: AgentPlugin;
+    priority?: (ticket: Ticket) => number;
+}
+/** A constructed candidate: the agent id, its BbAgent, and the config-side priority. */
+export interface ResolvedAgent {
+    alias?: string;
+    description?: string;
+    /** The candidate's configured model, when it pins one. Preferred over the
+     * transcript-derived model at run close, because an explicit human answer
+     * beats a guess; absent when the harness's own local configuration chooses
+     * the model, in which case the transcript's raw model id is used instead. */
+    model?: string;
+    /** The candidate's configured exact model version, when it pins one.
+     * Preferred over the transcript-derived version at run close for the same
+     * reason as `model`; absent when the transcript's raw model id should be
+     * used instead. */
+    modelVersion?: string;
+    id: string;
+    agent: BbAgent;
+    priority?: (ticket: Ticket) => number;
+}
+/**
+ * Pick the agent for a ticket: highest `priority(ticket)` wins; a candidate with
+ * no `priority` scores lowest; ties resolve by config array order (stable sort).
+ */
+export declare function selectAgent(candidates: ResolvedAgent[], ticket: Ticket): ResolvedAgent;
+/** Constructs every agent candidate from the normalized effective catalog. */
+export declare function selectAgents(config: ConductorFileConfig): Promise<ResolvedAgent[]>;
+/** Resolve logical aliases without changing the legacy priority selector. */
+export declare function resolveAgent(candidates: ResolvedAgent[], ticket: Ticket, options?: {
+    warn?: (message: string) => void;
+    selectAgent?: ConductorFileConfig['selectAgent'];
+    routes?: AgentRoutes;
+    defaultAgent?: string;
+}): ResolvedAgent;

package/dist/src/plugins/plugins.js

@@ -0,0 +1,120 @@
+/** Resolves the remote from its named config slot. */
+export async function selectRemote(config) {
+    return config.remote.createRemote(config);
+}
+/** Resolves the executor from its named config slot, injecting the logger. */
+export async function selectExecutor(config, logger) {
+    return config.executor.createExecutor(config, { logger });
+}
+/**
+ * Resolves the workspace from its named config slot, injecting the logger when
+ * the caller has one — mirroring {@link selectExecutor}. Without it the herdr
+ * workspace's best-effort open-layout warn would land on a noop logger
+ * (BB-234).
+ */
+export async function selectWorkspace(config, logger) {
+    return config.workspace.createWorkspace(config, logger ? { logger } : undefined);
+}
+/** A missing `priority` scores strictly below any real number (AC-4). */
+const DEFAULT_PRIORITY = Number.NEGATIVE_INFINITY;
+/**
+ * Pick the agent for a ticket: highest `priority(ticket)` wins; a candidate with
+ * no `priority` scores lowest; ties resolve by config array order (stable sort).
+ */
+export function selectAgent(candidates, ticket) {
+    const best = candidates
+        .map((c, index) => ({
+        c,
+        index,
+        score: c.priority ? c.priority(ticket) : DEFAULT_PRIORITY,
+    }))
+        .sort((a, b) => b.score - a.score || a.index - b.index)[0];
+    if (!best) {
+        throw new Error('selectAgent: no agent candidates configured');
+    }
+    return best.c;
+}
+/** Constructs every agent candidate from the normalized effective catalog. */
+export async function selectAgents(config) {
+    const candidates = config.agents;
+    return Promise.all(candidates.map(async (c) => ({
+        id: c.agent.id,
+        ...(c.alias !== undefined ? { alias: c.alias } : {}),
+        ...(c.description !== undefined ? { description: c.description } : {}),
+        ...(c.model !== undefined ? { model: c.model } : {}),
+        ...(c.modelVersion !== undefined ? { modelVersion: c.modelVersion } : {}),
+        agent: await c.agent.createAgent(config),
+        ...(c.priority ? { priority: c.priority } : {}),
+    })));
+}
+/** Resolve logical aliases without changing the legacy priority selector. */
+export function resolveAgent(candidates, ticket, options = {}) {
+    if (options.selectAgent)
+        return options.selectAgent(candidates, ticket);
+    const labels = ticket.labels.filter((label) => label.startsWith('agent:'));
+    const scoped = [];
+    const general = [];
+    for (const label of labels) {
+        const [alias, state, extra] = label.slice('agent:'.length).split('@');
+        if (!alias || extra !== undefined)
+            continue;
+        if (state === ticket.state)
+            scoped.push(alias);
+        else if (state === undefined)
+            general.push(alias);
+    }
+    const warn = options.warn ?? console.warn;
+    const routes = options.routes ?? {};
+    const direct = (aliases) => {
+        for (const alias of aliases) {
+            const candidate = candidates.find((c) => c.alias === alias);
+            if (candidate)
+                return candidate;
+            if (routes[alias] !== undefined)
+                continue;
+            warn(`${ticket.identifier}: agent alias '${alias}' is unavailable; trying the next fallback`);
+        }
+        return undefined;
+    };
+    const directCandidate = direct(scoped) ?? direct(general);
+    if (directCandidate)
+        return directCandidate;
+    const resolveRoutes = (names) => {
+        for (const name of names) {
+            if (name === 'default')
+                continue;
+            const route = routes[name];
+            if (route === undefined)
+                continue;
+            const alias = route[ticket.state] ?? route['*'];
+            if (alias === undefined) {
+                warn(`${ticket.identifier}: agent route '${name}' has no entry for '${ticket.state}' or '*'; trying the next fallback`);
+                continue;
+            }
+            const candidate = candidates.find((c) => c.alias === alias);
+            if (candidate)
+                return candidate;
+            warn(`${ticket.identifier}: agent route '${name}' resolves to unavailable alias '${alias}'; trying the next fallback`);
+        }
+        return undefined;
+    };
+    const routeCandidate = resolveRoutes(scoped) ?? resolveRoutes(general);
+    if (routeCandidate)
+        return routeCandidate;
+    const defaultRoute = routes.default;
+    for (const alias of [defaultRoute?.[ticket.state], defaultRoute?.['*']]) {
+        if (alias === undefined)
+            continue;
+        const candidate = candidates.find((c) => c.alias === alias);
+        if (candidate)
+            return candidate;
+        warn(`${ticket.identifier}: agent route 'default' resolves to unavailable alias '${alias}'; trying the next fallback`);
+    }
+    if (options.defaultAgent !== undefined) {
+        const candidate = candidates.find((c) => c.alias === options.defaultAgent);
+        if (candidate)
+            return candidate;
+        warn(`${ticket.identifier}: agent alias '${options.defaultAgent}' is unavailable; trying the next fallback`);
+    }
+    return selectAgent(candidates, ticket);
+}