@multiclawcli/core 0.4.0 → 0.5.1

package/dist/types/event.d.ts

@@ -0,0 +1,115 @@
+import type { AgentResult, OrchestratorResult } from "./index";
+export interface StageInfo {
+    stageIndex: number;
+    agents: Array<{
+        id: string;
+        name: string;
+        icon?: string;
+        model?: string;
+        description?: string;
+        taskTitle?: string;
+    }>;
+}
+export type MultiClawEvent = {
+    type: "orchestration:start";
+    timestamp: string;
+    payload: {
+        name: string;
+        requirement?: string;
+        totalAgents: number;
+        stages: StageInfo[];
+        /** The leader's explanation for the agent set, when it gave one. */
+        selectionReason?: string;
+    };
+} | {
+    /**
+     * The stage list changed after the turn had already started.
+     *
+     * The leader plans first, so `orchestration:start` necessarily carries the
+     * *pre-plan* grouping. Once the architect's task plan is applied the team is
+     * regrouped, and consumers that drew the first grouping need to be told —
+     * otherwise the console shows a pipeline that never ran.
+     */
+    type: "orchestration:stages";
+    timestamp: string;
+    payload: {
+        totalAgents: number;
+        stages: StageInfo[];
+    };
+} | {
+    type: "orchestration:complete";
+    timestamp: string;
+    payload: OrchestratorResult;
+} | {
+    type: "orchestration:warning";
+    timestamp: string;
+    payload: {
+        message: string;
+    };
+} | {
+    type: "stage:start";
+    timestamp: string;
+    payload: {
+        stageIndex: number;
+        agentIds: string[];
+    };
+} | {
+    type: "stage:complete";
+    timestamp: string;
+    payload: {
+        stageIndex: number;
+    };
+} | {
+    type: "agent:start";
+    timestamp: string;
+    payload: {
+        agentId: string;
+        agentName: string;
+        icon?: string;
+        model?: string;
+        taskTitle?: string;
+    };
+} | {
+    type: "agent:output";
+    timestamp: string;
+    payload: {
+        agentId: string;
+        chunk: string;
+        /**
+         * What kind of output this chunk is. Absent means `"text"`, so every
+         * producer and consumer written before this field existed is unchanged.
+         *
+         * - `"text"` — the agent's natural-language output (default)
+         * - `"tool"` — a summary line of tool activity, shown by default
+         * - `"tool-detail"` — a successful tool's detail, shown only in verbose mode
+         */
+        kind?: "text" | "tool" | "tool-detail";
+    };
+} | {
+    type: "agent:complete";
+    timestamp: string;
+    payload: AgentResult;
+} | {
+    type: "agent:failed";
+    timestamp: string;
+    payload: AgentResult;
+} | {
+    type: "agent:skipped";
+    timestamp: string;
+    payload: {
+        agentId: string;
+        agentName: string;
+        icon?: string;
+    };
+} | {
+    type: "agent:retrying";
+    timestamp: string;
+    payload: {
+        agentId: string;
+        agentName: string;
+        attempt: number;
+        maxAttempts: number;
+        error: string;
+    };
+};
+export type EventListener = (event: MultiClawEvent) => void;

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./agent";
+export * from "./config";
+export * from "./event";
+export * from "./leader";
+export * from "./runtime";

package/dist/types/leader.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What the leader decided a request needs.
+ *
+ * The leader is the only agent that runs before the pipeline exists, which makes
+ * it the only place where "does this even need the team?" can be answered. `run`
+ * is the familiar case; the other two exist so that a greeting or a question is
+ * answered instead of spinning up every agent in the config.
+ */
+export type LeaderMode = "run" | "reply" | "ask";
+export type LeaderDecision = {
+    mode: "run";
+    run: string[];
+    /**
+     * Why these agents, in the leader's own words.
+     *
+     * Optional because the field was added after the decision shape was: a
+     * model that omits it still gets its plan honoured. It exists so a user
+     * can ask "why did this run only two agents?" and get an answer from the
+     * run itself rather than from a re-run of the leader.
+     */
+    reason?: string;
+} | {
+    mode: "reply" | "ask";
+    message: string;
+};
+/**
+ * A turn that ended in words rather than in a pipeline.
+ *
+ * Carried on {@link OrchestratorResult} so a caller can tell "the team ran and
+ * succeeded" from "the leader answered you" — both of which are `success: true`
+ * with an empty `agentResults`.
+ */
+export interface LeaderMessage {
+    mode: "reply" | "ask";
+    message: string;
+}

