@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/root/computer-composition.ts

@@ -0,0 +1,191 @@
+import {
+  ComputerProviderError,
+  ComputerProviderRegistry,
+  computerProviderRegistrationSnapshot,
+} from '../../../packages/plugin-runtime/computer/index';
+import {
+  COMPUTER_BROWSER_AUTOMATION_CAPABILITY,
+  COMPUTER_CONSOLE_UNLOCK_CAPABILITY,
+  type ComputerBrowserAutomationRequest,
+  type ComputerBrowserProduct,
+  type ComputerConsoleUnlockCommandRequest,
+  type ComputerConsoleUnlockProviderRequest,
+  type ComputerRuntimeExecutionRequest,
+  type ComputerRuntimeProviderExecutionRequest,
+} from '../../../packages/protocols/computer/index';
+import { DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID } from '../../../adapters/computer/desktop-operator-contract';
+import { createDesktopOperatorComputerProvider, type DesktopOperatorComputerProvider } from '../../../adapters/computer/index';
+import { resolveControllerHome } from '../../cli/repositories/controller-home';
+import { currentComputerPlatform } from '../platform/computer-platform';
+import { getExternalPluginAdapter } from '../plugins/external-adapter';
+import { getExternalPluginRegistration } from '../plugins/external-registration';
+import { AssistantPluginError } from '../plugins/errors';
+import type { AssistantPluginActionExecutionInput } from '../plugins/types';
+
+let computerProviders: ComputerProviderRegistry | undefined;
+let computerProviderCompositionKey: string | undefined;
+let desktopOperatorProvider: DesktopOperatorComputerProvider | undefined;
+const NATIVE_BROWSER_BUNDLE_IDS: Record<ComputerBrowserProduct, string> = {
+  chrome: 'com.google.Chrome',
+  vivaldi: 'com.vivaldi.Vivaldi',
+};
+function currentDesktopOperatorRegistration(controllerHome: string) {
+  return getExternalPluginRegistration(controllerHome, DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID);
+}
+
+function computerCompositionKey(controllerHome: string): string {
+  const registration = currentDesktopOperatorRegistration(controllerHome);
+  const fingerprint = registration
+    ? `${registration.revision}:${registration.registrationFingerprint}:${registration.enabled ? 'enabled' : 'disabled'}`
+    : 'desktop_operator:unregistered_v0_2';
+  return `${controllerHome}:${currentComputerPlatform()}:${fingerprint}`;
+}
+
+function ensureComputerComposition(controllerHome: string = resolveControllerHome()): ComputerProviderRegistry {
+  const compositionKey = computerCompositionKey(controllerHome);
+  if (computerProviders && computerProviderCompositionKey === compositionKey) return computerProviders;
+
+  computerProviders?.dispose();
+  const next = new ComputerProviderRegistry();
+  if (currentComputerPlatform() === 'darwin') {
+    const registration = currentDesktopOperatorRegistration(controllerHome);
+    desktopOperatorProvider = createDesktopOperatorComputerProvider({
+      lookupRegistration: (providerPluginId) => {
+        if (providerPluginId !== DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID || !registration) return undefined;
+        return computerProviderRegistrationSnapshot(registration);
+      },
+      // Compatibility is an explicit Runtime composition decision, never an adapter fallback.
+      // Remove this switch once Desktop Operator 0.2.x support is retired.
+      legacyFallback: 'unregistered_v0_2',
+    });
+    next.register(desktopOperatorProvider);
+  }
+  computerProviders = next;
+  computerProviderCompositionKey = compositionKey;
+  return next;
+}
+
+async function executeComputerProviderRequest(
+  request: ComputerRuntimeProviderExecutionRequest,
+  timeoutMs: number,
+  controllerHome: string,
+): Promise<Record<string, unknown>> {
+  const providers = ensureComputerComposition(controllerHome);
+  try {
+    return await providers.execute(request, timeoutMs);
+  } catch (error) {
+    if (error instanceof ComputerProviderError) {
+      throw new AssistantPluginError(error.code, error.detailMessage, {
+        retryable: error.retryable,
+        effectOutcome: error.effectOutcome,
+        details: error.details,
+      });
+    }
+    throw error;
+  }
+}
+
+export async function executeRuntimeComputer(
+  request: ComputerRuntimeExecutionRequest,
+  timeoutMs: number,
+  controllerHome: string = resolveControllerHome(),
+): Promise<Record<string, unknown>> {
+  return await executeComputerProviderRequest(request, timeoutMs, controllerHome);
+}
+
+export interface RuntimeComputerConsoleUnlockAuthorization {
+  kind: 'explicit_single_use';
+  confirmed: true;
+  invocationId: string;
+}
+
+/**
+ * Protected Computer path. The caller must obtain explicit authorization for either
+ * provider-local credential preparation or one handle-bound unlock attempt. Raw console
+ * credential material never enters Runtime, generic Plugin actions, Jobs, or receipts.
+ */
+export async function executeRuntimeComputerConsoleUnlock(
+  request: ComputerConsoleUnlockCommandRequest,
+  authorization: RuntimeComputerConsoleUnlockAuthorization,
+  timeoutMs: number,
+  controllerHome: string = resolveControllerHome(),
+): Promise<Record<string, unknown>> {
+  if (request.capability !== COMPUTER_CONSOLE_UNLOCK_CAPABILITY
+    || !['prepare_unlock_console', 'unlock_console'].includes(request.action)) {
+    throw new AssistantPluginError('COMPUTER_CONSOLE_UNLOCK_REQUEST_INVALID', 'Protected console unlock accepts only computer.console.unlock.v1 prepare/unlock commands.', { retryable: false });
+  }
+  if (authorization.kind !== 'explicit_single_use'
+    || authorization.confirmed !== true
+    || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(authorization.invocationId)) {
+    throw new AssistantPluginError('COMPUTER_CONSOLE_UNLOCK_EXPLICIT_AUTHORIZATION_REQUIRED', 'Protected console unlock requires one explicit single-use authorization bound to this invocation.', { retryable: false });
+  }
+  if (request.action === 'unlock_console'
+    && !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(request.credentialHandle)) {
+    throw new AssistantPluginError('COMPUTER_CONSOLE_UNLOCK_CREDENTIAL_HANDLE_REQUIRED', 'Protected console unlock requires one provider-local opaque credential handle.', { retryable: false });
+  }
+  const providerRequest: ComputerConsoleUnlockProviderRequest = { ...request, authorization };
+  return await executeComputerProviderRequest(providerRequest, timeoutMs, controllerHome);
+}
+
+export async function executeRuntimeComputerBrowserAutomation(
+  request: ComputerBrowserAutomationRequest,
+  timeoutMs: number,
+  controllerHome: string = resolveControllerHome(),
+): Promise<Record<string, unknown>> {
+  ensureComputerComposition(controllerHome);
+  if (!desktopOperatorProvider) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_COMPATIBILITY_PROVIDER_UNAVAILABLE',
+      'Native Browser compatibility requires the macOS Desktop Operator provider.',
+      { retryable: true, details: { providerId: DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID } },
+    );
+  }
+  return await desktopOperatorProvider.executeBrowserCompatibility(request, timeoutMs);
+}
+
+export async function activateRuntimeComputerBrowserApplication(
+  input: AssistantPluginActionExecutionInput,
+  product: ComputerBrowserProduct,
+): Promise<void> {
+  const platform = currentComputerPlatform();
+  if (platform !== 'darwin') {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_FOREGROUND_ACTIVATOR_UNSUPPORTED_PLATFORM',
+      `Native browser foreground activation is unavailable on ${platform} until a platform Computer provider is registered.`,
+      { retryable: false, details: { browserProduct: product, platform } },
+    );
+  }
+  const desktopOperator = getExternalPluginAdapter(input.controllerHome, DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID);
+  if (!desktopOperator) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_FOREGROUND_ACTIVATOR_UNAVAILABLE',
+      'Native browser foreground activation requires an available Computer application provider.',
+      { retryable: true, details: { browserProduct: product, providerId: DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID } },
+    );
+  }
+  await desktopOperator.executeAction({
+    controllerHome: input.controllerHome,
+    repoId: input.repoId,
+    repoRoot: input.repoRoot,
+    pluginId: DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID,
+    actionId: 'desktop_session_open',
+    requestId: `${input.requestId}:native-browser-foreground:${product}`,
+    args: { bundle_id: NATIVE_BROWSER_BUNDLE_IDS[product], launch: false, activate: true },
+    origin: input.origin,
+    jobId: input.jobId,
+    timeoutMs: input.timeoutMs,
+    signal: input.signal,
+    deadlineAtMs: input.deadlineAtMs,
+  });
+}
+
+export function runtimeComputerProviderSnapshot(controllerHome: string = resolveControllerHome()): Array<{ providerId: string; capabilities: string[] }> {
+  return ensureComputerComposition(controllerHome).snapshot();
+}
+
+export function disposeRuntimeComputerComposition(): void {
+  computerProviders?.dispose();
+  computerProviders = undefined;
+  computerProviderCompositionKey = undefined;
+  desktopOperatorProvider = undefined;
+}

