@moretea-labs/forge 1.5.1 → 1.6.0

package/src/runtime/workflow/schedules/work-continuation.ts

@@ -19,9 +19,11 @@ import type {
 } from './types';
 
 export type ContinuationControllerType = 'chatgpt' | 'codex' | 'claude' | 'grok';
+export type WorkScheduleMode = 'continuation' | 'browser_watch' | 'browser_keepalive';
 
 export interface WorkContinuationScheduleInput {
   workId: string;
+  scheduleMode?: WorkScheduleMode;
   controllerType?: ContinuationControllerType;
   executable?: string;
   launchArgs?: string[];
@@ -30,6 +32,18 @@ export interface WorkContinuationScheduleInput {
   browserSessionId?: string;
   conversationUrl?: string;
   continuationPrompt?: string;
+  probeUrl?: string;
+  probeBrowserSessionId?: string;
+  probeSelector?: string;
+  probeMaxChars?: number;
+  probeTimeoutMs?: number;
+  includeTerms?: string[];
+  ignorePatterns?: string[];
+  loginUrlTerms?: string[];
+  loginTextTerms?: string[];
+  wakeOnFirstObservation?: boolean;
+  wakeOnAuthRequired?: boolean;
+  authRequiredPrompt?: string;
   scheduleName?: string;
   requestId?: string;
   triggerType?: ScheduleTriggerType;
@@ -70,7 +84,7 @@ function activeWork(controllerHome: string, repoId: string, workId: string): Wor
 }
 
 function continuationSchedule(schedule: RepositorySchedule): RepositorySchedule {
-  if (schedule.action.operation !== 'external_controller_wake') {
+  if (!['external_controller_wake', 'browser_probe'].includes(schedule.action.operation)) {
     throw new Error(`SCHEDULE_NOT_WORK_CONTINUATION: ${schedule.scheduleId}`);
   }
   return schedule;
@@ -105,6 +119,29 @@ function wakeArguments(input: WorkContinuationScheduleInput, controllerType: Con
   };
 }
 
+function probeArguments(input: WorkContinuationScheduleInput, controllerType: ContinuationControllerType, keepaliveOnly: boolean): Record<string, unknown> {
+  if (!input.probeUrl?.trim() && !input.probeBrowserSessionId?.trim()) {
+    throw new Error('SCHEDULE_BROWSER_PROBE_TARGET_REQUIRED');
+  }
+  return {
+    ...wakeArguments(input, controllerType),
+    ...(input.probeUrl?.trim() ? { probe_url: input.probeUrl.trim() } : {}),
+    ...(input.probeBrowserSessionId?.trim() ? { probe_session_id: input.probeBrowserSessionId.trim() } : {}),
+    ...(input.probeSelector?.trim() ? { selector: input.probeSelector.trim() } : {}),
+    ...(input.probeMaxChars !== undefined ? { max_chars: Math.max(256, Math.min(Math.trunc(input.probeMaxChars), 100_000)) } : {}),
+    ...(input.probeTimeoutMs !== undefined ? { timeout_ms: Math.max(1_000, Math.min(Math.trunc(input.probeTimeoutMs), 120_000)) } : {}),
+    ...(input.includeTerms ? { include_terms: input.includeTerms.map(String).filter(Boolean) } : {}),
+    ...(input.ignorePatterns ? { ignore_patterns: input.ignorePatterns.map(String).filter(Boolean) } : {}),
+    ...(input.loginUrlTerms ? { login_url_terms: input.loginUrlTerms.map(String).filter(Boolean) } : {}),
+    ...(input.loginTextTerms ? { login_text_terms: input.loginTextTerms.map(String).filter(Boolean) } : {}),
+    ...(input.wakeOnFirstObservation === true ? { wake_on_first_observation: true } : {}),
+    ...(input.wakeOnAuthRequired === false ? { wake_on_auth_required: false } : {}),
+    ...(input.authRequiredPrompt?.trim() ? { auth_required_prompt: input.authRequiredPrompt.trim() } : {}),
+    keepalive_only: keepaliveOnly,
+    wake_on_change: !keepaliveOnly,
+  };
+}
+
 export function createWorkContinuationSchedule(
   controllerHome: string,
   repoId: string,
@@ -112,26 +149,70 @@ export function createWorkContinuationSchedule(
 ): { schedule: RepositorySchedule; work: WorkContract } {
   const work = activeWork(controllerHome, repoId, input.workId);
   const controllerType = input.controllerType ?? 'chatgpt';
+  const scheduleMode = input.scheduleMode ?? 'continuation';
   const trigger = normalizedTrigger(input);
-  const actionArguments = wakeArguments(input, controllerType);
-  assertAutomatedOperationAllowed('external_controller_wake', actionArguments);
-  const name = input.scheduleName?.trim() || `Continue Work ${work.workId}`;
+  const operation = scheduleMode === 'continuation' ? 'external_controller_wake' : 'browser_probe';
+  const actionArguments = scheduleMode === 'continuation'
+    ? wakeArguments(input, controllerType)
+    : probeArguments(input, controllerType, scheduleMode === 'browser_keepalive');
+  assertAutomatedOperationAllowed(operation, actionArguments);
+  const name = input.scheduleName?.trim()
+    || (scheduleMode === 'browser_watch' ? `Watch external state for Work ${work.workId}`
+      : scheduleMode === 'browser_keepalive' ? `Keep browser session alive for Work ${work.workId}`
+        : `Continue Work ${work.workId}`);
+  const policy = {
+    maxActiveOccurrences: 1,
+    maxFailures: input.maxFailures !== undefined ? Math.max(1, Math.trunc(input.maxFailures)) : 3,
+    cooldownMinutes: input.cooldownMinutes !== undefined ? Math.max(0, Math.trunc(input.cooldownMinutes)) : 120,
+    dailyBudgetMinutes: input.dailyBudgetMinutes !== undefined ? Math.max(1, Math.trunc(input.dailyBudgetMinutes)) : 180,
+    shadowMode: input.shadowMode !== false,
+    backoffBaseMinutes: input.backoffBaseMinutes !== undefined ? Math.max(1, Math.trunc(input.backoffBaseMinutes)) : 5,
+    backoffMaxMinutes: input.backoffMaxMinutes !== undefined ? Math.max(1, Math.trunc(input.backoffMaxMinutes)) : 24 * 60,
+  };
+  const stopConditions = input.stopConditions ?? ['work_terminal', 'human_review_required', 'external_blocker'];
+
+  // A durable Work has one authoritative continuation lane. Changing cadence,
+  // prompt, controller, or policy updates that lane instead of minting another
+  // Workflow. Browser watches/keepalives are intentionally excluded because one
+  // Work may legitimately observe several independent external targets.
+  if (scheduleMode === 'continuation') {
+    const existing = listSchedules(controllerHome, repoId)
+      .filter((candidate) => candidate.action.operation === 'external_controller_wake')
+      .filter((candidate) => candidate.action.arguments?.work_id === work.workId);
+    const authoritative = [...existing].reverse().find((candidate) => candidate.enabled) ?? existing.at(-1);
+    if (authoritative) {
+      const schedule = saveSchedule(controllerHome, {
+        ...authoritative,
+        name,
+        enabled: true,
+        trigger,
+        policy,
+        action: { operation, target: 'runtime', arguments: actionArguments, resourceClaims: [] },
+        stopConditions,
+        pausedReason: undefined,
+      });
+      for (const duplicate of existing) {
+        if (duplicate.scheduleId === schedule.scheduleId || !duplicate.enabled) continue;
+        saveSchedule(controllerHome, {
+          ...duplicate,
+          enabled: false,
+          pausedReason: `Superseded by authoritative continuation ${schedule.scheduleId} for Work ${work.workId}.`,
+        });
+      }
+      return { schedule, work };
+    }
+  }
+
   const semantic = JSON.stringify({
     repoId,
     workId: work.workId,
     controllerType,
+    scheduleMode,
     trigger,
     name,
     actionArguments,
-    policy: {
-      maxFailures: input.maxFailures,
-      cooldownMinutes: input.cooldownMinutes,
-      dailyBudgetMinutes: input.dailyBudgetMinutes,
-      shadowMode: input.shadowMode,
-      backoffBaseMinutes: input.backoffBaseMinutes,
-      backoffMaxMinutes: input.backoffMaxMinutes,
-    },
-    stopConditions: input.stopConditions,
+    policy,
+    stopConditions,
   });
   const requestId = input.requestId?.trim()
     || `work-continuation:${repoId}:${work.workId}:${createHash('sha256').update(semantic).digest('hex').slice(0, 16)}`;
@@ -141,19 +222,11 @@ export function createWorkContinuationSchedule(
     name,
     enabled: true,
     trigger,
-    policy: {
-      maxActiveOccurrences: 1,
-      maxFailures: input.maxFailures !== undefined ? Math.max(1, Math.trunc(input.maxFailures)) : 3,
-      cooldownMinutes: input.cooldownMinutes !== undefined ? Math.max(0, Math.trunc(input.cooldownMinutes)) : 120,
-      dailyBudgetMinutes: input.dailyBudgetMinutes !== undefined ? Math.max(1, Math.trunc(input.dailyBudgetMinutes)) : 180,
-      shadowMode: input.shadowMode !== false,
-      backoffBaseMinutes: input.backoffBaseMinutes !== undefined ? Math.max(1, Math.trunc(input.backoffBaseMinutes)) : 5,
-      backoffMaxMinutes: input.backoffMaxMinutes !== undefined ? Math.max(1, Math.trunc(input.backoffMaxMinutes)) : 24 * 60,
-    },
-    // The schedule only wakes a Controller. The Controller acquires Work/resource
-    // ownership separately, so the wake itself must not claim repository writes.
-    action: { operation: 'external_controller_wake', target: 'runtime', arguments: actionArguments, resourceClaims: [] },
-    stopConditions: input.stopConditions ?? ['work_terminal', 'human_review_required', 'external_blocker'],
+    policy,
+    // Work-bound schedules only perform a deterministic wake or a bounded read-only
+    // browser probe. Controller/Work write ownership is acquired separately.
+    action: { operation, target: 'runtime', arguments: actionArguments, resourceClaims: [] },
+    stopConditions,
   });
   return { schedule, work };
 }
@@ -164,7 +237,7 @@ export function listWorkContinuationSchedules(
   options: WorkContinuationScheduleListOptions = {},
 ): { schedules: RepositorySchedule[]; occurrences?: ScheduleOccurrence[] } {
   const schedules = listSchedules(controllerHome, repoId)
-    .filter((entry) => entry.action.operation === 'external_controller_wake')
+    .filter((entry) => ['external_controller_wake', 'browser_probe'].includes(entry.action.operation))
     .filter((entry) => !options.workId || entry.action.arguments?.work_id === options.workId);
   if (!options.includeOccurrences) return { schedules };
   const scheduleIds = new Set(schedules.map((entry) => entry.scheduleId));

package/bin/forge-desktop-helper.mjs

@@ -1,204 +0,0 @@
-#!/usr/bin/env node
-import { execFile } from 'child_process';
-import { existsSync } from 'fs';
-import { createInterface } from 'readline';
-
-const SCHEMA_VERSION = 1;
-const PLUGIN_ID = 'desktop';
-const HELPER_VERSION = '1.0.0';
-const MAX_LINE_BYTES = 1_048_576;
-const MAX_COMMAND_OUTPUT_BYTES = 64 * 1024;
-const OSASCRIPT = '/usr/bin/osascript';
-const OPEN = '/usr/bin/open';
-const CAPABILITIES = ['status', 'observe', 'open_application'];
-
-function write(value) {
-  process.stdout.write(`${JSON.stringify(value)}\n`);
-}
-
-function bounded(value, max = 2_000) {
-  const source = String(value ?? '').replace(/(token|secret|password|authorization)\s*[=:]\s*\S+/gi, '$1=[REDACTED]');
-  return source.length > max ? source.slice(-max) : source;
-}
-
-function failure(requestId, code, message, retryable = false, details) {
-  write({
-    schemaVersion: SCHEMA_VERSION,
-    type: 'result',
-    requestId,
-    ok: false,
-    error: { code, message, retryable, ...(details ? { details } : {}) },
-  });
-}
-
-function success(requestId, result) {
-  write({ schemaVersion: SCHEMA_VERSION, type: 'result', requestId, ok: true, result });
-}
-
-function run(command, args, timeoutMs = 10_000) {
-  return new Promise((resolve) => {
-    execFile(command, args, {
-      encoding: 'utf8',
-      timeout: timeoutMs,
-      maxBuffer: MAX_COMMAND_OUTPUT_BYTES,
-      windowsHide: true,
-      env: {
-        PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
-        HOME: process.env.HOME,
-        TMPDIR: process.env.TMPDIR,
-        LANG: process.env.LANG,
-        LC_ALL: process.env.LC_ALL,
-      },
-    }, (error, stdout, stderr) => {
-      resolve({
-        ok: !error,
-        code: typeof error?.code === 'number' ? error.code : null,
-        stdout: String(stdout ?? ''),
-        stderr: bounded(stderr || error?.message || ''),
-      });
-    });
-  });
-}
-
-function permissionDiagnostics() {
-  return {
-    accessibility: {
-      state: 'not_probed',
-      reason: 'The bundled helper does not trigger macOS consent prompts during status or observation.',
-    },
-    screenRecording: {
-      state: 'not_required',
-      reason: 'This version does not capture screenshots or screen pixels.',
-    },
-  };
-}
-
-async function status() {
-  return {
-    platform: process.platform,
-    helperVersion: HELPER_VERSION,
-    protocolVersion: SCHEMA_VERSION,
-    managed: true,
-    transport: 'stdio-jsonl',
-    capabilities: CAPABILITIES,
-    commands: {
-      openAvailable: existsSync(OPEN),
-      frontmostApplicationProbeAvailable: existsSync(OSASCRIPT),
-    },
-    permissions: permissionDiagnostics(),
-  };
-}
-
-async function observe() {
-  if (process.platform !== 'darwin') {
-    throw Object.assign(new Error('Desktop observation currently supports macOS only.'), { code: 'PLUGIN_DESKTOP_PLATFORM_UNSUPPORTED' });
-  }
-  if (!existsSync(OSASCRIPT)) {
-    return {
-      observed: false,
-      frontmostApplication: null,
-      permissions: permissionDiagnostics(),
-      warnings: ['The macOS NSWorkspace inspection bridge is unavailable.'],
-    };
-  }
-  const script = "ObjC.import('AppKit'); const app=$.NSWorkspace.sharedWorkspace.frontmostApplication; JSON.stringify({name:ObjC.unwrap(app.localizedName),bundleId:ObjC.unwrap(app.bundleIdentifier),pid:Number(app.processIdentifier)})";
-  const inspected = await run(OSASCRIPT, ['-l', 'JavaScript', '-e', script], 5_000);
-  if (!inspected.ok || !inspected.stdout.trim()) {
-    return {
-      observed: false,
-      frontmostApplication: null,
-      permissions: permissionDiagnostics(),
-      warnings: [bounded(inspected.stderr || 'Unable to resolve the frontmost application.')],
-    };
-  }
-  try {
-    const app = JSON.parse(inspected.stdout.trim());
-    return {
-      observed: true,
-      frontmostApplication: {
-        name: typeof app.name === 'string' ? app.name : null,
-        bundleId: typeof app.bundleId === 'string' ? app.bundleId : null,
-        pid: Number.isInteger(app.pid) && app.pid > 0 ? app.pid : null,
-      },
-      permissions: permissionDiagnostics(),
-      warnings: [],
-    };
-  } catch {
-    return {
-      observed: false,
-      frontmostApplication: null,
-      permissions: permissionDiagnostics(),
-      warnings: ['The macOS NSWorkspace bridge returned malformed application metadata.'],
-    };
-  }
-}
-
-async function openApplication(input) {
-  if (process.platform !== 'darwin') {
-    throw Object.assign(new Error('Application opening currently supports macOS only.'), { code: 'PLUGIN_DESKTOP_PLATFORM_UNSUPPORTED' });
-  }
-  const appName = typeof input.app_name === 'string' ? input.app_name.trim() : '';
-  const bundleId = typeof input.bundle_id === 'string' ? input.bundle_id.trim() : '';
-  if ((!appName && !bundleId) || (appName && bundleId)) {
-    throw Object.assign(new Error('Provide exactly one of app_name or bundle_id.'), { code: 'PLUGIN_ACTION_ARGUMENT_INVALID' });
-  }
-  const args = bundleId ? ['-b', bundleId] : ['-a', appName];
-  const opened = await run(OPEN, args, 20_000);
-  if (!opened.ok) {
-    throw Object.assign(new Error(opened.stderr || 'macOS open command failed.'), {
-      code: 'PLUGIN_DESKTOP_OPEN_FAILED',
-      retryable: true,
-    });
-  }
-  return { opened: true, selector: bundleId ? { bundleId } : { appName } };
-}
-
-async function execute(message) {
-  if (!message || typeof message !== 'object' || message.schemaVersion !== SCHEMA_VERSION || message.type !== 'execute') {
-    throw Object.assign(new Error('Invalid managed Desktop request envelope.'), { code: 'PLUGIN_MANAGED_PROCESS_PROTOCOL_ERROR' });
-  }
-  if (typeof message.requestId !== 'string' || typeof message.actionId !== 'string' || !message.input || typeof message.input !== 'object' || Array.isArray(message.input)) {
-    throw Object.assign(new Error('Invalid managed Desktop request fields.'), { code: 'PLUGIN_MANAGED_PROCESS_PROTOCOL_ERROR' });
-  }
-  if (message.actionId === 'status') return await status();
-  if (message.actionId === 'observe') return await observe();
-  if (message.actionId === 'open_application') return await openApplication(message.input);
-  throw Object.assign(new Error(`desktop/${message.actionId} is not supported.`), { code: 'PLUGIN_ACTION_NOT_SUPPORTED' });
-}
-
-write({
-  schemaVersion: SCHEMA_VERSION,
-  type: 'handshake',
-  protocolVersion: SCHEMA_VERSION,
-  pluginId: PLUGIN_ID,
-  helperVersion: HELPER_VERSION,
-  capabilities: CAPABILITIES,
-});
-
-const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
-let handled = false;
-lines.on('line', async (line) => {
-  if (handled) return;
-  handled = true;
-  if (Buffer.byteLength(line, 'utf8') > MAX_LINE_BYTES) {
-    failure('unknown', 'PLUGIN_MANAGED_PROCESS_REQUEST_TOO_LARGE', 'Managed Desktop request exceeded the bounded input limit.');
-    lines.close();
-    return;
-  }
-  let message;
-  try {
-    message = JSON.parse(line);
-    const result = await execute(message);
-    success(message.requestId, result);
-  } catch (error) {
-    const requestId = typeof message?.requestId === 'string' ? message.requestId : 'unknown';
-    failure(
-      requestId,
-      typeof error?.code === 'string' ? error.code : 'PLUGIN_DESKTOP_ACTION_FAILED',
-      bounded(error?.message || error),
-      error?.retryable === true,
-    );
-  } finally {
-    lines.close();
-  }
-});

package/docs/operations/controller-desktop-plugin.md

@@ -1,112 +0,0 @@
-# Controller Desktop Plugin
-
-The `desktop` plugin is a bundled first-party Forge capability for bounded
-macOS desktop observation and application launch. It is not downloaded from a
-marketplace and it does not require a user-configured socket, executable path, or
-registration descriptor.
-
-## Architecture
-
-```text
-ChatGPT / CLI / Local UI
-  -> list_plugins / get_plugin / plugin_action_execute
-     -> existing plugin policy, schema, receipt, and audit layers
-        -> Desktop adapter (Controller process)
-           -> one-shot managed child process
-              -> JSON-lines stdio handshake and action
-                 -> bundled forge-desktop-helper.mjs
-```
-
-The Controller starts the helper on demand for one action. The child performs a
-versioned handshake, executes one bounded request, returns one structured result,
-and exits. Forge enforces request and response size limits, timeout,
-cancellation, capability negotiation, bounded diagnostics, and process cleanup.
-The helper is launched directly without a shell.
-
-This initial implementation deliberately does not provide:
-
-- plugin search, download, installation, or a marketplace;
-- arbitrary commands or user-configured helper paths;
-- sockets, background registration files, or a second plugin registry;
-- screen capture, clicks, coordinates, keyboard input, or text entry;
-- dynamic MCP tool loading.
-
-The existing static MCP tools remain the public entry point, while action schemas,
-permissions, lifecycle, health, receipts, and audit events remain authoritative in
-the existing plugin runtime.
-
-## Actions
-
-| Action | Effect | Policy |
-| --- | --- | --- |
-| `configure` | Enable or disable the bundled Desktop plugin. | Authorization required. |
-| `status` | Run a live helper handshake and return bounded readiness diagnostics. | Read-only. |
-| `observe` | Read the frontmost macOS application through `NSWorkspace`; no screen pixels are captured. | Read-only. |
-| `open_application` | Open one app by exact `app_name` or `bundle_id`. | Authorization required. |
-
-`open_application` accepts exactly one selector. It invokes `/usr/bin/open` with an
-argv array and never interpolates a shell command.
-
-## Enable on this Mac
-
-Use the controller-scoped plugin action without a repository id:
-
-```json
-{
-  "plugin_id": "desktop",
-  "action_id": "configure",
-  "request_id": "desktop-enable-1",
-  "confirm_authorization": true,
-  "arguments": {
-    "enabled": true
-  }
-}
-```
-
-Then call `get_plugin` for `desktop`, followed by `status` and `observe`.
-No ChatGPT reconnect is required because Forge reuses the existing
-`list_plugins`, `get_plugin`, and `plugin_action_execute` tool schemas. Loading a
-new Runtime revision may require the external lifecycle owner to restart the
-existing single Forge Runtime; it must not create a second Runtime or rollout slot.
-
-Configuration authority is stored under:
-
-```text
-<controller-home>/system/desktop/config.json
-```
-
-The derived manifest and registry remain Controller projections. The helper path
-is resolved from the active Forge installation and is not returned as
-user-facing configuration.
-
-## Permissions
-
-The current version does not request Screen Recording permission because it does
-not capture screenshots. Read-only observation uses AppKit `NSWorkspace` through
-the system JavaScript bridge and does not intentionally trigger Accessibility
-consent prompts. Health reports Accessibility as `not_probed` rather than claiming
-permission that has not been verified.
-
-Future click, keyboard, screenshot, or accessibility-tree actions must be added as
-separate capabilities with explicit permission probes, stronger policy, redaction,
-and fault-injection coverage. They must not be inferred from this initial plugin.
-
-## Failure behavior
-
-The plugin fails closed when:
-
-- it is disabled;
-- the platform is not macOS;
-- the bundled helper is missing;
-- the helper handshake or capability set is incompatible;
-- a response is malformed or exceeds the output bound;
-- the helper crashes, times out, or is cancelled;
-- `open_application` receives zero or multiple selectors.
-
-A helper failure is surfaced as a structured `PLUGIN_MANAGED_PROCESS_*` or
-`PLUGIN_DESKTOP_*` error through the existing plugin receipt and audit path.
-
-
-## Immutable release packaging
-
-Whole-Runtime releases include `forge-desktop-helper.mjs` as a required, hashed sibling artifact. The Desktop adapter resolves it from the validated active Runtime release identity, then uses argv/source candidates only as development compatibility fallbacks. It launches the helper with the same trusted Node resolver used by the bounded Node bridge path; it does not execute the compiled Forge binary as a JavaScript interpreter. Release validation fails closed when the helper is missing or empty, and plugin health reports helper and trusted-runtime availability without returning either local path.