@moretea-labs/forge 1.7.1 → 1.8.0

package/packages/protocols/computer/contract.ts

@@ -0,0 +1,199 @@
+export const COMPUTER_CAPABILITY_PROTOCOL_VERSION = 1 as const;
+export const COMPUTER_ELEMENT_PROTOCOL_VERSION = 2 as const;
+export const COMPUTER_CAPABILITY_EXECUTION_METHOD = 'computer_execute' as const;
+
+/** Compatibility-only Computer capability retained for providers that still expose Browser automation. */
+export const COMPUTER_BROWSER_AUTOMATION_CAPABILITY = 'computer.browser_automation.v1' as const;
+export const COMPUTER_OBSERVE_CAPABILITY = 'computer.observe.v1' as const;
+export const COMPUTER_INPUT_CAPABILITY = 'computer.input.v1' as const;
+export const COMPUTER_CONSOLE_UNLOCK_CAPABILITY = 'computer.console.unlock.v1' as const;
+export const COMPUTER_CAPTURE_CAPABILITY = 'computer.capture.v1' as const;
+export const COMPUTER_ELEMENT_OBSERVE_CAPABILITY = 'computer.element.observe.v2' as const;
+export const COMPUTER_ELEMENT_ACTION_CAPABILITY = 'computer.element.action.v2' as const;
+
+export type ComputerCapabilityId =
+  | typeof COMPUTER_BROWSER_AUTOMATION_CAPABILITY
+  | typeof COMPUTER_OBSERVE_CAPABILITY
+  | typeof COMPUTER_INPUT_CAPABILITY
+  | typeof COMPUTER_CONSOLE_UNLOCK_CAPABILITY
+  | typeof COMPUTER_CAPTURE_CAPABILITY
+  | typeof COMPUTER_ELEMENT_OBSERVE_CAPABILITY
+  | typeof COMPUTER_ELEMENT_ACTION_CAPABILITY;
+
+/** Unified Computer provider capabilities dispatched through the typed provider registry. Browser automation remains compatibility-only. */
+export type ComputerRuntimeProviderCapabilityId = Exclude<
+  ComputerCapabilityId,
+  typeof COMPUTER_BROWSER_AUTOMATION_CAPABILITY
+>;
+
+export function computerCapabilityProtocolVersion(capability: ComputerRuntimeProviderCapabilityId): 1 | 2 {
+  return capability === COMPUTER_ELEMENT_OBSERVE_CAPABILITY || capability === COMPUTER_ELEMENT_ACTION_CAPABILITY
+    ? COMPUTER_ELEMENT_PROTOCOL_VERSION
+    : COMPUTER_CAPABILITY_PROTOCOL_VERSION;
+}
+
+/** Runtime advertisement used to negotiate one provider-neutral Computer capability. */
+export interface ComputerCapabilityAdvertisement {
+  capabilityId: string;
+  protocolVersion: number;
+  method: string;
+  actions: string[];
+}
+
+export type ComputerBrowserProduct = 'chrome' | 'vivaldi';
+
+export interface ComputerBrowserTabRef {
+  windowId: string;
+  tabId: string;
+}
+
+export interface ComputerCaptureRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type ComputerTrustedInput =
+  | { kind: 'click'; x: number; y: number; button: 'left' | 'middle' | 'right'; clickCount: number }
+  | { kind: 'move'; x: number; y: number; steps: number }
+  | { kind: 'wheel'; deltaX: number; deltaY: number }
+  | { kind: 'drag'; fromX: number; fromY: number; toX: number; toY: number; button: 'left' | 'middle' | 'right'; steps: number }
+  | { kind: 'key'; key: string }
+  | { kind: 'text'; text: string };
+
+/** Provider-neutral browser automation request retained only for explicit compatibility providers. */
+export type ComputerBrowserAutomationRequest =
+  | { action: 'metadata'; product: ComputerBrowserProduct; ref?: ComputerBrowserTabRef }
+  | { action: 'list_tabs'; product: ComputerBrowserProduct }
+  | { action: 'create_tab'; product: ComputerBrowserProduct; url: string }
+  | { action: 'close_tab'; product: ComputerBrowserProduct; ref: ComputerBrowserTabRef }
+  | { action: 'navigate'; product: ComputerBrowserProduct; ref?: ComputerBrowserTabRef; url: string }
+  | { action: 'reload'; product: ComputerBrowserProduct; ref?: ComputerBrowserTabRef }
+  | { action: 'execute_javascript'; product: ComputerBrowserProduct; ref?: ComputerBrowserTabRef; source: string }
+  | { action: 'activate'; product: ComputerBrowserProduct; ref?: ComputerBrowserTabRef }
+  | { action: 'trusted_input'; product: ComputerBrowserProduct; ref: ComputerBrowserTabRef; input: ComputerTrustedInput }
+  | { action: 'capture_region'; region: ComputerCaptureRegion };
+
+export interface ComputerSemanticSelector {
+  ref?: string;
+  role?: string;
+  title?: string;
+  identifier?: string;
+}
+
+export interface ComputerObserveRequest {
+  capability: typeof COMPUTER_OBSERVE_CAPABILITY;
+  action: 'observe';
+  interactionId: string;
+  maxDepth?: number;
+  maxNodes?: number;
+  includeValues?: boolean;
+  includeActions?: boolean;
+  includeWindows?: boolean;
+  rootSelector?: ComputerSemanticSelector;
+}
+
+export type ComputerInputRequest =
+  | { capability: typeof COMPUTER_INPUT_CAPABILITY; action: 'press'; interactionId: string; selector: ComputerSemanticSelector; semanticAction?: 'press' | 'show_menu' | 'pick' | 'open' | 'confirm' | 'scroll_down_page' | 'scroll_up_page' }
+  | { capability: typeof COMPUTER_INPUT_CAPABILITY; action: 'select_rows'; interactionId: string; selector: ComputerSemanticSelector; startIndex: number; endIndex?: number }
+  | { capability: typeof COMPUTER_INPUT_CAPABILITY; action: 'type_text'; interactionId: string; selector: ComputerSemanticSelector; text: string; replace?: boolean }
+  | { capability: typeof COMPUTER_INPUT_CAPABILITY; action: 'key'; interactionId: string; keys: string[] }
+  | { capability: typeof COMPUTER_INPUT_CAPABILITY; action: 'open_url'; url: string };
+
+
+export interface ComputerConsoleUnlockPrepareRequest {
+  capability: typeof COMPUTER_CONSOLE_UNLOCK_CAPABILITY;
+  action: 'prepare_unlock_console';
+}
+
+export interface ComputerConsoleUnlockRequest {
+  capability: typeof COMPUTER_CONSOLE_UNLOCK_CAPABILITY;
+  action: 'unlock_console';
+  /** Opaque provider-local handle. Raw console credential material never enters Forge Runtime. */
+  credentialHandle: string;
+}
+
+export type ComputerConsoleUnlockCommandRequest = ComputerConsoleUnlockPrepareRequest | ComputerConsoleUnlockRequest;
+
+export interface ComputerConsoleUnlockAuthorization {
+  kind: 'explicit_single_use';
+  confirmed: true;
+  /** Unique per authorized attempt; provider replay protection consumes this exact id once. */
+  invocationId: string;
+}
+
+export type ComputerConsoleUnlockProviderRequest = ComputerConsoleUnlockCommandRequest & {
+  authorization: ComputerConsoleUnlockAuthorization;
+};
+
+export interface ComputerCaptureRequest {
+  capability: typeof COMPUTER_CAPTURE_CAPABILITY;
+  action: 'screenshot';
+  scope?: 'display' | 'window';
+  interactionId?: string;
+  windowId?: number;
+  label?: string;
+}
+
+export interface ComputerElementTarget {
+  interactionId: string;
+  pid: number;
+  bundleIdentifier?: string | null;
+  appName: string;
+  /** Provider-local AX window ref. It is valid only inside the observed snapshot epoch. */
+  windowRef?: string | null;
+  snapshotRevision: number;
+}
+
+export interface ComputerElementObserveRequest {
+  capability: typeof COMPUTER_ELEMENT_OBSERVE_CAPABILITY;
+  action: 'observe_elements';
+  interactionId: string;
+  maxDepth?: number;
+  maxNodes?: number;
+  includeValues?: boolean;
+  rootSelector?: ComputerSemanticSelector;
+}
+
+export type ComputerElementSemanticAction =
+  | 'invoke'
+  | 'focus'
+  | 'set_value'
+  | 'toggle'
+  | 'expand'
+  | 'collapse'
+  | 'select'
+  | 'open'
+  | 'show_menu'
+  | 'scroll_page_down'
+  | 'scroll_page_up';
+
+export interface ComputerElementActionRequest {
+  capability: typeof COMPUTER_ELEMENT_ACTION_CAPABILITY;
+  action: ComputerElementSemanticAction;
+  target: ComputerElementTarget;
+  ref: string;
+  value?: unknown;
+}
+
+export type ComputerExecutionRequest =
+  | { capability: typeof COMPUTER_BROWSER_AUTOMATION_CAPABILITY; request: ComputerBrowserAutomationRequest }
+  | ComputerObserveRequest
+  | ComputerInputRequest
+  | ComputerConsoleUnlockCommandRequest
+  | ComputerCaptureRequest
+  | ComputerElementObserveRequest
+  | ComputerElementActionRequest;
+
+/** Requests eligible for the Unified Computer provider registry. Browser automation remains an explicit compatibility path. */
+export type ComputerRuntimeExecutionRequest = Exclude<
+  ComputerExecutionRequest,
+  | { capability: typeof COMPUTER_BROWSER_AUTOMATION_CAPABILITY }
+  | { capability: typeof COMPUTER_CONSOLE_UNLOCK_CAPABILITY }
+>;
+
+/** Provider-internal execution includes protected capabilities after trusted Runtime authorization. */
+export type ComputerRuntimeProviderExecutionRequest =
+  | ComputerRuntimeExecutionRequest
+  | ComputerConsoleUnlockProviderRequest;

