@multiclawcli/core 0.3.2 → 0.5.0

package/dist/orchestrator/AgentRunner.d.ts

@@ -0,0 +1,19 @@
+import type { EventBus } from "../event/EventBus";
+import type { AgentDefinition, AgentResult } from "../types/agent";
+import type { MultiClawConfig } from "../types/config";
+import type { ContextManager } from "./ContextManager";
+export declare class AgentRunner {
+    private eventBus;
+    private contextManager;
+    private globalWorkDir;
+    private config;
+    constructor(eventBus: EventBus, contextManager: ContextManager, globalWorkDir: string, config: MultiClawConfig);
+    run(agent: AgentDefinition, signal?: AbortSignal): Promise<AgentResult>;
+    /**
+     * Publish one chunk of agent output.
+     *
+     * `kind` is omitted for text so the payload shape is unchanged for every
+     * consumer written before tool activity was surfaced.
+     */
+    private emitOutput;
+}

package/dist/orchestrator/ContextManager.d.ts

@@ -0,0 +1,7 @@
+export declare class ContextManager {
+    private store;
+    constructor(initial?: Record<string, string>);
+    set(key: string, value: string): void;
+    get(key: string): string | undefined;
+    snapshot(): Record<string, string>;
+}

package/dist/orchestrator/Orchestrator.d.ts

@@ -0,0 +1,109 @@
+import { EventBus } from "../event/EventBus";
+import type { MultiClawConfig, OrchestrationPreview, OrchestratorResult } from "../types/config";
+export declare class Orchestrator {
+    private config;
+    readonly eventBus: EventBus;
+    private contextManager;
+    private runner;
+    private workDir;
+    constructor(config: MultiClawConfig);
+    preview(options?: {
+        signal?: AbortSignal;
+    }): Promise<OrchestrationPreview>;
+    run(options?: {
+        signal?: AbortSignal;
+    }): Promise<OrchestratorResult>;
+    private stageInfos;
+    /**
+     * Order the agents into stages, degrading to declaration order if the graph is
+     * broken.
+     *
+     * `buildStages` throws on a missing dependency and on a cycle. Letting that
+     * escape would reject `run()` before `orchestration:complete` is emitted, so
+     * the caller sees an unhandled rejection instead of a structured failure. A
+     * bad ordering is not a reason to run nothing.
+     */
+    private buildStagesOrFallback;
+    /**
+     * Drop last run's task plan before the architect gets a chance to write one.
+     *
+     * The console runs every turn against the same workspace, so the plan file
+     * survives between turns. If a turn's architect fails to write a new one,
+     * `applyTaskPlan` would silently re-apply the previous turn's titles, scopes
+     * and dependencies to a completely different requirement.
+     */
+    private clearStaleTaskPlan;
+    /**
+     * Decide what this turn is: a pipeline, an answer, or a question.
+     *
+     * Only the leader can answer that, so without one the configured team is the
+     * whole story. With one, its prose output is *not* a failure mode to be papered
+     * over by running everybody — a leader that answers a greeting has done its
+     * job, and that is what `message` records.
+     */
+    private resolveTurn;
+    /**
+     * The configured team, as copies.
+     *
+     * `applyTaskPlan` writes `taskTitle` / `dependsOn` / `agentScope` onto whatever
+     * objects it is handed. The console reuses a single config across turns, so
+     * returning the config's own objects would leak turn 1's dependency graph into
+     * turn 2 — the exact cross-turn contamination `clearStaleTaskPlan` exists to
+     * prevent, but for the in-memory fields rather than the file.
+     */
+    private configuredAgents;
+    /**
+     * Narrow the configured team to the ids `namedBy` asked for.
+     *
+     * Always a subset: an id that is not in the config is reported and dropped
+     * rather than added, so a typo in a prompt cannot conjure an agent that has no
+     * definition behind it.
+     *
+     * `namedBy` labels the warning. A resume names agents too — with no leader in
+     * the run at all — so blaming "the leader" for a bad resumed id would send the
+     * reader looking in the wrong place.
+     */
+    private selectAgents;
+    private runStage;
+    /**
+     * Whether `agent` owns task decomposition.
+     *
+     * The explicit `role` is the source of truth, so a config can name its planner
+     * anything. The id `"architect"` is kept as a fallback so every config written
+     * before `role` existed keeps working unchanged.
+     */
+    private isPlanner;
+    private applyTaskPlan;
+    /**
+     * The `requirement` field for a result, present only when the caller set one.
+     *
+     * Spread into every result builder so all three outcomes carry it the same
+     * way: a completion event doubles as the report a resume driver reads back,
+     * and a requirement that never reaches the report cannot be resumed.
+     */
+    private requirementField;
+    /**
+     * The `selectionReason` field, present only when the leader explained itself.
+     *
+     * Omitted rather than sent as `undefined`/`""` so a run without an
+     * explanation stays byte-identical to one from before the field existed.
+     */
+    private reasonField;
+    /**
+     * Close out a turn the leader answered rather than planned.
+     *
+     * `success: true` on purpose: the user asked something and got an answer. What
+     * keeps that from reading as a completed pipeline is `reply`, which the console
+     * uses to say "answered" instead of "done".
+     */
+    private finishWithMessage;
+    private warn;
+    /**
+     * Close out a turn that scheduled no agents.
+     *
+     * Reported as a failure rather than a no-op: the user asked for work, and the
+     * only honest outcome is to say that none was done. Running the whole team
+     * instead would contradict the leader's explicit choice.
+     */
+    private finishEmpty;
+}

