@pellux/goodvibes-sdk 0.18.14 → 0.18.16

package/dist/_internal/platform/runtime/ops/playbooks/index.js

@@ -0,0 +1,10 @@
+/**
+ * Barrel export for operational playbooks.
+ */
+export { stuckTurnPlaybook } from './stuck-turn.js';
+export { reconnectFailurePlaybook } from '@pellux/goodvibes-sdk/platform/runtime/ops/playbooks/reconnect-failure';
+export { permissionDeadlockPlaybook } from '@pellux/goodvibes-sdk/platform/runtime/ops/playbooks/permission-deadlock';
+export { pluginDegradationPlaybook } from '@pellux/goodvibes-sdk/platform/runtime/ops/playbooks/plugin-degradation';
+export { exportRecoveryPlaybook } from '@pellux/goodvibes-sdk/platform/runtime/ops/playbooks/export-recovery';
+export { sessionUnrecoverablePlaybook } from './session-unrecoverable.js';
+export { compactionFailurePlaybook } from '@pellux/goodvibes-sdk/platform/runtime/ops/playbooks/compaction-failure';

package/dist/_internal/platform/runtime/ops/playbooks/session-unrecoverable.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Playbook: Session Unrecoverable
+ *
+ * Handles the scenario where session recovery has been exhausted and the
+ * runtime has emitted SESSION_UNRECOVERABLE — triggering a full-system cascade.
+ */
+import type { Playbook } from '@pellux/goodvibes-sdk/platform/runtime/ops/types';
+import type { OpsRuntimeContextState } from '../runtime-context.js';
+export declare function createSessionUnrecoverablePlaybook(getRuntimeContext?: () => OpsRuntimeContextState | null): Playbook;
+/** Session unrecoverable resolution playbook. */
+export declare const sessionUnrecoverablePlaybook: Playbook;
+//# sourceMappingURL=session-unrecoverable.d.ts.map

package/dist/_internal/platform/runtime/ops/playbooks/session-unrecoverable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-unrecoverable.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/ops/playbooks/session-unrecoverable.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,kDAAkD,CAAC;AAIxG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE,wBAAgB,kCAAkC,CAChD,iBAAiB,GAAE,MAAM,sBAAsB,GAAG,IAAiB,GAClE,QAAQ,CAkLV;AAED,iDAAiD;AACjD,eAAO,MAAM,4BAA4B,EAAE,QAA+C,CAAC"}

package/dist/_internal/platform/runtime/ops/playbooks/session-unrecoverable.js

