openclaw-swarm-layer 0.1.0

package/dist/src/runtime/public-api-seams.js

@@ -0,0 +1,79 @@
+export const ACP_PUBLIC_REPLACEMENT_EXPORT = "getAcpSessionManager";
+export const SUBAGENT_PUBLIC_REPLACEMENT_EXPORT = "spawnSubagentDirect";
+export function buildMigrationChecklist(plan) {
+    const steps = [
+        "Run `openclaw swarm doctor --json` before changing bridge or public API integration code.",
+    ];
+    for (const item of plan) {
+        if (item.available) {
+            steps.push(`[${item.runner}] Replace ${item.currentImplementation} with ${item.targetImplementation}. Update modules: ${item.affectedModules.join(", ")}.`);
+        }
+        else {
+            steps.push(`[${item.runner}] Keep the current bridge path until the public export ${item.publicExport} is available.`);
+        }
+    }
+    steps.push("After any replacement, rerun unit tests, e2e regressions, and at least one live smoke before relaxing bridge guards.");
+    return steps;
+}
+export async function detectPublicApiAvailability(sdkLoader = async () => (await import("openclaw/plugin-sdk"))) {
+    const sdk = await sdkLoader();
+    const acpControlPlaneExport = typeof sdk[ACP_PUBLIC_REPLACEMENT_EXPORT] === "function";
+    const subagentSpawnExport = typeof sdk[SUBAGENT_PUBLIC_REPLACEMENT_EXPORT] === "function";
+    const readyReplacementPoints = [];
+    const notes = [];
+    if (!acpControlPlaneExport) {
+        notes.push(`Top-level public plugin SDK does not expose ${ACP_PUBLIC_REPLACEMENT_EXPORT}().`);
+    }
+    else {
+        readyReplacementPoints.push(`acp:${ACP_PUBLIC_REPLACEMENT_EXPORT}`);
+        notes.push(`Top-level public plugin SDK exposes ${ACP_PUBLIC_REPLACEMENT_EXPORT}(); ACP bridge replacement is now technically possible.`);
+    }
+    if (!subagentSpawnExport) {
+        notes.push(`Top-level public plugin SDK does not expose ${SUBAGENT_PUBLIC_REPLACEMENT_EXPORT}().`);
+    }
+    else {
+        readyReplacementPoints.push(`subagent:${SUBAGENT_PUBLIC_REPLACEMENT_EXPORT}`);
+        notes.push(`Top-level public plugin SDK exposes ${SUBAGENT_PUBLIC_REPLACEMENT_EXPORT}(); subagent bridge replacement is now technically possible.`);
+    }
+    return {
+        acpControlPlaneExport,
+        subagentSpawnExport,
+        readyReplacementPoints,
+        notes,
+    };
+}
+export function buildReplacementPlan(availability) {
+    return [
+        {
+            runner: "acp",
+            publicExport: ACP_PUBLIC_REPLACEMENT_EXPORT,
+            available: availability.acpControlPlaneExport,
+            status: availability.acpControlPlaneExport ? "ready" : "blocked",
+            currentImplementation: "bridge-openclaw-session-adapter -> openclaw-exec-bridge",
+            targetImplementation: "real-openclaw-session-adapter via top-level public plugin-sdk export",
+            affectedModules: [
+                "src/runtime/bridge-openclaw-session-adapter.ts",
+                "src/runtime/openclaw-exec-bridge.ts",
+                "src/runtime/real-openclaw-session-adapter.ts",
+            ],
+            nextStep: availability.acpControlPlaneExport
+                ? "Prototype replacing the ACP bridge control-plane path with the public export."
+                : "Keep using the bridge-backed ACP adapter until a public control-plane export is available.",
+        },
+        {
+            runner: "subagent",
+            publicExport: SUBAGENT_PUBLIC_REPLACEMENT_EXPORT,
+            available: availability.subagentSpawnExport,
+            status: availability.subagentSpawnExport ? "ready" : "blocked",
+            currentImplementation: "bridge-openclaw-subagent-adapter -> openclaw-exec-bridge patched helpers",
+            targetImplementation: "public subagent spawn helper from top-level plugin-sdk export",
+            affectedModules: [
+                "src/runtime/bridge-openclaw-subagent-adapter.ts",
+                "src/runtime/openclaw-exec-bridge.ts",
+            ],
+            nextStep: availability.subagentSpawnExport
+                ? "Prototype replacing the subagent bridge spawn path with the public export."
+                : "Keep using the bridge-backed subagent adapter until a public spawn export is available.",
+        },
+    ];
+}

