@pellux/goodvibes-tui 0.18.4

package/src/runtime/remote/runner-registry.ts

@@ -0,0 +1,438 @@
+import { mkdirSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import type { AgentManager } from '../../tools/agent/index.ts';
+import type { AgentRecord } from '../../tools/agent/manager.ts';
+import type { RuntimeStore } from '../store/index.ts';
+import type { AcpConnection } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/acp';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import type {
+  RemoteExecutionArtifact,
+  RemoteRunnerContract,
+  RemoteRunnerCapabilityCeiling,
+  RemoteRunnerEvidenceSummary,
+  RemoteRunnerPool,
+  RemoteSessionBundle,
+} from '@pellux/goodvibes-sdk/platform/runtime/remote/types';
+import type { RuntimeTask } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/tasks';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+const DEFAULT_ARTIFACT_DIR = '.goodvibes/remote-artifacts';
+const DEFAULT_SESSION_BUNDLE_DIR = '.goodvibes/remote-sessions';
+
+function buildCapabilityCeiling(agent: AgentRecord): RemoteRunnerCapabilityCeiling {
+  return Object.freeze({
+    allowedTools: [...agent.tools],
+    capabilityCeilingTools: [...(agent.capabilityCeilingTools ?? agent.tools)],
+    executionProtocol: agent.executionProtocol,
+    reviewMode: agent.reviewMode,
+    communicationLane: agent.communicationLane,
+    orchestrationDepth: agent.orchestrationDepth,
+    successCriteria: [...(agent.successCriteria ?? [])],
+    requiredEvidence: [...(agent.requiredEvidence ?? [])],
+    writeScope: [...(agent.writeScope ?? [])],
+  });
+}
+
+function buildEvidenceSummary(agent: AgentRecord, connection?: AcpConnection): RemoteRunnerEvidenceSummary {
+  return Object.freeze({
+    toolCallCount: agent.toolCallCount,
+    messageCount: connection?.messageCount ?? 0,
+    errorCount: connection?.errorCount ?? 0,
+    transportState: connection?.transportState ?? 'disconnected',
+    connectedAt: connection?.connectedAt,
+    lastError: connection?.lastError ?? agent.error,
+    hasKnowledgeInjections: (agent.knowledgeInjections?.length ?? 0) > 0,
+  });
+}
+
+function summarizeOutput(agent: AgentRecord): string {
+  const raw = agent.fullOutput ?? agent.progress ?? agent.error ?? 'No output recorded.';
+  const normalized = raw.replace(/\s+/g, ' ').trim();
+  return normalized.length <= 180 ? normalized : `${normalized.slice(0, 177)}...`;
+}
+
+function buildContract(agent: AgentRecord, connection?: AcpConnection, existing?: RemoteRunnerContract): RemoteRunnerContract {
+  return Object.freeze({
+    id: `runner:${agent.id}`,
+    runnerId: agent.id,
+    poolId: existing?.poolId,
+    taskId: connection?.taskId,
+    label: connection?.label ?? `${agent.template} runner`,
+    sourceTransport: connection ? 'acp' : 'daemon',
+    trustClass: connection ? 'self-hosted-acp' : 'local-daemon',
+    template: agent.template,
+    parentAgentId: agent.parentAgentId,
+    orchestrationGraphId: agent.orchestrationGraphId,
+    orchestrationNodeId: agent.orchestrationNodeId,
+    capabilityCeiling: buildCapabilityCeiling(agent),
+    createdAt: agent.startedAt,
+    lastUpdatedAt: agent.completedAt ?? Date.now(),
+    transport: Object.freeze({
+      state: connection?.transportState ?? 'disconnected',
+      connectedAt: connection?.connectedAt,
+      messageCount: connection?.messageCount ?? 0,
+      errorCount: connection?.errorCount ?? 0,
+      lastError: connection?.lastError,
+    }),
+  });
+}
+
+function buildArtifact(agent: AgentRecord, contract: RemoteRunnerContract, connection?: AcpConnection): RemoteExecutionArtifact {
+  return Object.freeze({
+    id: `artifact:${agent.id}:${Date.now()}`,
+    runnerId: agent.id,
+    createdAt: Date.now(),
+    runnerContract: contract,
+    task: Object.freeze({
+      task: agent.task,
+      status: agent.status,
+      startedAt: agent.startedAt,
+      completedAt: agent.completedAt,
+      summary: summarizeOutput(agent),
+      fullOutput: agent.fullOutput,
+      error: agent.error,
+      progress: agent.progress,
+    }),
+    evidence: buildEvidenceSummary(agent, connection),
+    knowledgeInjections: Object.freeze([...(agent.knowledgeInjections ?? [])]),
+  });
+}
+
+function summarizeTaskOutput(task?: RuntimeTask): string {
+  if (!task) return 'No task output recorded.';
+  const payload = (
+    typeof task.result === 'string'
+      ? task.result
+      : task.error
+        ?? (task.result !== undefined ? JSON.stringify(task.result) : task.description)
+        ?? task.title
+  );
+  const normalized = String(payload).replace(/\s+/g, ' ').trim();
+  return normalized.length <= 180 ? normalized : `${normalized.slice(0, 177)}...`;
+}
+
+function findTaskForContract(contract: RemoteRunnerContract, store?: RuntimeStore): RuntimeTask | undefined {
+  if (!store) return undefined;
+  const tasks = store.getState().tasks.tasks;
+  if (contract.taskId) {
+    const byTaskId = tasks.get(contract.taskId);
+    if (byTaskId) return byTaskId;
+  }
+  for (const task of tasks.values()) {
+    if (task.owner === contract.runnerId && task.kind === 'acp') {
+      return task;
+    }
+  }
+  return undefined;
+}
+
+function mapTaskStatus(
+  task?: RuntimeTask,
+): 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' {
+  switch (task?.status) {
+    case 'queued':
+      return 'pending';
+    case 'running':
+    case 'blocked':
+      return 'running';
+    case 'completed':
+      return 'completed';
+    case 'failed':
+      return 'failed';
+    case 'cancelled':
+      return 'cancelled';
+    default:
+      return 'running';
+  }
+}
+
+function buildArtifactFromStore(
+  contract: RemoteRunnerContract,
+  store?: RuntimeStore,
+): RemoteExecutionArtifact {
+  const connection = contract.runnerId ? store?.getState().acp.connections.get(contract.runnerId) : undefined;
+  const task = findTaskForContract(contract, store);
+  return Object.freeze({
+    id: `artifact:${contract.runnerId}:${Date.now()}`,
+    runnerId: contract.runnerId,
+    createdAt: Date.now(),
+    runnerContract: contract,
+    task: Object.freeze({
+      task: task?.description ?? task?.title ?? contract.label,
+      status: mapTaskStatus(task),
+      startedAt: task?.startedAt ?? contract.createdAt,
+      completedAt: task?.endedAt,
+      summary: summarizeTaskOutput(task),
+      ...(typeof task?.result === 'string' ? { fullOutput: task.result } : {}),
+      ...(task?.error ? { error: task.error } : {}),
+    }),
+    evidence: Object.freeze({
+      toolCallCount: 0,
+      messageCount: connection?.messageCount ?? contract.transport.messageCount,
+      errorCount: connection?.errorCount ?? contract.transport.errorCount,
+      transportState: connection?.transportState ?? contract.transport.state,
+      connectedAt: connection?.connectedAt ?? contract.transport.connectedAt,
+      lastError: connection?.lastError ?? contract.transport.lastError,
+      hasKnowledgeInjections: false,
+    }),
+    knowledgeInjections: Object.freeze([]),
+  });
+}
+
+export class RemoteRunnerRegistry {
+  private readonly contracts = new Map<string, RemoteRunnerContract>();
+  private readonly artifacts = new Map<string, RemoteExecutionArtifact>();
+  private readonly pools = new Map<string, RemoteRunnerPool>();
+  constructor(private readonly agentManager: Pick<AgentManager, 'getStatus' | 'list'>) {
+  }
+
+  private resolveConnection(agentId: string, store?: RuntimeStore): AcpConnection | undefined {
+    return store?.getState().acp.connections.get(agentId);
+  }
+
+  upsertContractForAgent(agentId: string, store?: RuntimeStore): RemoteRunnerContract | null {
+    const agent = this.agentManager.getStatus(agentId);
+    if (!agent) return null;
+    const contract = buildContract(agent, this.resolveConnection(agentId, store), this.contracts.get(agentId) ?? undefined);
+    this.contracts.set(agentId, contract);
+    if (contract.poolId) {
+      this.assignRunnerToPool(contract.poolId, contract.runnerId);
+    }
+    return contract;
+  }
+
+  getContract(agentId: string): RemoteRunnerContract | null {
+    return this.contracts.get(agentId) ?? null;
+  }
+
+  registerContract(contract: RemoteRunnerContract): RemoteRunnerContract {
+    this.contracts.set(contract.runnerId, contract);
+    if (contract.poolId) {
+      this.assignRunnerToPool(contract.poolId, contract.runnerId);
+    }
+    return contract;
+  }
+
+  listContracts(): RemoteRunnerContract[] {
+    return [...this.contracts.values()].sort((a, b) => b.lastUpdatedAt - a.lastUpdatedAt);
+  }
+
+  createPool(input: {
+    id: string;
+    label?: string;
+    description?: string;
+    trustClass?: RemoteRunnerPool['trustClass'];
+    preferredTemplate?: string;
+    maxRunners?: number;
+  }): RemoteRunnerPool {
+    const existing = this.pools.get(input.id);
+    const now = Date.now();
+    const pool: RemoteRunnerPool = Object.freeze({
+      id: input.id,
+      label: input.label ?? existing?.label ?? input.id,
+      description: input.description ?? existing?.description,
+      trustClass: input.trustClass ?? existing?.trustClass ?? 'self-hosted-acp',
+      preferredTemplate: input.preferredTemplate ?? existing?.preferredTemplate,
+      maxRunners: input.maxRunners ?? existing?.maxRunners,
+      runnerIds: existing?.runnerIds ?? [],
+      createdAt: existing?.createdAt ?? now,
+      lastUpdatedAt: now,
+    });
+    this.pools.set(pool.id, pool);
+    return pool;
+  }
+
+  getPool(poolId: string): RemoteRunnerPool | null {
+    return this.pools.get(poolId) ?? null;
+  }
+
+  listPools(): RemoteRunnerPool[] {
+    return [...this.pools.values()].sort((a, b) => b.lastUpdatedAt - a.lastUpdatedAt);
+  }
+
+  assignRunnerToPool(poolId: string, runnerId: string): RemoteRunnerPool | null {
+    const contract = this.contracts.get(runnerId);
+    const pool = this.pools.get(poolId) ?? this.createPool({ id: poolId, label: poolId });
+    if (pool.maxRunners !== undefined && !pool.runnerIds.includes(runnerId) && pool.runnerIds.length >= pool.maxRunners) {
+      return null;
+    }
+    const nextRunnerIds = pool.runnerIds.includes(runnerId)
+      ? pool.runnerIds
+      : [...pool.runnerIds, runnerId];
+    const nextPool: RemoteRunnerPool = Object.freeze({
+      ...pool,
+      runnerIds: nextRunnerIds,
+      lastUpdatedAt: Date.now(),
+    });
+    this.pools.set(poolId, nextPool);
+    if (contract && contract.poolId !== poolId) {
+      this.contracts.set(runnerId, Object.freeze({ ...contract, poolId, lastUpdatedAt: Date.now() }));
+    }
+    return nextPool;
+  }
+
+  removeRunnerFromPool(poolId: string, runnerId: string): RemoteRunnerPool | null {
+    const pool = this.pools.get(poolId);
+    if (!pool) return null;
+    const nextPool: RemoteRunnerPool = Object.freeze({
+      ...pool,
+      runnerIds: pool.runnerIds.filter((id) => id !== runnerId),
+      lastUpdatedAt: Date.now(),
+    });
+    this.pools.set(poolId, nextPool);
+    const contract = this.contracts.get(runnerId);
+    if (contract?.poolId === poolId) {
+      this.contracts.set(runnerId, Object.freeze({ ...contract, poolId: undefined, lastUpdatedAt: Date.now() }));
+    }
+    return nextPool;
+  }
+
+  captureArtifactForAgent(agentId: string, store?: RuntimeStore): RemoteExecutionArtifact | null {
+    const agent = this.agentManager.getStatus(agentId);
+    if (!agent) return null;
+    const connection = this.resolveConnection(agentId, store);
+    const contract = this.upsertContractForAgent(agentId, store) ?? buildContract(agent, connection);
+    const artifact = buildArtifact(agent, contract, connection);
+    this.artifacts.set(artifact.id, artifact);
+    return artifact;
+  }
+
+  captureArtifactForRunner(runnerId: string, store?: RuntimeStore): RemoteExecutionArtifact | null {
+    const byAgent = this.captureArtifactForAgent(runnerId, store);
+    if (byAgent) return byAgent;
+    const contract = this.contracts.get(runnerId);
+    if (!contract) return null;
+    const artifact = buildArtifactFromStore(contract, store);
+    this.artifacts.set(artifact.id, artifact);
+    return artifact;
+  }
+
+  getArtifact(artifactId: string): RemoteExecutionArtifact | null {
+    return this.artifacts.get(artifactId) ?? null;
+  }
+
+  listArtifacts(): RemoteExecutionArtifact[] {
+    return [...this.artifacts.values()].sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async exportArtifact(
+    artifactId: string,
+    explicitPath?: string,
+  ): Promise<{ artifact: RemoteExecutionArtifact; path: string } | null> {
+    const artifact = this.getArtifact(artifactId);
+    if (!artifact) return null;
+    const path = explicitPath
+      ? resolve(explicitPath)
+      : resolve(DEFAULT_ARTIFACT_DIR, `${artifact.id.replace(/[:]/g, '_')}.json`);
+    mkdirSync(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(artifact, null, 2)}\n`, 'utf-8');
+    return { artifact, path };
+  }
+
+  async importArtifact(path: string): Promise<RemoteExecutionArtifact> {
+    const raw = await readFile(resolve(path), 'utf-8');
+    const parsed = JSON.parse(raw) as RemoteExecutionArtifact;
+    this.artifacts.set(parsed.id, parsed);
+    this.contracts.set(parsed.runnerId, parsed.runnerContract);
+    return parsed;
+  }
+
+  buildSessionBundle(store?: RuntimeStore): RemoteSessionBundle {
+    this.ensureContractsFromStore(store);
+    const activeConnectionIds = store?.getState().acp.activeConnectionIds ?? [];
+    return Object.freeze({
+      version: 1,
+      exportedAt: Date.now(),
+      sessionId: store?.getState().session.id || 'unknown-session',
+      activeConnectionIds: Object.freeze([...activeConnectionIds]),
+      pools: Object.freeze(this.listPools()),
+      contracts: Object.freeze(this.listContracts()),
+      artifacts: Object.freeze(this.listArtifacts()),
+    });
+  }
+
+  async exportSessionBundle(
+    store?: RuntimeStore,
+    explicitPath?: string,
+  ): Promise<{ bundle: RemoteSessionBundle; path: string }> {
+    const bundle = this.buildSessionBundle(store);
+    const path = explicitPath
+      ? resolve(explicitPath)
+      : resolve(DEFAULT_SESSION_BUNDLE_DIR, `${bundle.sessionId}-${bundle.exportedAt}.json`);
+    mkdirSync(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(bundle, null, 2)}\n`, 'utf-8');
+    return { bundle, path };
+  }
+
+  async importSessionBundle(path: string): Promise<RemoteSessionBundle> {
+    const raw = await readFile(resolve(path), 'utf-8');
+    const parsed = JSON.parse(raw) as RemoteSessionBundle;
+    for (const pool of parsed.pools) {
+      this.pools.set(pool.id, pool);
+    }
+    for (const contract of parsed.contracts) {
+      this.contracts.set(contract.runnerId, contract);
+    }
+    for (const artifact of parsed.artifacts) {
+      this.artifacts.set(artifact.id, artifact);
+    }
+    return parsed;
+  }
+
+  buildReviewSummary(artifactId: string): string | null {
+    const artifact = this.getArtifact(artifactId);
+    if (!artifact) return null;
+    const lines = [
+      `Remote Artifact ${artifact.id}`,
+      `  runner: ${artifact.runnerId}`,
+      `  template: ${artifact.runnerContract.template}`,
+      `  status: ${artifact.task.status}`,
+      `  summary: ${artifact.task.summary}`,
+      `  tools: ${artifact.runnerContract.capabilityCeiling.allowedTools.join(', ') || '(none)'}`,
+      `  evidence: toolCalls=${artifact.evidence.toolCallCount} messages=${artifact.evidence.messageCount} errors=${artifact.evidence.errorCount}`,
+    ];
+    if (artifact.task.error) lines.push(`  error: ${artifact.task.error}`);
+    if (artifact.knowledgeInjections.length > 0) {
+      lines.push(`  knowledge: ${artifact.knowledgeInjections.map((entry) => entry.id).join(', ')}`);
+    }
+    return lines.join('\n');
+  }
+
+  ensureContractsFromStore(store?: RuntimeStore): void {
+    for (const agent of this.agentManager.list()) {
+      if (agent.orchestrationGraphId || agent.parentAgentId || store?.getState().acp.connections.has(agent.id)) {
+        this.upsertContractForAgent(agent.id, store);
+      }
+    }
+  }
+
+  clear(): void {
+    this.contracts.clear();
+    this.artifacts.clear();
+    this.pools.clear();
+  }
+}
+
+export async function exportRemoteArtifactForAgent(
+  registry: RemoteRunnerRegistry,
+  agentId: string,
+  store?: RuntimeStore,
+  path?: string,
+): Promise<{ artifact: RemoteExecutionArtifact; path: string } | null> {
+  const artifact = registry.captureArtifactForAgent(agentId, store);
+  if (!artifact) return null;
+  return registry.exportArtifact(artifact.id, path);
+}
+
+export async function importRemoteArtifact(
+  registry: RemoteRunnerRegistry,
+  path: string,
+): Promise<RemoteExecutionArtifact> {
+  try {
+    return await registry.importArtifact(path);
+  } catch (error) {
+    logger.debug('RemoteRunnerRegistry.importArtifact failed', { path, error: summarizeError(error) });
+    throw error;
+  }
+}