@@ -0,0 +1,175 @@
+import { safeCheck } from '@pellux/goodvibes-sdk/platform/runtime/ops/safe-check';
+import { existsSync } from 'fs';
+import { readRecoveryFileMetadata } from '../runtime-context.js';
+export function createSessionUnrecoverablePlaybook(getRuntimeContext = () => null) {
+    return {
+        id: 'session-unrecoverable',
+        name: 'Session Unrecoverable',
+        description: 'Diagnoses and recovers from SESSION_UNRECOVERABLE events. ' +
+            'Fired when all session recovery attempts are exhausted, cascading to all domains.',
+        symptoms: [
+            'SESSION_UNRECOVERABLE event emitted on the runtime event bus',
+            'All domain health checks transitioning to failed or unknown',
+            'No new turns can be started; all in-flight operations cancelled',
+            'TUI shows system-wide failure banner',
+            'Session state file missing or corrupted',
+        ],
+        checks: [
+            {
+                id: 'session.recovery-attempts',
+                label: 'Session recovery attempts exhausted',
+                description: 'Confirms that all configured recovery attempts have been made before the cascade.',
+                run: async () => safeCheck(async () => {
+                    const runtime = getRuntimeContext();
+                    if (!runtime) {
+                        return {
+                            passed: false,
+                            summary: 'Ops runtime context is not configured.',
+                            severity: 'warning',
+                        };
+                    }
+                    const { session } = runtime.store.getState();
+                    const exhausted = session.recoveryState === 'failed';
+                    return {
+                        passed: !exhausted,
+                        summary: exhausted
+                            ? `Session recovery is in a failed state${session.recoveryError ? `: ${session.recoveryError}` : '.'}`
+                            : `Session recovery state is ${session.recoveryState}.`,
+                        severity: exhausted ? 'critical' : 'info',
+                        context: {
+                            recoveryState: session.recoveryState,
+                            recoveryError: session.recoveryError ?? '',
+                        },
+                    };
+                }),
+            },
+            {
+                id: 'session.state-file',
+                label: 'Session state file integrity',
+                description: 'Checks whether the session state file exists and is parseable.',
+                run: async () => safeCheck(async () => {
+                    const runtime = getRuntimeContext();
+                    if (!runtime) {
+                        return {
+                            passed: false,
+                            summary: 'Ops runtime context is not configured.',
+                            severity: 'warning',
+                        };
+                    }
+                    const recoveryMeta = readRecoveryFileMetadata(runtime.recoveryFilePath);
+                    const pointerExists = existsSync(runtime.lastSessionPointerPath);
+                    const passed = recoveryMeta.ok && pointerExists;
+                    return {
+                        passed,
+                        summary: passed
+                            ? 'Recovery artifact and last-session pointer are both present and readable.'
+                            : `${recoveryMeta.summary}${pointerExists ? '' : ' Last-session pointer file is missing.'}`,
+                        severity: passed ? 'info' : 'error',
+                        context: {
+                            recoveryFilePresent: existsSync(runtime.recoveryFilePath),
+                            lastSessionPointerPresent: pointerExists,
+                        },
+                    };
+                }),
+            },
+            {
+                id: 'session.event-bus-silent',
+                label: 'Event bus silent after cascade',
+                description: 'Verifies that no further domain events are being processed after SESSION_UNRECOVERABLE.',
+                run: async () => safeCheck(async () => {
+                    const runtime = getRuntimeContext();
+                    if (!runtime) {
+                        return {
+                            passed: false,
+                            summary: 'Ops runtime context is not configured.',
+                            severity: 'warning',
+                        };
+                    }
+                    if (!runtime.sessionRecoveryFailedAt) {
+                        return {
+                            passed: true,
+                            summary: 'No SESSION_RECOVERY_FAILED event has been observed in this runtime context.',
+                            severity: 'info',
+                            context: {
+                                sessionRecoveryFailedCount: runtime.sessionRecoveryFailedCount,
+                                sessionRecoveryFailedAt: 0,
+                                lastEventAt: runtime.lastEventAt,
+                            },
+                        };
+                    }
+                    const postCascadeActivity = runtime.lastEventAt > runtime.sessionRecoveryFailedAt;
+                    return {
+                        passed: !postCascadeActivity,
+                        summary: postCascadeActivity
+                            ? 'Runtime events are still being processed after SESSION_UNRECOVERABLE.'
+                            : 'No runtime events have been observed after SESSION_UNRECOVERABLE.',
+                        severity: postCascadeActivity ? 'warning' : 'info',
+                        context: {
+                            sessionRecoveryFailedAt: runtime.sessionRecoveryFailedAt,
+                            lastEventAt: runtime.lastEventAt,
+                            sessionRecoveryFailedCount: runtime.sessionRecoveryFailedCount,
+                        },
+                    };
+                }),
+            },
+        ],
+        steps: [
+            {
+                step: 1,
+                title: 'Capture full session state dump',
+                action: 'Before any recovery attempt, export the full runtime state snapshot ' +
+                    '(health, tasks, agents, active spans) to a diagnostic file.',
+                kind: 'observe',
+                expectedOutcome: 'State dump captured for post-mortem analysis.',
+                automatable: false,
+            },
+            {
+                step: 2,
+                title: 'Attempt graceful session restart',
+                action: 'Call runtime.session.restart() to attempt a clean session re-initialization. ' +
+                    'This resets all domain health, clears the event queue, and reinitialises plugins.',
+                kind: 'command',
+                command: 'runtime.session.restart()',
+                expectedOutcome: 'Session health returns to healthy; all domains reinitialise.',
+                automatable: true,
+            },
+            {
+                step: 3,
+                title: 'Clear corrupted session state',
+                action: 'If restart fails, remove or rename the corrupted session state file and restart. ' +
+                    'This loses in-progress turns but allows the runtime to boot fresh.',
+                kind: 'command',
+                command: 'runtime.session.clearState()',
+                expectedOutcome: 'Clean session state; turns must be re-submitted.',
+                automatable: true,
+            },
+            {
+                step: 4,
+                title: 'Verify plugin and MCP connectivity',
+                action: 'After session restart, confirm all plugins have re-connected to their MCP servers ' +
+                    'and tool registrations are complete.',
+                kind: 'observe',
+                expectedOutcome: 'All plugins HEALTHY; tool registry populated.',
+                automatable: false,
+            },
+            {
+                step: 5,
+                title: 'Escalate if restart loop detected',
+                action: 'If the session reaches SESSION_UNRECOVERABLE again within 5 minutes, ' +
+                    'escalate to human review — the root cause is not self-healing.',
+                kind: 'escalate',
+                expectedOutcome: 'Human-reviewed root cause identified and resolved.',
+                automatable: false,
+            },
+        ],
+        escalationCriteria: [
+            'SESSION_UNRECOVERABLE fires more than once within 5 minutes',
+            'Session state file cannot be written (disk full, permission denied)',
+            'All plugins fail to reconnect after session restart',
+            'Runtime process exits immediately after restart attempt',
+        ],
+        tags: ['session', 'unrecoverable', 'cascade', 'critical'],
+    };
+}
+/** Session unrecoverable resolution playbook. */
+export const sessionUnrecoverablePlaybook = createSessionUnrecoverablePlaybook();

