@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/work/ports/work-contract-store.ts

@@ -0,0 +1,21 @@
+import type { SemanticWorkState, WorkContract, WorkContractStore } from '../domain/types';
+
+export interface WorkContractStoreLocation {
+  controllerHome?: string;
+  /** Canonical storage scope. Semantic Work uses the portable semantic scope; repository Work may omit this and use repoId. */
+  scopeKey?: string;
+  /** Legacy/repository execution storage scope and optional placement context. */
+  repoId?: string;
+  root?: string;
+}
+
+export interface WorkContractStoreOptions extends WorkContractStoreLocation {
+  now?: () => string;
+}
+
+/** Infrastructure contract only. Lifecycle mutation policy belongs to application/domain. */
+export interface WorkContractPersistencePort {
+  read(options: WorkContractStoreOptions): WorkContractStore;
+  get(options: WorkContractStoreOptions, workId: string): WorkContract | undefined;
+  list(options: WorkContractStoreOptions & { state?: SemanticWorkState | 'active' | 'all'; limit?: number }): WorkContract[];
+}

package/packages/plugin-runtime/browser/index.ts

@@ -0,0 +1,3 @@
+export * from './runtime-contract';
+export * from './provider-registry';
+export * from './session-authority';

package/packages/plugin-runtime/browser/provider-registry.ts

@@ -0,0 +1,110 @@
+import {
+  providerSupports,
+  type BrowserForegroundRequirement,
+  type BrowserProviderCapabilities,
+  type BrowserProviderCapability,
+} from './runtime-contract';
+
+export interface BrowserRuntimeProvider<TInput, TResult> extends BrowserProviderCapabilities {
+  /** Lower values are preferred when multiple providers satisfy the same capability contract. */
+  priority: number;
+  /** Availability is decided before execution; ordinary provider failures are never fallback signals. */
+  supportsInput(input: TInput): boolean;
+  execute(input: TInput): Promise<TResult>;
+  /** Runs only after an explicit stale/restart/configuration boundary. */
+  revalidate?: () => Promise<void> | void;
+}
+
+interface BrowserProviderState<TInput, TResult> {
+  provider: BrowserRuntimeProvider<TInput, TResult>;
+  generation: number;
+  invalidatedReason?: string;
+}
+
+export interface BrowserProviderSelection<TInput, TResult> {
+  provider: BrowserRuntimeProvider<TInput, TResult>;
+  generation: number;
+}
+
+/** Provider-neutral selection failure. Adapter surfaces map this to their public error contract. */
+export class BrowserProviderSelectionError extends Error {
+  readonly code = 'PLUGIN_BROWSER_PROVIDER_UNAVAILABLE';
+  readonly retryable = true;
+
+  constructor(readonly requiredCapabilities: readonly BrowserProviderCapability[]) {
+    super(`No Browser provider satisfies required capabilities: ${requiredCapabilities.join(', ') || 'browser.transaction'}.`);
+    this.name = 'BrowserProviderSelectionError';
+  }
+}
+
+/**
+ * A typed pre-action rejection. Runtime may select another provider because this proves the action
+ * was not attempted. Arbitrary provider errors are intentionally not mapped to this signal.
+ */
+export class BrowserProviderUnavailableBeforeActionError extends Error {
+  readonly providerId: string;
+  readonly reason: string;
+
+  constructor(providerId: string, reason: string) {
+    super(`${providerId} unavailable before action: ${reason}`);
+    this.name = 'BrowserProviderUnavailableBeforeActionError';
+    this.providerId = providerId;
+    this.reason = reason;
+  }
+}
+
+function foregroundCompatible(
+  provider: BrowserProviderCapabilities,
+  requested: BrowserForegroundRequirement,
+): boolean {
+  return requested === 'explicit_required' || provider.foreground === 'none';
+}
+
+export class BrowserProviderRegistry<TInput, TResult> {
+  private readonly providers = new Map<string, BrowserProviderState<TInput, TResult>>();
+
+  register(provider: BrowserRuntimeProvider<TInput, TResult>): void {
+    const current = this.providers.get(provider.providerId);
+    if (current) {
+      current.provider = provider;
+      return;
+    }
+    this.providers.set(provider.providerId, { provider, generation: 1 });
+  }
+
+  invalidate(providerId: string, reason: string): void {
+    const state = this.providers.get(providerId);
+    if (state) state.invalidatedReason = reason;
+  }
+
+  invalidateAll(reason: string): void {
+    for (const state of this.providers.values()) state.invalidatedReason = reason;
+  }
+
+  private async prepare(state: BrowserProviderState<TInput, TResult>): Promise<void> {
+    if (!state.invalidatedReason) return;
+    await state.provider.revalidate?.();
+    state.invalidatedReason = undefined;
+    state.generation += 1;
+  }
+
+  async select(options: {
+    input: TInput;
+    requiredCapabilities: readonly BrowserProviderCapability[];
+    foreground: BrowserForegroundRequirement;
+    excludedProviderIds?: ReadonlySet<string>;
+  }): Promise<BrowserProviderSelection<TInput, TResult>> {
+    const candidates = [...this.providers.values()]
+      .filter(({ provider }) => !options.excludedProviderIds?.has(provider.providerId))
+      .filter(({ provider }) => provider.supportsInput(options.input))
+      .filter(({ provider }) => providerSupports(provider, options.requiredCapabilities))
+      .filter(({ provider }) => foregroundCompatible(provider, options.foreground))
+      .sort((left, right) => left.provider.priority - right.provider.priority
+        || left.provider.providerId.localeCompare(right.provider.providerId));
+
+    const selected = candidates[0];
+    if (!selected) throw new BrowserProviderSelectionError(options.requiredCapabilities);
+    await this.prepare(selected);
+    return { provider: selected.provider, generation: selected.generation };
+  }
+}