package/src/runtime/remote/supervisor.ts

@@ -0,0 +1,70 @@
+import type { RuntimeStore } from '../store/index.ts';
+import type { AcpConnection } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/acp';
+import { RemoteRunnerRegistry } from './runner-registry.ts';
+import type { RemoteRunnerContract, RemoteRunnerPool } from '@pellux/goodvibes-sdk/platform/runtime/remote/types';
+import { deriveRemoteCapabilities, type RemoteCapabilitySnapshot } from '@pellux/goodvibes-sdk/platform/runtime/remote/capabilities';
+import { deriveRemoteHeartbeat, type RemoteHeartbeatSnapshot } from '@pellux/goodvibes-sdk/platform/runtime/remote/heartbeat';
+import { deriveRemoteNegotiation, type RemoteNegotiationSnapshot } from '@pellux/goodvibes-sdk/platform/runtime/remote/negotiation';
+import { deriveRemoteRecoveryActions, type RemoteRecoveryAction } from '@pellux/goodvibes-sdk/platform/runtime/remote/recovery';
+import { buildRemoteSessionStateSnapshot, type RemoteSessionStateSnapshot } from '@pellux/goodvibes-sdk/platform/runtime/remote/session-state';
+
+export interface RemoteSupervisorSnapshot {
+  readonly capturedAt: number;
+  readonly totalConnections: number;
+  readonly activeConnections: number;
+  readonly degradedConnections: number;
+  readonly pools: readonly RemoteRunnerPool[];
+  readonly sessions: readonly RemoteSessionStateSnapshot[];
+}
+
+function stateIsDegraded(state: string): boolean {
+  return state === 'degraded' || state === 'reconnecting' || state === 'terminal_failure';
+}
+
+export class RemoteSupervisor {
+  constructor(private readonly remoteRegistry: RemoteRunnerRegistry) {}
+
+  public getSnapshot(store: RuntimeStore): RemoteSupervisorSnapshot {
+    this.remoteRegistry.ensureContractsFromStore(store);
+    const state = store.getState();
+    const pools = this.remoteRegistry.listPools();
+    const contracts = this.remoteRegistry.listContracts();
+    const connections = [...state.acp.connections.values()];
+    const runnerIds = new Set<string>([
+      ...connections.map((connection) => connection.agentId),
+      ...contracts.map((contract) => contract.runnerId),
+    ]);
+    const sessions = [...runnerIds].map((runnerId) => this.describeRunner(runnerId, connections, contracts));
+    return Object.freeze({
+      capturedAt: Date.now(),
+      totalConnections: connections.length,
+      activeConnections: state.acp.activeConnectionIds.length,
+      degradedConnections: sessions.filter((session) => stateIsDegraded(session.transportState) || session.heartbeat.status !== 'fresh').length,
+      pools,
+      sessions,
+    });
+  }
+
+  private describeRunner(
+    runnerId: string,
+    connections: readonly AcpConnection[],
+    contracts: readonly RemoteRunnerContract[],
+  ): RemoteSessionStateSnapshot {
+    const connection = connections.find((entry) => entry.agentId === runnerId) ?? null;
+    const contract = contracts.find((entry) => entry.runnerId === runnerId) ?? null;
+    const capabilities: readonly RemoteCapabilitySnapshot[] = deriveRemoteCapabilities(contract, connection);
+    const heartbeat: RemoteHeartbeatSnapshot = deriveRemoteHeartbeat(connection, contract);
+    const negotiation: RemoteNegotiationSnapshot = deriveRemoteNegotiation(contract, connection);
+    const recovery: readonly RemoteRecoveryAction[] = deriveRemoteRecoveryActions(connection, contract, heartbeat);
+    return buildRemoteSessionStateSnapshot({
+      runnerId,
+      label: connection?.label ?? contract?.label ?? runnerId,
+      connection,
+      contract,
+      heartbeat,
+      negotiation,
+      capabilities,
+      recovery,
+    });
+  }
+}