package/dist/orchestrator/StageBuilder.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types/agent";
+export declare function buildStages(agents: AgentDefinition[]): AgentDefinition[][];

package/dist/providers/bridge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ACP bridges that multiclaw bundles and resolves from its own `node_modules`
+ * rather than requiring the user to install them globally.
+ *
+ * Key = the binary name used in an agent's `command`; value = the npm package
+ * that provides it. `opencode` is deliberately absent: it speaks ACP natively,
+ * so it *is* the user's agent and is installed by the user.
+ */
+export declare const BRIDGE_PACKAGES: Record<string, string>;
+/** True when `command` names an executable file on PATH. */
+export declare function resolvesOnPath(command: string): boolean;
+/**
+ * Resolve a bundled bridge binary to an absolute path inside multiclaw's
+ * installed `node_modules`. Returns null when `command` is not a bridge we
+ * bundle (e.g. a user-supplied binary such as `opencode`).
+ *
+ * This lets multiclaw drive the ACP bridge without it being on the user's PATH:
+ * the user only installs their own agent (`claude` / `codex` / `opencode`), and
+ * multiclaw supplies the thin bridge in front of it.
+ */
+export declare function resolveBridgeBinary(command: string): string | null;
+/**
+ * Resolve the executable multiclaw should spawn for `command`.
+ *
+ * Prefers the user's own install on PATH (this is also what the test suite
+ * relies on — fake binaries are placed on PATH), and falls back to a bridge
+ * multiclaw bundles. Returns null when neither is available.
+ */
+export declare function resolveExecutable(command: string): string | null;

package/dist/providers/catalog.d.ts

