@pellux/goodvibes-sdk 0.18.14 → 0.18.15

package/dist/_internal/platform/runtime/operator-client.js

@@ -0,0 +1,110 @@
+import { buildAuthInspectionSnapshot } from './auth/inspection.js';
+import { buildProviderAccountSnapshot } from './provider-accounts/registry.js';
+import { getProviderRuntimeSnapshot, getProviderUsageSnapshot, listProviderRuntimeSnapshots } from '../providers/runtime-snapshot.js';
+function normalizeLimit(limit) {
+    if (!Number.isFinite(limit))
+        return 1;
+    return Math.max(1, Math.floor(limit));
+}
+function listTasksSnapshot(snapshot, limit = 100) {
+    return snapshot.tasks.slice(0, normalizeLimit(limit));
+}
+function getTaskSnapshot(snapshot, taskId) {
+    return snapshot.tasks.find((task) => task.id === taskId) ?? null;
+}
+export function createOperatorClient(services) {
+    const sessions = {
+        current: () => services.readModels.session.getSnapshot(),
+        list: (limit = 100) => services.sessionBroker.listSessions(normalizeLimit(limit)),
+        get: (sessionId) => services.sessionBroker.getSession(sessionId),
+        messages: (sessionId, limit = 100) => services.sessionBroker.getMessages(sessionId, normalizeLimit(limit)),
+        inputs: (sessionId, limit = 100) => services.sessionBroker.getInputs(sessionId, normalizeLimit(limit)),
+        ensureSession: (input = {}) => services.sessionBroker.ensureSession(input),
+        close: (sessionId) => services.sessionBroker.closeSession(sessionId),
+        reopen: (sessionId) => services.sessionBroker.reopenSession(sessionId),
+        bindAgent: (sessionId, agentId) => services.sessionBroker.bindAgent(sessionId, agentId),
+        submitMessage: (input) => services.sessionBroker.submitMessage(input),
+        steerMessage: (input) => services.sessionBroker.steerMessage(input),
+        followUpMessage: (input) => services.sessionBroker.followUpMessage(input),
+        cancelInput: (sessionId, inputId) => services.sessionBroker.cancelInput(sessionId, inputId),
+    };
+    const tasks = {
+        snapshot: () => services.readModels.tasks.getSnapshot(),
+        list: (limit = 100) => listTasksSnapshot(services.readModels.tasks.getSnapshot(), limit),
+        get: (taskId) => getTaskSnapshot(services.readModels.tasks.getSnapshot(), taskId),
+        running: () => services.readModels.tasks.getSnapshot().tasks.filter((task) => task.status === 'running'),
+    };
+    const approvals = {
+        list: (limit = 100) => services.approvalBroker.listApprovals(normalizeLimit(limit)),
+        get: (approvalId) => services.approvalBroker.getApproval(approvalId),
+        request: (input) => services.approvalBroker.requestApproval(input),
+        claim: (approvalId, actor, actorSurface = 'operator', note) => services.approvalBroker.claimApproval(approvalId, actor, actorSurface, note),
+        resolve: (approvalId, input) => services.approvalBroker.resolveApproval(approvalId, input),
+        approve: (approvalId, actor, actorSurface = 'operator', note) => services.approvalBroker.resolveApproval(approvalId, {
+            approved: true,
+            actor,
+            actorSurface,
+            note,
+        }),
+        deny: (approvalId, actor, actorSurface = 'operator', note) => services.approvalBroker.resolveApproval(approvalId, {
+            approved: false,
+            actor,
+            actorSurface,
+            note,
+        }),
+        cancel: (approvalId, actor, actorSurface = 'operator', note) => services.approvalBroker.cancelApproval(approvalId, actor, actorSurface, note),
+        update: (approvalId, input) => services.approvalBroker.recordRemoteUpdate(approvalId, input),
+    };
+    const providers = {
+        listIds: () => services.readModels.providers.getSnapshot().providerIds,
+        runtimeSnapshots: () => listProviderRuntimeSnapshots(services.providerRegistry),
+        runtimeSnapshot: (providerId) => getProviderRuntimeSnapshot(services.providerRegistry, providerId),
+        usageSnapshot: (providerId) => getProviderUsageSnapshot(services.providerRegistry, providerId),
+        accountSnapshot: () => buildProviderAccountSnapshot({
+            providerRegistry: services.providerRegistry,
+            serviceRegistry: services.serviceRegistry,
+            subscriptionManager: services.subscriptionManager,
+            secretsManager: services.secretsManager,
+        }),
+        authInspection: () => buildAuthInspectionSnapshot({
+            serviceRegistry: services.serviceRegistry,
+            subscriptionManager: services.subscriptionManager,
+            secretsManager: services.secretsManager,
+        }),
+        snapshot: async () => {
+            const [runtimeSnapshots, accountSnapshot, authInspection] = await Promise.all([
+                listProviderRuntimeSnapshots(services.providerRegistry),
+                buildProviderAccountSnapshot({
+                    providerRegistry: services.providerRegistry,
+                    serviceRegistry: services.serviceRegistry,
+                    subscriptionManager: services.subscriptionManager,
+                    secretsManager: services.secretsManager,
+                }),
+                buildAuthInspectionSnapshot({
+                    serviceRegistry: services.serviceRegistry,
+                    subscriptionManager: services.subscriptionManager,
+                    secretsManager: services.secretsManager,
+                }),
+            ]);
+            return {
+                providerIds: services.readModels.providers.getSnapshot().providerIds,
+                runtimeSnapshots,
+                accountSnapshot,
+                authInspection,
+            };
+        },
+    };
+    const controlPlane = {
+        snapshot: () => services.readModels.controlPlane.getSnapshot(),
+        recentEvents: (limit = 6) => services.readModels.controlPlane.getSnapshot().recentEvents.slice(0, normalizeLimit(limit)),
+    };
+    return Object.freeze({
+        sessions,
+        tasks,
+        approvals,
+        providers,
+        controlPlane,
+        events: services.events,
+        shellPaths: services.shellPaths,
+    });
+}