package/dist/types/runtime.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Everything a runtime emits about a run carries the same envelope. `seq` is a
+ * per-run monotonic counter so a consumer can order events without trusting the
+ * clock; `runId` is fresh for every `execute()` call.
+ */
+export interface RuntimeEventBase {
+    runId: string;
+    agentId: string;
+    seq: number;
+}
+/**
+ * The structured stream a runtime produces while an agent runs.
+ *
+ * This is deliberately wider than any single adapter implements: a runtime only
+ * emits the variants it can actually produce, and `RuntimeInfo.capabilities`
+ * tells the caller which those are. `raw` is the escape hatch for vendor output
+ * we recognise the shape of but have not modelled yet — it must never be the
+ * reason a run fails.
+ */
+export type RuntimeEvent = (RuntimeEventBase & {
+    type: "run_started";
+    model?: string;
+}) | (RuntimeEventBase & {
+    type: "message_delta";
+    role: "agent" | "thought" | "user";
+    text: string;
+}) | (RuntimeEventBase & {
+    type: "message";
+    role: "agent" | "thought" | "user";
+    text: string;
+}) | (RuntimeEventBase & {
+    type: "tool_call";
+    id: string;
+    name: string;
+    input: unknown;
+}) | (RuntimeEventBase & {
+    type: "tool_result";
+    id: string;
+    output: string;
+    isError: boolean;
+}) | (RuntimeEventBase & {
+    type: "plan";
+    entries: string[];
+}) | (RuntimeEventBase & {
+    type: "usage";
+    inputTokens?: number;
+    outputTokens?: number;
+    contextTokens?: number;
+    contextSize?: number;
+}) | (RuntimeEventBase & {
+    type: "cost";
+    costUsd?: number;
+    modelBreakdown?: Record<string, unknown>;
+    amount?: number;
+    currency?: string;
+}) | (RuntimeEventBase & {
+    type: "raw";
+    vendor: string;
+    payload: unknown;
+}) | (RuntimeEventBase & {
+    type: "run_finished";
+    stopReason: "success" | "max_turns" | "cancelled" | "timeout" | "error";
+}) | (RuntimeEventBase & {
+    type: "run_error";
+    message: string;
+    code?: string;
+});
+/**
+ * What a *runtime adapter* implements — not what the upstream binary is capable
+ * of. A flag is only `true` when this adapter actually wires the behaviour; an
+ * unhonoured `true` would make callers pass options that are silently dropped.
+ */
+export interface RuntimeCapabilities {
+    streaming: boolean;
+    sessions: boolean;
+    resume: boolean;
+    permissions: boolean;
+    tools: boolean;
+    models: boolean;
+    images: boolean;
+    usage: boolean;
+    cost: boolean;
+    sandbox: boolean;
+}
+/** The result of capability negotiation, returned by `AgentRuntime.describe()`. */
+export interface RuntimeInfo {
+    name: string;
+    version?: string;
+    available: boolean;
+    capabilities: RuntimeCapabilities;
+}
+/** Caller-supplied context for {@link AgentRuntime.describe}. */
+export interface RuntimeQuery {
+    /** Binary this runtime would launch, when the caller knows it. */
+    command?: string;
+}
+export interface AgentTask {
+    agentId: string;
+    systemPrompt: string;
+    prompt: string;
+    tools: string[];
+    workDir: string;
+    timeout: number;
+    signal?: AbortSignal;
+    onEvent?: (event: RuntimeEvent) => void;
+    /**
+     * Non-fatal diagnostics the runtime wants the caller to surface.
+     *
+     * A runtime runs under a TUI's alternate screen, where anything written
+     * straight to stderr is invisible — so a warning the user needs to see has to
+     * travel on a channel the caller can render. Optional, so a direct caller that
+     * supplies nothing keeps the old behaviour (the runtime falls back to stderr).
+     */
+    onWarning?: (message: string) => void;
+    /** Ask the runtime to run under a specific session id, if it supports sessions. */
+    sessionId?: string;
+    /** How to treat an existing session: continue it in place, or fork a copy. */
+    resume?: "continue" | "fork";
+    model?: string;
+    /**
+     * Command to launch, for runtimes that drive an external process (e.g. ACP).
+     * Generic — it names a binary, not a protocol — so runtimes that do not spawn
+     * anything ignore it.
+     */
+    command?: string;
+    /** Arguments for {@link command}. */
+    args?: string[];
+}
+export interface AgentOutput {
+    output: string;
+    exitCode: number;
+    sessionId?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        contextTokens?: number;
+        contextSize?: number;
+    };
+    costUsd?: number;
+    stopReason?: string;
+}
+export interface AgentRuntime {
+    readonly name: string;
+    describe(options?: RuntimeQuery): Promise<RuntimeInfo>;
+    execute(task: AgentTask): Promise<AgentOutput>;
+}