package/src/runtime/root/computer-target-composition.ts

@@ -0,0 +1,16 @@
+import type { ComputerInteractionTargetAuthorityPort, ComputerInteractionTargetCleanupReport } from '../../../packages/plugin-runtime/computer/target-authority';
+import { createComputerInteractionTargetAuthority } from '../../../adapters/computer/interaction-target-authority';
+import { createRuntimeComputerTargetPersistence } from './computer-target-persistence';
+
+const computerInteractionTargetAuthority = createComputerInteractionTargetAuthority(createRuntimeComputerTargetPersistence());
+
+export function runtimeComputerInteractionTargetAuthority(): ComputerInteractionTargetAuthorityPort {
+  return computerInteractionTargetAuthority;
+}
+
+export function cleanupRuntimeComputerInteractionTargets(
+  controllerHome: string,
+  options?: { nowMs?: number; ttlMs?: number; maxTombstones?: number; maxRemovals?: number },
+): Promise<ComputerInteractionTargetCleanupReport> {
+  return computerInteractionTargetAuthority.cleanupTombstones(controllerHome, options);
+}

package/src/runtime/root/computer-target-persistence.ts

@@ -0,0 +1,39 @@
+import type { ComputerTargetPersistencePort } from '../../../packages/plugin-runtime/computer/target-persistence';
+import { CONTROLLER_SCOPE_REPO_ID } from '../../cli/repositories/controller-home';
+import { withControllerLockAsync } from '../../cli/repositories/locks';
+import {
+  deleteControlPlaneRecord,
+  deleteControlPlaneRecordWithinTransaction,
+  listAllControlPlaneRecords,
+  listAllControlPlaneRecordsWithinTransaction,
+  listControlPlaneRecords,
+  listControlPlaneRecordsWithinTransaction,
+  readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  withControlPlaneTransaction,
+  writeControlPlaneRecord,
+  writeControlPlaneRecordWithinTransaction,
+} from '../control-plane/persistence/sqlite-store';
+
+export function createRuntimeComputerTargetPersistence(): ComputerTargetPersistencePort {
+  return {
+    read: (controllerHome, namespace, scope, key) => readControlPlaneRecord(controllerHome, namespace, scope, key),
+    list: (controllerHome, input) => listControlPlaneRecords(controllerHome, input),
+    listAll: (controllerHome, input) => listAllControlPlaneRecords(controllerHome, input),
+    write: (controllerHome, input) => writeControlPlaneRecord(controllerHome, input),
+    delete: (controllerHome, input) => deleteControlPlaneRecord(controllerHome, input),
+    transaction: (controllerHome, operation) => withControlPlaneTransaction(controllerHome, (database) => operation({
+      read: (namespace, scope, key) => readControlPlaneRecordWithinTransaction(database, namespace, scope, key),
+      list: (input) => listControlPlaneRecordsWithinTransaction(database, input),
+      listAll: (input) => listAllControlPlaneRecordsWithinTransaction(database, input),
+      write: (input) => writeControlPlaneRecordWithinTransaction(database, input),
+      delete: (input) => deleteControlPlaneRecordWithinTransaction(database, input),
+    })),
+    withTargetLock: (controllerHome, targetId, operation) => withControllerLockAsync(
+      controllerHome,
+      { scope: 'task', repoId: CONTROLLER_SCOPE_REPO_ID, taskId: `computer-target-${targetId}` },
+      `computer-target:${targetId}`,
+      operation,
+    ),
+  };
+}