@@ -0,0 +1,73 @@
+import type { AgentTask } from "../types/runtime";
+export type ProviderId = "claude" | "opencode" | "codex" | "cursor" | (string & {});
+export type ModelTier = "strong" | "balanced" | "fast";
+export interface ProviderModel {
+    id: string;
+    label: string;
+    tier?: ModelTier;
+    /** True when this model is the default for its tier within this provider. */
+    defaultForTier?: boolean;
+}
+/**
+ * How a provider is told which model to run.
+ *
+ * `"arg"` used to be a member here, but nothing in `AcpRuntime` ever implemented
+ * it — so a provider that declared it silently ran with its own default. It is
+ * gone rather than kept as a dead branch: re-introducing it means also
+ * implementing the `arg` path in `AcpRuntime`, and this note is the cost the
+ * next person to add it back has to pay.
+ */
+export type ModelSelectionMode = "config-option" | "none";
+export interface ProviderSpec {
+    id: ProviderId;
+    label: string;
+    /** Binary to spawn. */
+    command: string;
+    /** Arguments after the binary. */
+    args: string[];
+    /** Additional binary names that resolve to this provider (for detection). */
+    aliases?: string[];
+    /**
+     * Build the `_meta` payload for a session-defining request.
+     * Returns `undefined` when there is nothing to say — the role prompt
+     * then falls back to a prompt prefix.
+     */
+    meta?: (task: AgentTask) => Record<string, unknown> | undefined;
+    /** Whether this provider honours a tool allowlist at all. */
+    tools: boolean;
+    /** How model selection is communicated to the agent. */
+    modelSelection: ModelSelectionMode;
+    /** Models offered by this provider. */
+    models: ProviderModel[];
+    /** Fallback when no tier or explicit model is configured. */
+    defaultModel: string;
+    install: {
+        hint: string;
+        url?: string;
+    };
+    /** Auth prerequisite — shown as a hint, not a hard gate (v1). */
+    auth: {
+        kind: "ambient" | "login" | "api-key" | "none";
+        hint: string;
+    };
+    /**
+     * When the binary name is ambiguous (e.g. cursor's `agent`),
+     * use `--version` output to confirm identity. Mandatory for generic names.
+     */
+    confirm?: (versionOutput: string) => boolean;
+}
+export declare const PROVIDERS: readonly ProviderSpec[];
+/** Lookup a provider by its id. */
+export declare function specForProvider(id: string): ProviderSpec | undefined;
+/**
+ * Lookup a provider by the binary name it is launched with.
+ * Keys on basename (strips paths and Windows suffixes) so
+ * `/opt/bin/claude-agent-acp` and `claude-agent-acp.exe` both hit.
+ */
+export declare function specForCommand(command: string): ProviderSpec | undefined;
+/** All provider ids known to the catalog. */
+export declare function providerIds(): string[];
+/** All commands (primary + aliases) that map to a provider. */
+export declare function providerCommands(): string[];
+/** Resolve a tier to a concrete model id for a given provider. */
+export declare function tierModel(spec: ProviderSpec, tier: ModelTier): string | undefined;

package/dist/providers/detect.d.ts

@@ -0,0 +1,34 @@
+export type ProviderStatus = "present" | "missing";
+/**
+ * Where the executable for a present provider came from.
+ *
+ * `path` is the user's own install on PATH — the expected case. `bundled` means
+ * multiclaw's own `node_modules` supplied the bridge, so the provider works
+ * without the bridge being installed globally; that is worth telling the user,
+ * because "present" then says nothing about what they have installed.
+ */
+export type ProviderSource = "path" | "bundled";
+export interface DetectedProvider {
+    id: string;
+    label: string;
+    command: string;
+    status: ProviderStatus;
+    version?: string;
+    note?: string;
+    /** How the executable resolves. Absent for a missing provider. */
+    source?: ProviderSource;
+    /** Absolute path actually spawned, set only for a bundled bridge. */
+    resolvedPath?: string;
+}
+/**
+ * Discover which providers are installed on this machine.
+ *
+ * Availability comes from PATH lookups (fast, no spawn). When
+ * `withVersion` is true, ambiguous binary names (e.g. cursor's `agent`)
+ * are confirmed via `--version` output.
+ */
+export declare function detectProviders(opts?: {
+    withVersion?: boolean;
+}): Promise<DetectedProvider[]>;
+/** Just the ids of providers that are present. */
+export declare function presentProviders(detected: DetectedProvider[]): string[];

package/dist/providers/index.d.ts

@@ -0,0 +1,4 @@
+export { BRIDGE_PACKAGES, resolveBridgeBinary, resolveExecutable, resolvesOnPath, } from "./bridge";
+export { type ModelSelectionMode, type ModelTier, PROVIDERS, type ProviderId, type ProviderModel, type ProviderSpec, providerCommands, providerIds, specForCommand, specForProvider, tierModel, } from "./catalog";
+export { type DetectedProvider, detectProviders, type ProviderSource, type ProviderStatus, presentProviders, } from "./detect";
+export { resolveAgentRuntime, resolveArgs, resolveCommand, resolveModel, resolveProvider, } from "./resolve";