package/dist/_internal/platform/runtime/ops/playbooks/stuck-turn.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Playbook: Stuck Turn / Task
+ *
+ * Diagnoses and resolves turns or tasks that have stopped progressing.
+ * Common causes: LLM timeout, tool deadlock, event loop stall.
+ */
+import type { Playbook } from '@pellux/goodvibes-sdk/platform/runtime/ops/types';
+import type { OpsRuntimeContextState } from '../runtime-context.js';
+export declare function createStuckTurnPlaybook(getRuntimeContext?: () => OpsRuntimeContextState | null): Playbook;
+/** Stuck turn / task resolution playbook. */
+export declare const stuckTurnPlaybook: Playbook;
+//# sourceMappingURL=stuck-turn.d.ts.map

package/dist/_internal/platform/runtime/ops/playbooks/stuck-turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stuck-turn.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/ops/playbooks/stuck-turn.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,kDAAkD,CAAC;AAExG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE,wBAAgB,uBAAuB,CACrC,iBAAiB,GAAE,MAAM,sBAAsB,GAAG,IAAiB,GAClE,QAAQ,CAqLV;AAED,6CAA6C;AAC7C,eAAO,MAAM,iBAAiB,EAAE,QAAoC,CAAC"}

package/dist/_internal/platform/runtime/ops/playbooks/stuck-turn.js