package/dist/src/runtime/real-openclaw-session-adapter.d.ts

@@ -0,0 +1,83 @@
+import type { SwarmPluginConfig } from "../config.js";
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { OpenClawSessionAdapter, AcpAcceptedSession, AcpSessionStatus } from "./openclaw-session-adapter.js";
+import type { AcpSpawnParams } from "./acp-mapping.js";
+type AcpManager = {
+    initializeSession(input: {
+        cfg: unknown;
+        sessionKey: string;
+        agent: string;
+        mode: "persistent" | "oneshot";
+        cwd?: string;
+        backendId?: string;
+    }): Promise<{
+        handle: {
+            sessionKey: string;
+            backend: string;
+            backendSessionId?: string;
+            agentSessionId?: string;
+        };
+    }>;
+    runTurn(input: {
+        cfg: unknown;
+        sessionKey: string;
+        text: string;
+        mode: "prompt" | "steer";
+        requestId: string;
+    }): Promise<void>;
+    getSessionStatus(input: {
+        cfg: unknown;
+        sessionKey: string;
+    }): Promise<{
+        sessionKey: string;
+        backend: string;
+        state: "idle" | "running" | "error";
+        identity?: {
+            acpxSessionId?: string;
+            agentSessionId?: string;
+        };
+        runtimeStatus?: {
+            backendSessionId?: string;
+            agentSessionId?: string;
+            summary?: string;
+        };
+        lastError?: string;
+    }>;
+    cancelSession(input: {
+        cfg: unknown;
+        sessionKey: string;
+        reason?: string;
+    }): Promise<void>;
+    closeSession(input: {
+        cfg: unknown;
+        sessionKey: string;
+        reason: string;
+    }): Promise<{
+        runtimeClosed: boolean;
+        runtimeNotice?: string;
+    }>;
+};
+type SdkLike = {
+    getAcpSessionManager?: () => AcpManager;
+};
+export declare class ExperimentalRealOpenClawSessionAdapter implements OpenClawSessionAdapter {
+    private readonly runtime;
+    private readonly config;
+    private readonly sdkLoader;
+    constructor(runtime: Pick<PluginRuntime, "config">, config: Pick<SwarmPluginConfig, "acp">, sdkLoader?: () => Promise<SdkLike>);
+    private getManager;
+    spawnAcpSession(params: AcpSpawnParams): Promise<AcpAcceptedSession>;
+    getAcpSessionStatus(sessionKey: string): Promise<AcpSessionStatus>;
+    cancelAcpSession(sessionKey: string, reason?: string): Promise<{
+        sessionKey: string;
+        cancelledAt?: string;
+        message?: string;
+    }>;
+    closeAcpSession(sessionKey: string, reason?: string): Promise<{
+        sessionKey: string;
+        closedAt?: string;
+        message?: string;
+    }>;
+}
+export declare function createSessionAdapter(runtime: Pick<PluginRuntime, "config"> | undefined, config: Pick<SwarmPluginConfig, "acp">): OpenClawSessionAdapter | null;
+export {};

