@enderfga/claw-orchestrator 5.1.0 → 6.0.1

package/dist/src/session-manager.d.ts

@@ -16,8 +16,11 @@ interface PersistedSession {
     lastActivity: number;
 }
 import { type Logger } from './logger.js';
+import { type RunSummary } from './kernel/store.js';
+import type { KernelEvent, RunRecord, RunState, WorkflowSpec } from './kernel/types.js';
+import { type EvidenceBundle } from './verify/evidence.js';
 import { type RunLedgerQuery, type RunLedgerRow, type RunLedgerSummary } from './run-ledger.js';
-import { type SessionConfig, type SessionInfo, type SendResult, type PluginConfig, type EffortLevel, type EngineType, type CustomEngineConfig, type AgentInfo, type SkillInfo, type RuleInfo, type StreamEvent, type ISession, type CouncilConfig, type CouncilSession, type CouncilReviewResult, type CouncilAcceptResult, type CouncilRejectResult, type InboxMessage, type UltraplanResult, type UltrareviewResult } from './types.js';
+import { type SessionConfig, type SessionInfo, type SendOptions, type SendResult, type PluginConfig, type EffortLevel, type EngineType, type CustomEngineConfig, type AgentInfo, type SkillInfo, type RuleInfo, type ISession, type CouncilConfig, type CouncilSession, type CouncilReviewResult, type CouncilAcceptResult, type CouncilRejectResult, type InboxMessage, type UltraplanResult, type UltrareviewResult } from './types.js';
 import { Council } from './council.js';
 import { type FanoutConfig, type FanoutSession } from './fanout.js';
 import { AutoloopRunner } from './autoloop/runner.js';
@@ -25,88 +28,7 @@ import { ClaudeAgentDispatcher } from './autoloop/dispatcher.js';
 import type { AutoloopState } from './autoloop/types.js';
 import { UltraappManager } from './ultraapp/manager.js';
 import type { UltraappRouter } from './ultraapp/router.js';