package/src/runtime/root/controller-round-composition.ts

@@ -0,0 +1,107 @@
+import { createHash } from 'crypto';
+import type { AssistantContextSnapshot, ControllerRoundRelayRecord } from '../../../packages/kernel/controller/api/index';
+import { prepareAssistantWorkContext } from '../context/assistant-work-context';
+import { renderAssistantContext, type AssistantContextResolution } from '../context/assistant-context';
+import { getChatgptWorkConversationBinding } from '../../../adapters/chatgpt/work-conversation-binding-store';
+import {
+  buildChatgptControllerRoundPrompt,
+  chatgptControllerRoundBindingAuthorizesRecovery,
+} from '../../../adapters/chatgpt/controller-round-host';
+import {
+  recordChatgptControllerRoundSettlement,
+  type ChatgptControllerRoundSettlementStatus,
+} from '../../../adapters/chatgpt/controller-round-settlement-store';
+
+// Kernel V2 composition root: provider-specific adapter wiring lives here, not in transport adapters.
+export interface ControllerRoundCompositionStore {
+  controllerHome: string;
+  repoId: string;
+}
+
+export interface ChatgptControllerRoundBindingSnapshot {
+  bindingId?: string;
+  browserSessionId?: string;
+  conversationUrl?: string;
+}
+
+export function chatgptControllerRoundBinding(
+  store: ControllerRoundCompositionStore,
+  workId: string,
+): ChatgptControllerRoundBindingSnapshot | undefined {
+  const binding = getChatgptWorkConversationBinding(store, workId);
+  if (!binding) return undefined;
+  return {
+    bindingId: binding.bindingId,
+    browserSessionId: binding.latestBrowserSessionId,
+    conversationUrl: binding.conversationUrl,
+  };
+}
+
+export function chatgptControllerRoundRecoveryAuthorized(
+  store: ControllerRoundCompositionStore,
+  workId: string,
+  relay: ControllerRoundRelayRecord | undefined,
+): boolean {
+  return chatgptControllerRoundBindingAuthorizesRecovery(
+    relay,
+    getChatgptWorkConversationBinding(store, workId),
+  );
+}
+
+export function renderChatgptControllerRoundPrompt(
+  store: ControllerRoundCompositionStore,
+  relay: ControllerRoundRelayRecord,
+  options: { exactOriginWork?: boolean } = {},
+): string {
+  return buildChatgptControllerRoundPrompt({ ...store,
+    prepareAssistantContext: workId => prepareControllerAssistantContext(store, workId),
+  }, relay, options);
+}
+
+export function recordChatgptControllerRoundTabSettlement(
+  store: ControllerRoundCompositionStore,
+  input: {
+    workId: string;
+    relayScopeId: string;
+    status: ChatgptControllerRoundSettlementStatus;
+    error?: string;
+  },
+): void {
+  recordChatgptControllerRoundSettlement(store, input);
+}
+
+function controllerAssistantContextSnapshot(resolution: AssistantContextResolution): AssistantContextSnapshot {
+  const items = resolution.items.map((item) => ({
+    kind: item.kind,
+    itemId: item.id,
+    digest: item.provenance.digest,
+    revision: item.provenance.revision,
+    sourceRevision: item.provenance.sourceRevision,
+  }));
+  const identity = {
+    projectId: resolution.projectId,
+    items,
+    gaps: resolution.gaps,
+    missingRequiredSources: resolution.missingRequiredSources,
+    truncated: resolution.truncated,
+  };
+  return {
+    digest: `sha256:${createHash('sha256').update(JSON.stringify(identity)).digest('hex')}`,
+    ...identity,
+  };
+}
+
+/** Resolve once at claim so rendered context and retained round evidence share one identity. */
+export function prepareControllerAssistantContextBundle(
+  store: ControllerRoundCompositionStore,
+  workId: string,
+): { rendered: string; snapshot: AssistantContextSnapshot; resolution: AssistantContextResolution } | undefined {
+  const resolution = prepareAssistantWorkContext({ controllerHome: store.controllerHome, repoId: store.repoId, workId });
+  if (!resolution) return undefined;
+  return { rendered: renderAssistantContext(resolution), snapshot: controllerAssistantContextSnapshot(resolution), resolution };
+}
+
+/** Provider-neutral context refresh used immediately after a successful claim. */
+export function prepareControllerAssistantContext(store: ControllerRoundCompositionStore, workId: string): string | undefined {
+  return prepareControllerAssistantContextBundle(store, workId)?.rendered;
+}