package/packages/plugin-runtime/browser/runtime-contract.ts

@@ -0,0 +1,150 @@
+export const MAX_BROWSER_CDP_ENDPOINT_CANDIDATES = 5;
+
+export type BrowserProviderCapability =
+  | 'dom.read'
+  | 'dom.interact'
+  | 'browser.internal_resources'
+  | 'browser.screenshot'
+  | 'browser.trusted_input'
+  | 'browser.foreground'
+  | 'browser.transaction'
+  | 'browser.persistent_handle';
+
+export type BrowserTargetOwnership = 'plugin_owned' | 'user_owned' | 'provider_owned';
+export type BrowserTargetKind = 'page' | 'tab' | 'browser_internal_resource';
+export type BrowserForegroundRequirement = 'none' | 'explicit_required';
+export type BrowserActionReplaySafety = 'read_only' | 'idempotent' | 'non_idempotent';
+
+/** Stable resource identity. URL/title are deliberately excluded because they are mutable observations. */
+export interface BrowserTargetIdentity {
+  providerId: string;
+  resourceKind: BrowserTargetKind;
+  resourceId: string;
+  browserProduct?: string;
+  ownership: BrowserTargetOwnership;
+}
+
+export interface BrowserObservedState {
+  url: string;
+  title?: string;
+  observedAt: string;
+  providerRevision?: string;
+}
+
+export interface BrowserProviderCapabilities {
+  providerId: string;
+  capabilities: readonly BrowserProviderCapability[];
+  foreground: BrowserForegroundRequirement;
+  /** True only when the provider can verify postconditions in the same provider call that performs the action. */
+  verifiesPostconditions: boolean;
+  /** True only when an already-bound provider handle can be reused across bounded consecutive actions. */
+  persistentHandle: boolean;
+}
+
+export type BrowserCondition =
+  | { kind: 'target_identity'; target: BrowserTargetIdentity }
+  | { kind: 'url_equals'; url: string }
+  | { kind: 'url_matches'; pattern: string }
+  | { kind: 'selector_exists'; selector: string }
+  | { kind: 'selector_visible'; selector: string }
+  | { kind: 'text_contains'; text: string; selector?: string }
+  | { kind: 'attribute_equals'; selector: string; attribute: string; value: string }
+  | { kind: 'provider_assertion'; assertion: string; expected: string | number | boolean };
+
+export type BrowserTransactionAction =
+  | { kind: 'read'; operation: string; arguments?: Record<string, unknown> }
+  | { kind: 'dom'; operation: string; arguments?: Record<string, unknown> }
+  | { kind: 'internal_resource'; operation: string; arguments?: Record<string, unknown> }
+  | { kind: 'trusted_input'; operation: string; arguments?: Record<string, unknown> };
+
+export interface BrowserTransaction {
+  transactionId: string;
+  target: BrowserTargetIdentity;
+  requiredCapabilities: readonly BrowserProviderCapability[];
+  foreground: BrowserForegroundRequirement;
+  replaySafety: BrowserActionReplaySafety;
+  preconditions?: readonly BrowserCondition[];
+  action: BrowserTransactionAction;
+  /** Writes/interactions require at least one postcondition unless the action itself returns a typed read result. */
+  postconditions?: readonly BrowserCondition[];
+  timeoutMs: number;
+}
+
+export interface BrowserConditionEvidence {
+  condition: BrowserCondition;
+  satisfied: boolean;
+  observed?: unknown;
+  reason?: string;
+}
+
+export interface BrowserTransactionTiming {
+  providerCalls: number;
+  providerDurationMs: number;
+  totalDurationMs: number;
+}
+
+export interface BrowserTransactionResult<T = unknown> {
+  transactionId: string;
+  target: BrowserTargetIdentity;
+  transportSucceeded: boolean;
+  actionPerformed: boolean;
+  /** Authoritative success bit. Provider/transport success alone must never set this true. */
+  verified: boolean;
+  result?: T;
+  observedState?: BrowserObservedState;
+  preconditionEvidence: readonly BrowserConditionEvidence[];
+  postconditionEvidence: readonly BrowserConditionEvidence[];
+  timing: BrowserTransactionTiming;
+}
+
+export interface BrowserRuntimeBudget {
+  p95Ms: number;
+  maxProviderCallsWarm: number;
+  maxProviderCallsCold: number;
+  foregroundAllowed: boolean;
+}
+
+export const BROWSER_RUNTIME_V2_BUDGETS = {
+  read: { p95Ms: 350, maxProviderCallsWarm: 1, maxProviderCallsCold: 2, foregroundAllowed: false },
+  domInteraction: { p95Ms: 600, maxProviderCallsWarm: 1, maxProviderCallsCold: 2, foregroundAllowed: false },
+  internalResource: { p95Ms: 700, maxProviderCallsWarm: 1, maxProviderCallsCold: 2, foregroundAllowed: false },
+  physicalInput: { p95Ms: 1_500, maxProviderCallsWarm: 1, maxProviderCallsCold: 2, foregroundAllowed: true },
+} as const satisfies Record<string, BrowserRuntimeBudget>;
+
+export function browserTargetKey(target: BrowserTargetIdentity): string {
+  return [target.providerId, target.browserProduct ?? '', target.resourceKind, target.resourceId, target.ownership].join(':');
+}
+
+export function providerSupports(
+  provider: BrowserProviderCapabilities,
+  required: readonly BrowserProviderCapability[],
+): boolean {
+  const available = new Set(provider.capabilities);
+  return required.every((capability) => available.has(capability));
+}
+
+export function browserTransactionVerified(result: BrowserTransactionResult): boolean {
+  return result.transportSucceeded
+    && result.actionPerformed
+    && result.verified
+    && result.preconditionEvidence.every((entry) => entry.satisfied)
+    && result.postconditionEvidence.every((entry) => entry.satisfied);
+}
+
+export function browserTransactionRequiresPostcondition(transaction: BrowserTransaction): boolean {
+  return transaction.replaySafety !== 'read_only';
+}
+
+export function validateBrowserTransaction(transaction: BrowserTransaction): string[] {
+  const errors: string[] = [];
+  if (!transaction.transactionId.trim()) errors.push('transactionId is required');
+  if (!transaction.target.providerId.trim() || !transaction.target.resourceId.trim()) errors.push('stable target identity is incomplete');
+  if (!Number.isFinite(transaction.timeoutMs) || transaction.timeoutMs <= 0) errors.push('timeoutMs must be positive');
+  if (transaction.foreground === 'none' && transaction.requiredCapabilities.includes('browser.foreground')) {
+    errors.push('foreground capability cannot be required by a foreground-free transaction');
+  }
+  if (browserTransactionRequiresPostcondition(transaction) && (transaction.postconditions?.length ?? 0) === 0) {
+    errors.push('interactive transactions require at least one postcondition');
+  }
+  return errors;
+}