package/src/runtime/runtime-hook-api.ts

@@ -0,0 +1,5 @@
+import { createHookApi, type HookApi } from '../hooks/hook-api.ts';
+
+export function createRuntimeHookApi(options: Parameters<typeof createHookApi>[0]): HookApi {
+  return createHookApi(options);
+}

package/src/runtime/runtime-knowledge-api.ts

@@ -0,0 +1,14 @@
+import { createKnowledgeApi, type CreateKnowledgeApiOptions, type KnowledgeApi } from '../knowledge/knowledge-api.ts';
+import type { RuntimeServices } from './services.ts';
+
+export interface RuntimeKnowledgeApiServices
+  extends Pick<RuntimeServices, 'knowledgeService' | 'memoryRegistry'> {}
+
+export function createRuntimeKnowledgeApi(
+  runtimeServices: RuntimeKnowledgeApiServices,
+): KnowledgeApi {
+  const options: CreateKnowledgeApiOptions = {
+    memoryRegistry: runtimeServices.memoryRegistry,
+  };
+  return createKnowledgeApi(runtimeServices.knowledgeService, options);
+}

package/src/runtime/runtime-mcp-api.ts

@@ -0,0 +1,5 @@
+import { createMcpApi, type McpApi, type McpApiRegistry } from '../mcp/mcp-api.ts';
+
+export function createRuntimeMcpApi(registry: McpApiRegistry): McpApi {
+  return createMcpApi(registry);
+}