package/dist/_internal/platform/runtime/ops/control-plane.d.ts

@@ -0,0 +1,96 @@
+import type { TaskManager } from '@pellux/goodvibes-sdk/platform/runtime/tasks/types';
+import type { RuntimeEventBus } from '../events/index.js';
+import type { RuntimeStore } from '../store/index.js';
+/** Thrown when an ops action is rejected because the state machine disallows it. */
+export declare class OpsIllegalActionError extends Error {
+    readonly targetId: string;
+    readonly action: string;
+    readonly currentState: string;
+    constructor(targetId: string, action: string, currentState: string);
+}
+/** Thrown when the target task or agent is not found. */
+export declare class OpsTargetNotFoundError extends Error {
+    readonly targetId: string;
+    readonly targetKind: 'task' | 'agent';
+    constructor(targetId: string, targetKind: 'task' | 'agent');
+}
+export declare class OpsControlPlane {
+    private readonly _taskManager;
+    private readonly _bus;
+    private readonly _store;
+    private readonly _dispatch;
+    private readonly _sessionId;
+    constructor(taskManager: TaskManager, bus: RuntimeEventBus, store: RuntimeStore, sessionId: string);
+    /**
+     * Cancel a task. Only legal from states that allow → cancelled transition.
+     *
+     * @param taskId - Target task ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the task doesn't exist.
+     * @throws {OpsIllegalActionError} if the task is in a terminal state.
+     */
+    cancelTask(taskId: string, note?: string): void;
+    /**
+     * Pause a running task (transitions running → blocked).
+     *
+     * Only legal from the 'running' state.
+     *
+     * @param taskId - Target task ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the task doesn't exist.
+     * @throws {OpsIllegalActionError} if the task is not running.
+     */
+    pauseTask(taskId: string, note?: string): void;
+    /**
+     * Resume a blocked task (transitions blocked → running).
+     *
+     * Only legal from the 'blocked' state.
+     *
+     * @param taskId - Target task ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the task doesn't exist.
+     * @throws {OpsIllegalActionError} if the task is not blocked.
+     */
+    resumeTask(taskId: string, note?: string): void;
+    /**
+     * Retry a failed task (transitions failed → queued by re-creating as queued).
+     *
+     * Re-queues the task via TaskManager, which clears terminal-state fields
+     * and transitions it back to 'queued'.
+     * This is only permitted from 'failed' or 'cancelled' states.
+     *
+     * @param taskId - Target task ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the task doesn't exist.
+     * @throws {OpsIllegalActionError} if the task is not in a retryable state.
+     */
+    retryTask(taskId: string, note?: string): void;
+    /**
+     * Cancel a running agent.
+     *
+     * Only legal for agents in non-terminal states (spawning, running,
+     * awaiting_message, awaiting_tool, finalizing).
+     *
+     * The agent state update is dispatched directly to the store since there is
+     * no AgentManager interface with lifecycle methods (agents are managed
+     * by their hosting subsystem). The store update signals the UI; the
+     * underlying subsystem must observe the store and act accordingly.
+     *
+     * @param agentId - Target agent ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the agent doesn't exist.
+     * @throws {OpsIllegalActionError} if the agent is already in a terminal state.
+     */
+    cancelAgent(agentId: string, note?: string): void;
+    /**
+     * Returns whether a task action is currently legal given its state.
+     * Used by the UI to conditionally render action controls.
+     */
+    canCancelTask(taskId: string): boolean;
+    canPauseTask(taskId: string): boolean;
+    canResumeTask(taskId: string): boolean;
+    canRetryTask(taskId: string): boolean;
+    canCancelAgent(agentId: string): boolean;
+    private _makeCtx;
+}
+//# sourceMappingURL=control-plane.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/ops/control-plane.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oDAAoD,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,mBAAmB,CAAC;AAiBtE,oFAAoF;AACpF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,YAAY,EAAE,MAAM,CAAC;gBAElB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAS1E;AAED,yDAAyD;AACzD,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;gBAE1B,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;CAMlE;AA+BD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGlC,WAAW,EAAE,WAAW,EACxB,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM;IAWnB;;;;;;;OAOG;IACI,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IA4BtD;;;;;;;;;OASG;IACI,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IA4BrD;;;;;;;;;OASG;IACI,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IA4BtD;;;;;;;;;;;OAWG;IACI,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IA+BrD;;;;;;;;;;;;;;;OAeG;IACI,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAqCxD;;;OAGG;IACI,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAKtC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAKrC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAKtC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAMrC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQ/C,OAAO,CAAC,QAAQ;CASjB"}