package/dist/providers/resolve.d.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../types/agent";
+import type { MultiClawConfig } from "../types/config";
+import { type ProviderSpec } from "./catalog";
+/** Resolve the provider id for an agent, falling back through config defaults. */
+export declare function resolveProvider(agent: AgentDefinition, config: MultiClawConfig): string;
+/** Resolve the launch command for an agent. */
+export declare function resolveCommand(agent: AgentDefinition, config: MultiClawConfig): string;
+/**
+ * Resolve the launch arguments for an agent.
+ *
+ * Paired with {@link resolveCommand}: the catalog carries per-provider args
+ * (`opencode acp` needs `["acp"]`, the bundled bridges need `[]`), so leaving
+ * `args` undefined would let the runtime fall back to its `["acp"]` default and
+ * launch e.g. `claude-agent-acp acp`. Returns undefined for a truly custom
+ * command so the runtime's default still applies.
+ */
+export declare function resolveArgs(agent: AgentDefinition, config: MultiClawConfig): string[] | undefined;
+/** Resolve the model id an agent will actually run with. */
+export declare function resolveModel(agent: AgentDefinition, config: MultiClawConfig): string | undefined;
+/** Convenience: full resolution in one call. */
+export declare function resolveAgentRuntime(agent: AgentDefinition, config: MultiClawConfig): {
+    provider: string;
+    command: string;
+    model: string | undefined;
+    spec: ProviderSpec | undefined;
+};

package/dist/runtime/AcpRuntime.d.ts

@@ -0,0 +1,17 @@
+import type { AgentOutput, AgentTask, RuntimeInfo, RuntimeQuery } from "../types/runtime";
+import { RuntimeBase } from "./RuntimeBase";
+/**
+ * Grace period between SIGTERM and SIGKILL when an agent will not stop.
+ *
+ * This is time a single attempt can still consume *after* its `timeout`: the
+ * inner timeout fires a SIGTERM, and a child that ignores it is not reaped until
+ * this grace elapses — the reject itself lands on the child's `close`. A caller
+ * that budgets for a whole retry sequence must therefore add this to the
+ * per-attempt timeout, or its "upper bound" is not one (see `retryBudgetMs`).
+ */
+export declare const KILL_ESCALATION_MS = 3000;
+export declare class AcpRuntime extends RuntimeBase {
+    readonly name = "acp";
+    describe(options?: RuntimeQuery): Promise<RuntimeInfo>;
+    execute(task: AgentTask): Promise<AgentOutput>;
+}

package/dist/runtime/RuntimeBase.d.ts