package/packages/protocols/computer/index.ts

@@ -0,0 +1 @@
+export * from './contract';

package/packages/protocols/failure/contract.ts

@@ -0,0 +1,158 @@
+export const FAILURE_CLASSES = [
+  'controller_unavailable',
+  'connector_stale',
+  'infrastructure_failure',
+  'acceptance_failure',
+  'invalid_check_id',
+  'approval_required',
+  'handoff_required',
+  'timeout',
+  'policy_denied',
+  'not_found',
+  'unknown_failure',
+] as const;
+
+export type FailureClass = (typeof FAILURE_CLASSES)[number];
+export type FailureRetryDisposition = 'never' | 'transient' | 'after_user_action' | 'reconcile_before_retry';
+export type FailureCodeProvenance = 'typed_code' | 'legacy_code_prefix' | 'fallback';
+
+export interface FailureDescriptor {
+  schemaVersion: 1;
+  code: string;
+  class: FailureClass;
+  retryDisposition: FailureRetryDisposition;
+  message: string;
+  provenance: FailureCodeProvenance;
+  httpStatus?: number;
+}
+
+export interface DescribeFailureOptions {
+  fallbackCode?: string;
+  fallbackHttpStatus?: number;
+  retryable?: boolean;
+}
+
+const FAILURE_CODE_TOKEN = /^[A-Z][A-Z0-9_]{1,127}$/;
+const TRANSIENT_FAILURE_CODES = new Set([
+  'EAI_AGAIN',
+  'ECONNABORTED',
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'EHOSTUNREACH',
+  'ENETDOWN',
+  'ENETUNREACH',
+  'EPIPE',
+  'ETIMEDOUT',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_SOCKET',
+]);
+
+function text(value: unknown): string {
+  return value instanceof Error ? value.message : typeof value === 'string' ? value : String(value ?? '');
+}
+
+function typedFailureCode(error: unknown): string | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+  const code = (error as { code?: unknown }).code;
+  if (typeof code !== 'string') return undefined;
+  const normalized = code.trim().toUpperCase();
+  return FAILURE_CODE_TOKEN.test(normalized) ? normalized : undefined;
+}
+
+function legacyFailureCodePrefix(message: string): string | undefined {
+  const match = /^([A-Z][A-Z0-9_]{1,127})(?::|\s|$)/.exec(message.trim());
+  return match && FAILURE_CODE_TOKEN.test(match[1]!) ? match[1] : undefined;
+}
+
+export function failureCodeFromUnknown(
+  error: unknown,
+  fallbackCode = 'UNKNOWN_FAILURE',
+): { code: string; provenance: FailureCodeProvenance } {
+  const typed = typedFailureCode(error);
+  if (typed) return { code: typed, provenance: 'typed_code' };
+  const legacy = legacyFailureCodePrefix(text(error));
+  if (legacy) return { code: legacy, provenance: 'legacy_code_prefix' };
+  const fallback = fallbackCode.trim().toUpperCase();
+  return {
+    code: FAILURE_CODE_TOKEN.test(fallback) ? fallback : 'UNKNOWN_FAILURE',
+    provenance: 'fallback',
+  };
+}
+
+export function classifyFailureCode(rawCode: unknown): FailureClass {
+  const code = typeof rawCode === 'string' ? rawCode.trim().toUpperCase() : '';
+  if (!FAILURE_CODE_TOKEN.test(code)) return 'unknown_failure';
+  if (code.includes('ACCEPTANCE') || code.includes('VALID_FAIL') || code.includes('CHECK_FAILED')) return 'acceptance_failure';
+  if (code.includes('INVALID_CHECK') || code.includes('CHECK_ID_INVALID') || code.includes('CHECK_NOT_FOUND')) return 'invalid_check_id';
+  if (code.includes('APPROVAL_REQUIRED') || code.includes('AUTHORIZATION_REQUIRED') || code.includes('WAITING_FOR_APPROVAL')) return 'approval_required';
+  if (code.includes('HANDOFF') || code.includes('NEEDS_REVIEW') || code.includes('HUMAN_ATTENTION')) return 'handoff_required';
+  if (code.includes('TIMED_OUT') || code.includes('TIMEOUT') || code === 'ETIMEDOUT') return 'timeout';
+  if (code.includes('CONNECTOR_STALE') || code.includes('CLIENT_SCHEMA_STALE') || code.includes('TOOL_SURFACE_STALE')) return 'connector_stale';
+  if (code.includes('CONTROLLER_UNAVAILABLE') || code.includes('RUNTIME_NOT_READY') || code === 'ECONNREFUSED') return 'controller_unavailable';
+  if (code.includes('SCOPE_DENIED') || code.includes('POLICY_DENIED') || code.includes('FORBIDDEN') || code.includes('NOT_ALLOWED')) return 'policy_denied';
+  if (code.includes('INFRASTRUCTURE') || code.includes('RUNTIME_STORAGE') || code.includes('WORKER_') || code.includes('SPAWN_') || code === 'ENOENT') return 'infrastructure_failure';
+  if (code.includes('NOT_FOUND')) return 'not_found';
+  return 'unknown_failure';
+}
+
+/**
+ * Compatibility-only presentation classifier for failures whose producer has
+ * not yet emitted a machine-readable code. Retry, authorization, placement,
+ * and persistence decisions must never call this function.
+ */
+export function classifyLegacyFailureMessage(rawMessage: unknown): FailureClass {
+  const message = typeof rawMessage === 'string' ? rawMessage.trim().toLowerCase() : '';
+  if (!message) return 'unknown_failure';
+  if (message.includes('acceptance') || message.includes('valid_fail') || message.includes('check failed') || message.includes('] failed') || (message.includes('expected ') && message.includes(' got '))) return 'acceptance_failure';
+  if ((message.includes('check not found') || message.includes('check_id')) && (message.includes('invalid') || message.includes('not found') || message.includes('not registered'))) return 'invalid_check_id';
+  if (message.includes('approval required') || message.includes('requires approval') || message.includes('awaiting approval') || message.includes('authorization required') || message.includes('confirm authorization')) return 'approval_required';
+  if (message.includes('handoff') || message.includes('needs_review') || message.includes('human_attention')) return 'handoff_required';
+  if (message.includes('timed out') || message.includes('timeout')) return 'timeout';
+  if (message.includes('stale connector') || message.includes('tool surface') || message.includes('fingerprint') || message.includes('reconnect')) return 'connector_stale';
+  if (message.includes('daemon') || message.includes('controller unavailable') || message.includes('not ready') || message.includes('econnrefused')) return 'controller_unavailable';
+  if (message.includes('denied') || message.includes('policy') || message.includes('forbidden') || message.includes('not allowed')) return 'policy_denied';
+  if (message.includes('infrastructure') || message.includes('runtime_storage') || message.includes('worker') || message.includes('spawn') || message.includes('enoent')) return 'infrastructure_failure';
+  if (message.includes('not found') || message.includes('not_found')) return 'not_found';
+  return 'unknown_failure';
+}
+
+export function retryDispositionForFailureCode(
+  rawCode: unknown,
+  explicitRetryable?: boolean,
+): FailureRetryDisposition {
+  if (explicitRetryable === true) return 'transient';
+  if (explicitRetryable === false) return 'never';
+  const code = typeof rawCode === 'string' ? rawCode.trim().toUpperCase() : '';
+  if (code.includes('OUTCOME_UNKNOWN')) return 'reconcile_before_retry';
+  return TRANSIENT_FAILURE_CODES.has(code) ? 'transient' : 'never';
+}
+
+export function httpStatusForFailureCode(rawCode: unknown, fallback = 400): number {
+  const code = typeof rawCode === 'string' ? rawCode.trim().toUpperCase() : '';
+  if (code.includes('RATE_LIMITED')) return 429;
+  if (code.includes('SCOPE_DENIED') || code.includes('POLICY_DENIED') || code.includes('FORBIDDEN')) return 403;
+  if (/^MOBILE_INTENT_(?:TOKEN|SIGNATURE|REPLAY|TIMESTAMP|NONCE|DEVICE)_/.test(code)) return 401;
+  if (code.includes('NOT_FOUND')) return 404;
+  return fallback;
+}
+
+export function describeFailure(error: unknown, options: DescribeFailureOptions = {}): FailureDescriptor {
+  const message = text(error);
+  const identity = failureCodeFromUnknown(error, options.fallbackCode);
+  const explicitRetryable = typeof options.retryable === 'boolean'
+    ? options.retryable
+    : error && typeof error === 'object' && typeof (error as { retryable?: unknown }).retryable === 'boolean'
+      ? (error as { retryable: boolean }).retryable
+      : undefined;
+  return {
+    schemaVersion: 1,
+    code: identity.code,
+    class: classifyFailureCode(identity.code),
+    retryDisposition: retryDispositionForFailureCode(identity.code, explicitRetryable),
+    message,
+    provenance: identity.provenance,
+    ...(options.fallbackHttpStatus !== undefined
+      ? { httpStatus: httpStatusForFailureCode(identity.code, options.fallbackHttpStatus) }
+      : {}),
+  };
+}

