@moretea-labs/forge 1.8.0 → 1.8.1

package/supervisor/native-messaging/host.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env bun
+import { callExternalUnixJsonl } from '../../packages/plugin-runtime/external/unix-jsonl-transport';
+import { workflowSupervisorSocketPath } from '../paths';
+import { encodeNativeMessage, NativeMessageDecoder } from './protocol';
+
+export const WORKFLOW_SUPERVISOR_NATIVE_HOST_NAME = 'com.moretea.forge.workflow_supervisor';
+export const ALLOWED_BROWSER_METHODS = new Set([
+  'health','browser_discovery','browser_discovery_update','browser_project_scopes',
+  'computer_extension_heartbeat','computer_extension_claim','computer_extension_complete',
+]);
+
+interface BrowserNativeRequest { id: string; method: string; params: Record<string, unknown> }
+function request(value: unknown): BrowserNativeRequest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('WORKFLOW_SUPERVISOR_NATIVE_REQUEST_INVALID');
+  const record = value as Record<string, unknown>;
+  if (typeof record.id !== 'string' || !record.id || typeof record.method !== 'string' || !ALLOWED_BROWSER_METHODS.has(record.method)) throw new Error('WORKFLOW_SUPERVISOR_NATIVE_METHOD_DENIED');
+  return { id: record.id, method: record.method, params: record.params && typeof record.params === 'object' && !Array.isArray(record.params) ? record.params as Record<string, unknown> : {} };
+}
+export async function forwardNativeRequest(value: unknown, forgeHome?: string): Promise<Record<string, unknown>> {
+  const req = request(value);
+  try {
+    const result = await callExternalUnixJsonl({ socketPath: workflowSupervisorSocketPath(forgeHome), requestId: req.id, method: req.method, params: req.params, timeoutMs: 30_000 });
+    return { id: req.id, ok: true, result };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { id: req.id, ok: false, error: { code: message.includes(':') ? message.slice(0, message.indexOf(':')) : 'WORKFLOW_SUPERVISOR_NATIVE_FORWARD_FAILED', message } };
+  }
+}
+export function runNativeMessagingHost(forgeHome?: string): void {
+  const decoder = new NativeMessageDecoder();
+  let chain = Promise.resolve();
+  process.stdin.on('data', (chunk: Buffer) => {
+    let messages: unknown[];
+    try { messages = decoder.push(chunk); } catch (error) { process.stdout.write(encodeNativeMessage({ id: 'invalid', ok: false, error: { code: 'WORKFLOW_SUPERVISOR_NATIVE_FRAME_INVALID', message: String(error) } })); return; }
+    for (const message of messages) chain = chain.then(async () => { process.stdout.write(encodeNativeMessage(await forwardNativeRequest(message, forgeHome))); });
+  });
+  process.stdin.resume();
+}
+if (import.meta.main) runNativeMessagingHost(process.env.FORGE_HOME);

package/supervisor/native-messaging/manifest.ts

