@multiclawcli/core 0.5.0 → 0.6.0

package/dist/orchestrator/AgentRunner.d.ts

@@ -1,14 +1,16 @@
 import type { EventBus } from "../event/EventBus";
 import type { AgentDefinition, AgentResult } from "../types/agent";
 import type { MultiClawConfig } from "../types/config";
+import type { AgentSessionManager } from "./AgentSessionManager";
 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>;
+    private sessionManager?;
+    constructor(eventBus: EventBus, contextManager: ContextManager, globalWorkDir: string, config: MultiClawConfig, sessionManager?: AgentSessionManager | undefined);
+    run(agent: AgentDefinition, signal?: AbortSignal, instruction?: string): Promise<AgentResult>;
     /**
      * Publish one chunk of agent output.
      *

package/dist/orchestrator/AgentSessionManager.d.ts

@@ -0,0 +1,40 @@
+import type { AgentOutput, AgentRuntime, AgentTask } from "../types/runtime";
+/** What one agent did with a mid-turn message. */
+export interface SupplementReport {
+    agentId: string;
+    /**
+     * `injected` landed in the running turn; `idle` had no turn to land in;
+     * `unsupported` cannot take mid-turn input at all; `error` failed.
+     */
+    status: "injected" | "idle" | "unsupported" | "error";
+    error?: string;
+}
+/** Owns reusable agent sessions across independent orchestration turns. */
+export declare class AgentSessionManager {
+    private entries;
+    private resetting?;
+    private closing?;
+    private closed;
+    execute(runtime: AgentRuntime, task: AgentTask): Promise<AgentOutput>;
+    /**
+     * Deliver a message into every session that is running a turn right now.
+     *
+     * Only `running` sessions are candidates, and that is the whole safety
+     * argument: a session between turns has nothing to inject into, and asking a
+     * provider to steer an idle session makes it *start* a turn that this manager
+     * never scheduled — one whose output belongs to no turn and which nothing
+     * would ever settle. Sessions that are idle are therefore not reported as
+     * failures but simply absent, and the caller sees an empty list.
+     *
+     * One agent failing never stops the others: each report stands alone, because
+     * the caller has to be able to say "architect took it, qa did not" rather than
+     * "steering failed".
+     */
+    supplement(text: string): Promise<SupplementReport[]>;
+    /** Closes all sessions and permits a fresh conversation after cleanup completes. */
+    reset(): Promise<void>;
+    /** Terminal, idempotent cleanup barrier. No new executions may start. */
+    close(): Promise<void>;
+    private drain;
+    private closeEntry;
+}

package/dist/orchestrator/Orchestrator.d.ts

@@ -1,18 +1,21 @@
 import { EventBus } from "../event/EventBus";
 import type { MultiClawConfig, OrchestrationPreview, OrchestratorResult } from "../types/config";
+import type { AgentSessionManager } from "./AgentSessionManager";
 export declare class Orchestrator {
     private config;
     readonly eventBus: EventBus;
     private contextManager;
     private runner;
     private workDir;
-    constructor(config: MultiClawConfig);
+    constructor(config: MultiClawConfig, sessions?: AgentSessionManager);
     preview(options?: {
         signal?: AbortSignal;
     }): Promise<OrchestrationPreview>;
     run(options?: {
         signal?: AbortSignal;
     }): Promise<OrchestratorResult>;
+    private reviewPolicyError;
+    private reviewDelivery;
     private stageInfos;
     /**
      * Order the agents into stages, degrading to declaration order if the graph is
@@ -98,6 +101,7 @@ export declare class Orchestrator {
      */
     private finishWithMessage;
     private warn;
+    private finishCancelled;
     /**
      * Close out a turn that scheduled no agents.
      *

package/dist/runtime/AcpRuntime.d.ts

@@ -1,17 +1,11 @@
-import type { AgentOutput, AgentTask, RuntimeInfo, RuntimeQuery } from "../types/runtime";
+import type { AgentOutput, AgentTask, RuntimeInfo, RuntimeQuery, RuntimeSession, RuntimeSessionOptions } 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`).
- */
+/** Grace period between SIGTERM and SIGKILL during process cleanup. */
 export declare const KILL_ESCALATION_MS = 3000;
+export declare function validateRuntimeQuestionContent(schema: unknown, content: unknown): content is Record<string, string | number | boolean | string[]>;
 export declare class AcpRuntime extends RuntimeBase {
     readonly name = "acp";
     describe(options?: RuntimeQuery): Promise<RuntimeInfo>;
     execute(task: AgentTask): Promise<AgentOutput>;
+    openSession(options: RuntimeSessionOptions): Promise<RuntimeSession>;
 }

package/dist/types/config.d.ts

@@ -1,5 +1,6 @@
 import type { AgentDefinition } from "./agent";
 import type { LeaderMessage } from "./leader";
+import type { RuntimePermissionHandler, RuntimeQuestionHandler } from "./runtime";
 /**
  * One finished turn of a session, as dialogue the leader can read back.
  *
@@ -14,6 +15,26 @@ export interface TurnRecord {
     /** How the turn ended in words, when it ended that way. */
     reply?: LeaderMessage;
 }