@@ -0,0 +1,176 @@
+import { safeCheck } from '@pellux/goodvibes-sdk/platform/runtime/ops/safe-check';
+export function createStuckTurnPlaybook(getRuntimeContext = () => null) {
+    return {
+        id: 'stuck-turn',
+        name: 'Stuck Turn / Task',
+        description: 'Diagnoses turns or tasks that have stopped progressing. ' +
+            'Covers LLM timeout, tool deadlock, and event-loop stall scenarios.',
+        symptoms: [
+            'Turn has been in-flight longer than the configured timeout',
+            'No new events emitted on the task event bus for > 30 s',
+            'Spinner/progress indicator frozen in TUI',
+            'CPU near 0% with pending async operations',
+            'Health check reports degraded turn throughput',
+        ],
+        checks: [
+            {
+                id: 'turn.timeout-elapsed',
+                label: 'Turn timeout elapsed',
+                description: 'Checks whether the active turn has exceeded its configured timeout.',
+                run: async () => safeCheck(async () => {
+                    const runtime = getRuntimeContext();
+                    if (!runtime) {
+                        return {
+                            passed: false,
+                            summary: 'Ops runtime context is not configured.',
+                            severity: 'warning',
+                        };
+                    }
+                    const { conversation } = runtime.store.getState();
+                    if (!conversation.currentTurnId || !conversation.turnStartedAt || conversation.turnState === 'idle') {
+                        return {
+                            passed: true,
+                            summary: 'No active turn is currently in flight.',
+                            severity: 'info',
+                        };
+                    }
+                    const elapsedMs = runtime.now() - conversation.turnStartedAt;
+                    const thresholdMs = 30_000;
+                    const exceeded = elapsedMs > thresholdMs;
+                    return {
+                        passed: !exceeded,
+                        summary: exceeded
+                            ? `Active turn ${conversation.currentTurnId} has exceeded ${thresholdMs}ms (${elapsedMs}ms elapsed).`
+                            : `Active turn ${conversation.currentTurnId} is still within the ${thresholdMs}ms threshold.`,
+                        severity: exceeded ? 'error' : 'info',
+                        context: {
+                            turnId: conversation.currentTurnId,
+                            turnState: conversation.turnState,
+                            elapsedMs,
+                            thresholdMs,
+                        },
+                    };
+                }),
+            },
+            {
+                id: 'turn.event-bus-silent',
+                label: 'Event bus silent',
+                description: 'Checks whether the RuntimeEventBus has emitted any events recently.',
+                run: async () => safeCheck(async () => {
+                    const runtime = getRuntimeContext();
+                    if (!runtime) {
+                        return {
+                            passed: false,
+                            summary: 'Ops runtime context is not configured.',
+                            severity: 'warning',
+                        };
+                    }
+                    const silenceMs = runtime.now() - runtime.lastEventAt;
+                    const thresholdMs = 30_000;
+                    const silent = silenceMs > thresholdMs;
+                    return {
+                        passed: !silent,
+                        summary: silent
+                            ? `No runtime events have been observed for ${silenceMs}ms.`
+                            : `Runtime event flow is active (${silenceMs}ms since the last event).`,
+                        severity: silent ? 'warning' : 'info',
+                        context: {
+                            silenceMs,
+                            thresholdMs,
+                            lastEventAt: runtime.lastEventAt,
+                        },
+                    };
+                }),
+            },
+            {
+                id: 'turn.pending-tool-calls',
+                label: 'Pending tool calls',
+                description: 'Checks for tool calls that have been dispatched but not yet resolved.',
+                run: async () => safeCheck(async () => {
+                    const runtime = getRuntimeContext();
+                    if (!runtime) {
+                        return {
+                            passed: false,
+                            summary: 'Ops runtime context is not configured.',
+                            severity: 'warning',
+                        };
+                    }
+                    const { conversation, permissions } = runtime.store.getState();
+                    const pendingToolCalls = conversation.activeToolCalls.size;
+                    const awaitingDecision = permissions.awaitingDecision;
+                    const blocked = pendingToolCalls > 0 || awaitingDecision;
+                    return {
+                        passed: !blocked,
+                        summary: blocked
+                            ? `Detected ${pendingToolCalls} active tool call(s)${awaitingDecision ? ' with a permission decision still pending' : ''}.`
+                            : 'No active tool calls or pending permission decisions detected.',
+                        severity: blocked ? 'warning' : 'info',
+                        context: {
+                            pendingToolCalls,
+                            awaitingDecision,
+                        },
+                    };
+                }),
+            },
+        ],
+        steps: [
+            {
+                step: 1,
+                title: 'Identify stuck span',
+                action: 'Query the active span list from the RuntimeTracer. ' +
+                    'Look for spans with durationMs > turnTimeoutMs and status UNSET.',
+                kind: 'observe',
+                expectedOutcome: 'One or more spans identified as candidates.',
+                automatable: false,
+            },
+            {
+                step: 2,
+                title: 'Check for tool deadlock',
+                action: 'Inspect the PhasedToolExecutor queue for tools awaiting permissions or locks. ' +
+                    'Cross-reference with PermissionManager.pendingRequests().',
+                kind: 'observe',
+                command: 'runtime.tools.executor.dumpState()',
+                expectedOutcome: 'Tool queue is empty or shows a specific blocked tool.',
+                automatable: false,
+            },
+            {
+                step: 3,
+                title: 'Cancel the stuck turn',
+                action: 'Emit a task.cancel event on the RuntimeEventBus with the stuck taskId. ' +
+                    'The TaskStateMachine should transition to CANCELLED within 1 s.',
+                kind: 'command',
+                command: 'eventBus.emit("task.cancel", { taskId })',
+                expectedOutcome: 'Turn transitions to CANCELLED; health check recovers.',
+                automatable: true,
+            },
+            {
+                step: 4,
+                title: 'Restart turn with reduced timeout',
+                action: 'Re-submit the failed turn with a shorter LLM timeout (e.g. 30 s) and ' +
+                    'tool-use disabled to isolate whether the model or a tool is the root cause.',
+                kind: 'command',
+                command: 'runtime.submitTurn({ ...turnPayload, timeoutMs: 30_000, tools: [] })',
+                expectedOutcome: 'Turn completes or fails fast with a clear error.',
+                automatable: false,
+            },
+            {
+                step: 5,
+                title: 'Review LLM provider health',
+                action: 'Check the provider health dashboard or call the provider status endpoint. ' +
+                    'Consider switching to a fallback provider if degraded.',
+                kind: 'observe',
+                expectedOutcome: 'Provider status confirmed healthy or fallback selected.',
+                automatable: false,
+            },
+        ],
+        escalationCriteria: [
+            'Multiple consecutive turns stuck after attempting cancel+restart',
+            'Event loop stall confirmed by > 60 s with zero runtime events',
+            'Memory usage growing continuously without turns completing',
+            'Core health check reports CRITICAL for > 5 minutes',
+        ],
+        tags: ['turn', 'task', 'timeout', 'deadlock', 'llm'],
+    };
+}
+/** Stuck turn / task resolution playbook. */
+export const stuckTurnPlaybook = createStuckTurnPlaybook();