package/dist/src/runtime/real-openclaw-session-adapter.js

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+function mapManagerState(status) {
+    if (status.state === "running") {
+        return "running";
+    }
+    if (status.state === "error") {
+        return "failed";
+    }
+    return "completed";
+}
+export class ExperimentalRealOpenClawSessionAdapter {
+    runtime;
+    config;
+    sdkLoader;
+    constructor(runtime, config, sdkLoader = async () => (await import("openclaw/plugin-sdk"))) {
+        this.runtime = runtime;
+        this.config = config;
+        this.sdkLoader = sdkLoader;
+    }
+    async getManager() {
+        if (!this.config.acp.experimentalControlPlaneAdapter) {
+            throw new Error("Experimental ACP control-plane adapter is disabled in plugin config");
+        }
+        const sdk = await this.sdkLoader();
+        const manager = sdk.getAcpSessionManager?.();
+        if (!manager) {
+            throw new Error("OpenClaw plugin-sdk does not expose getAcpSessionManager at runtime; real ACP adapter remains blocked on an upstream public control-plane export");
+        }
+        const cfg = this.runtime.config.loadConfig();
+        return { manager, cfg };
+    }
+    async spawnAcpSession(params) {
+        const { manager, cfg } = await this.getManager();
+        const sessionKey = `agent:${params.agentId}:acp:${randomUUID()}`;
+        const initialized = await manager.initializeSession({
+            cfg,
+            sessionKey,
+            agent: params.agentId,
+            mode: params.mode === "session" ? "persistent" : "oneshot",
+            cwd: params.cwd,
+            backendId: this.config.acp.backendId,
+        });
+        void manager.runTurn({
+            cfg,
+            sessionKey,
+            text: params.task,
+            mode: "prompt",
+            requestId: randomUUID(),
+        });
+        return {
+            sessionKey,
+            backend: initialized.handle.backend,
+            backendSessionId: initialized.handle.backendSessionId,
+            agentSessionId: initialized.handle.agentSessionId,
+            acceptedAt: new Date().toISOString(),
+        };
+    }
+    async getAcpSessionStatus(sessionKey) {
+        const { manager, cfg } = await this.getManager();
+        const status = await manager.getSessionStatus({ cfg, sessionKey });
+        return {
+            sessionKey,
+            state: mapManagerState(status),
+            backend: status.backend,
+            backendSessionId: status.runtimeStatus?.backendSessionId ?? status.identity?.acpxSessionId,
+            agentSessionId: status.runtimeStatus?.agentSessionId ?? status.identity?.agentSessionId,
+            checkedAt: new Date().toISOString(),
+            message: status.lastError ?? status.runtimeStatus?.summary,
+        };
+    }
+    async cancelAcpSession(sessionKey, reason) {
+        const { manager, cfg } = await this.getManager();
+        await manager.cancelSession({ cfg, sessionKey, reason });
+        return { sessionKey, cancelledAt: new Date().toISOString(), message: reason };
+    }
+    async closeAcpSession(sessionKey, reason) {
+        const { manager, cfg } = await this.getManager();
+        const closed = await manager.closeSession({ cfg, sessionKey, reason: reason ?? "closed by swarm layer" });
+        return {
+            sessionKey,
+            closedAt: new Date().toISOString(),
+            message: closed.runtimeNotice ?? reason,
+        };
+    }
+}
+export function createSessionAdapter(runtime, config) {
+    if (!runtime || !config.acp.experimentalControlPlaneAdapter) {
+        return null;
+    }
+    return new ExperimentalRealOpenClawSessionAdapter(runtime, config);
+}

package/dist/src/runtime/retry-engine.d.ts

@@ -0,0 +1,7 @@
+import type { RetryHistoryEntry, RetryPolicy, RunRecord, TaskNode } from "../types.js";
+export declare function isRetryableStatus(status: RunRecord["status"], policy: RetryPolicy): boolean;
+export declare function shouldRetry(task: TaskNode, runRecord: RunRecord): {
+    retry: boolean;
+    reason: string;
+};
+export declare function appendRetryHistory(runRecord: RunRecord): RetryHistoryEntry[];

package/dist/src/runtime/retry-engine.js