+export interface ReviewPolicy {
+    /** Configured agent reserved for final review, outside the normal pipeline. */
+    reviewer: string;
+    /** Configured workers allowed to repair, in dependency order. */
+    repairAgents: string[];
+    /** Maximum repair passes (0–5); defaults to 1. Review runs once more after each pass. */
+    maxRepairRounds?: number;
+}
+export interface ReviewVerdict {
+    verdict: "approved" | "changes_required";
+    summary: string;
+    issues: string[];
+}
+export interface AcceptanceResult {
+    status: "approved" | "changes_required" | "failed" | "cancelled";
+    reviewer: string;
+    repairRounds: number;
+    reviews: ReviewVerdict[];
+    reason?: string;
+}
 export interface MultiClawConfig {
     name: string;
     workDir: string;
@@ -48,6 +69,17 @@ export interface MultiClawConfig {
     continueOnError?: boolean;
     maxConcurrency?: number;
     useLeader?: boolean;
+    /** Opt-in delivery gate. Execution success alone does not satisfy this policy. */
+    review?: ReviewPolicy;
+    /** Caller-owned live approvals. Ask mode without a handler fails closed. */
+    permissions?: {
+        mode: "auto" | "ask" | "deny";
+        onRequest?: RuntimePermissionHandler;
+    };
+    /** Caller-owned structured questions; headless callers cancel explicitly. */
+    questions?: {
+        onRequest: RuntimeQuestionHandler;
+    };
     /**
      * Project-level defaults applied to every agent that does not override them.
      * Keeps generated configs readable: one line instead of 12 repeated parameters.
@@ -77,7 +109,10 @@ export interface DeliverableSummary {
 }
 export interface OrchestratorResult {
     name: string;
+    /** With review enabled, true only when execution and delivery acceptance both succeed. */
     success: boolean;
+    /** Present only for a review-gated pipeline, never for a leader reply/ask. */
+    acceptance?: AcceptanceResult;
     totalDuration: number;
     agentResults: import("./agent").AgentResult[];
     startTime: string;

package/dist/types/leader.d.ts

@@ -10,6 +10,8 @@ export type LeaderMode = "run" | "reply" | "ask";
 export type LeaderDecision = {
     mode: "run";
     run: string[];
+    /** Complete task combining the original goal with clarification constraints. */
+    requirement?: string;
     /**
      * Why these agents, in the leader's own words.
      *

package/dist/types/runtime.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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.
+ * clock; `runId` is fresh for every `execute()` call or session `prompt()` turn.
  */
 export interface RuntimeEventBase {
     runId: string;
@@ -94,6 +94,38 @@ export interface RuntimeQuery {
     /** Binary this runtime would launch, when the caller knows it. */
     command?: string;
 }
+export interface RuntimePermissionRequest extends RuntimeEventBase {
+    requestId: string;
+    sessionId: string;
+    toolCallId: string;
+    title: string;
+    toolName?: string;
+    kind?: string;
+    input?: unknown;
+    /** Only choices permitted by the configured tools policy are offered. */
+    options: Array<{
+        optionId: string;
+        name: string;
+        kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+    }>;
+}
+/** Return an offered option id, or undefined to cancel/deny. Never grant outside the tools policy. */
+export type RuntimePermissionHandler = (request: RuntimePermissionRequest, signal: AbortSignal) => Promise<string | undefined>;
+export interface RuntimeQuestionRequest extends RuntimeEventBase {
+    requestId: string;
+    sessionId: string;
+    toolCallId?: string;
+    message: string;
+    requestedSchema: import("@agentclientprotocol/sdk").ElicitationSchema;
+}
+export type RuntimeQuestionResponse = {
+    action: "accept";
+    content: Record<string, string | number | boolean | string[]>;
+} | {
+    action: "decline" | "cancel";
+};
+/** Structured form input only; the signal aborts when the requesting turn ends. */
+export type RuntimeQuestionHandler = (request: RuntimeQuestionRequest, signal: AbortSignal) => Promise<RuntimeQuestionResponse>;
 export interface AgentTask {
     agentId: string;
     systemPrompt: string;
@@ -103,6 +135,10 @@ export interface AgentTask {
     timeout: number;
     signal?: AbortSignal;
     onEvent?: (event: RuntimeEvent) => void;
+    /** Automatic tools policy by default; ask without a handler denies. */
+    permissionMode?: "auto" | "ask" | "deny";
+    onPermission?: RuntimePermissionHandler;
+    onQuestion?: RuntimeQuestionHandler;
     /**
      * Non-fatal diagnostics the runtime wants the caller to surface.
      *
@@ -139,8 +175,83 @@ export interface AgentOutput {
     costUsd?: number;
     stopReason?: string;
 }
+/** Immutable agent configuration shared by all turns in an open session. */
+export type RuntimeSessionOptions = Omit<AgentTask, "prompt" | "onEvent" | "signal" | "timeout" | "permissionMode" | "onPermission" | "onQuestion"> & {
+    /** Immutable negotiated form capability; callbacks remain turn-local. */
+    questionForms?: boolean;
+    /** Lifetime cancellation, including startup and idle time; closes the session. */
+    signal?: AbortSignal;
+    /** Startup deadline and default per-turn timeout in ms (ACP defaults to 600,000). */
+    timeout?: number;
+};
+export interface RuntimePromptOptions {
+    /** Cancels only this turn. A cooperative provider leaves the session reusable. */
+    signal?: AbortSignal;
+    /** Overrides the session's default per-turn deadline. */
+    timeout?: number;
+    /** Turn-local events, with a fresh runId and sequence counter. */
+    onEvent?: (event: RuntimeEvent) => void;
+    /** Waiting uses the existing turn timeout; it does not pause the deadline. */
+    permissionMode?: "auto" | "ask" | "deny";
+    onPermission?: RuntimePermissionHandler;
+    onQuestion?: RuntimeQuestionHandler;
+}
+/**
+ * What a mid-turn message did.
+ *
+ * `injected` means the running turn took it — the agent will see it before it
+ * finishes. `idle` means no turn was running, so nothing was applied and the
+ * caller still owns the text; deciding to queue it is the caller's job, not the
+ * runtime's.
+ */
+export type RuntimeSupplementResult = {
+    status: "injected";
+} | {
+    status: "idle";
+};
+/** Caller-owned live session. Always await close() in a finally block. */
+export interface RuntimeSession {
+    readonly sessionId: string;
+    readonly state: "idle" | "running" | "cancelling" | "closing" | "closed";
+    /**
+     * What this session can do beyond a single turn.
+     *
+     * `supplement` is negotiated with the provider rather than assumed: it is true
+     * only when the agent advertised mid-turn input during `initialize` (ACP
+     * `_meta.steering.supported`), so a bridge that does not implement it is
+     * reported as unable instead of being sent a method it will ignore.
+     */
+    readonly capabilities: {
+        continuation: boolean;
+        supplement: boolean;
+    };
+    /** Rejects overlapping turns; it does not implicitly queue or inject input. */
+    prompt(text: string, options?: RuntimePromptOptions): Promise<AgentOutput>;
+    /**
+     * Delivers a message into the turn that is running *now*, when
+     * {@link RuntimeSession.capabilities} allows it.
+     *
+     * Only meaningful mid-turn. An idle session resolves `idle` and must not start
+     * a turn from it: `prompt` is how a turn starts, and a turn the caller never
+     * started has no owner to settle it, cancel it or show its output. Rejects on
+     * provider errors — "did it land?" must never be a guess.
+     */
+    supplement?(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RuntimeSupplementResult>;
+    /**
+     * Idempotently cancels the current turn and waits for its terminal response.
+     * ACP closes uncooperative providers after a grace period; cleanup failure rejects.
+     * Idle cancellation is a no-op. The prompt may reject independently.
+     */
+    cancelTurn(): Promise<void>;
+    /** Idempotent cleanup barrier; rejects if process cleanup cannot be acknowledged. */
+    close(): Promise<void>;
+}
 export interface AgentRuntime {
     readonly name: string;
     describe(options?: RuntimeQuery): Promise<RuntimeInfo>;
     execute(task: AgentTask): Promise<AgentOutput>;
+    /** Optional live-session API; existing execute-only runtimes remain compatible. */
+    openSession?(options: RuntimeSessionOptions): Promise<RuntimeSession>;
 }

package/dist/utils/timeout.d.ts

@@ -1 +1,3 @@
-export declare function withTimeout<T>(factory: (signal: AbortSignal) => Promise<T>, ms: number, label: string, signal?: AbortSignal): Promise<T>;
+export declare function withTimeout<T>(factory: (signal: AbortSignal) => Promise<T>, ms: number, label: string, signal?: AbortSignal, options?: {
+    waitForCleanup?: boolean;
+}): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiclawcli/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,9 +26,9 @@
     "vitest": "^5.0.4"
   },
   "dependencies": {
-    "@agentclientprotocol/claude-agent-acp": "^0.93.0",
+    "@agentclientprotocol/claude-agent-acp": "^0.95.0",
     "@agentclientprotocol/codex-acp": "^2.2.2",
-    "@agentclientprotocol/sdk": "^1.9.0"
+    "@agentclientprotocol/sdk": "^2.0.2"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",