package/dist/_internal/platform/runtime/ops/runtime-context.d.ts

@@ -0,0 +1,26 @@
+import type { RuntimeEventBus } from '../events/index.js';
+import type { RuntimeStore } from '../store/index.js';
+export interface OpsRuntimeContextConfig {
+    runtimeBus: RuntimeEventBus;
+    store: RuntimeStore;
+    recoveryFilePath: string;
+    lastSessionPointerPath: string;
+    now?: () => number;
+}
+export interface OpsRuntimeContextState {
+    runtimeBus: RuntimeEventBus;
+    store: RuntimeStore;
+    recoveryFilePath: string;
+    lastSessionPointerPath: string;
+    now: () => number;
+    lastEventAt: number;
+    sessionRecoveryFailedAt?: number;
+    sessionRecoveryFailedCount: number;
+    detach: () => void;
+}
+export declare function withOpsRuntimeContext<T>(config: OpsRuntimeContextConfig, fn: () => Promise<T> | T): Promise<T>;
+export declare function readRecoveryFileMetadata(path: string): {
+    ok: boolean;
+    summary: string;
+};
+//# sourceMappingURL=runtime-context.d.ts.map

package/dist/_internal/platform/runtime/ops/runtime-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-context.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/ops/runtime-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,0BAA0B,EAAE,MAAM,CAAC;IACnC,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AA8CD,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,MAAM,EAAE,uBAAuB,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiBvF"}