package/dist/utils/abort.d.ts

@@ -0,0 +1,4 @@
+/** Error name used for cooperative cancellation across the orchestrator. */
+export declare const ABORT_ERROR_NAME = "AbortError";
+export declare function abortError(message?: string): Error;
+export declare function isAbortError(err: unknown): boolean;

package/dist/utils/conversation.d.ts

@@ -0,0 +1,29 @@
+import type { TurnRecord } from "../types/config";
+/**
+ * How many earlier turns the leader is shown.
+ *
+ * Deliberately small. The point is to resolve an anaphoric answer — "Postgres",
+ * "the second one", "yes" — and that only ever needs the turn or two behind it.
+ * A long transcript would spend the leader's attention on work that is already
+ * done and written to the workspace, which it can read instead.
+ */
+export declare const MAX_CONVERSATION_TURNS = 6;
+/**
+ * Ceiling on the rendered block, in characters.
+ *
+ * Oldest turns are dropped to stay under it. A budget rather than a turn count
+ * alone because a requirement can be a pasted stack trace; six of those would
+ * otherwise bury the one turn that actually matters.
+ */
+export declare const MAX_CONVERSATION_CHARS = 4000;
+/**
+ * Render earlier turns into a block for the leader's prompt, or "" when there
+ * are none.
+ *
+ * Empty rather than a placeholder: the leader's template carries `{{…}}` for it,
+ * and an unresolved placeholder would be handed to the model as literal text.
+ *
+ * The newlines belong to the block, not to the template — a section that is not
+ * there must not leave its blank lines behind.
+ */
+export declare function renderConversation(history: readonly TurnRecord[] | undefined): string;

package/dist/utils/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * An error that will not be fixed by trying again.
+ *
+ * `withRetry` retries any error that is not an abort, which is the right default
+ * — a flaky connection, a transient non-zero exit, a slow turn are all worth a
+ * second attempt. But some failures are permanent properties of the setup: a
+ * binary that is not installed (ENOENT), one that is not executable (EACCES), or
+ * a capability the agent does not advertise (no `session/load`). Retrying those
+ * only stretches a doomed run by the whole backoff budget, so the sites that can
+ * detect them throw a `PermanentError` and the retry loop fails fast.
+ */
+export declare class PermanentError extends Error {
+    constructor(message: string);
+}
+/** True when `err` was classified as non-retryable. */
+export declare function isPermanent(err: unknown): boolean;

package/dist/utils/json.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extract every top-level JSON object found in `text`.
+ *
+ * Leader / architect agents are instructed to emit a bare JSON object, but real
+ * output frequently wraps it in prose or markdown fences. A regular expression
+ * cannot cope with nested braces or strings that contain `}` — this scans with
+ * brace and string awareness instead and simply skips spans that are not valid
+ * JSON, so a stray `{` in prose does not poison the whole parse.
+ */
+export declare function extractJsonObjects(text: string): unknown[];

package/dist/utils/leaderDecision.d.ts

@@ -0,0 +1,17 @@
+import type { LeaderDecision } from "../types/leader";
+/**
+ * Read the leader's decision out of its raw output.
+ *
+ * The leader is asked for a bare JSON object, but a model will happily wrap it in
+ * prose or markdown fences, so every object in the text is considered in order
+ * and the first one that reads as a decision wins.
+ *
+ * `{"run": [...]}` with no `mode` is still accepted as a run: the field was added
+ * after the shape was, and a model that forgets it has named the agents it wants
+ * all the same.
+ *
+ * Returns `undefined` when nothing parses. That is deliberately *not* an error —
+ * the caller treats it as the leader having answered in prose, which is exactly
+ * what a reply looks like.
+ */
+export declare function parseLeaderDecision(text: string): LeaderDecision | undefined;