package/packages/protocols/failure/index.ts

@@ -0,0 +1 @@
+export * from './contract';

package/packages/protocols/handoff/index.ts

@@ -0,0 +1 @@
+export * from './status';

package/packages/protocols/handoff/status.ts

@@ -0,0 +1,22 @@
+export const HANDOFF_STATUSES = [
+  'pending',
+  'acknowledged',
+  'in_progress',
+  'resolved',
+  'dismissed',
+  'superseded',
+  'expired',
+] as const;
+
+export type HandoffStatus = (typeof HANDOFF_STATUSES)[number];
+
+export const TERMINAL_HANDOFF_STATUSES: readonly HandoffStatus[] = [
+  'resolved',
+  'dismissed',
+  'superseded',
+  'expired',
+] as const;
+
+export function isTerminalHandoffStatus(status: HandoffStatus): boolean {
+  return TERMINAL_HANDOFF_STATUSES.includes(status);
+}

package/packages/protocols/mcp/execution-context.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal transport-bound execution identity passed from the MCP adapter into
+ * Runtime execution services. Runtime code must not depend on the full MCP
+ * server/tool context or on adapter implementation modules.
+ */
+export interface McpExecutionContext {
+  controllerHome: string;
+  sessionId?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+}

package/packages/protocols/mcp/index.ts