package/packages/plugin-runtime/browser/session-authority.ts

@@ -0,0 +1,62 @@
+export const DEFAULT_BROWSER_SESSION_LIST_LIMIT = 50;
+export const MAX_BROWSER_SESSION_LIST_LIMIT = 200;
+
+/** State-free Browser execution scope. Durable interaction identity belongs to Computer SurfaceTarget authority. */
+export interface BrowserSessionExecutionContext {
+  controllerHome: string;
+  /** Optional repository visibility/migration context; never Browser session authority. */
+  repoId?: string;
+}
+
+/** @deprecated Compatibility alias for frozen callers; this is context, not an authority capability. */
+export type BrowserSessionAuthorityContext = BrowserSessionExecutionContext;
+
+/** Compatibility shape for Browser-facing session metadata. It is persisted only inside a Computer SurfaceTarget record. */
+export interface BrowserSessionAuthoritySession {
+  schemaVersion: 1;
+  sessionId: string;
+  url: string;
+  title?: string;
+  createdAt: string;
+  updatedAt: string;
+  browser?: {
+    provider?: string;
+    browserProduct?: string;
+    tab?: {
+      windowId?: string;
+      tabId?: string;
+      ownership?: string;
+    };
+  };
+}
+
+export interface BrowserSessionAuthorityPage<T extends BrowserSessionAuthoritySession = BrowserSessionAuthoritySession> {
+  sessions: T[];
+  limit: number;
+  totalCount: number;
+  nextCursor?: string;
+}
+
+export interface BrowserSessionLegacyCutoverRepository {
+  repoId: string;
+  repoRoot: string;
+}
+
+export interface BrowserSessionLegacyCutoverReport {
+  closed: boolean;
+  alreadyClosed: boolean;
+  repositoryCount: number;
+  migratedRecordCount: number;
+}
+
+/** Compatibility-only report shape; Browser no longer owns tombstone retention. */
+export interface BrowserSessionTombstoneCleanupReport {
+  policyVersion: 'browser-session-tombstone-retention-v1';
+  cutoverClosed: boolean;
+  inspected: number;
+  eligible: number;
+  removed: number;
+  retained: number;
+  blockers: string[];
+  budgetExhausted: boolean;
+}