@@ -0,0 +1,26 @@
+import { isAbsolute } from 'node:path';
+import { WORKFLOW_SUPERVISOR_NATIVE_HOST_NAME } from './host';
+
+export interface WorkflowSupervisorNativeManifestInput {
+  executablePath: string;
+  extensionId?: string;
+  extensionIds?: readonly string[];
+}
+
+export function renderWorkflowSupervisorNativeManifest(input: WorkflowSupervisorNativeManifestInput): string {
+  if (!isAbsolute(input.executablePath)) throw new Error('WORKFLOW_SUPERVISOR_NATIVE_EXECUTABLE_ABSOLUTE_REQUIRED');
+  const extensionIds = (input.extensionIds ?? (input.extensionId ? [input.extensionId] : []))
+    .map((value) => value.trim())
+    .filter((value, index, values) => Boolean(value) && values.indexOf(value) === index)
+    .sort();
+  if (extensionIds.length === 0 || extensionIds.some((value) => !/^[a-p]{32}$/.test(value))) {
+    throw new Error('WORKFLOW_SUPERVISOR_EXTENSION_ID_INVALID');
+  }
+  return `${JSON.stringify({
+    name: WORKFLOW_SUPERVISOR_NATIVE_HOST_NAME,
+    description: 'Stateless Chrome relay to the Forge Workflow Supervisor authority',
+    path: input.executablePath,
+    type: 'stdio',
+    allowed_origins: extensionIds.map((extensionId) => `chrome-extension://${extensionId}/`),
+  }, null, 2)}\n`;
+}

package/supervisor/native-messaging/protocol.ts

@@ -0,0 +1,27 @@
+const MAX_NATIVE_MESSAGE_BYTES = 1024 * 1024;
+
+export function encodeNativeMessage(value: unknown): Buffer {
+  const payload = Buffer.from(JSON.stringify(value), 'utf8');
+  if (payload.length > MAX_NATIVE_MESSAGE_BYTES) throw new Error('WORKFLOW_SUPERVISOR_NATIVE_MESSAGE_TOO_LARGE');
+  const frame = Buffer.allocUnsafe(payload.length + 4);
+  frame.writeUInt32LE(payload.length, 0);
+  payload.copy(frame, 4);
+  return frame;
+}
+
+export class NativeMessageDecoder {
+  private buffer = Buffer.alloc(0);
+  push(chunk: Buffer): unknown[] {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    const values: unknown[] = [];
+    while (this.buffer.length >= 4) {
+      const length = this.buffer.readUInt32LE(0);
+      if (length > MAX_NATIVE_MESSAGE_BYTES) throw new Error('WORKFLOW_SUPERVISOR_NATIVE_MESSAGE_TOO_LARGE');
+      if (this.buffer.length < length + 4) break;
+      const raw = this.buffer.subarray(4, length + 4).toString('utf8');
+      this.buffer = this.buffer.subarray(length + 4);
+      try { values.push(JSON.parse(raw)); } catch { throw new Error('WORKFLOW_SUPERVISOR_NATIVE_MESSAGE_INVALID_JSON'); }
+    }
+    return values;
+  }
+}

package/supervisor/paths.ts

@@ -0,0 +1,18 @@
+import { join } from 'node:path';
+import { resolveControllerHome } from '../src/cli/repositories/controller-home';
+
+export function resolveWorkflowSupervisorForgeHome(controllerHome?: string): string {
+  return resolveControllerHome(controllerHome);
+}
+
+export function workflowSupervisorRootPath(controllerHome?: string): string {
+  return join(resolveWorkflowSupervisorForgeHome(controllerHome), 'supervisor');
+}
+
+export function workflowSupervisorDatabasePathValue(controllerHome?: string): string {
+  return join(workflowSupervisorRootPath(controllerHome), 'supervisor.sqlite');
+}
+
+export function workflowSupervisorSocketPath(controllerHome?: string): string {
+  return join(workflowSupervisorRootPath(controllerHome), 'supervisor.sock');
+}

package/supervisor/protocol.ts

@@ -0,0 +1,202 @@
+import { createHash } from 'node:crypto';
+import type { WorkflowEffectKind, WorkflowSupervisorProposal, WorkflowSupervisorState, WorkflowSupervisorTask, WorkflowSupervisorTurnEnvelope } from './types';
+
+// Newly-rendered Supervisor turns use one compact causal receipt because the
+// provider/browser output path can truncate longer machine-shaped payloads. Older
+// block formats remain read-only compatibility for already-durable conversations.
+export const SUPERVISOR_BLOCK_START = 'FORGE_WORKFLOW_SUPERVISOR_V1_BEGIN';
+export const SUPERVISOR_BLOCK_END = 'FORGE_WORKFLOW_SUPERVISOR_V1_END';
+const COMPACT_RECEIPT = /^([CDU]) ([0-9a-f]{7})$/;
+export const LEGACY_BRACKET_SUPERVISOR_BLOCK_START = '[[[FORGE_WORKFLOW_SUPERVISOR_V1]]]';
+export const LEGACY_BRACKET_SUPERVISOR_BLOCK_END = '[[[END_FORGE_WORKFLOW_SUPERVISOR_V1]]]';
+export const LEGACY_SUPERVISOR_BLOCK_START = '<<<FORGE_WORKFLOW_SUPERVISOR_V1>>>';
+export const LEGACY_SUPERVISOR_BLOCK_END = '<<<END_FORGE_WORKFLOW_SUPERVISOR_V1>>>';
+export const EFFECT_MARKER_PREFIX = '<<<FORGE_WORKFLOW_EFFECT_V1:';
+export const SUPERVISOR_TURN_BLOCK_START = 'FORGE_WORKFLOW_TURN_V2_BEGIN';
+export const SUPERVISOR_TURN_BLOCK_END = 'FORGE_WORKFLOW_TURN_V2_END';
+const EFFECT_ID = /^(?:fx|crpe)_[a-zA-Z0-9_-]{8,120}$/;
+const MAX_RESPONSE = 512 * 1024;
+const SUPERVISOR_BLOCK_MARKERS = [
+  { start: SUPERVISOR_BLOCK_START, end: SUPERVISOR_BLOCK_END },
+  { start: LEGACY_BRACKET_SUPERVISOR_BLOCK_START, end: LEGACY_BRACKET_SUPERVISOR_BLOCK_END },
+  { start: LEGACY_SUPERVISOR_BLOCK_START, end: LEGACY_SUPERVISOR_BLOCK_END },
+] as const;
+
+function boundedString(value: unknown, name: string, max: number): string {
+  if (typeof value !== 'string') throw new Error(`WORKFLOW_SUPERVISOR_${name}_REQUIRED`);
+  const normalized = value.trim();
+  if (!normalized || normalized.length > max) throw new Error(`WORKFLOW_SUPERVISOR_${name}_INVALID`);
+  return normalized;
+}
+
+export function validateEffectId(value: string): string {
+  if (!EFFECT_ID.test(value)) throw new Error('WORKFLOW_SUPERVISOR_EFFECT_ID_INVALID');
+  return value;
+}
+
+export function renderEffectMarker(effectId: string): string {
+  return `${EFFECT_MARKER_PREFIX}${validateEffectId(effectId)}>>>`;
+}
+
+export function supervisorReceiptChallenge(task: Pick<WorkflowSupervisorTask, 'taskId' | 'conversationId'>, effectId: string): string {
+  return createHash('sha256')
+    .update(`${task.taskId}\n${task.conversationId}\n${validateEffectId(effectId)}`)
+    .digest('hex')
+    .slice(0, 7);
+}
+
+export function renderSupervisorReceipt(
+  task: Pick<WorkflowSupervisorTask, 'taskId' | 'conversationId'>,
+  effectId: string,
+  action: WorkflowSupervisorProposal['action'],
+): string {
+  const code = action === 'CONTINUE' ? 'C' : action === 'DONE' ? 'D' : 'U';
+  return `${code} ${supervisorReceiptChallenge(task, effectId)}`;
+}
+
+function supervisorBlockEnvelope(responseText: string): { start: number; end: number; startMarker: string; endMarker: string } {
+  const candidates = SUPERVISOR_BLOCK_MARKERS.flatMap((marker) => {
+    const end = responseText.lastIndexOf(marker.end);
+    if (end < 0 || responseText.slice(end + marker.end.length).trim()) return [];
+    const start = responseText.lastIndexOf(marker.start, end);
+    return start < 0 ? [] : [{ start, end, startMarker: marker.start, endMarker: marker.end }];
+  });
+  if (candidates.length === 0) throw new Error('WORKFLOW_SUPERVISOR_END_MARKER_REQUIRED');
+  if (candidates.length !== 1) throw new Error('WORKFLOW_SUPERVISOR_CONTROL_BLOCK_AMBIGUOUS');
+  const envelope = candidates[0]!;
+  const prefix = responseText.slice(0, envelope.start);
+  if (SUPERVISOR_BLOCK_MARKERS.some((marker) => prefix.includes(marker.start))) {
+    throw new Error('WORKFLOW_SUPERVISOR_CONTROL_BLOCK_AMBIGUOUS');
+  }
+  return envelope;
+}
+
+export function hasCommittedSupervisorEnvelope(responseText: string): boolean {
+  if (Buffer.byteLength(responseText, 'utf8') > MAX_RESPONSE) return false;
+  if (COMPACT_RECEIPT.test(responseText.trim())) return true;
+  try { supervisorBlockEnvelope(responseText); return true; } catch { return false; }
+}
+
+export function parseSupervisorCompletion(
+  responseText: string,
+  expected?: { task: Pick<WorkflowSupervisorTask, 'taskId' | 'conversationId'>; effectId: string },
+): { proposal: WorkflowSupervisorProposal; controlBlock: string } {
+  if (Buffer.byteLength(responseText, 'utf8') > MAX_RESPONSE) throw new Error('WORKFLOW_SUPERVISOR_RESPONSE_TOO_LARGE');
+  const compact = COMPACT_RECEIPT.exec(responseText.trim());
+  if (compact) {
+    if (!expected) throw new Error('WORKFLOW_SUPERVISOR_COMPACT_RECEIPT_CONTEXT_REQUIRED');
+    const challenge = supervisorReceiptChallenge(expected.task, expected.effectId);
+    if (compact[2] !== challenge) throw new Error('WORKFLOW_SUPERVISOR_COMPACT_RECEIPT_CHALLENGE_MISMATCH');
+    const action = compact[1] === 'C' ? 'CONTINUE' : compact[1] === 'D' ? 'DONE' : 'NEEDS_USER';
+    const supervisorState: WorkflowSupervisorState = action === 'CONTINUE' ? 'running' : action === 'DONE' ? 'done' : 'needs_user';
+    return {
+      proposal: {
+        action,
+        sourceEffectId: validateEffectId(expected.effectId),
+        checkpoint: `receipt:${challenge}`,
+        reason: 'compact_receipt',
+        evidence: [],
+        conversationId: expected.task.conversationId,
+        taskId: expected.task.taskId,
+        supervisorState,
+      },
+      controlBlock: responseText.trim(),
+    };
+  }
+  const { start, end, startMarker, endMarker } = supervisorBlockEnvelope(responseText);
+  const jsonText = responseText.slice(start + startMarker.length, end).trim();
+  let parsed: unknown;
+  try { parsed = JSON.parse(jsonText); } catch { throw new Error('WORKFLOW_SUPERVISOR_CONTROL_BLOCK_JSON_INVALID'); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('WORKFLOW_SUPERVISOR_CONTROL_BLOCK_INVALID');
+  const record = parsed as Record<string, unknown>;
+  const allowed = new Set(['action', 'source_effect_id', 'checkpoint', 'reason', 'evidence', 'conversation_id', 'task_id', 'supervisor_state', 'active_scope']);
+  if (Object.keys(record).some((key) => !allowed.has(key))) throw new Error('WORKFLOW_SUPERVISOR_CONTROL_BLOCK_FIELD_INVALID');
+  const action = boundedString(record.action, 'ACTION', 32);
+  if (!['CONTINUE', 'DONE', 'NEEDS_USER'].includes(action)) throw new Error('WORKFLOW_SUPERVISOR_ACTION_INVALID');
+  const sourceEffectId = validateEffectId(boundedString(record.source_effect_id, 'SOURCE_EFFECT_ID', 128));
+  const checkpoint = boundedString(record.checkpoint, 'CHECKPOINT', 2_000);
+  const reason = boundedString(record.reason, 'REASON', 2_000);
+  if (!Array.isArray(record.evidence) || record.evidence.length > 16) throw new Error('WORKFLOW_SUPERVISOR_EVIDENCE_INVALID');
+  const evidence = record.evidence.map((value) => boundedString(value, 'EVIDENCE_ITEM', 1_000));
+  const conversationId = record.conversation_id === undefined ? undefined : boundedString(record.conversation_id, 'CONVERSATION_ID', 256);
+  const taskId = record.task_id === undefined ? undefined : boundedString(record.task_id, 'TASK_ID', 512);
+  const supervisorState = record.supervisor_state === undefined ? undefined : boundedString(record.supervisor_state, 'SUPERVISOR_STATE', 32) as WorkflowSupervisorState;
+  const activeScope = record.active_scope === undefined ? undefined : boundedString(record.active_scope, 'ACTIVE_SCOPE', 512);
+  if (supervisorState && !['running', 'done', 'needs_user'].includes(supervisorState)) throw new Error('WORKFLOW_SUPERVISOR_STATE_INVALID');
+  const expectedState: WorkflowSupervisorState = action === 'CONTINUE' ? 'running' : action === 'DONE' ? 'done' : 'needs_user';
+  if (supervisorState && supervisorState !== expectedState) throw new Error('WORKFLOW_SUPERVISOR_STATE_ACTION_MISMATCH');
+  if (activeScope && !/^(?:requirement|goal):[^\s]{1,480}$/.test(activeScope)) throw new Error('WORKFLOW_SUPERVISOR_ACTIVE_SCOPE_INVALID');
+  const controlBlock = responseText.slice(start, end + endMarker.length);
+  return {
+    proposal: {
+      action: action as WorkflowSupervisorProposal['action'], sourceEffectId, checkpoint, reason, evidence,
+      ...(conversationId ? { conversationId } : {}),
+      ...(taskId ? { taskId } : {}),
+      ...(supervisorState ? { supervisorState } : {}),
+      ...(activeScope ? { activeScope } : {}),
+    },
+    controlBlock,
+  };
+}
+
+export function renderSupervisorPrompt(
+  task: WorkflowSupervisorTask,
+  effectId: string,
+  kind: WorkflowEffectKind,
+  _checkpoint?: string,
+  _correctionReason?: string,
+  _lowerLayerContext?: string,
+  advisoryCognition?: string,
+): string {
+  const repoId = typeof task.completionContract.repo_id === 'string'
+    ? task.completionContract.repo_id.trim()
+    : typeof task.continuationPolicy.repo_id === 'string' ? task.continuationPolicy.repo_id.trim() : '';
+  const checkoutId = typeof task.completionContract.checkout_id === 'string'
+    ? task.completionContract.checkout_id.trim()
+    : typeof task.continuationPolicy.checkout_id === 'string' ? task.continuationPolicy.checkout_id.trim() : '';
+  const checkpoint = typeof _checkpoint === 'string' ? _checkpoint.trim().slice(0, 2_000) : '';
+  // Recovery/correction context is model-facing advisory evidence, not another
+  // authority. Discarding it made a recovery look like the original request
+  // and allowed the model to repeat previously completed work.
+  const recoveryContext = kind === 'recovery' || kind === 'correction'
+    ? (typeof _correctionReason === 'string' ? _correctionReason.trim() : '') : '';
+  // Preserve both parts even when an older checkpoint occupies the full bound.
+  const continuity = recoveryContext
+    ? [checkpoint.slice(0, 950), recoveryContext.slice(0, 1_000)].filter(Boolean).join('\n')
+    : checkpoint;
+  const cognition = advisoryCognition?.trim().slice(0, 8_000) ?? '';
+  const envelope: WorkflowSupervisorTurnEnvelope = {
+    schema_version: 2,
+    identity: {
+      task_id: task.taskId,
+      effect_id: validateEffectId(effectId),
+      kind,
+    },
+    goal: {
+      role: 'outcome',
+      objective: task.objective.slice(0, 8_000),
+    },
+    ...(continuity ? { continuity: { role: 'advisory' as const, summary: continuity } } : {}),
+    ...(repoId ? { repository: { repo_id: repoId, ...(checkoutId ? { checkout_id: checkoutId } : {}) } } : {}),
+    ...(cognition ? { cognition: { role: 'advisory' as const, projection: cognition } } : {}),
+    automation: {
+      automation_task_id: task.taskId,
+      automation_type: 'autonomous_continuation',
+      intermediate_status: 'working',
+      final_statuses: ['continue', 'done', 'needs_user'],
+    },
+  };
+  return [
+    '@forge',
+    renderEffectMarker(effectId),
+    SUPERVISOR_TURN_BLOCK_START,
+    JSON.stringify(envelope),
+    SUPERVISOR_TURN_BLOCK_END,
+    // The tool receipt, not prose in the page, settles the same applied effect.
+    // One instruction for every turn: no new scheduler, no extra state, no
+    // unconditional CONTINUE when no real work has been done.
+    'FORGE_AUTONOMOUS_RECEIPT_V1: Use automation_task_id and automation_type from this envelope on Forge calls. Use automation_status=working during execution. After substantive progress, submit automation_status=continue in the final Forge call; use done only after the stated goal is met, or needs_user only for a genuine external decision/blocker. A text-only answer does not settle the turn. Do not report continue for a status-only or empty round.',
+  ].join('\n');
+}
+
+export function sha256(value: string): string { return createHash('sha256').update(value).digest('hex'); }