package/src/runtime/runtime-ops-api.ts

@@ -0,0 +1,86 @@
+import type { OpsApi } from './ops-api.ts';
+import type { OpsControlPlane } from './ops/control-plane.ts';
+import type { RuntimeTask } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/tasks';
+import type { UiTasksSnapshot } from './ui-read-models.ts';
+import type { TaskManager } from '@pellux/goodvibes-sdk/platform/runtime/tasks/types';
+
+export interface RuntimeOpsApiOptions {
+  readonly tasksReadModel: {
+    getSnapshot(): UiTasksSnapshot;
+  };
+  readonly taskManager: TaskManager;
+  readonly opsControlPlane?: Pick<
+    OpsControlPlane,
+    'cancelTask' | 'pauseTask' | 'resumeTask' | 'retryTask' | 'cancelAgent'
+  >;
+}
+
+function normalizeLimit(limit: number): number {
+  if (!Number.isFinite(limit)) return 1;
+  return Math.max(1, Math.floor(limit));
+}
+
+function listTasksSnapshot(snapshot: UiTasksSnapshot, limit = 100): readonly RuntimeTask[] {
+  return snapshot.tasks.slice(0, normalizeLimit(limit));
+}
+
+function getTaskSnapshot(snapshot: UiTasksSnapshot, taskId: string): RuntimeTask | null {
+  return snapshot.tasks.find((task) => task.id === taskId) ?? null;
+}
+
+function requireControlPlane(
+  controlPlane: RuntimeOpsApiOptions['opsControlPlane'],
+): NonNullable<RuntimeOpsApiOptions['opsControlPlane']> {
+  if (!controlPlane) {
+    throw new Error('Ops control plane is not available in this runtime.');
+  }
+  return controlPlane;
+}
+
+export function createRuntimeOpsApi(options: RuntimeOpsApiOptions): OpsApi {
+  return {
+    tasks: {
+      snapshot(): UiTasksSnapshot {
+        return options.tasksReadModel.getSnapshot();
+      },
+      list(limit = 100): readonly RuntimeTask[] {
+        return listTasksSnapshot(options.tasksReadModel.getSnapshot(), limit);
+      },
+      get(taskId: string): RuntimeTask | null {
+        return getTaskSnapshot(options.tasksReadModel.getSnapshot(), taskId);
+      },
+      running(): readonly RuntimeTask[] {
+        return options.tasksReadModel.getSnapshot().tasks.filter((task) => task.status === 'running');
+      },
+      create(input) {
+        return options.taskManager.createTask(input);
+      },
+      update(taskId, input) {
+        return options.taskManager.updateTask(taskId, input);
+      },
+      complete(taskId, result) {
+        return options.taskManager.completeTask(taskId, result);
+      },
+      fail(taskId, input) {
+        return options.taskManager.failTask(taskId, input);
+      },
+      cancel(taskId, note) {
+        requireControlPlane(options.opsControlPlane).cancelTask(taskId, note);
+      },
+      pause(taskId, note) {
+        requireControlPlane(options.opsControlPlane).pauseTask(taskId, note);
+      },
+      resume(taskId, note) {
+        requireControlPlane(options.opsControlPlane).resumeTask(taskId, note);
+      },
+      retry(taskId, note) {
+        requireControlPlane(options.opsControlPlane).retryTask(taskId, note);
+      },
+    },
+    agents: {
+      cancel(agentId, note) {
+        requireControlPlane(options.opsControlPlane).cancelAgent(agentId, note);
+      },
+    },
+  };
+}

package/src/runtime/runtime-provider-api.ts

@@ -0,0 +1,18 @@
+import { createProviderApi, type ProviderApi } from '../providers/provider-api.ts';
+import type { RuntimeServices } from './services.ts';
+
+export interface RuntimeProviderApiServices extends Pick<
+  RuntimeServices,
+  'benchmarkStore' | 'favoritesStore' | 'providerRegistry'
+> {}
+
+export function createRuntimeProviderApi(
+  runtimeServices: RuntimeProviderApiServices,
+): ProviderApi {
+  return createProviderApi({
+    providerRegistry: runtimeServices.providerRegistry,
+    favoritesStore: runtimeServices.favoritesStore,
+    benchmarkStore: runtimeServices.benchmarkStore,
+  });
+}
+