@@ -0,0 +1,29 @@
+const DEFAULT_RETRYABLE_STATUSES = ["failed", "timed_out"];
+export function isRetryableStatus(status, policy) {
+    const retryOn = policy.retryOn.length > 0 ? policy.retryOn : DEFAULT_RETRYABLE_STATUSES;
+    return retryOn.includes(status);
+}
+export function shouldRetry(task, runRecord) {
+    const policy = task.runner.retryPolicy;
+    if (!policy) {
+        return { retry: false, reason: "no retry policy configured" };
+    }
+    if (!isRetryableStatus(runRecord.status, policy)) {
+        return { retry: false, reason: `status ${runRecord.status} is not retryable` };
+    }
+    const pastAttempts = runRecord.retryHistory?.length ?? 0;
+    const currentAttempt = pastAttempts + 1;
+    if (currentAttempt >= policy.maxAttempts) {
+        return { retry: false, reason: `exhausted ${policy.maxAttempts} attempts` };
+    }
+    return { retry: true, reason: `attempt ${currentAttempt + 1} of ${policy.maxAttempts}` };
+}
+export function appendRetryHistory(runRecord) {
+    const entry = {
+        attempt: runRecord.attempt,
+        runId: runRecord.runId,
+        status: runRecord.status,
+        at: runRecord.endedAt ?? runRecord.startedAt,
+    };
+    return [...(runRecord.retryHistory ?? []), entry];
+}

package/dist/src/runtime/runner-registry.d.ts

@@ -0,0 +1,6 @@
+import type { TaskRunner } from "./task-runner.js";
+export declare class RunnerRegistry {
+    private readonly runners;
+    constructor(runners?: TaskRunner[]);
+    resolve(kind: TaskRunner["kind"]): TaskRunner;
+}

package/dist/src/runtime/runner-registry.js

@@ -0,0 +1,25 @@
+import { AcpRunner } from "./acp-runner.js";
+import { ManualRunner } from "./manual-runner.js";
+import { UnsupportedOpenClawSessionAdapter } from "./openclaw-session-adapter.js";
+import { UnsupportedOpenClawSubagentAdapter } from "./openclaw-subagent-adapter.js";
+import { SubagentRunner } from "./subagent-runner.js";
+export class RunnerRegistry {
+    runners = new Map();
+    constructor(runners) {
+        const defaults = runners ?? [
+            new ManualRunner(),
+            new AcpRunner(undefined, new UnsupportedOpenClawSessionAdapter()),
+            new SubagentRunner(new UnsupportedOpenClawSubagentAdapter()),
+        ];
+        defaults.forEach((runner) => {
+            this.runners.set(runner.kind, runner);
+        });
+    }
+    resolve(kind) {
+        const runner = this.runners.get(kind);
+        if (!runner) {
+            throw new Error(`Unknown runner: ${kind}`);
+        }
+        return runner;
+    }
+}

package/dist/src/runtime/session-sync.d.ts

@@ -0,0 +1,9 @@
+import type { RunRecord } from "../types.js";
+import type { AcpSessionStatus } from "./openclaw-session-adapter.js";
+import type { SubagentRunStatus } from "./openclaw-subagent-adapter.js";
+export type SessionSyncResult<TRemoteStatus = AcpSessionStatus | SubagentRunStatus> = {
+    runRecord: RunRecord;
+    remoteStatus: TRemoteStatus;
+};
+export declare function syncAcpRunRecord(runRecord: RunRecord, remoteStatus: AcpSessionStatus): SessionSyncResult<AcpSessionStatus>;
+export declare function syncSubagentRunRecord(runRecord: RunRecord, remoteStatus: SubagentRunStatus): SessionSyncResult<SubagentRunStatus>;

package/dist/src/runtime/session-sync.js

