@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -0,0 +1,18 @@
+import type { WorkContract, WorkContractStore, WorkContractStatus } from '../domain/types';
+
+export interface WorkContractStoreLocation {
+  controllerHome?: string;
+  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 & { status?: WorkContractStatus | '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,61 @@
+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;
+  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/index.ts

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

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));
+  }
+}

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

@@ -0,0 +1,19 @@
+import type {
+  ComputerRuntimeProviderExecutionRequest,
+  ComputerRuntimeProviderCapabilityId,
+} from '../../protocols/computer/index';
+
+/** Concrete OS/browser implementations live in adapters. Plugin Runtime owns typed dispatch only. */
+export interface ComputerProvider {
+  providerId: string;
+  capabilities: readonly ComputerRuntimeProviderCapabilityId[];
+  execute(
+    request: ComputerRuntimeProviderExecutionRequest,
+    timeoutMs: number,
+  ): Promise<Record<string, unknown>>;
+  dispose?(): void;
+}
+
+export function computerProviderSupports(provider: ComputerProvider, capability: ComputerRuntimeProviderCapabilityId): boolean {
+  return provider.capabilities.includes(capability);
+}