package/packages/plugin-runtime/computer/chatgpt-identity.ts

@@ -0,0 +1,24 @@
+const CHATGPT_HOSTS = new Set(['chatgpt.com', 'www.chatgpt.com', 'chat.openai.com']);
+const MAX_CONVERSATION_ID_CHARS = 256;
+
+export interface CanonicalChatgptConversationIdentity {
+  conversationUrl: string;
+  conversationId: string;
+}
+
+export function parseCanonicalChatgptConversationIdentity(value: string): CanonicalChatgptConversationIdentity {
+  let url: URL;
+  try { url = new URL(value); } catch { throw new Error('CHATGPT_CONVERSATION_URL_INVALID'); }
+  if (url.protocol !== 'https:' || !CHATGPT_HOSTS.has(url.hostname)) throw new Error('CHATGPT_CONVERSATION_URL_INVALID');
+  const parts = url.pathname.split('/').filter(Boolean);
+  const marker = parts.lastIndexOf('c');
+  if (marker < 0 || marker + 2 !== parts.length) throw new Error('CHATGPT_CONVERSATION_ID_MISSING');
+  const conversationId = parts[marker + 1]?.trim() ?? '';
+  if (!conversationId) throw new Error('CHATGPT_CONVERSATION_ID_MISSING');
+  if (conversationId.length > MAX_CONVERSATION_ID_CHARS) throw new Error('CHATGPT_CONVERSATION_ID_INVALID');
+  url.protocol = 'https:';
+  url.hostname = 'chatgpt.com';
+  url.search = '';
+  url.hash = '';
+  return { conversationUrl: url.toString(), conversationId };
+}

package/packages/plugin-runtime/computer/conversation-target.ts