package/dist/_internal/platform/runtime/ops/control-plane.js

@@ -0,0 +1,298 @@
+/**
+ * OpsControlPlane — central dispatch point for all operator interventions.
+ *
+ * All task and agent control actions flow through this class. It:
+ * - Validates that the requested action is legal given the current state
+ * - Dispatches through the TaskManager (for task ops) or store (for agent ops)
+ * - Emits typed audit events via the RuntimeEventBus for every intervention
+ *
+ * This is the single integration point for the /ops commands and Ctrl+O panel.
+ */
+import { randomUUID } from 'node:crypto';
+import { createDomainDispatch } from '../store/index.js';
+import { canTransition } from '@pellux/goodvibes-sdk/platform/runtime/tasks/lifecycle';
+import { emitOpsTaskCancelled, emitOpsTaskPaused, emitOpsTaskResumed, emitOpsTaskRetried, emitOpsAgentCancelled, } from '../emitters/ops.js';
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+/** Thrown when an ops action is rejected because the state machine disallows it. */
+export class OpsIllegalActionError extends Error {
+    targetId;
+    action;
+    currentState;
+    constructor(targetId, action, currentState) {
+        super(`[OpsControlPlane] Action '${action}' is illegal for ${targetId} in state '${currentState}'`);
+        this.name = 'OpsIllegalActionError';
+        this.targetId = targetId;
+        this.action = action;
+        this.currentState = currentState;
+    }
+}
+/** Thrown when the target task or agent is not found. */
+export class OpsTargetNotFoundError extends Error {
+    targetId;
+    targetKind;
+    constructor(targetId, targetKind) {
+        super(`[OpsControlPlane] ${targetKind} not found: ${targetId}`);
+        this.name = 'OpsTargetNotFoundError';
+        this.targetId = targetId;
+        this.targetKind = targetKind;
+    }
+}
+// ---------------------------------------------------------------------------
+// OpsControlPlane
+// ---------------------------------------------------------------------------
+/**
+ * Task states from which a retry is permitted.
+ */
+const RETRYABLE_STATES = new Set(['failed', 'cancelled']);
+/**
+ * Terminal agent lifecycle states — agents in these states cannot be cancelled.
+ */
+const TERMINAL_AGENT_STATES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+]);
+/**
+ * Agent states from which cancellation is permitted.
+ */
+const CANCELLABLE_AGENT_STATES = new Set([
+    'spawning',
+    'running',
+    'awaiting_message',
+    'awaiting_tool',
+    'finalizing',
+]);
+export class OpsControlPlane {
+    _taskManager;
+    _bus;
+    _store;
+    _dispatch;
+    _sessionId;
+    constructor(taskManager, bus, store, sessionId) {
+        this._taskManager = taskManager;
+        this._bus = bus;
+        this._store = store;
+        this._dispatch = createDomainDispatch(store);
+        this._sessionId = sessionId;
+    }
+    // ── Task actions ──────────────────────────────────────────────────────────
+    /**
+     * Cancel a task. Only legal from states that allow → cancelled transition.
+     *
+     * @param taskId - Target task ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the task doesn't exist.
+     * @throws {OpsIllegalActionError} if the task is in a terminal state.
+     */
+    cancelTask(taskId, note) {
+        const task = this._taskManager.getTask(taskId);
+        if (!task) {
+            throw new OpsTargetNotFoundError(taskId, 'task');
+        }
+        if (!task.cancellable || !canTransition(task.status, 'cancelled')) {
+            const err = new OpsIllegalActionError(taskId, 'cancel', task.status);
+            emitOpsTaskCancelled(this._bus, this._makeCtx(taskId), {
+                taskId,
+                reason: 'ops_cancel',
+                note,
+                outcome: 'rejected',
+                errorMessage: err.message,
+            });
+            throw err;
+        }
+        this._taskManager.cancelTask(taskId, { reason: note ?? 'operator-cancel' });
+        emitOpsTaskCancelled(this._bus, this._makeCtx(taskId), {
+            taskId,
+            reason: 'ops_cancel',
+            note,
+            outcome: 'success',
+        });
+    }
+    /**
+     * Pause a running task (transitions running → blocked).
+     *
+     * Only legal from the 'running' state.
+     *
+     * @param taskId - Target task ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the task doesn't exist.
+     * @throws {OpsIllegalActionError} if the task is not running.
+     */
+    pauseTask(taskId, note) {
+        const task = this._taskManager.getTask(taskId);
+        if (!task) {
+            throw new OpsTargetNotFoundError(taskId, 'task');
+        }
+        if (!canTransition(task.status, 'blocked')) {
+            const err = new OpsIllegalActionError(taskId, 'pause', task.status);
+            emitOpsTaskPaused(this._bus, this._makeCtx(taskId), {
+                taskId,
+                reason: 'ops_pause',
+                note,
+                outcome: 'rejected',
+                errorMessage: err.message,
+            });
+            throw err;
+        }
+        this._taskManager.blockTask(taskId, note ?? 'operator-pause');
+        emitOpsTaskPaused(this._bus, this._makeCtx(taskId), {
+            taskId,
+            reason: 'ops_pause',
+            note,
+            outcome: 'success',
+        });
+    }
+    /**
+     * Resume a blocked task (transitions blocked → running).
+     *
+     * Only legal from the 'blocked' state.
+     *
+     * @param taskId - Target task ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the task doesn't exist.
+     * @throws {OpsIllegalActionError} if the task is not blocked.
+     */
+    resumeTask(taskId, note) {
+        const task = this._taskManager.getTask(taskId);
+        if (!task) {
+            throw new OpsTargetNotFoundError(taskId, 'task');
+        }
+        if (!canTransition(task.status, 'running')) {
+            const err = new OpsIllegalActionError(taskId, 'resume', task.status);
+            emitOpsTaskResumed(this._bus, this._makeCtx(taskId), {
+                taskId,
+                reason: 'ops_resume',
+                note,
+                outcome: 'rejected',
+                errorMessage: err.message,
+            });
+            throw err;
+        }
+        this._taskManager.startTask(taskId);
+        emitOpsTaskResumed(this._bus, this._makeCtx(taskId), {
+            taskId,
+            reason: 'ops_resume',
+            note,
+            outcome: 'success',
+        });
+    }
+    /**
+     * Retry a failed task (transitions failed → queued by re-creating as queued).
+     *
+     * Re-queues the task via TaskManager, which clears terminal-state fields
+     * and transitions it back to 'queued'.
+     * This is only permitted from 'failed' or 'cancelled' states.
+     *
+     * @param taskId - Target task ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the task doesn't exist.
+     * @throws {OpsIllegalActionError} if the task is not in a retryable state.
+     */
+    retryTask(taskId, note) {
+        const task = this._taskManager.getTask(taskId);
+        if (!task) {
+            throw new OpsTargetNotFoundError(taskId, 'task');
+        }
+        if (!RETRYABLE_STATES.has(task.status)) {
+            const err = new OpsIllegalActionError(taskId, 'retry', task.status);
+            emitOpsTaskRetried(this._bus, this._makeCtx(taskId), {
+                taskId,
+                reason: 'ops_retry',
+                note,
+                outcome: 'rejected',
+                errorMessage: err.message,
+            });
+            throw err;
+        }
+        // Route retry through TaskManager for consistent state management and event emission.
+        this._taskManager.retryTask(taskId);
+        emitOpsTaskRetried(this._bus, this._makeCtx(taskId), {
+            taskId,
+            reason: 'ops_retry',
+            note,
+            outcome: 'success',
+        });
+    }
+    // ── Agent actions ─────────────────────────────────────────────────────────
+    /**
+     * Cancel a running agent.
+     *
+     * Only legal for agents in non-terminal states (spawning, running,
+     * awaiting_message, awaiting_tool, finalizing).
+     *
+     * The agent state update is dispatched directly to the store since there is
+     * no AgentManager interface with lifecycle methods (agents are managed
+     * by their hosting subsystem). The store update signals the UI; the
+     * underlying subsystem must observe the store and act accordingly.
+     *
+     * @param agentId - Target agent ID.
+     * @param note - Optional operator note for the audit log.
+     * @throws {OpsTargetNotFoundError} if the agent doesn't exist.
+     * @throws {OpsIllegalActionError} if the agent is already in a terminal state.
+     */
+    cancelAgent(agentId, note) {
+        const state = this._store.getState();
+        const agent = state.agents.agents.get(agentId);
+        if (!agent) {
+            throw new OpsTargetNotFoundError(agentId, 'agent');
+        }
+        if (!CANCELLABLE_AGENT_STATES.has(agent.status)) {
+            const err = new OpsIllegalActionError(agentId, 'cancel', agent.status);
+            emitOpsAgentCancelled(this._bus, this._makeCtx(undefined, agentId), {
+                agentId,
+                reason: 'ops_agent_cancel',
+                note,
+                outcome: 'rejected',
+                errorMessage: err.message,
+            });
+            throw err;
+        }
+        this._dispatch.transitionRuntimeAgent(agentId, 'cancelled', { endedAt: Date.now() }, 'ops-control-plane');
+        emitOpsAgentCancelled(this._bus, this._makeCtx(undefined, agentId), {
+            agentId,
+            reason: 'ops_agent_cancel',
+            note,
+            outcome: 'success',
+        });
+    }
+    // ── Query helpers ─────────────────────────────────────────────────────────
+    /**
+     * Returns whether a task action is currently legal given its state.
+     * Used by the UI to conditionally render action controls.
+     */
+    canCancelTask(taskId) {
+        const task = this._taskManager.getTask(taskId);
+        return task != null && task.cancellable && canTransition(task.status, 'cancelled');
+    }
+    canPauseTask(taskId) {
+        const task = this._taskManager.getTask(taskId);
+        return task != null && canTransition(task.status, 'blocked');
+    }
+    canResumeTask(taskId) {
+        const task = this._taskManager.getTask(taskId);
+        return task != null && canTransition(task.status, 'running');
+    }
+    canRetryTask(taskId) {
+        const task = this._taskManager.getTask(taskId);
+        if (!task)
+            return false;
+        return task.status === 'failed' || task.status === 'cancelled';
+    }
+    canCancelAgent(agentId) {
+        const state = this._store.getState();
+        const agent = state.agents.agents.get(agentId);
+        return agent != null && CANCELLABLE_AGENT_STATES.has(agent.status);
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    _makeCtx(taskId, agentId) {
+        return {
+            sessionId: this._sessionId,
+            source: 'ops-control-plane',
+            traceId: randomUUID(),
+            ...(taskId !== undefined ? { taskId } : {}),
+            ...(agentId !== undefined ? { agentId } : {}),
+        };
+    }
+}

package/dist/_internal/platform/runtime/ops/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Operational runbook registry for the GoodVibes platform runtime.
+ *
+ * Provides a machine-readable playbook registry consumed by the diagnostics
+ * panel. Each playbook describes symptoms, diagnostic checks, resolution
+ * steps, and escalation criteria for a specific failure scenario.
+ *
+ * @example
+ * ```ts
+ * import { getPlaybookRegistry, getPlaybook } from './index.js';
+ *
+ * const registry = getPlaybookRegistry();
+ * const playbook = getPlaybook('stuck-turn');
+ * if (playbook) {
+ *   for (const check of playbook.checks) {
+ *     const result = await check.run();
+ *     console.log(check.label, result.passed ? 'PASS' : 'FAIL', result.summary);
+ *   }
+ * }
+ * ```
+ */
+export type { DiagnosticSeverity, DiagnosticCheckResult, DiagnosticCheck, PlaybookStepKind, PlaybookStep, Playbook, PlaybookRegistryEntry, PlaybookRegistry, } from '@pellux/goodvibes-sdk/platform/runtime/ops/types';
+export { stuckTurnPlaybook, reconnectFailurePlaybook, permissionDeadlockPlaybook, pluginDegradationPlaybook, exportRecoveryPlaybook, sessionUnrecoverablePlaybook, compactionFailurePlaybook, } from './playbooks/index.js';
+import type { Playbook, PlaybookRegistry } from '@pellux/goodvibes-sdk/platform/runtime/ops/types';
+/** Registry version — bump when playbooks are added or updated. */
+export declare const REGISTRY_VERSION = "1.0.0";
+/**
+ * Build and return the playbook registry.
+ *
+ * The registry is a Map keyed by playbook ID for O(1) lookup.
+ */
+export declare function getPlaybookRegistry(): PlaybookRegistry;
+/**
+ * Look up a single playbook by ID.
+ *
+ * @param id - The playbook ID (e.g. 'stuck-turn').
+ * @returns The playbook, or undefined if not found.
+ */
+export declare function getPlaybook(id: string): Playbook | undefined;
+/**
+ * Find playbooks whose tags overlap with the provided set.
+ *
+ * @param tags - One or more tag strings to match.
+ * @returns Playbooks that have at least one matching tag.
+ */
+export declare function findPlaybooksByTag(...tags: string[]): Playbook[];
+/**
+ * Find playbooks whose symptoms partially match the provided query string.
+ *
+ * @param query - A substring to search for in symptom descriptions.
+ * @returns Matching playbooks, sorted by number of matching symptoms (desc).
+ */
+export declare function findPlaybooksBySymptom(query: string): Playbook[];
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/ops/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/ops/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,kDAAkD,CAAC;AAG1D,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAyB,MAAM,kDAAkD,CAAC;AAsB1H,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAUtD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAOhE"}

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

@@ -0,0 +1,85 @@
+/**
+ * Operational runbook registry for the GoodVibes platform runtime.
+ *
+ * Provides a machine-readable playbook registry consumed by the diagnostics
+ * panel. Each playbook describes symptoms, diagnostic checks, resolution
+ * steps, and escalation criteria for a specific failure scenario.
+ *
+ * @example
+ * ```ts
+ * import { getPlaybookRegistry, getPlaybook } from './index.js';
+ *
+ * const registry = getPlaybookRegistry();
+ * const playbook = getPlaybook('stuck-turn');
+ * if (playbook) {
+ *   for (const check of playbook.checks) {
+ *     const result = await check.run();
+ *     console.log(check.label, result.passed ? 'PASS' : 'FAIL', result.summary);
+ *   }
+ * }
+ * ```
+ */
+// Re-export all playbooks
+export { stuckTurnPlaybook, reconnectFailurePlaybook, permissionDeadlockPlaybook, pluginDegradationPlaybook, exportRecoveryPlaybook, sessionUnrecoverablePlaybook, compactionFailurePlaybook, } from './playbooks/index.js';
+import { stuckTurnPlaybook, reconnectFailurePlaybook, permissionDeadlockPlaybook, pluginDegradationPlaybook, exportRecoveryPlaybook, sessionUnrecoverablePlaybook, compactionFailurePlaybook, } from './playbooks/index.js';
+/** All registered playbooks in definition order. */
+const ALL_PLAYBOOKS = [
+    stuckTurnPlaybook,
+    reconnectFailurePlaybook,
+    permissionDeadlockPlaybook,
+    pluginDegradationPlaybook,
+    exportRecoveryPlaybook,
+    sessionUnrecoverablePlaybook,
+    compactionFailurePlaybook,
+];
+/** Registry version — bump when playbooks are added or updated. */
+export const REGISTRY_VERSION = '1.0.0';
+/**
+ * Build and return the playbook registry.
+ *
+ * The registry is a Map keyed by playbook ID for O(1) lookup.
+ */
+export function getPlaybookRegistry() {
+    const registry = new Map();
+    for (const playbook of ALL_PLAYBOOKS) {
+        registry.set(playbook.id, {
+            playbook,
+            version: REGISTRY_VERSION,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    return registry;
+}
+/**
+ * Look up a single playbook by ID.
+ *
+ * @param id - The playbook ID (e.g. 'stuck-turn').
+ * @returns The playbook, or undefined if not found.
+ */
+export function getPlaybook(id) {
+    return ALL_PLAYBOOKS.find((p) => p.id === id);
+}
+/**
+ * Find playbooks whose tags overlap with the provided set.
+ *
+ * @param tags - One or more tag strings to match.
+ * @returns Playbooks that have at least one matching tag.
+ */
+export function findPlaybooksByTag(...tags) {
+    const tagSet = new Set(tags);
+    return ALL_PLAYBOOKS.filter((p) => p.tags.some((t) => tagSet.has(t)));
+}
+/**
+ * Find playbooks whose symptoms partially match the provided query string.
+ *
+ * @param query - A substring to search for in symptom descriptions.
+ * @returns Matching playbooks, sorted by number of matching symptoms (desc).
+ */
+export function findPlaybooksBySymptom(query) {
+    const lower = query.toLowerCase();
+    const scored = ALL_PLAYBOOKS.map((p) => ({
+        playbook: p,
+        matches: p.symptoms.filter((s) => s.toLowerCase().includes(lower)).length,
+    })).filter(({ matches }) => matches > 0);
+    return scored.sort((a, b) => b.matches - a.matches).map(({ playbook }) => playbook);
+}

package/dist/_internal/platform/runtime/ops/playbooks/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/ops/playbooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/ops/playbooks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,wEAAwE,CAAC;AAClH,OAAO,EAAE,0BAA0B,EAAE,MAAM,0EAA0E,CAAC;AACtH,OAAO,EAAE,yBAAyB,EAAE,MAAM,yEAAyE,CAAC;AACpH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sEAAsE,CAAC;AAC9G,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,yEAAyE,CAAC"}