-interface SendOptions {
-    effort?: EffortLevel;
-    plan?: boolean;
-    autoResume?: boolean;
-    timeout?: number;
-    onEvent?: (event: StreamEvent) => void;
-    onChunk?: (chunk: string) => void;
-    /**
-     * council id / fanout id / autoloop run id. Recorded on the run-ledger row so
-     * a multi-agent run can be reconstructed from the ledger after the fact.
-     */
-    parentRunId?: string;
-}
-/** Public shape returned by listCouncilsFromDisk(). Mirrors a subset of CouncilSession. */
-export interface CouncilDiskRecord {
-    id: string;
-    task: string;
-    status: string;
-    startTime: string;
-}
-/**
- * One row in ~/.claw-orchestrator/autoloop-registry.jsonl. Used to make
- * autoloop runs visible across processes (the ledger lives at
- * <workspace>/tasks/<run_id>/, workspaces vary, so we keep a central
- * append-only index here).
- */
-export interface AutoloopRegistryEntry {
-    run_id: string;
-    workspace: string;
-    ledger_dir: string;
-    started_at: string;
-    planner_session: string;
-    /** Optional for compatibility with registry rows written before role-level engine support. */
-    planner_engine?: EngineType;
-    planner_model?: string;
-    coder_engine?: EngineType;
-    coder_model?: string;
-    reviewer_engine?: EngineType;
-    reviewer_model?: string;
-}
-/** Append-only registry write. Safe under concurrent writers — append is atomic for short lines. */
-export declare function appendAutoloopRegistry(file: string, entry: AutoloopRegistryEntry): void;
-/**
- * Write the current row for a run, dropping any older rows for the same id.
- *
- * The registry is append-only and `listAutoloopsFromRegistry` dedups on read
- * (newest wins), so correctness never depended on cleanup — but a run now emits
- * a row at start, another on every successful `spawn_subagents`, and another on
- * every resume, none of which were ever removed. The file grew monotonically and
- * every list / resume parses all of it. Callers use this AFTER the operation
- * succeeds, so a failed start still leaves the previous row intact.
- */
-export declare function upsertAutoloopRegistry(file: string, entry: AutoloopRegistryEntry): void;
-/**
- * Read the registry, dedup by run_id (newest entry wins), drop entries whose
- * ledger_dir no longer exists on disk (cleanup of moved/deleted workspaces).
- * Returns entries newest-first.
- */
-export declare function listAutoloopsFromRegistry(file?: string): AutoloopRegistryEntry[];
-/**
- * Rewrite the registry with every line for the given run_id filtered out.
- * Used by autoloopDelete to scrub a run from cross-process visibility.
- * No-op if the file does not exist. Returns the number of lines removed.
- */
-export declare function removeAutoloopFromRegistry(file: string, runId: string): number;
-/**
- * Enumerate council sessions from on-disk transcripts. Called by
- * SessionManager.councilList() to surface runs that the current process didn't
- * spawn itself (e.g. runs started in another process whose transcripts have
- * already been flushed to ~/.openclaw/council-logs/).
- *
- * Format parsed (matches src/council.ts saveTranscript):
- *   - **ID**: <session.id>
- *   - **Time**: <iso>
- *   - **Task**: <text>
- *   - **Status**: <consensus|max_rounds|...>
- *
- * Legacy transcripts written before the ID field was added fall back to a
- * filename-derived id (basename without .md). That's stable across reruns
- * even if uncomfortable as a display id.
- */
-export declare function listCouncilsFromDisk(logDir?: string): CouncilDiskRecord[];
+type AutoloopRoleName = 'planner' | 'coder' | 'reviewer';
 export declare class SessionManager {
     private sessions;
     private _pendingSessions;
@@ -119,6 +41,8 @@ export declare class SessionManager {
     private _activePids;
     private _circuitBreaker;
     private _inbox;
+    /** cwd → detected language, so the manifest probe runs once per directory. */
+    private _repoLangCache;
     private logger;
     private _ultraappManager;
     private _ultraappRouter;
@@ -162,6 +86,12 @@ export declare class SessionManager {
      * query gives the spend for that window without double-counting.
      */
     private _recordRunTurn;
+    /**
+     * Repo language for the ledger row, memoised per cwd — the detector stats a
+     * handful of manifest paths and a turn-rate filesystem probe is wasteful when
+     * a session's cwd never changes.
+     */
+    private _repoLang;
     private _reportedModel;
     private _turnWasEstimated;
     /**
@@ -172,6 +102,68 @@ export declare class SessionManager {
         rows: RunLedgerRow[];
         summary: RunLedgerSummary;
     };
+    /**
+     * Lazily built, like every other subsystem here — constructing it at plugin
+     * load would create run directories for a process that may never run anything.
+     */
+    private get kernel();
+    /** Named built-ins available to `subflow` nodes and to `workflow_start`. */
+    private _resolveTemplate;
+    /**
+     * Subscribe to kernel events (for the SSE endpoint). Returns an unsubscribe
+     * function — SessionManager is not an EventEmitter, and making it one just for
+     * this would widen its surface for one consumer.
+     */
+    onWorkflowEvent(listener: (e: {
+        runId: string;
+        event: KernelEvent;
+    }) => void): () => void;
+    workflowStart(spec: WorkflowSpec, opts?: {
+        runId?: string;
+        cwd?: string;
+        contract?: unknown;
+    }): Promise<RunRecord>;
+    workflowStatus(runId: string): RunRecord;
+    workflowList(query?: {
+        workflow?: string;
+        state?: RunState;
+        limit?: number;
+    }): RunSummary[];
+    workflowCancel(runId: string): {
+        cancelled: boolean;
+    };
+    /**
+     * Re-attach to a run.
+     *
+     * `secrets` re-supplies the material the spec deliberately does not carry —
+     * per-agent custom-engine configs, keyed as `{ agentCustomEngines: { <name>: cfg } }`.
+     * A run that used one cannot be resumed in a fresh process without them,
+     * because they were never written down.
+     */
+    workflowResume(runId: string, opts?: {
+        secrets?: Record<string, unknown>;
+    }): Promise<RunRecord>;
+    workflowSteer(runId: string, text: string): {
+        steered: boolean;
+    };
+    workflowApprove(runId: string, approved: boolean): {
+        answered: boolean;
+    };
+    workflowDelete(runId: string): void;
+    workflowEvidence(runId: string, evidenceId?: string): EvidenceBundle | undefined;
+    /**
+     * Run an acceptance contract against a directory, outside any workflow.
+     *
+     * This is the escape hatch for work that did not come through the kernel — a
+     * plain `session_send` that edited a repo, or a run from an older version. The
+     * contract comes from the caller and is normalized before anything executes.
+     */
+    verifyRun(args: {
+        cwd: string;
+        contract: unknown;
+        baseSha?: string;
+        label?: string;
+    }): Promise<EvidenceBundle>;
     stopSession(name: string, opts?: {
         keepPersisted?: boolean;
     }): Promise<void>;
@@ -481,42 +473,43 @@ export declare class SessionManager {
     private _storedResumeId;
     private _listMdFiles;
     private _createSession;
-    private councils;
-    private councilCleanupTimers;
-    councilStart(task: string, config: CouncilConfig): CouncilSession;
-    private _scheduleCouncilCleanup;
-    /** Clear and forget a cleanup timer (used on abort/shutdown so it can't fire late). */
-    private _clearCleanupTimer;
+    councilStart(task: string, config: CouncilConfig): Promise<CouncilSession>;
     councilStatus(id: string): CouncilSession | undefined;
     /**
-     * List all council sessions visible to this process.
+     * Every council this machine has run, newest first.
      *
-     * Includes (a) in-memory sessions managed by this SessionManager and (b)
-     * sessions reconstructed from on-disk transcripts at ~/.openclaw/council-logs/.
-     * The disk path lets the dashboard see runs started in OTHER processes
-     * (e.g. plugin-managed runs visible to a standalone clawo-serve dashboard).
-     * Dedup by id; in-memory wins. Sorted by startTime descending so the newest
-     * appears at the top of the sidebar.
+     * Cross-process visibility used to come from scraping `~/.openclaw/council-logs/*.md`
+     * with a regex and fabricating a stub session with no responses and an empty
+     * config. Runs are stored records now, so the dashboard sees the real thing.
      */
     councilList(): CouncilSession[];
     /** Used by embedded-server to subscribe to a council's event stream. */
     getCouncil(id: string): Council | undefined;
+    /** The live council for a run, or a clear error about why there isn't one. */
+    private _liveCouncil;
     councilAbort(id: string): void;
     councilInject(id: string, message: string): void;
     councilReview(id: string): Promise<CouncilReviewResult>;
     councilAccept(id: string): Promise<CouncilAcceptResult>;
     councilReject(id: string, feedback: string): Promise<CouncilRejectResult>;
-    private fanouts;
-    private fanoutCleanupTimers;
+    /**
+     * A `Council` for review / accept / reject.
+     *
+     * These three act on the git state a finished council left behind — branches,
+     * worktrees, plan.md — so they do not need the instance that produced it, only
+     * one pointed at the same project directory. Reconstructing from the run
+     * record is what makes them work after a restart, which the in-memory map made
+     * impossible.
+     */
+    private _councilForPostProcessing;
     /**
      * Start a fan-out: run the task across N engine/model agents in parallel and
      * collect their answers (optional synthesis). Runs in the background; poll
      * with fanoutStatus. Distinct from council — no rounds, votes, or worktrees.
      */
-    fanoutStart(config: FanoutConfig): FanoutSession;
+    fanoutStart(config: FanoutConfig): Promise<FanoutSession>;
     fanoutStatus(id: string): FanoutSession;
     fanoutAbort(id: string): void;
-    private _scheduleFanoutCleanup;
     private get _sessionLookup();
     sessionSendTo(from: string, to: string, message: string, summary?: string): Promise<{
         delivered: boolean;
@@ -524,38 +517,75 @@ export declare class SessionManager {
     }>;
     sessionInbox(name: string, unreadOnly?: boolean): InboxMessage[];
     sessionDeliverInbox(name: string): Promise<number>;
-    private ultraplans;
+    private _kernel;
+    /**
+     * Deferreds resolved by the `autoloop` node once its engine is up, so
+     * `autoloopStart` can return the Planner session name the caller expects
+     * without polling.
+     */
+    /**
+     * Deferreds resolved by the `autoloop` node once its engine is up.
+     *
+     * Keyed by the start's tag rather than its run id. A run id gets reused — a
+     * start that failed frees it for a retry — so keying on the id let a dying
+     * start settle, or clear, the retry's deferred instead of its own, and the
+     * retry then waited forever for a signal with nowhere to land.
+     */
+    private _autoloopReady;
+    /**
+     * Run ids with a start in flight — the window between "run created" and
+     * "engine up". Deleting inside it would drop the run while its Planner
+     * session is still being created, orphaning a session that finishes a moment
+     * later with nothing pointing at it.
+     */
+    private _autoloopStarting;
+    /** Latest role selection per run, published into the node payload. */
+    private _autoloopSelection;
+    /** Per-run checkpoint refreshers, registered by the autoloop node executor. */
+    private _autoloopPublishers;
     ultraplanStart(task: string, opts?: {
         model?: string;
         cwd?: string;
         timeout?: number;
-    }): UltraplanResult;
-    private _runUltraplan;
+    }): Promise<UltraplanResult>;
     ultraplanStatus(id: string): UltraplanResult | undefined;
-    private ultrareviews;
-    private ultrareviewPollers;
     ultrareviewStart(cwd: string, opts?: {
         agentCount?: number;
         maxDurationMinutes?: number;
         model?: string;
         focus?: string;
         engines?: EngineType[];
-    }): UltrareviewResult;
+    }): Promise<UltrareviewResult>;
     ultrareviewStatus(id: string): UltrareviewResult | undefined;
-    private autoloops;
-    private _deletingAutoloops;
     /**
-     * Runs whose Planner is mid-startup. The delete fence was one-directional:
-     * a start could not race a delete, but a delete COULD race a start — it would
-     * resolve `true`, drop the registry row, and leave the still-starting Planner
-     * session orphaned (no run to stop it, no entry to find it by). Deleting a run
-     * that is still coming up is rejected instead.
+     * Build and start the Planner/Coder/Reviewer engine for a run.
+     *
+     * This is everything `autoloopStart` used to be except the bookkeeping: the
+     * `autoloops` map and the private JSONL registry are gone, and the kernel owns
+     * the lifecycle. Called from the `autoloop` node executor, which holds the
+     * returned objects for as long as the loop runs.
+     */
+    /**
+     * Resolve until the loop stops.
+     *
+     * The runner is an event emitter, not a promise: it settles when a
+     * `terminate` envelope is drained or the phase-error circuit trips. Cancelling
+     * the run stops it too, which is what makes `workflow_cancel` work on an
+     * autoloop.
      */
-    private _startingAutoloops;
+    private _awaitAutoloopExit;
+    private _bootAutoloop;
     /**
      * Start a v2 autoloop in chat mode. Creates the Planner persistent session,
      * returns the run handle. Coder/Reviewer are NOT started until S3's
      * spawn_subagents tool is called.
+     *
+     * The run is a kernel run whose single `autoloop` node holds the loop for as
+     * long as it lives. That is what replaced the `autoloops` map, the
+     * `autoloop-registry.jsonl` file with its four bespoke read/write helpers, and
+     * the two `Set`s that fenced start against delete: a run has one owner now,
+     * and `runId` collisions are refused by the run store rather than by a map
+     * lookup that only saw this process.
      */
     autoloopStart(opts: {
         runId: string;
@@ -583,15 +613,15 @@ export declare class SessionManager {
     autoloopChat(runId: string, text: string): Promise<{
         reply: string;
     }>;
-    autoloopStatus(runId: string): AutoloopState | undefined;
-    autoloopList(): AutoloopState[];
     /**
-     * Reset a single subagent on a v2 run. Useful when an agent has drifted
-     * (chat memory implies hallucination, repeated rejects, or context bloat).
-     * Coder/Reviewer: safe to reset; the next directive/review_request will
-     * re-prime from system prompt + ledger artifacts.
-     * Planner: requires force=true and discards user-conversation context.
+     * The running loop for a run, or a clear reason why there is not one.
+     *
+     * Chatting with a Planner needs the live dispatcher; a run that finished or
+     * belongs to another process has a readable record and no one to talk to.
      */
+    private _liveAutoloop;
+    autoloopStatus(runId: string): AutoloopState | undefined;
+    autoloopList(): AutoloopState[];
     autoloopResetAgent(runId: string, agent: 'planner' | 'coder' | 'reviewer', opts?: {
         force?: boolean;
         eagerRestart?: boolean;
@@ -614,23 +644,40 @@ export declare class SessionManager {
      * is still served via /autoloop/<id>/chat_history so the dashboard can
      * replay the conversation visually.
      */
+    /**
+     * Which roles of a stored autoloop run need a custom-engine config before it
+     * can be resumed.
+     *
+     * Custom-engine configs are never persisted, so a resume has to be given them
+     * again — and a caller that cannot find out which roles need one can only
+     * guess. The dashboard's Resume button used to send an empty body
+     * unconditionally, which meant a custom-engine run could be resumed from the
+     * library and from the HTTP API but not from the UI that offers the button.
+     *
+     * Returns role names only. Nothing here is sensitive: the engine kind is
+     * already in `spec.json`, and the answer is a list of roles, not credentials.
+     */
+    autoloopResumeRequirements(runId: string): {
+        runId: string;
+        rolesNeedingCustomEngine: AutoloopRoleName[];
+    };
     autoloopResume(runId: string, opts?: {
         plannerCustomEngine?: CustomEngineConfig;
         coderCustomEngine?: CustomEngineConfig;
         reviewerCustomEngine?: CustomEngineConfig;
     }): Promise<AutoloopState>;
+    /** Re-attach a stored autoloop run: same run id, same spec, fresh engine. */
+    private _resumeAutoloopRun;
     /**
-     * Delete a run from the system: stop the runner if it's still alive in this
-     * process, then scrub the row from the cross-process registry so it stops
-     * appearing in `autoloop_list` / the dashboard. The ledger directory on disk
-     * is NOT removed — postmortem artifacts (chat history, push log, plan.md)
-     * are kept for the user to inspect or `rm` manually.
+     * Delete a run: really gone, not paused.
      *
-     * Returns true if anything was removed (in-memory entry OR registry row).
+     * The two `Set` fences this used to open with — one refusing a delete while a
+     * start was in flight, one blocking a concurrent start during the async
+     * teardown — protected a shared `Map` that no longer exists. Cancelling the
+     * run is what stops it, and the run store refuses to recreate a live id.
      */
     autoloopDelete(runId: string): Promise<boolean>;
-    private _autoloopDeleteInner;
-    /** Used by embedded-server to attach SSE listeners. */
+    /** Used by embedded-server to attach SSE listeners. Live runs only. */
     getAutoloop(runId: string): {
         runner: AutoloopRunner;
         dispatcher: ClaudeAgentDispatcher;