package/dist/utils/prompt.d.ts

@@ -0,0 +1 @@
+export declare function renderPrompt(template: string, context: Record<string, string>, workDir: string): Promise<string>;

package/dist/utils/resumePlan.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a resume or retry will actually do, in words.
+ *
+ * `config.resume` runs the agents it names and nothing else, which changes two
+ * things silently: an agent continues the ACP session it reported last time
+ * only when a session id is handed back for it, and a `dependsOn` that points
+ * outside the resumed set is pruned so the agent can run at all. Retrying one
+ * failed agent therefore re-runs a *different* pipeline from the one that
+ * failed, with nothing saying so — this is that sentence.
+ *
+ * The pruning rule mirrors `Orchestrator.selectAgents`: a dependency counts as
+ * dropped when it names a *configured* agent that is not being resumed. A
+ * dependency on an id that is not configured at all is left in place by core
+ * and breaks the stage ordering in every run equally — a config bug, not
+ * something a retry changes, so it is not reported here.
+ */
+export interface ResumePlan {
+    /** Ids that will run, in the order the caller named them. */
+    agents: readonly string[];
+    /** Agent id → the session id to continue, for the agents that reported one. */
+    sessions?: Readonly<Record<string, string>>;
+    /** The team the ids were chosen from; supplies each agent's dependencies. */
+    team: readonly {
+        id: string;
+        dependsOn?: readonly string[];
+    }[];
+}
+/**
+ * One clause per agent — `dev starts fresh`, `reviewer continues its session` —
+ * followed by one clause per agent whose dependencies were pruned.
+ *
+ * Deliberately a description, not a plan: what actually runs stays core's
+ * decision (`selectAgents`), and this only reports it.
+ */
+export declare function describeResumePlan({ agents, sessions, team }: ResumePlan): string;

package/dist/utils/retry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Default backoff unit for {@link withRetry}.
+ *
+ * Exported so a caller that must budget for a whole retry sequence — see
+ * {@link retryBudgetMs} — sleeps the same amount the loop actually sleeps. A
+ * second literal `2000` elsewhere would silently drift from this one.
+ */
+export declare const DEFAULT_RETRY_DELAY_MS = 2000;
+/**
+ * Sleep, interrupted by cancellation.
+ *
+ * Without the signal, cancelling during backoff leaves the timer running for the
+ * rest of the delay. The retry loop already refuses to invoke `fn` again, so the
+ * work is safe — but the continuation lingers for up to `ms`, keeping a turn
+ * alive after the user asked it to stop.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, retries: number, onRetry?: (failedAttempt: number, error: unknown) => void, delayMs?: number, signal?: AbortSignal, shouldRetry?: (error: unknown, attempt: number) => boolean): Promise<T>;
+/**
+ * Wall-clock upper bound for one full retry sequence.
+ *
+ * `withRetry` allows `retries + 1` attempts and sleeps `delayMs * attempt`
+ * between them (`attempt` runs 1..retries), so the worst case is every attempt
+ * spending its whole per-attempt budget plus the sum of the backoffs.
+ *
+ * `perAttemptMs` is the *worst-case wall-clock time of one attempt*, not the
+ * nominal timeout the runtime is handed: an attempt can overrun its own timeout
+ * by whatever cleanup grace the runtime needs after the deadline (for ACP, the
+ * SIGTERM→SIGKILL grace — `KILL_ESCALATION_MS`). A caller that passes the bare
+ * timeout gets an "upper bound" that is not one, and the outer timer then races
+ * — and can beat — the final attempt.
+ *
+ * Kept beside the loop above on purpose: the loop is the only definition of this
+ * arithmetic, and the two would drift apart if they lived in separate files.
+ */
+export declare function retryBudgetMs(perAttemptMs: number, retries: number, delayMs?: number): number;

package/dist/utils/timeout.d.ts

@@ -0,0 +1 @@
+export declare function withTimeout<T>(factory: (signal: AbortSignal) => Promise<T>, ms: number, label: string, signal?: AbortSignal): Promise<T>;

package/dist/utils/toolSummary.d.ts