@@ -0,0 +1,143 @@
+import type { ComputerSurfaceProviderBinding } from './target-authority';
+
+export interface ComputerChatgptConversationIdentity {
+  namespace: 'chatgpt.conversation';
+  conversationId: string;
+  canonicalUrl: string;
+}
+
+export interface ComputerChatgptBootstrapIdentity {
+  namespace: 'chatgpt.bootstrap';
+  bootstrapKey: string;
+  projectUrl: string;
+}
+
+export type ComputerChatgptTargetIdentity = ComputerChatgptConversationIdentity | ComputerChatgptBootstrapIdentity;
+
+export interface ComputerChatgptConversationObservation {
+  url: string;
+  title: string;
+  latestUserText: string;
+  latestAssistantResponse: string;
+  userMessages?: string[];
+  assistantMessages?: string[];
+  composerText?: string;
+  providerActivityText: string;
+  providerFailureText: string;
+  pageText?: string;
+  latestTurnRole?: 'user' | 'assistant';
+  isGenerating: boolean;
+}
+
+export interface ComputerChatgptConversationObservationOptions {
+  includeUserHistory?: boolean;
+  includePageText?: boolean;
+}
+
+/**
+ * Opaque exact-conversation attachment. The targetId is durable Computer
+ * identity; provider ids and tab/window handles remain inside the Computer
+ * implementation and can be replaced without changing Supervisor authority.
+ */
+export interface ComputerChatgptConversationTarget {
+  targetId: string;
+  identity: ComputerChatgptTargetIdentity;
+  observe(options?: ComputerChatgptConversationObservationOptions): Promise<ComputerChatgptConversationObservation>;
+  /** UI-only preparation. Must never click Send or create a provider turn. */
+  prepare(prompt: string, options?: { mode?: 'send' | 'resume' | 'recover'; reasoning?: 'medium' | 'high' | 'xhigh' }): Promise<{ ready: true } | { ready: false; reasonCode: string }>;
+  dispatch(
+    prompt: string,
+    options?: { mode?: 'send' | 'resume' | 'recover'; reasoning?: 'medium' | 'high' | 'xhigh' },
+  ): Promise<
+    | { mutation: 'not_attempted'; reasonCode: string }
+    | { mutation: 'attempted'; confirmed?: boolean; reasoningVerified?: 'medium' | 'high' | 'xhigh' }
+  >;
+}
+
+export type ComputerChatgptTargetFailure = {
+  code: string;
+  retryable: boolean;
+  /** Failover is legal only while provider mutation is mechanically impossible. */
+  phase: 'pre_mutation';
+  /** False when provider resource recovery is itself outcome-unknown. */
+  failoverSafe?: boolean;
+  humanAction?: 'login' | 'grant_permission';
+};
+
+export type ComputerChatgptTargetResult =
+  | { state: 'ready'; target: ComputerChatgptConversationTarget; observation?: ComputerChatgptConversationObservation }
+  | { state: 'unavailable'; failure: ComputerChatgptTargetFailure };
+
+export interface ComputerObservedChatgptConversation {
+  conversationId: string;
+  canonicalUrl: string;
+  title?: string;
+  projectTitle?: string;
+  projectUrl?: string;
+  isCurrent?: boolean;
+}
+
+export interface ComputerChatgptConversationInventory {
+  conversations: ComputerObservedChatgptConversation[];
+  complete: boolean;
+  unavailableProviders: string[];
+}
+
+/**
+ * Browser/Computer-owned target boundary consumed by Workflow Supervisor.
+ * Implementations own discovery, exact target recovery, provider binding and
+ * transport replacement. They never decide effect admission or effect outcome.
+ */
+export type ComputerChatgptExtensionCommand =
+  | { commandId: string; kind: 'ensure'; identity: ComputerChatgptTargetIdentity; providerBinding?: ComputerSurfaceProviderBinding }
+  | { commandId: string; kind: 'observe'; identity: ComputerChatgptTargetIdentity; providerBinding?: ComputerSurfaceProviderBinding; options?: ComputerChatgptConversationObservationOptions }
+  | { commandId: string; kind: 'dispatch' | 'prepare'; identity: ComputerChatgptTargetIdentity; providerBinding?: ComputerSurfaceProviderBinding; prompt: string; mode?: 'send' | 'resume' | 'recover'; reasoning?: 'medium' | 'high' | 'xhigh' }
+  | { commandId: string; kind: 'find_marker'; marker: string; bootstrapKey?: string }
+  | { commandId: string; kind: 'close'; identity: ComputerChatgptTargetIdentity; providerBinding?: ComputerSurfaceProviderBinding };
+export type ComputerChatgptExtensionCommandInput = ComputerChatgptExtensionCommand extends infer Command
+  ? Command extends { commandId: string }
+    ? Omit<Command, 'commandId'>
+    : never
+  : never;
+
+
+export type ComputerChatgptExtensionCommandResult =
+  | { kind: 'ensured'; providerBinding?: ComputerSurfaceProviderBinding; observation?: ComputerChatgptConversationObservation }
+  | { kind: 'observation'; providerBinding?: ComputerSurfaceProviderBinding; observation: ComputerChatgptConversationObservation }
+  | { kind: 'prepared'; ready: true }
+  | { kind: 'prepared'; ready: false; reasonCode: string }
+  | { kind: 'dispatch'; mutation: 'not_attempted'; reasonCode: string }
+  | { kind: 'dispatch'; mutation: 'attempted'; confirmed?: boolean; reasoningVerified?: 'medium' | 'high' | 'xhigh'; observation?: ComputerChatgptConversationObservation }
+  | { kind: 'marker_matches'; matches: Array<{ identity: ComputerChatgptConversationIdentity; providerBinding?: ComputerSurfaceProviderBinding; observation: ComputerChatgptConversationObservation }> }
+  | { kind: 'closed' }
+  | { kind: 'failed'; code: string; retryable?: boolean; failoverSafe?: boolean; humanAction?: 'login' | 'grant_permission' };
+
+export interface ComputerChatgptExtensionHeartbeat {
+  providerId: string;
+  /** Ephemeral browser/profile provider runtime identity; mechanical binding only. */
+  providerInstanceId: string;
+  observedAt: string;
+  conversations: Array<ComputerObservedChatgptConversation & { providerBinding?: ComputerSurfaceProviderBinding }>;
+}
+
+export interface ComputerChatgptExtensionBrokerRpc {
+  heartbeat(input: ComputerChatgptExtensionHeartbeat): void;
+  claim(providerInstanceId: string): ComputerChatgptExtensionCommand | undefined;
+  complete(providerInstanceId: string, commandId: string, result: ComputerChatgptExtensionCommandResult): boolean;
+}
+
+export interface ComputerChatgptConversationTargetPort {
+  inventory(): Promise<ComputerChatgptConversationInventory>;
+  ensureExact(identity: ComputerChatgptConversationIdentity): Promise<ComputerChatgptTargetResult>;
+  openBootstrap(projectUrl: string, bootstrapKey: string): Promise<ComputerChatgptTargetResult>;
+  findBySubmittedMarker(
+    marker: string,
+    bootstrapKey?: string,
+    betweenObservations?: () => Promise<void>,
+  ): Promise<ComputerChatgptTargetResult[]>;
+  promoteBootstrap(targetId: string, identity: ComputerChatgptConversationIdentity): Promise<ComputerChatgptTargetResult>;
+  /** Mechanical cleanup of provider-owned attachments; semantic target identity remains durable. */
+  cleanup(activeResourceKeys: readonly string[]): Promise<void>;
+  release(targetId: string): Promise<void>;
+  close(): Promise<void>;
+}