package/dist/_internal/platform/runtime/ops/runtime-context.js

@@ -0,0 +1,71 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { existsSync, readFileSync } from 'fs';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+const OBSERVED_DOMAINS = [
+    'session',
+    'turn',
+    'tools',
+    'tasks',
+    'agents',
+    'workflows',
+    'providers',
+    'permissions',
+    'planner',
+    'plugins',
+    'mcp',
+    'transport',
+    'ops',
+];
+const scopedContext = new AsyncLocalStorage();
+function createOpsRuntimeContextState(config) {
+    const now = config.now ?? Date.now;
+    const unsubs = OBSERVED_DOMAINS.map((domain) => config.runtimeBus.onDomain(domain, (envelope) => {
+        state.lastEventAt = envelope.ts;
+        if (envelope.type === 'SESSION_RECOVERY_FAILED') {
+            state.sessionRecoveryFailedAt = envelope.ts;
+            state.sessionRecoveryFailedCount += 1;
+        }
+    }));
+    const state = {
+        runtimeBus: config.runtimeBus,
+        store: config.store,
+        recoveryFilePath: config.recoveryFilePath,
+        lastSessionPointerPath: config.lastSessionPointerPath,
+        now,
+        lastEventAt: now(),
+        sessionRecoveryFailedCount: 0,
+        detach: () => {
+            for (const unsub of unsubs)
+                unsub();
+        },
+    };
+    return state;
+}
+export async function withOpsRuntimeContext(config, fn) {
+    const state = createOpsRuntimeContextState(config);
+    try {
+        return await scopedContext.run(state, fn);
+    }
+    finally {
+        state.detach();
+    }
+}
+export function readRecoveryFileMetadata(path) {
+    if (!existsSync(path)) {
+        return { ok: false, summary: 'Recovery file does not exist.' };
+    }
+    try {
+        const [firstLine] = readFileSync(path, 'utf-8').split('\n');
+        if (!firstLine) {
+            return { ok: false, summary: 'Recovery file exists but is empty.' };
+        }
+        JSON.parse(firstLine);
+        return { ok: true, summary: 'Recovery file exists and has valid metadata.' };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: `Recovery file is not parseable: ${summarizeError(error)}`,
+        };
+    }
+}

package/dist/_internal/platform/runtime/ops-api.d.ts

@@ -0,0 +1,25 @@
+import type { RuntimeTask } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/tasks';
+import type { UiTasksSnapshot } from './ui-read-models.js';
+import type { TaskCreateParams, TaskFailParams, TaskUpdateParams } from '@pellux/goodvibes-sdk/platform/runtime/tasks/types';
+export interface OpsTaskApi {
+    snapshot(): UiTasksSnapshot;
+    list(limit?: number): readonly RuntimeTask[];
+    get(taskId: string): RuntimeTask | null;
+    running(): readonly RuntimeTask[];
+    create(input: TaskCreateParams): RuntimeTask;
+    update(taskId: string, input: TaskUpdateParams): RuntimeTask;
+    complete(taskId: string, result?: unknown): RuntimeTask;
+    fail(taskId: string, input: TaskFailParams): RuntimeTask;
+    cancel(taskId: string, note?: string): void;
+    pause(taskId: string, note?: string): void;
+    resume(taskId: string, note?: string): void;
+    retry(taskId: string, note?: string): void;
+}
+export interface OpsAgentApi {
+    cancel(agentId: string, note?: string): void;
+}
+export interface OpsApi {
+    readonly tasks: OpsTaskApi;
+    readonly agents: OpsAgentApi;
+}
+//# sourceMappingURL=ops-api.d.ts.map