@@ -0,0 +1,2 @@
+export * from './tool-contract';
+export * from './execution-context';

package/packages/protocols/mcp/tool-contract.ts

@@ -0,0 +1,42 @@
+import type { CallToolResult as SdkCallToolResult, Tool as SdkTool } from "@modelcontextprotocol/server";
+
+/** Transport-neutral MCP tool schema used by legacy, repository and Runtime surfaces. */
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations?: Record<string, unknown>;
+}
+
+/** Convert an SDK tool into Forge's transport-neutral tool contract. */
+export function mcpToolDefinitionFromSdk(tool: SdkTool): McpToolDefinition {
+  return {
+    name: tool.name,
+    description: tool.description ?? '',
+    inputSchema: tool.inputSchema as Record<string, unknown>,
+    ...(tool.annotations ? { annotations: tool.annotations as unknown as Record<string, unknown> } : {}),
+  };
+}
+
+/**
+ * Convert the Forge tool contract at the SDK boundary. Forge intentionally
+ * keeps JSON Schema transport-neutral internally; MCP tools are object-input
+ * operations, so enforce that invariant once instead of leaking SDK schema
+ * types through every tool-definition module.
+ */
+export function mcpToolDefinitionToSdk(tool: McpToolDefinition): SdkTool {
+  if (tool.inputSchema.type !== 'object') {
+    throw new Error(`MCP_TOOL_INPUT_SCHEMA_OBJECT_REQUIRED: ${tool.name}`);
+  }
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema as SdkTool['inputSchema'],
+    ...(tool.annotations ? { annotations: tool.annotations as SdkTool['annotations'] } : {}),
+  };
+}
+
+/** Bounded text-first result contract shared by Forge MCP adapters. */
+export type CallToolResult = Omit<SdkCallToolResult, 'content'> & {
+  content: Array<{ type: 'text'; text: string }>;
+};

package/packages/workflow-runtime/api/index.ts

@@ -0,0 +1,2 @@
+export * from '../domain/workflow-asset';
+export * from '../application/interpreter';