package/packages/plugin-runtime/computer/index.ts

@@ -0,0 +1,8 @@
+export * from './provider';
+export * from './provider-registry';
+export * from './provider-error';
+export * from './provider-registration';
+export * from './target-authority';
+export * from './target-persistence';
+export * from './conversation-target';
+export * from './chatgpt-identity';

package/packages/plugin-runtime/computer/provider-error.ts

@@ -0,0 +1,26 @@
+export type ComputerProviderEffectOutcome = 'failed' | 'outcome_unknown';
+
+export interface ComputerProviderErrorOptions {
+  retryable?: boolean;
+  effectOutcome?: ComputerProviderEffectOutcome;
+  details?: Record<string, unknown>;
+}
+
+export class ComputerProviderError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+  readonly effectOutcome: ComputerProviderEffectOutcome;
+  readonly details?: Record<string, unknown>;
+  readonly detailMessage: string;
+
+  constructor(code: string, message: string, options: ComputerProviderErrorOptions = {}) {
+    const boundedMessage = message.slice(0, 1_000);
+    super(`${code}: ${boundedMessage}`);
+    this.name = 'ComputerProviderError';
+    this.code = code;
+    this.retryable = options.retryable === true;
+    this.effectOutcome = options.effectOutcome ?? 'failed';
+    this.details = options.details;
+    this.detailMessage = boundedMessage;
+  }
+}

package/packages/plugin-runtime/computer/provider-registration.ts