package/src/runtime/root/controller-services.ts

@@ -1,3 +1,4 @@
+import { initializeWorkCandidateIndex } from '../../../packages/kernel/work/api/index';
 import {
   inspectControlPlaneDatabase,
   type ControlPlaneDatabaseInspection,
@@ -21,6 +22,7 @@ export class RuntimeControllerServices {
 
   initialize(): ControlPlaneDatabaseInspection {
     this.initializedDatabase = this.inspectDatabase(this.controllerHome);
+    initializeWorkCandidateIndex(this.controllerHome);
     return this.initializedDatabase;
   }
 

package/src/runtime/root/entry.ts

@@ -6,7 +6,7 @@ import { CanonicalForgeRuntime } from './runtime';
 
 interface CliOptions {
   controllerHome: string;
-  repo: string;
+  repo?: string;
   releaseManifest: string;
   host: string;
   port: string;
@@ -24,7 +24,7 @@ export async function runCanonicalRuntimeCli(argv = process.argv): Promise<void>
   const command = new Command('forge-runtime')
     .description('Run the canonical single Forge Runtime root process')
     .requiredOption('--controller-home <path>', 'Explicit Controller Home')
-    .requiredOption('--repo <path>', 'Explicit repository root')
+    .option('--repo <path>', 'Optional default repository root for development/repository UI')
     .requiredOption('--release-manifest <path>', 'Complete immutable release manifest')
     .requiredOption('--host <host>', 'MCP listener host')
     .requiredOption('--port <port>', 'MCP listener port')
@@ -36,7 +36,7 @@ export async function runCanonicalRuntimeCli(argv = process.argv): Promise<void>
   if (!Number.isInteger(port) || port < 1 || port > 65_535) throw new Error('RUNTIME_CONFIG_INVALID: port');
   const runtime = new CanonicalForgeRuntime({
     controllerHome: resolve(options.controllerHome),
-    repositoryRoot: resolve(options.repo),
+    ...(options.repo?.trim() ? { repositoryRoot: resolve(options.repo) } : {}),
     releaseManifestPath: resolve(options.releaseManifest),
     host: options.host,
     port,
@@ -46,6 +46,7 @@ export async function runCanonicalRuntimeCli(argv = process.argv): Promise<void>
   await runtime.start();
   process.stderr.write(`${JSON.stringify({
     event: 'forge_runtime_started',
+    forgeInstanceId: runtime.forgeInstanceId,
     runtimeInstanceId: runtime.runtimeInstanceId,
     endpoint: runtime.endpoint(),
     readiness: runtime.readiness(),

package/src/runtime/root/gateway-adapter.ts

@@ -1,6 +1,6 @@
-import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { createForgeMcpServerFromContext, createMcpToolContext } from '../../cli/mcp/server';
-import { controllerExposureSnapshot } from '../../cli/mcp/toolset';
+import type { Server } from "@modelcontextprotocol/server";
+import { createForgeMcpServerFromContext, createMcpToolContext } from '../../../adapters/mcp/server';
+import { controllerExposureSnapshot } from '../../../adapters/mcp/toolset';
 import type { RuntimeControllerServices } from './controller-services';
 
 export interface RuntimeGatewayServerOptions {

package/src/runtime/root/local-bridge.ts

@@ -2,7 +2,7 @@ import {
   loadMcpServiceLocalConfig,
   loadMcpServiceRuntimeState,
   writeMcpServiceRuntimeState,
-} from '../../cli/mcp/auth';
+} from '../../../adapters/mcp/auth';
 import { startLocalBridgeServer } from '../../cli/local-bridge/server';
 import { readRuntimeGeneration } from '../control-plane/runtime-generation';
 
@@ -18,13 +18,16 @@ export interface RuntimeLocalBridgeHandle {
  */
 export async function startConfiguredRuntimeLocalBridge(input: {
   controllerHome: string;
-  repositoryRoot: string;
+  repositoryRoot?: string;
 }): Promise<RuntimeLocalBridgeHandle | undefined> {
   const config = loadMcpServiceLocalConfig(input.controllerHome);
   const local = config?.localController;
   if (local?.enabled !== true || local.mode === 'disabled' || local.mode === 'remote' || local.mode === 'standalone') {
     return undefined;
   }
+  // Embedded Local Bridge remains repository-oriented today. Do not invent a
+  // package/source directory as a fake repository merely to start the Runtime.
+  if (!input.repositoryRoot?.trim()) return undefined;
 
   const startedAt = new Date().toISOString();
   const handle = await startLocalBridgeServer({

package/src/runtime/root/mcp-transport.ts

@@ -2,12 +2,12 @@ import { createHash, randomUUID, timingSafeEqual } from 'crypto';
 import type { Server as NodeHttpServer } from 'http';
 import type { AddressInfo } from 'net';
 import express, { type NextFunction, type Request, type Response } from 'express';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Server } from "@modelcontextprotocol/server";
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
 import type { RuntimeReadiness } from './types';
 
 interface ManagedSession {
-  transport: StreamableHTTPServerTransport;
+  transport: NodeStreamableHTTPServerTransport;
   lastActivityAt: number;
   activePosts: number;
   activeStreams: number;
@@ -235,7 +235,7 @@ export async function startRuntimeMcpTransport(
           res.status(503).json({ error: 'mcp_session_capacity_exhausted' });
           return;
         }
-        let transport: StreamableHTTPServerTransport;
+        let transport: NodeStreamableHTTPServerTransport;
         let committedSessionId: string | undefined;
         const forwardedPrincipalId = typeof req.headers['x-forge-forwarded-principal-id'] === 'string'
           ? req.headers['x-forge-forwarded-principal-id'].trim().slice(0, 512)
@@ -251,7 +251,7 @@ export async function startRuntimeMcpTransport(
           : undefined;
         const principal = forwardedPrincipalId || principalId(options.authToken);
         const server = options.createServer(principal, forwardedSessionId || undefined, forwardedControllerType);
-        transport = new StreamableHTTPServerTransport({
+        transport = new NodeStreamableHTTPServerTransport({
           sessionIdGenerator: () => randomUUID(),
           onsessioninitialized: (createdSessionId) => {
             committedSessionId = createdSessionId;