@@ -0,0 +1,165 @@
+function parseAcpSummary(message) {
+    if (!message) {
+        return {};
+    }
+    const match = (pattern) => message.match(pattern)?.[1];
+    return {
+        rawStatus: match(/status=([^\s]+)/),
+        recordId: match(/acpxRecordId=([^\s]+)/),
+        sessionId: match(/acpxSessionId=([^\s]+)/),
+        pid: match(/pid=([^\s]+)/),
+    };
+}
+function buildAcpSummary(remoteStatus, fallback) {
+    const parsed = parseAcpSummary(remoteStatus.message);
+    const details = [
+        parsed.rawStatus ? `status=${parsed.rawStatus}` : null,
+        parsed.recordId ? `record=${parsed.recordId}` : null,
+        parsed.sessionId ? `session=${parsed.sessionId}` : null,
+        parsed.pid ? `pid=${parsed.pid}` : null,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    const detailText = details ? ` (${details})` : "";
+    if (remoteStatus.state === "completed") {
+        return `Completed: ACP session finished${detailText}`;
+    }
+    if (remoteStatus.state === "running") {
+        return `Running: ACP session still active${detailText}`;
+    }
+    if (remoteStatus.state === "accepted") {
+        return `Accepted: ACP session accepted${detailText}`;
+    }
+    if (remoteStatus.state === "cancelled") {
+        return `Cancelled: ACP session stopped${detailText}`;
+    }
+    if (remoteStatus.state === "timed_out") {
+        return `Timed out: ACP session exceeded allowed time${detailText}`;
+    }
+    if (remoteStatus.state === "failed") {
+        return remoteStatus.message ? `Failed: ${remoteStatus.message}` : fallback;
+    }
+    return fallback;
+}
+function buildSubagentSummary(remoteStatus, fallback) {
+    const normalizedOutput = remoteStatus.outputText?.trim();
+    const normalizedMessage = remoteStatus.message?.trim();
+    if (remoteStatus.state === "completed") {
+        if (normalizedOutput) {
+            return `Completed: ${normalizedOutput.replace(/\s+/g, " ").trim()}`;
+        }
+        if (normalizedMessage) {
+            return `Completed: ${normalizedMessage}`;
+        }
+    }
+    if (remoteStatus.state === "running") {
+        return normalizedMessage ? `Running: ${normalizedMessage}` : fallback;
+    }
+    if (remoteStatus.state === "accepted") {
+        return normalizedMessage ? `Accepted: ${normalizedMessage}` : fallback;
+    }
+    if (remoteStatus.state === "cancelled") {
+        return normalizedMessage ? `Cancelled: ${normalizedMessage}` : fallback;
+    }
+    if (remoteStatus.state === "failed") {
+        return normalizedMessage ? `Failed: ${normalizedMessage}` : fallback;
+    }
+    return fallback;
+}
+function appendStatusEvent(runRecord, remoteStatus) {
+    const events = [...(runRecord.events ?? [])];
+    events.push({
+        at: remoteStatus.checkedAt ?? new Date().toISOString(),
+        type: "status_polled",
+        detail: {
+            state: remoteStatus.state,
+            message: remoteStatus.message,
+        },
+    });
+    if (remoteStatus.state === "completed") {
+        events.push({ at: remoteStatus.checkedAt ?? new Date().toISOString(), type: "done" });
+    }
+    else if (remoteStatus.state === "failed") {
+        events.push({ at: remoteStatus.checkedAt ?? new Date().toISOString(), type: "error", detail: { message: remoteStatus.message } });
+    }
+    else if (remoteStatus.state === "cancelled") {
+        events.push({ at: remoteStatus.checkedAt ?? new Date().toISOString(), type: "cancelled" });
+    }
+    else if (remoteStatus.state === "timed_out") {
+        events.push({ at: remoteStatus.checkedAt ?? new Date().toISOString(), type: "timeout" });
+    }
+    return events;
+}
+function summarizeRemoteStatus(remoteStatus, fallback) {
+    const labelByState = {
+        planned: "Planned",
+        accepted: "Accepted",
+        running: "Running",
+        completed: "Completed",
+        failed: "Failed",
+        cancelled: "Cancelled",
+        timed_out: "Timed out",
+    };
+    const normalizedOutput = remoteStatus.outputText?.trim();
+    if (normalizedOutput) {
+        const singleLine = normalizedOutput.replace(/\s+/g, " ").trim();
+        const summary = singleLine.length > 240 ? `${singleLine.slice(0, 237)}...` : singleLine;
+        return `${labelByState[remoteStatus.state]}: ${summary}`;
+    }
+    const normalizedMessage = remoteStatus.message?.trim();
+    if (normalizedMessage) {
+        return `${labelByState[remoteStatus.state]}: ${normalizedMessage}`;
+    }
+    return fallback ? `${labelByState[remoteStatus.state]}: ${fallback}` : fallback;
+}
+function applyTerminalFields(runRecord, remoteStatus, runtime) {
+    const nextStatus = remoteStatus.state;
+    return {
+        ...runRecord,
+        status: nextStatus,
+        endedAt: nextStatus === "completed" || nextStatus === "failed" || nextStatus === "cancelled" || nextStatus === "timed_out"
+            ? remoteStatus.checkedAt ?? new Date().toISOString()
+            : runRecord.endedAt,
+        resultSummary: summarizeRemoteStatus(remoteStatus, runRecord.resultSummary),
+        sessionRef: {
+            ...runRecord.sessionRef,
+            runtime,
+            sessionKey: runRecord.sessionRef?.sessionKey,
+        },
+        events: appendStatusEvent(runRecord, remoteStatus),
+    };
+}
+export function syncAcpRunRecord(runRecord, remoteStatus) {
+    if (runRecord.runner.type !== "acp") {
+        throw new Error("Only ACP run records can be synced");
+    }
+    const synced = {
+        ...applyTerminalFields(runRecord, remoteStatus, "acp"),
+        resultSummary: buildAcpSummary(remoteStatus, runRecord.resultSummary),
+        sessionRef: {
+            ...runRecord.sessionRef,
+            runtime: "acp",
+            sessionKey: remoteStatus.sessionKey,
+            backend: remoteStatus.backend ?? runRecord.sessionRef?.backend,
+            backendSessionId: remoteStatus.backendSessionId ?? runRecord.sessionRef?.backendSessionId,
+            agentSessionId: remoteStatus.agentSessionId ?? runRecord.sessionRef?.agentSessionId,
+        },
+    };
+    return {
+        runRecord: synced,
+        remoteStatus,
+    };
+}
+export function syncSubagentRunRecord(runRecord, remoteStatus) {
+    if (runRecord.runner.type !== "subagent") {
+        throw new Error("Only subagent run records can be synced");
+    }
+    const synced = {
+        ...applyTerminalFields(runRecord, remoteStatus, "subagent"),
+        resultSummary: buildSubagentSummary(remoteStatus, runRecord.resultSummary),
+    };
+    return {
+        runRecord: synced,
+        remoteStatus,
+    };
+}

package/dist/src/runtime/subagent-mapping.d.ts

@@ -0,0 +1,9 @@
+import type { TaskNode, WorkflowState } from "../types.js";
+import type { SubagentSpawnParams } from "./openclaw-subagent-adapter.js";
+export type SubagentPreflightResult = {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+};
+export declare function preflightSubagentTask(task: TaskNode): SubagentPreflightResult;
+export declare function buildSubagentSpawnParams(task: TaskNode, workflow: WorkflowState): SubagentSpawnParams;

package/dist/src/runtime/subagent-mapping.js

@@ -0,0 +1,31 @@
+export function preflightSubagentTask(task) {
+    const errors = [];
+    const warnings = [];
+    const mode = task.runner.mode ?? "run";
+    const thread = Boolean(task.runner.threadRequested);
+    if (mode === "session" && !thread) {
+        errors.push('subagent mode "session" requires threadRequested=true');
+    }
+    if (task.runner.persistentSession) {
+        warnings.push("persistentSession is ignored for subagent runner");
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+export function buildSubagentSpawnParams(task, workflow) {
+    const preflight = preflightSubagentTask(task);
+    if (!preflight.ok) {
+        throw new Error(`Subagent preflight failed: ${preflight.errors.join("; ")}`);
+    }
+    return {
+        task: task.description || task.title,
+        label: `${task.taskId}:${task.title}`,
+        agentId: task.runner.agentId,
+        mode: task.runner.mode ?? "run",
+        thread: Boolean(task.runner.threadRequested),
+        runTimeoutSeconds: task.runner.timeoutSeconds,
+    };
+}

package/dist/src/runtime/subagent-runner.d.ts

@@ -0,0 +1,9 @@
+import { type OpenClawSubagentAdapter } from "./openclaw-subagent-adapter.js";
+import type { RunnerPlan, RunnerPlanInput, RunnerRunInput, RunnerRunResult, TaskRunner } from "./task-runner.js";
+export declare class SubagentRunner implements TaskRunner {
+    private readonly subagentAdapter;
+    readonly kind: "subagent";
+    constructor(subagentAdapter?: OpenClawSubagentAdapter);
+    plan(input: RunnerPlanInput): Promise<RunnerPlan>;
+    run(input: RunnerRunInput): Promise<RunnerRunResult>;
+}

package/dist/src/runtime/subagent-runner.js

@@ -0,0 +1,63 @@
+import { buildSubagentSpawnParams } from "./subagent-mapping.js";
+import { UnsupportedOpenClawSubagentAdapter } from "./openclaw-subagent-adapter.js";
+export class SubagentRunner {
+    subagentAdapter;
+    kind = "subagent";
+    constructor(subagentAdapter = new UnsupportedOpenClawSubagentAdapter()) {
+        this.subagentAdapter = subagentAdapter;
+    }
+    async plan(input) {
+        const params = buildSubagentSpawnParams(input.task, input.workflow);
+        return {
+            runnable: true,
+            summary: `subagent runner is prepared for task ${input.task.taskId} in ${params.mode} mode`,
+            workspacePath: input.projectRoot,
+            nextStatus: "running",
+        };
+    }
+    async run(input) {
+        const params = buildSubagentSpawnParams(input.task, input.workflow);
+        const requestedAt = new Date().toISOString();
+        const accepted = await this.subagentAdapter.spawnSubagent(params);
+        const acceptedAt = accepted.acceptedAt ?? new Date().toISOString();
+        return {
+            accepted: true,
+            nextTaskStatus: "running",
+            runRecord: {
+                runId: accepted.runId,
+                taskId: input.task.taskId,
+                attempt: 1,
+                status: "accepted",
+                runner: { type: "subagent" },
+                workspacePath: input.projectRoot,
+                startedAt: requestedAt,
+                promptSummary: params.task,
+                resultSummary: accepted.note ?? `Subagent accepted: ${accepted.childSessionKey}`,
+                artifacts: [],
+                sessionRef: {
+                    runtime: "subagent",
+                    sessionKey: accepted.childSessionKey,
+                },
+                events: [
+                    {
+                        at: requestedAt,
+                        type: "spawn_requested",
+                        detail: {
+                            mode: params.mode,
+                            thread: params.thread,
+                            agentId: params.agentId,
+                        },
+                    },
+                    {
+                        at: acceptedAt,
+                        type: "spawn_accepted",
+                        detail: {
+                            childSessionKey: accepted.childSessionKey,
+                            runId: accepted.runId,
+                        },
+                    },
+                ],
+            },
+        };
+    }
+}

package/dist/src/runtime/task-runner.d.ts

@@ -0,0 +1,38 @@
+import type { RunRecord, SessionRecord, TaskNode, WorkflowState } from "../types.js";
+export type RunnerPlanInput = {
+    projectRoot: string;
+    task: TaskNode;
+    workflow: WorkflowState;
+    dryRun?: boolean;
+};
+export type RunnerPlan = {
+    runnable: boolean;
+    summary: string;
+    workspacePath: string;
+    nextStatus: TaskNode["status"];
+};
+export type RunnerRunInput = {
+    projectRoot: string;
+    task: TaskNode;
+    workflow: WorkflowState;
+    reusedSession?: SessionRecord;
+};
+export type RunnerRunResult = {
+    accepted: boolean;
+    runRecord: RunRecord;
+    nextTaskStatus: TaskNode["status"];
+};
+export type RunnerSyncInput = {
+    projectRoot: string;
+    task: TaskNode;
+    runRecord: RunRecord;
+};
+export type RunnerSyncResult = {
+    runRecord: RunRecord;
+};
+export interface TaskRunner {
+    kind: "manual" | "acp" | "subagent";
+    plan(input: RunnerPlanInput): Promise<RunnerPlan>;
+    run(input: RunnerRunInput): Promise<RunnerRunResult>;
+    sync?(input: RunnerSyncInput): Promise<RunnerSyncResult>;
+}

package/dist/src/runtime/task-runner.js

@@ -0,0 +1 @@
+export {};