@@ -0,0 +1,6 @@
+import type { AgentOutput, AgentRuntime, AgentTask, RuntimeInfo, RuntimeQuery } from "../types/runtime";
+export declare abstract class RuntimeBase implements AgentRuntime {
+    abstract readonly name: string;
+    abstract describe(options?: RuntimeQuery): Promise<RuntimeInfo>;
+    abstract execute(task: AgentTask): Promise<AgentOutput>;
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,12 @@
+import type { AgentRuntime } from "../types/runtime";
+import { AcpRuntime, KILL_ESCALATION_MS } from "./AcpRuntime";
+declare class RuntimeRegistry {
+    private runtimes;
+    constructor();
+    register(r: AgentRuntime): void;
+    get(name: string): AgentRuntime;
+    has(name: string): boolean;
+    list(): string[];
+}
+export declare const runtimeRegistry: RuntimeRegistry;
+export { AcpRuntime, KILL_ESCALATION_MS };

package/dist/types/agent.d.ts

@@ -0,0 +1,96 @@
+import type { AgentOutput } from "./runtime";
+export type ToolName = "Read" | "Write" | "Edit" | "MultiEdit" | "Bash" | "Glob" | "Grep" | "WebFetch";
+export interface AgentDefinition {
+    id: string;
+    name: string;
+    icon?: string;
+    runtime?: string;
+    /**
+     * Agent product (e.g. "claude", "opencode", "codex", "cursor").
+     * Distinct from `runtime` (the protocol, always "acp" today).
+     * When absent it is inferred from `command` or config defaults.
+     */
+    provider?: string;
+    /**
+     * Command to launch for this agent's runtime, when the runtime talks to an
+     * external process (e.g. ACP). Generic — "which binary to start", not a
+     * protocol detail — so a built-in runtime simply ignores it.
+     */
+    command?: string;
+    /** Arguments for {@link command}. */
+    args?: string[];
+    model?: string;
+    /**
+     * Map of provider ids (or the legacy alias "acp") to model names.
+     * Provider id is preferred; "acp" is kept for backward compatibility.
+     */
+    models?: Partial<Record<string, string>>;
+    /**
+     * Model tier preference. Used when `model` and `models` are absent.
+     * The catalog maps each tier to a provider-specific model id.
+     */
+    modelTier?: "strong" | "balanced" | "fast";
+    systemPrompt: string;
+    taskPrompt: string;
+    /**
+     * One-line role, for display. Every built-in agent declares one.
+     *
+     * Distinct from {@link taskTitle}, which the orchestrator fills in per turn
+     * from the leader's task plan — "what this agent was asked to do *this* run".
+     * A `description` is "what this agent is for", so it is the one that is still
+     * available before the first turn has been planned.
+     */
+    description?: string;
+    /**
+     * Marks the agent that owns task decomposition (writes task-plan.json).
+     * When absent, the orchestrator falls back to the id "architect" so every
+     * existing config keeps working unchanged.
+     */
+    role?: "planner";
+    taskTitle?: string;
+    agentScope?: string;
+    agentPlan?: string;
+    tools?: ToolName[];
+    dependsOn?: string[];
+    timeout?: number;
+    retries?: number;
+    workDir?: string;
+}
+export type AgentStatus = "pending" | "running" | "retrying" | "success" | "failed"
+/**
+ * The run was stopped by its AbortSignal rather than finishing or erroring.
+ * Distinct from `failed` so a Ctrl-C does not read as a crash, and so the
+ * roster can mark the agent stopped instead of broken.
+ */
+ | "cancelled" | "skipped";
+export interface AgentResult {
+    agentId: string;
+    agentName: string;
+    status: AgentStatus;
+    output: string;
+    duration: number;
+    attempts: number;
+    error?: string;
+    startTime: string;
+    endTime: string;
+    /** Model actually requested for this agent. */
+    model?: string;
+    /** Context-window usage the runtime reported; absent when it reported none. */
+    usage?: AgentOutput["usage"];
+    /** USD cost the runtime reported; absent when the provider does not price in USD. */
+    costUsd?: number;
+    /** Session the runtime ran under, when it reported one. */
+    sessionId?: string;
+}
+export interface SubTask {
+    id: string;
+    title: string;
+    scope: string;
+    plan?: string[];
+    dependsOn?: string[];
+}
+export interface TaskPlan {
+    projectName: string;
+    requirement: string;
+    tasks: SubTask[];
+}

package/dist/types/config.d.ts

@@ -0,0 +1,126 @@
+import type { AgentDefinition } from "./agent";
+import type { LeaderMessage } from "./leader";
+/**
+ * One finished turn of a session, as dialogue the leader can read back.
+ *
+ * A requirement alone is not always interpretable: when the leader asked "which
+ * database?" and the user answered "Postgres", turn two's requirement is the
+ * bare word "Postgres". Paired with the turn that produced the question it is
+ * obvious; on its own it is not.
+ */
+export interface TurnRecord {
+    /** What the user asked for. */
+    requirement: string;
+    /** How the turn ended in words, when it ended that way. */
+    reply?: LeaderMessage;
+}
+export interface MultiClawConfig {
+    name: string;
+    workDir: string;
+    leader?: AgentDefinition;
+    agents: AgentDefinition[];
+    context?: Record<string, string>;
+    /**
+     * Earlier turns of this session, oldest first.
+     *
+     * Core has no notion of a session — the orchestrator is built fresh per turn —
+     * so whoever runs several turns in a row (the console) is the one that has to
+     * carry them. Rendered into the leader's prompt; a single-turn run leaves it
+     * unset and sees no conversation at all.
+     */
+    history?: TurnRecord[];
+    /**
+     * Re-run a known set of agents instead of letting the leader route, continuing
+     * their sessions where one is known.
+     *
+     * Set by a resume/retry driver — the CLI's `--resume`, the console's `/retry` —
+     * which already knows which agents to redo. Like `history`, it is per-run state
+     * the caller carries: core has no session of its own, and a config that never
+     * resumes leaves it unset and behaves exactly as before.
+     */
+    resume?: {
+        /** Agent ids to run, in the order they were originally selected. */
+        agents: string[];
+        /** agentId → session id, for agents whose session is worth continuing. */
+        sessions?: Record<string, string>;
+    };
+    logDir?: string;
+    continueOnError?: boolean;
+    maxConcurrency?: number;
+    useLeader?: boolean;
+    /**
+     * Project-level defaults applied to every agent that does not override them.
+     * Keeps generated configs readable: one line instead of 12 repeated parameters.
+     */
+    defaults?: {
+        provider?: string;
+        model?: string;
+        command?: string;
+    };
+}
+export interface OrchestrationPreview {
+    name: string;
+    requirement?: string;
+    totalAgents: number;
+    stages: import("./event").StageInfo[];
+    /** Present when the leader answered or asked instead of choosing a pipeline. */
+    reply?: LeaderMessage;
+    /** The leader's explanation for the agent set, when it gave one. */
+    selectionReason?: string;
+}
+export interface DeliverableSummary {
+    /** Path relative to the run work directory. */
+    path: string;
+    status: "created" | "modified";
+    size: number;
+    modifiedAt: string;
+}
+export interface OrchestratorResult {
+    name: string;
+    success: boolean;
+    totalDuration: number;
+    agentResults: import("./agent").AgentResult[];
+    startTime: string;
+    endTime: string;
+    /**
+     * Set when the run was stopped via its AbortSignal. Cancellation is a third
+     * outcome, not a flavour of failure: the team stopped because it was told to.
+     * It still reports `success: false` — a run that never finished must not exit
+     * 0 — but the console says "cancelled" rather than "failed", and the CLI can
+     * exit with the conventional 130.
+     */
+    cancelled?: boolean;
+    /**
+     * Set when the turn ended in words instead of a pipeline — the leader answered
+     * or asked a question, so no agent ran. Without it, "the team worked and
+     * succeeded" and "nobody worked" look identical: both are `success: true` with
+     * an empty `agentResults`.
+     */
+    reply?: LeaderMessage;
+    /**
+     * The leader's explanation for the agent set it selected, when it gave one.
+     *
+     * This is orchestration metadata, not agent state: it answers "why did this
+     * turn run these agents?" without asking the leader again. Absent for a
+     * resumed run, a leader-less run, and any leader that omitted the field.
+     */
+    selectionReason?: string;
+    /**
+     * Sum of the per-agent costs that were actually reported, in USD.
+     *
+     * Present only when at least one agent reported a cost — "no data" is not the
+     * same as "free", so a run in which nobody priced itself must leave this
+     * `undefined` rather than reporting `0`.
+     */
+    totalCostUsd?: number;
+    /**
+     * The requirement this turn was run for, when the caller supplied one.
+     *
+     * Carried on the result because the completion event *is* the report a resume
+     * driver reads back: without it, a resumed run has no way to recover the
+     * requirement it is continuing.
+     */
+    requirement?: string;
+    /** Files created or modified by this run, when the caller collected them. */
+    deliverables?: DeliverableSummary[];
+}