package/dist/_internal/platform/runtime/ops-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops-api.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/runtime/ops-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4DAA4D,CAAC;AAC9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oDAAoD,CAAC;AAE7H,MAAM,WAAW,UAAU;IACzB,QAAQ,IAAI,eAAe,CAAC;IAC5B,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAAC;IAC7C,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IACxC,OAAO,IAAI,SAAS,WAAW,EAAE,CAAC;IAClC,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAC7C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IACxD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,WAAW,CAAC;IACzD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B"}

package/dist/_internal/platform/runtime/ops-api.js

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

package/dist/_internal/platform/runtime/orchestration/spawn-policy.d.ts

@@ -0,0 +1,24 @@
+import type { ConfigManager } from '../../config/manager.js';
+export type OrchestrationSpawnMode = 'manual-batch' | 'plan-auto' | 'recursive-child';
+export type OrchestrationSpawnDecision = {
+    allowed: boolean;
+    reason?: string;
+    maxAgents: number;
+    activeAgents: number;
+    availableSlots: number;
+    requestedDepth: number;
+    maxDepth: number;
+    mode: OrchestrationSpawnMode;
+};
+export declare function evaluateOrchestrationSpawn(input: {
+    configManager: Pick<ConfigManager, 'get'>;
+    mode: OrchestrationSpawnMode;
+    activeAgents: number;
+    requestedDepth?: number;
+    overrides?: {
+        recursionEnabled?: boolean;
+        maxAgents?: number;
+        maxDepth?: number;
+    };
+}): OrchestrationSpawnDecision;
+//# sourceMappingURL=spawn-policy.d.ts.map

package/dist/_internal/platform/runtime/orchestration/spawn-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-policy.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/orchestration/spawn-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAEtF,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,sBAAsB,CAAC;CAC9B,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IAC1C,IAAI,EAAE,sBAAsB,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE;QACV,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH,GAAG,0BAA0B,CAyD7B"}

package/dist/_internal/platform/runtime/orchestration/spawn-policy.js

@@ -0,0 +1,54 @@
+export function evaluateOrchestrationSpawn(input) {
+    const maxAgents = input.overrides?.maxAgents ?? (input.configManager.get('orchestration.maxActiveAgents') ?? 8);
+    const maxDepth = input.overrides?.maxDepth ?? (input.configManager.get('orchestration.maxDepth') ?? 0);
+    const recursionEnabled = input.overrides?.recursionEnabled ?? (input.configManager.get('orchestration.recursionEnabled') ?? false);
+    const requestedDepth = input.requestedDepth ?? 0;
+    const availableSlots = Math.max(0, maxAgents - input.activeAgents);
+    if (input.mode === 'recursive-child' || input.mode === 'plan-auto') {
+        if (!recursionEnabled) {
+            return {
+                allowed: false,
+                reason: 'recursive orchestration is disabled',
+                maxAgents,
+                activeAgents: input.activeAgents,
+                availableSlots,
+                requestedDepth,
+                maxDepth,
+                mode: input.mode,
+            };
+        }
+    }
+    if (input.mode === 'recursive-child' && requestedDepth > maxDepth) {
+        return {
+            allowed: false,
+            reason: `requested depth ${requestedDepth} exceeds configured recursion depth ${maxDepth}`,
+            maxAgents,
+            activeAgents: input.activeAgents,
+            availableSlots,
+            requestedDepth,
+            maxDepth,
+            mode: input.mode,
+        };
+    }
+    if (availableSlots <= 0) {
+        return {
+            allowed: false,
+            reason: `agent capacity reached (${input.activeAgents}/${maxAgents})`,
+            maxAgents,
+            activeAgents: input.activeAgents,
+            availableSlots,
+            requestedDepth,
+            maxDepth,
+            mode: input.mode,
+        };
+    }
+    return {
+        allowed: true,
+        maxAgents,
+        activeAgents: input.activeAgents,
+        availableSlots,
+        requestedDepth,
+        maxDepth,
+        mode: input.mode,
+    };
+}