@@ -0,0 +1,52 @@
+export interface ComputerProviderRegistrationSource {
+  revision: number;
+  enabled: boolean;
+  providerPluginId: string;
+  protocolVersion: string;
+  capabilities: Array<{ capabilityId: string }>;
+  transport: {
+    kind: string;
+    socketPath?: string;
+    maxResponseBytes?: number;
+    healthTimeoutMs?: number;
+    actionTimeoutMs?: number;
+  };
+}
+
+export interface ComputerProviderRegistrationSnapshot {
+  revision: number;
+  enabled: boolean;
+  providerPluginId: string;
+  protocolVersion: string;
+  capabilityIds: string[];
+  transport: {
+    kind: string;
+    socketPath?: string;
+    maxResponseBytes?: number;
+    healthTimeoutMs?: number;
+    actionTimeoutMs?: number;
+  };
+}
+
+export type ComputerProviderRegistrationLookup = (
+  providerPluginId: string,
+) => ComputerProviderRegistrationSnapshot | undefined;
+
+export function computerProviderRegistrationSnapshot(
+  source: ComputerProviderRegistrationSource,
+): ComputerProviderRegistrationSnapshot {
+  return {
+    revision: source.revision,
+    enabled: source.enabled,
+    providerPluginId: source.providerPluginId,
+    protocolVersion: source.protocolVersion,
+    capabilityIds: source.capabilities.map((capability) => capability.capabilityId),
+    transport: {
+      kind: source.transport.kind,
+      ...(source.transport.socketPath ? { socketPath: source.transport.socketPath } : {}),
+      ...(source.transport.maxResponseBytes !== undefined ? { maxResponseBytes: source.transport.maxResponseBytes } : {}),
+      ...(source.transport.healthTimeoutMs !== undefined ? { healthTimeoutMs: source.transport.healthTimeoutMs } : {}),
+      ...(source.transport.actionTimeoutMs !== undefined ? { actionTimeoutMs: source.transport.actionTimeoutMs } : {}),
+    },
+  };
+}

package/packages/plugin-runtime/computer/provider-registry.ts

@@ -0,0 +1,63 @@
+import type {
+  ComputerRuntimeProviderExecutionRequest,
+  ComputerRuntimeProviderCapabilityId,
+} from '../../protocols/computer/index';
+import { ComputerProviderError } from './provider-error';
+import { computerProviderSupports, type ComputerProvider } from './provider';
+
+export class ComputerProviderRegistry {
+  private readonly providers = new Map<string, ComputerProvider>();
+
+  register(provider: ComputerProvider): void {
+    if (this.providers.has(provider.providerId)) {
+      throw new ComputerProviderError(
+        'COMPUTER_PROVIDER_DUPLICATE_ID',
+        `Computer provider ${provider.providerId} is already registered.`,
+        { retryable: false, details: { providerId: provider.providerId } },
+      );
+    }
+    this.providers.set(provider.providerId, provider);
+  }
+
+  resolve(capability: ComputerRuntimeProviderCapabilityId): ComputerProvider {
+    const matches = [...this.providers.values()]
+      .filter((candidate) => computerProviderSupports(candidate, capability));
+    if (matches.length === 0) {
+      throw new ComputerProviderError(
+        'COMPUTER_PROVIDER_UNAVAILABLE',
+        `No Computer provider is registered for ${capability}.`,
+        { retryable: true, details: { capability } },
+      );
+    }
+    if (matches.length > 1) {
+      throw new ComputerProviderError(
+        'COMPUTER_PROVIDER_AMBIGUOUS',
+        `Multiple Computer providers are registered for ${capability} without an explicit selection policy.`,
+        {
+          retryable: false,
+          details: { capability, providerIds: matches.map((provider) => provider.providerId).sort() },
+        },
+      );
+    }
+    return matches[0]!;
+  }
+
+  async execute(
+    request: ComputerRuntimeProviderExecutionRequest,
+    timeoutMs: number,
+  ): Promise<Record<string, unknown>> {
+    return await this.resolve(request.capability).execute(request, timeoutMs);
+  }
+
+
+  dispose(): void {
+    for (const provider of this.providers.values()) provider.dispose?.();
+    this.providers.clear();
+  }
+
+  snapshot(): Array<{ providerId: string; capabilities: ComputerRuntimeProviderCapabilityId[] }> {
+    return [...this.providers.values()]
+      .map((provider) => ({ providerId: provider.providerId, capabilities: [...provider.capabilities] }))
+      .sort((left, right) => left.providerId.localeCompare(right.providerId));
+  }
+}