@@ -0,0 +1,13 @@
+/**
+ * One-line summaries of an agent's tool activity.
+ *
+ * A tool call or result is a glance, not a transcript: the stream pane wants a
+ * single scannable row per tool, and the raw payloads are frequently multi-line
+ * (a whole file, a command's output). These helpers reduce any payload to one
+ * truncated line and are deliberately total — a summary is diagnostics and must
+ * never be the reason a run fails.
+ */
+/** One-line summary of a tool call's input. `input` is untrusted and may be circular. */
+export declare function summarizeToolInput(input: unknown): string;
+/** One-line summary of a tool result's output, which may be a string or a value. */
+export declare function summarizeToolOutput(output: unknown): string;

package/dist/utils/upstream.d.ts

@@ -0,0 +1,69 @@
+/**
+ * One agent's finished output, as a downstream agent should see it.
+ *
+ * `agentId` and `name` are carried alongside the text so the block can address
+ * the producer by name — a bare paragraph with no attribution reads as the
+ * reader's own thought.
+ */
+export interface UpstreamOutput {
+    agentId: string;
+    name: string;
+    output: string;
+}
+/**
+ * Ceiling on a single rendered entry, in characters.
+ *
+ * The entry is the whole bullet — its attribution line, its body, and the
+ * 2-space indent on every continuation line — not just the body. A budget that
+ * excluded its own framing would let the rendered entry exceed the constant,
+ * exactly as the block budget counts the heading and trailing newline.
+ *
+ * The ceiling is enforced by compacting the body, so it holds while the
+ * attribution line is small relative to the constant — the practical case. As
+ * the label grows, compaction has less body to work with, and past the point
+ * where it can keep nothing the entry is bounded by `label.length + markerLen`
+ * instead: there the label, not this constant, is what sets the size.
+ *
+ * An output past this is compacted rather than dropped: it is the one piece of
+ * upstream work that exists, and throwing it away would leave the downstream
+ * agent with nothing to build on.
+ */
+export declare const MAX_UPSTREAM_ENTRY_CHARS = 600;
+/**
+ * Ceiling on the whole rendered block, in characters.
+ *
+ * The block is what is injected into the prompt, so the heading and the
+ * trailing newline count against this — not just the entries. A budget that
+ * excluded its own framing would let the returned string exceed the constant.
+ *
+ * A budget rather than a count of agents because one agent's output can be a
+ * full document; a dozen of those would bury the requirement underneath them.
+ * Oldest entries are dropped to stay under it.
+ */
+export declare const MAX_UPSTREAM_CHARS = 4000;
+/**
+ * Render what earlier agents produced into a block for a downstream prompt, or
+ * "" when there is nothing.
+ *
+ * Empty rather than a placeholder: every built-in task template carries
+ * `{{upstreamOutputs}}`, and an unresolved placeholder would be handed to the
+ * model as literal text.
+ *
+ * The newlines belong to the block, not to the template — a section that is not
+ * there must not leave its blank lines behind. That is why the leading and
+ * trailing `\n` live here, and why the template places the placeholder on its
+ * own line with no section heading: an empty value then leaves nothing dangling.
+ *
+ * Oldest-first is the order worth reading, so the block is built forwards and
+ * trimmed from the front. The newest output is the most relevant to the stage
+ * about to run, so it is the last thing that may be dropped.
+ *
+ * Known limitation, recorded rather than fixed: `renderPrompt` substitutes
+ * `{{file:…}}` and then every context key, and `AgentRunner` layers
+ * `agentScope`/`agentPlan` *after* the snapshot. So if an upstream output's body
+ * literally contains `{{agentScope}}`, the downstream agent's own scope will
+ * replace it. This is a pre-existing property of the substitution order that
+ * `{{conversation}}` shares; cleaning agent output would corrupt legitimate text,
+ * so it is out of scope here.
+ */
+export declare function renderUpstreamOutputs(outputs: readonly UpstreamOutput[]): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiclawcli/core",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,17 +21,17 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "^26.6.4",
-    "typescript": "^5.4.0",
-    "vitest": "^4.1.11"
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.4"
   },
   "dependencies": {
-    "@agentclientprotocol/claude-agent-acp": "^0.89.1",
+    "@agentclientprotocol/claude-agent-acp": "^0.93.0",
     "@agentclientprotocol/codex-acp": "^2.2.2",
-    "@agentclientprotocol/sdk": "^1.8.0"
+    "@agentclientprotocol/sdk": "^1.9.0"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",