@multiclawcli/core 0.13.0 → 0.14.0

package/dist/orchestrator/AgentRunner.d.ts

@@ -1,7 +1,8 @@
 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 { SessionIntent } from "../types/session";
+import { AgentSessionManager } from "./AgentSessionManager";
 import type { ContextManager } from "./ContextManager";
 export declare class AgentRunner {
     private eventBus;
@@ -10,6 +11,8 @@ export declare class AgentRunner {
     private config;
     private sessionManager?;
     constructor(eventBus: EventBus, contextManager: ContextManager, globalWorkDir: string, config: MultiClawConfig, sessionManager?: AgentSessionManager | undefined);
+    private sessionTask;
+    previewSession(agent: AgentDefinition): SessionIntent;
     run(agent: AgentDefinition, signal?: AbortSignal, instruction?: string): Promise<AgentResult>;
     /**
      * Publish one chunk of agent output.

package/dist/orchestrator/AgentSessionManager.d.ts

@@ -1,4 +1,5 @@
 import type { AgentOutput, AgentRuntime, AgentTask } from "../types/runtime";
+import type { SessionEvent, SessionIntent, SessionRecord } from "../types/session";
 /** What one agent did with a mid-turn message. */
 export interface SupplementReport {
     agentId: string;
@@ -11,20 +12,24 @@ export interface SupplementReport {
 }
 /** Owns reusable agent sessions across independent orchestration turns. */
 export declare class AgentSessionManager {
+    private listeners;
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    private publish;
     private entries;
     private resetting?;
     private closing?;
     private closed;
-    execute(runtime: AgentRuntime, task: AgentTask): Promise<AgentOutput>;
-    /**
-     * Whether this manager still holds a session for `agentId`.
-     *
-     * A caller about to continue a past conversation uses this to avoid naming a
-     * session it already has open: passing the id would change the entry's
-     * fingerprint, and the manager would close a perfectly good session and
-     * `session/load` it straight back.
-     */
-    has(agentId: string): boolean;
+    private compatible;
+    inspect(runtime: AgentRuntime, task: AgentTask, context?: {
+        session?: SessionRecord;
+        strict?: boolean;
+    }): SessionIntent;
+    execute(runtime: AgentRuntime, task: AgentTask, context?: {
+        session?: SessionRecord;
+        strict?: boolean;
+        executionId?: string;
+        attempt?: number;
+    }): Promise<AgentOutput>;
     /**
      * Deliver a message into every session that is running a turn right now.
      *
@@ -40,10 +45,13 @@ export declare class AgentSessionManager {
      * "steering failed".
      */
     supplement(text: string): Promise<SupplementReport[]>;
+    /** Close selected idle conversations without resetting the leader. */
+    resetAgents(agentIds: string[]): Promise<void>;
     /** 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;
+    private closeSession;
 }

package/dist/orchestrator/Orchestrator.d.ts

@@ -1,21 +1,39 @@
 import { EventBus } from "../event/EventBus";
 import type { MultiClawConfig, OrchestrationPreview, OrchestratorResult } from "../types/config";
-import type { AgentSessionManager } from "./AgentSessionManager";
+import { AgentSessionManager } from "./AgentSessionManager";
 export declare class Orchestrator {
     private config;
+    private sessions?;
     readonly eventBus: EventBus;
     private contextManager;
     private runner;
     private workDir;
     /** Which configured checkpoints have already been triggered this run. */
     private checkpointTriggered;
-    constructor(config: MultiClawConfig, sessions?: AgentSessionManager);
+    private originalRequirement;
+    private work?;
+    private routing?;
+    private assignments;
+    private excluded;
+    private rerouting;
+    private repairSpent;
+    private leaderCosts;
+    private ownsSessions;
+    private cleanupAttempted;
+    private offSessions;
+    private sessionRecords;
+    private recovery;
+    private routeError?;
+    constructor(config: MultiClawConfig, sessions?: AgentSessionManager | undefined);
     preview(options?: {
         signal?: AbortSignal;
     }): Promise<OrchestrationPreview>;
+    private previewManaged;
     run(options?: {
         signal?: AbortSignal;
     }): Promise<OrchestratorResult>;
+    private runManaged;
+    private runPass;
     private reviewPolicyError;
     private reviewDelivery;
     private handleCheckpoint;
@@ -53,6 +71,8 @@ export declare class Orchestrator {
      * job, and that is what `message` records.
      */
     private resolveTurn;
+    private beginWork;
+    private captureWork;
     /**
      * The configured team, as copies.
      *

package/dist/types/agent.d.ts

@@ -64,7 +64,7 @@ export interface AgentDefinition {
     retries?: number;
     workDir?: string;
 }
-export type AgentStatus = "pending" | "running" | "retrying" | "success" | "failed"
+export type AgentStatus = "pending" | "running" | "retrying" | "handed_back" | "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
@@ -72,6 +72,7 @@ export type AgentStatus = "pending" | "running" | "retrying" | "success" | "fail
  */
  | "cancelled" | "skipped";
 export interface AgentResult {
+    handoffReason?: string;
     agentId: string;
     agentName: string;
     status: AgentStatus;
@@ -87,8 +88,8 @@ export interface AgentResult {
     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;
+    /** Reliable Session facts, including on failed and cancelled executions. */
+    session?: import("./session").SessionRecord;
 }
 export interface SubTask {
     id: string;

package/dist/types/config.d.ts

@@ -1,21 +1,36 @@
 import type { AgentDefinition, PermissionMode } 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.
- *
- * 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.
- */
+/** Caller-owned facts for the latest work in this console session. */
+export interface WorkContext {
+    id: string;
+    originalRequirement: string;
+    requirement: string;
+    agents: Array<{
+        agentId: string;
+        scope?: string;
+        plan?: string;
+        session?: import("./session").SessionRecord;
+        dependsOn?: string[];
+        taskTitle?: string;
+    }>;
+    outcome?: TurnOutcome;
+}
+export interface RoutingInfo {
+    mode: "run" | "continue";
+    workId?: string;
+    reroutes: number;
+    error?: string;
+}
+/** One session turn, paired with its reply and observed execution facts. */
 export interface TurnRecord {
     /** What the user asked for. */
     requirement: string;
     /** How the turn ended in words, when it ended that way. */
     reply?: LeaderMessage;
-    /** Observed execution and acceptance facts; absent in older caller-provided history. */
+    /** Observed execution and acceptance facts when agents ran. */
     outcome?: TurnOutcome;
+    work?: WorkContext;
 }
 /** Compact facts for the next leader turn, not a model-generated summary or retry instruction. */
 export interface TurnOutcome {
@@ -95,6 +110,8 @@ export interface MultiClawConfig {
      * unset and sees no conversation at all.
      */
     history?: TurnRecord[];
+    /** Latest work only; dialogue turns do not replace it. */
+    latestWork?: WorkContext;
     /**
      * Continue known agent sessions, and optionally re-run a fixed set of agents
      * instead of letting the leader route.
@@ -109,15 +126,14 @@ export interface MultiClawConfig {
      *   whichever agents the route happens to pick. This is what makes a new
      *   instruction land in a conversation the agents already remember.
      *
-     * 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.
+     * Session records are candidates, checked by core against work identity and
+     * immutable creation settings. Loading is confirmed only by runtime success.
      */
     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>;
+        /** agentId → observed Session facts used to check continuation or loading. */
+        sessions?: Record<string, import("./session").SessionRecord>;
     };
     logDir?: string;
     continueOnError?: boolean;
@@ -152,6 +168,9 @@ export interface MultiClawConfig {
     };
 }
 export interface OrchestrationPreview {
+    sessions?: import("./session").SessionIntent[];
+    originalRequirement?: string;
+    routing?: RoutingInfo;
     name: string;
     requirement?: string;
     totalAgents: number;
@@ -169,6 +188,11 @@ export interface DeliverableSummary {
     modifiedAt: string;
 }
 export interface OrchestratorResult {
+    originalRequirement?: string;
+    routing?: RoutingInfo;
+    work?: WorkContext;
+    /** Current route results; agentResults remains the full execution audit. */
+    effectiveAgentResults?: import("./agent").AgentResult[];
     name: string;
     /** With review enabled, true only when execution and delivery acceptance both succeed. */
     success: boolean;

package/dist/types/event.d.ts

@@ -11,6 +11,27 @@ export interface StageInfo {
     }>;
 }
 export type MultiClawEvent = {
+    type: "agent:session";
+    timestamp: string;
+    payload: import("./session").SessionEvent;
+} | {
+    type: "orchestration:route";
+    timestamp: string;
+    payload: {
+        routing: import("./config").RoutingInfo;
+        work?: import("./config").WorkContext;
+    };
+} | {
+    type: "orchestration:routing-error";
+    timestamp: string;
+    payload: {
+        message: string;
+    };
+} | {
+    type: "agent:handed-back";
+    timestamp: string;
+    payload: AgentResult;
+} | {
     type: "orchestration:start";
     timestamp: string;
     payload: {

package/dist/types/leader.d.ts

@@ -6,9 +6,14 @@
  * 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 LeaderMode = "run" | "continue" | "reply" | "ask";
 export type LeaderDecision = {
-    mode: "run";
+    mode: "run" | "continue";
+    workId?: string;
+    tasks?: Array<{
+        agentId: string;
+        scope: string;
+    }>;
     run: string[];
     /** Complete task combining the original goal with clarification constraints. */
     requirement?: string;

package/dist/types/runtime.d.ts

@@ -133,7 +133,10 @@ export type RuntimeQuestionResponse = {
 /** Structured form input only; the signal aborts when the requesting turn ends. */
 export type RuntimeQuestionHandler = (request: RuntimeQuestionRequest, signal: AbortSignal) => Promise<RuntimeQuestionResponse>;
 export interface AgentTask {
+    /** Host work identity, independent of provider session identity. */
+    workId?: string;
     agentId: string;
+    provider?: string;
     systemPrompt: string;
     prompt: string;
     workDir: string;
@@ -228,6 +231,7 @@ export interface RuntimeSession {
      */
     readonly capabilities: {
         continuation: boolean;
+        load: boolean;
         supplement: boolean;
     };
     /** Rejects overlapping turns; it does not implicitly queue or inject input. */

package/dist/types/session.d.ts

@@ -0,0 +1,36 @@
+/** Observed provider conversation facts, independent of an execution's outcome. */
+export interface SessionRecord {
+    bindingId: string;
+    agentId: string;
+    workId?: string;
+    sessionId?: string;
+    runtime: string;
+    compatibilityKey: string;
+    state: "opening" | "idle" | "running" | "cancelling" | "closing" | "closed" | "unknown";
+    capabilities: {
+        continuation: boolean;
+        load: boolean;
+        supplement: boolean;
+    };
+    action: "created" | "loaded" | "reused";
+    observedAt: string;
+    reason?: string;
+    failure?: {
+        code: "incompatible" | "unsupported" | "opening_failed" | "load_failed" | "turn_failed" | "cleanup_failed";
+        message: string;
+    };
+}
+export interface SessionEvent {
+    action: "opening" | "created" | "load_requested" | "loaded" | "reused" | "state_changed" | "opening_failed" | "load_failed" | "closing" | "closed" | "cleanup_failed";
+    executionId: string;
+    attempt: number;
+    record: SessionRecord;
+    requestedSessionId?: string;
+    reason?: string;
+}
+/** Read-only intent; loading and cleanup have not happened. */
+export interface SessionIntent {
+    agentId: string;
+    action: "create" | "reuse" | "load" | "unavailable";
+    reason: string;
+}

package/dist/utils/handoff.d.ts

@@ -0,0 +1,7 @@
+/** A terminal host control message, never inferred from ordinary prose. */
+export declare const HANDOFF_INSTRUCTION: string;
+export declare function parseHandoff(output: string): {
+    reason: string;
+} | {
+    error: string;
+} | undefined;

package/dist/utils/resumePlan.d.ts

@@ -17,8 +17,8 @@
 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>>;
+    /** Agent ID → observed Session metadata to check before resuming. */
+    sessions?: Readonly<Record<string, import("../types/session").SessionRecord>>;
     /** The team the ids were chosen from; supplies each agent's dependencies. */
     team: readonly {
         id: string;
@@ -26,7 +26,7 @@ export interface ResumePlan {
     }[];
 }
 /**
- * One clause per agent — `dev starts fresh`, `reviewer continues its session` —
+ * One clause per agent — `dev starts fresh`, `reviewer will attempt to resume its session` —
  * followed by one clause per agent whose dependencies were pruned.
  *
  * Deliberately a description, not a plan: what actually runs stays core's

package/dist/utils/session.d.ts

@@ -0,0 +1,7 @@
+import type { AgentRuntime, AgentTask } from "../types/runtime";
+import type { SessionEvent, SessionRecord } from "../types/session";
+/** Only immutable creation options participate; target IDs and work identity are checked separately. */
+export declare function sessionCompatibilityKey(runtime: Pick<AgentRuntime, "name">, task: AgentTask): string;
+export declare function isSessionRecord(value: unknown): value is SessionRecord;
+export declare function isSessionEvent(value: unknown): value is SessionEvent;
+export declare function describeSession(record: SessionRecord): string;

package/dist/utils/work.d.ts

@@ -0,0 +1,3 @@
+import type { WorkContext } from "../types/config";
+/** Validate persisted ownership and execution facts consumed by routing. */
+export declare function isWorkContext(value: unknown): value is WorkContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiclawcli/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",