@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/safe-tooling/workspace-auth.ts

@@ -0,0 +1,116 @@
+import type { AssistantPluginManifest } from '../plugins/types';
+import { bootstrapManagedRuntimeEnv } from '../shared/managed-env';
+import { prepareGoogleOAuthLogin, type GoogleOAuthService } from './google-oauth-broker';
+
+export type WorkspaceAuthService = GoogleOAuthService;
+
+interface WorkspaceAuthLoginInput {
+  service?: string;
+  scopes?: string[];
+  redirectUri?: string;
+}
+
+const SERVICE_SCOPES: Record<WorkspaceAuthService, string[]> = {
+  gmail: [
+    'https://www.googleapis.com/auth/gmail.readonly',
+    'https://www.googleapis.com/auth/gmail.compose',
+    'https://www.googleapis.com/auth/gmail.modify',
+    'https://www.googleapis.com/auth/gmail.send',
+  ],
+  calendar: ['https://www.googleapis.com/auth/calendar'],
+  tasks: ['https://www.googleapis.com/auth/tasks'],
+  'google-workspace': [
+    'https://www.googleapis.com/auth/gmail.readonly',
+    'https://www.googleapis.com/auth/gmail.compose',
+    'https://www.googleapis.com/auth/gmail.modify',
+    'https://www.googleapis.com/auth/gmail.send',
+    'https://www.googleapis.com/auth/calendar',
+    'https://www.googleapis.com/auth/tasks',
+  ],
+};
+
+const SCOPE_ALIASES: Record<string, string> = {
+  'gmail.readonly': 'https://www.googleapis.com/auth/gmail.readonly',
+  'gmail.compose': 'https://www.googleapis.com/auth/gmail.compose',
+  'gmail.modify': 'https://www.googleapis.com/auth/gmail.modify',
+  'gmail.send': 'https://www.googleapis.com/auth/gmail.send',
+  'calendar.events.readonly': 'https://www.googleapis.com/auth/calendar',
+  'calendar.events.write': 'https://www.googleapis.com/auth/calendar',
+  'calendar.events.delete': 'https://www.googleapis.com/auth/calendar',
+  'tasks.readonly': 'https://www.googleapis.com/auth/tasks',
+  'tasks.write': 'https://www.googleapis.com/auth/tasks',
+  'tasks.delete': 'https://www.googleapis.com/auth/tasks',
+};
+
+function normalizeService(value: unknown): WorkspaceAuthService {
+  const raw = String(value ?? 'google-workspace').trim().toLowerCase().replace(/^google_/, 'google-');
+  if (raw === 'gmail' || raw === 'calendar' || raw === 'tasks' || raw === 'google-workspace') return raw;
+  throw new Error('WORKSPACE_AUTH_SERVICE_UNSUPPORTED: choose gmail, calendar, tasks, or google-workspace');
+}
+
+function pluginAuthSummary(manifest: AssistantPluginManifest): Record<string, unknown> {
+  return {
+    pluginId: manifest.pluginId,
+    enabled: manifest.enabled,
+    lifecycleState: manifest.lifecycle.state,
+    lifecycleReason: manifest.lifecycle.reason,
+    healthState: manifest.health.state,
+    ready: manifest.health.ready,
+    authRequired: manifest.health.errors.some((error) => /access token|auth|authorization|oauth/i.test(error)),
+    errors: manifest.health.errors.slice(0, 5),
+    warnings: manifest.health.warnings.slice(0, 5),
+    grantedPermissions: manifest.permissions.filter((permission) => permission.granted).map((permission) => permission.scope),
+    missingRequiredPermissions: manifest.permissions.filter((permission) => permission.required && !permission.granted).map((permission) => permission.scope),
+  };
+}
+
+export function buildWorkspaceAuthStatus(manifests: AssistantPluginManifest[]): Record<string, unknown> {
+  const workspacePlugins = manifests.filter((manifest) => ['gmail', 'google_calendar', 'google_tasks', 'google-calendar', 'google-tasks'].includes(manifest.pluginId));
+  const summaries = workspacePlugins.map(pluginAuthSummary);
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    providers: summaries,
+    actionRequired: summaries.filter((entry) => entry.authRequired === true || entry.ready !== true).map((entry) => ({
+      pluginId: entry.pluginId,
+      reason: entry.lifecycleReason,
+      next: 'Call workspace_auth_login_prepare and open the returned local OAuth URL. The callback stores the refresh token in macOS Keychain.',
+    })),
+    safety: {
+      credentialMaterialReturned: false,
+      credentialMaterialPersistedInRepository: false,
+      repositoryMutation: false,
+    },
+  };
+}
+
+export function prepareWorkspaceAuthLogin(
+  controllerHomeOrInput: string | WorkspaceAuthLoginInput = {},
+  maybeInput: WorkspaceAuthLoginInput = {},
+): Record<string, unknown> {
+  bootstrapManagedRuntimeEnv();
+  const controllerHome = typeof controllerHomeOrInput === 'string'
+    ? controllerHomeOrInput
+    : process.env.FORGE_CONTROLLER_HOME?.trim() || process.cwd();
+  const input = typeof controllerHomeOrInput === 'string' ? maybeInput : controllerHomeOrInput;
+  const service = normalizeService(input.service);
+  const redirectUri = input.redirectUri || process.env.FORGE_GOOGLE_REDIRECT_URI || 'http://127.0.0.1:8766/oauth/google/callback';
+  const requestedScopes = Array.isArray(input.scopes) && input.scopes.length > 0
+    ? input.scopes.map((scope) => SCOPE_ALIASES[String(scope)] ?? String(scope)).filter(Boolean)
+    : SERVICE_SCOPES[service];
+  const prepared = prepareGoogleOAuthLogin(controllerHome, { service, scopes: requestedScopes, redirectUri });
+  const priorSafety = prepared.safety && typeof prepared.safety === 'object' && !Array.isArray(prepared.safety)
+    ? prepared.safety as Record<string, unknown>
+    : {};
+  return {
+    ...prepared,
+    tokenEnvironmentVariables: service === 'gmail'
+      ? ['FORGE_GMAIL_ACCESS_TOKEN', 'FORGE_GMAIL_REFRESH_TOKEN']
+      : ['FORGE_GOOGLE_WORKSPACE_ACCESS_TOKEN', 'FORGE_GOOGLE_WORKSPACE_REFRESH_TOKEN'],
+    safety: {
+      ...priorSafety,
+      credentialMaterialPersisted: false,
+      credentialMaterialPersistedInRepository: false,
+    },
+  };
+}

package/src/runtime/shared/bounded-child-supervisor.ts

@@ -0,0 +1,235 @@
+import { spawn, type ChildProcess, type StdioOptions } from 'child_process';
+import {
+  isProcessAlive,
+  listProcessTreeMembers,
+  signalProcessTree,
+  terminateProcessTree,
+  type ProcessTreeTerminationResult,
+} from './process-tree';
+
+export const CHILD_SUPERVISOR_FAILURE_CODES = {
+  CHILD_START_FAILED: 'CHILD_SUPERVISOR_START_FAILED',
+  WALL_TIMEOUT: 'CHILD_SUPERVISOR_WALL_TIMEOUT',
+  RESIDUAL_PROCESS: 'CHILD_SUPERVISOR_RESIDUAL_PROCESS',
+  DID_NOT_CONVERGE: 'CHILD_SUPERVISOR_DID_NOT_CONVERGE',
+} as const;
+
+export type ChildSupervisorFailureCode =
+  (typeof CHILD_SUPERVISOR_FAILURE_CODES)[keyof typeof CHILD_SUPERVISOR_FAILURE_CODES];
+
+export interface BoundedChildSupervisorOperations {
+  isProcessAlive(pid: number | undefined): boolean;
+  listProcessTreeMembers(pid: number | undefined): number[];
+  signalProcessTree(pid: number | undefined, signal: NodeJS.Signals): boolean;
+  terminateProcessTree(
+    pid: number | undefined,
+    options: { gracePeriodMs: number; killAfterMs: number; pollIntervalMs: number },
+  ): Promise<ProcessTreeTerminationResult>;
+}
+
+const defaultOperations: BoundedChildSupervisorOperations = {
+  isProcessAlive,
+  listProcessTreeMembers,
+  signalProcessTree,
+  terminateProcessTree,
+};
+
+export interface BoundedChildRunOptions {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs: number;
+  maxOutputBytes?: number;
+  stdio?: 'capture' | 'inherit';
+  forwardSignals?: boolean;
+  onSpawn?: (pid: number) => void;
+  operations?: BoundedChildSupervisorOperations;
+  termination?: { gracePeriodMs?: number; killAfterMs?: number; pollIntervalMs?: number };
+}
+
+export interface BoundedChildRunResult {
+  status: number;
+  signal: NodeJS.Signals | null;
+  timedOut: boolean;
+  stdout: string;
+  stderr: string;
+  pid?: number;
+  residualPids: number[];
+  remainingPids: number[];
+  pidReuseFenced: boolean;
+  failureCode?: ChildSupervisorFailureCode;
+  error?: string;
+}
+
+const DEFAULT_MAX_OUTPUT_BYTES = 256 * 1024;
+const DEFAULT_TERMINATION = { gracePeriodMs: 100, killAfterMs: 2_000, pollIntervalMs: 25 } as const;
+
+function appendBounded(current: string, chunk: Buffer | string, maxBytes: number): string {
+  const next = current + chunk.toString();
+  if (Buffer.byteLength(next, 'utf8') <= maxBytes * 2) return next;
+  return Buffer.from(next, 'utf8').subarray(-maxBytes * 2).toString('utf8');
+}
+
+function capOutput(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, 'utf8') <= maxBytes) return value;
+  return `${Buffer.from(value, 'utf8').subarray(-maxBytes).toString('utf8')}\n[earlier output truncated]`;
+}
+
+/**
+ * Inspect a closed child's process group exactly once. The live-leader fence
+ * prevents a reused PID/PGID from becoming a signal target.
+ */
+export async function cleanupOwnedProcessGroup(
+  pid: number | undefined,
+  operations: BoundedChildSupervisorOperations = defaultOperations,
+  termination: BoundedChildRunOptions['termination'] = {},
+): Promise<Pick<BoundedChildRunResult, 'residualPids' | 'remainingPids' | 'pidReuseFenced' | 'failureCode'>> {
+  if (!pid || pid <= 0) {
+    return { residualPids: [], remainingPids: [], pidReuseFenced: false };
+  }
+  if (operations.isProcessAlive(pid)) {
+    return { residualPids: [], remainingPids: [], pidReuseFenced: true };
+  }
+  const residualPids = operations.listProcessTreeMembers(pid).filter((member) => member !== pid);
+  if (residualPids.length === 0) {
+    return { residualPids: [], remainingPids: [], pidReuseFenced: false };
+  }
+  if (operations.isProcessAlive(pid)) {
+    return { residualPids: [], remainingPids: [], pidReuseFenced: true };
+  }
+  const result = await operations.terminateProcessTree(pid, {
+    gracePeriodMs: termination?.gracePeriodMs ?? DEFAULT_TERMINATION.gracePeriodMs,
+    killAfterMs: termination?.killAfterMs ?? DEFAULT_TERMINATION.killAfterMs,
+    pollIntervalMs: termination?.pollIntervalMs ?? DEFAULT_TERMINATION.pollIntervalMs,
+  });
+  return {
+    residualPids,
+    remainingPids: result.remainingPids,
+    pidReuseFenced: false,
+    failureCode: result.exited
+      ? CHILD_SUPERVISOR_FAILURE_CODES.RESIDUAL_PROCESS
+      : CHILD_SUPERVISOR_FAILURE_CODES.DID_NOT_CONVERGE,
+  };
+}
+
+export async function runBoundedChild(
+  command: string,
+  args: readonly string[],
+  options: BoundedChildRunOptions,
+): Promise<BoundedChildRunResult> {
+  const operations = options.operations ?? defaultOperations;
+  const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const stdio: StdioOptions = options.stdio === 'inherit'
+    ? ['ignore', 'inherit', 'inherit']
+    : ['ignore', 'pipe', 'pipe'];
+  let child: ChildProcess;
+  try {
+    child = spawn(command, [...args], {
+      cwd: options.cwd,
+      env: options.env,
+      detached: process.platform !== 'win32',
+      windowsHide: true,
+      stdio,
+    });
+  } catch (error) {
+    return {
+      status: 1,
+      signal: null,
+      timedOut: false,
+      stdout: '',
+      stderr: '',
+      residualPids: [],
+      remainingPids: [],
+      pidReuseFenced: false,
+      failureCode: CHILD_SUPERVISOR_FAILURE_CODES.CHILD_START_FAILED,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  const pid = child.pid;
+  if (pid) options.onSpawn?.(pid);
+  let stdout = '';
+  let stderr = '';
+  child.stdout?.on('data', (chunk) => { stdout = appendBounded(stdout, chunk, maxOutputBytes); });
+  child.stderr?.on('data', (chunk) => { stderr = appendBounded(stderr, chunk, maxOutputBytes); });
+
+  return await new Promise<BoundedChildRunResult>((resolve) => {
+    let settled = false;
+    let timedOut = false;
+    let requestedSignal: NodeJS.Signals | undefined;
+    let escalationTimer: NodeJS.Timeout | undefined;
+    let convergenceTimer: NodeJS.Timeout | undefined;
+
+    const clear = (): void => {
+      clearTimeout(wallTimer);
+      if (escalationTimer) clearTimeout(escalationTimer);
+      if (convergenceTimer) clearTimeout(convergenceTimer);
+      if (options.forwardSignals) {
+        process.off('SIGINT', onSigInt);
+        process.off('SIGTERM', onSigTerm);
+      }
+    };
+    const finish = async (
+      status: number,
+      signal: NodeJS.Signals | null,
+      error?: string,
+      forcedFailureCode?: ChildSupervisorFailureCode,
+      beforeClose = false,
+    ): Promise<void> => {
+      if (settled) return;
+      settled = true;
+      clear();
+      let cleanup: Pick<BoundedChildRunResult, 'residualPids' | 'remainingPids' | 'pidReuseFenced' | 'failureCode'>;
+      if (beforeClose) {
+        const remainingPids = operations.listProcessTreeMembers(pid);
+        cleanup = { residualPids: remainingPids, remainingPids, pidReuseFenced: false };
+      } else {
+        cleanup = await cleanupOwnedProcessGroup(pid, operations, options.termination);
+      }
+      const failureCode = forcedFailureCode
+        ?? cleanup.failureCode
+        ?? (timedOut ? CHILD_SUPERVISOR_FAILURE_CODES.WALL_TIMEOUT : undefined)
+        ?? (error ? CHILD_SUPERVISOR_FAILURE_CODES.CHILD_START_FAILED : undefined);
+      resolve({
+        status: failureCode ? 1 : status,
+        signal,
+        timedOut,
+        stdout: capOutput(stdout, maxOutputBytes),
+        stderr: capOutput(stderr, maxOutputBytes),
+        pid,
+        ...cleanup,
+        failureCode,
+        error,
+      });
+    };
+    const stop = (signal: NodeJS.Signals, timeout: boolean): void => {
+      if (requestedSignal) return;
+      requestedSignal = signal;
+      timedOut = timeout;
+      operations.signalProcessTree(pid, signal);
+      const gracePeriodMs = options.termination?.gracePeriodMs ?? DEFAULT_TERMINATION.gracePeriodMs;
+      const killAfterMs = options.termination?.killAfterMs ?? DEFAULT_TERMINATION.killAfterMs;
+      escalationTimer = setTimeout(() => operations.signalProcessTree(pid, 'SIGKILL'), gracePeriodMs);
+      convergenceTimer = setTimeout(() => {
+        operations.signalProcessTree(pid, 'SIGKILL');
+        child.unref();
+        void finish(
+          1,
+          signal,
+          `child process did not converge after ${signal}`,
+          CHILD_SUPERVISOR_FAILURE_CODES.DID_NOT_CONVERGE,
+          true,
+        );
+      }, killAfterMs);
+    };
+    const onSigInt = (): void => stop('SIGINT', false);
+    const onSigTerm = (): void => stop('SIGTERM', false);
+    if (options.forwardSignals) {
+      process.once('SIGINT', onSigInt);
+      process.once('SIGTERM', onSigTerm);
+    }
+    const wallTimer = setTimeout(() => stop('SIGTERM', true), Math.max(1, options.timeoutMs));
+    wallTimer.unref?.();
+    child.once('error', (error) => { void finish(1, null, error.message); });
+    child.once('close', (code, signal) => { void finish(code ?? 1, signal); });
+  });
+}

package/src/runtime/shared/idempotent-retry.ts

@@ -0,0 +1,128 @@
+/**
+ * Bounded retries for idempotent / readonly transport failures only.
+ * Mutations must not use this without an explicit idempotency key.
+ */
+
+export type RetryableTransportStatus = 408 | 429 | 502 | 503 | 504;
+
+export interface IdempotentRetryOptions {
+  /** Max attempts including the first call. Default 2 (one retry). */
+  maxAttempts?: number;
+  /** Base backoff in ms. Default 50. */
+  baseDelayMs?: number;
+  /** Max backoff in ms. Default 500. */
+  maxDelayMs?: number;
+  /** When false, never retry. Default true. */
+  enabled?: boolean;
+  /** Optional sleep implementation (tests inject). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Optional clock (tests inject). */
+  now?: () => number;
+}
+
+export interface RetryClassification {
+  retryable: boolean;
+  reason: string;
+  status?: number;
+  code?: string;
+}
+
+const RETRYABLE_STATUSES = new Set<number>([408, 429, 502, 503, 504]);
+const RETRYABLE_CODES = /ECONNRESET|ETIMEDOUT|EAI_AGAIN|ECONNREFUSED|UND_ERR_SOCKET|FETCH_FAILED|server_busy|session_capacity|gateway_unavailable|MCP_REQUEST_FAILED/i;
+
+export function classifyTransportFailure(error: unknown, status?: number): RetryClassification {
+  if (typeof status === 'number' && RETRYABLE_STATUSES.has(status)) {
+    return {
+      retryable: true,
+      reason: `http_${status}`,
+      status,
+      code: status === 502 ? 'GATEWAY_BAD_GATEWAY' : status === 503 ? 'SERVICE_UNAVAILABLE' : `HTTP_${status}`,
+    };
+  }
+  const message = error instanceof Error ? error.message : String(error ?? '');
+  if (RETRYABLE_CODES.test(message) || /(?:\b502\b|\b503\b|\b429\b|bad gateway|temporarily unavailable)/i.test(message)) {
+    return {
+      retryable: true,
+      reason: 'transient_transport',
+      status,
+      code: 'TRANSIENT_TRANSPORT',
+    };
+  }
+  return { retryable: false, reason: 'non_retryable', status };
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retry an idempotent async operation with short exponential backoff.
+ * Only retries when classifier says retryable; never for mutation paths.
+ */
+export async function withIdempotentRetry<T>(
+  operation: () => Promise<T>,
+  options: IdempotentRetryOptions & {
+    /** Caller must declare the call is safe to retry. */
+    idempotent: boolean;
+    isRetryableResult?: (value: T) => RetryClassification | undefined;
+  },
+): Promise<T> {
+  if (!options.idempotent || options.enabled === false) {
+    return operation();
+  }
+  // Cap retries for transport noise, but honor explicit test/call-site budgets up to 5.
+  const maxAttempts = Math.max(1, Math.min(options.maxAttempts ?? 2, 5));
+  const baseDelayMs = Math.max(10, options.baseDelayMs ?? 50);
+  const maxDelayMs = Math.max(baseDelayMs, options.maxDelayMs ?? 500);
+  const sleep = options.sleep ?? defaultSleep;
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const value = await operation();
+      if (options.isRetryableResult && attempt < maxAttempts) {
+        const classification = options.isRetryableResult(value);
+        if (classification?.retryable) {
+          const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+          await sleep(delay);
+          continue;
+        }
+      }
+      return value;
+    } catch (error) {
+      lastError = error;
+      const classification = classifyTransportFailure(error);
+      if (!classification.retryable || attempt >= maxAttempts) throw error;
+      const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+      await sleep(delay);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError ?? 'retry_exhausted'));
+}
+
+/**
+ * Fetch wrapper for idempotent GET/HEAD (and POST only when caller marks idempotent).
+ * Does not retry non-idempotent methods unless `idempotent: true` is explicit.
+ */
+export async function fetchIdempotent(
+  input: string | URL,
+  init: RequestInit & { idempotent?: boolean } = {},
+  options: IdempotentRetryOptions = {},
+): Promise<Response> {
+  const method = (init.method ?? 'GET').toUpperCase();
+  const idempotent = init.idempotent === true || method === 'GET' || method === 'HEAD';
+  const { idempotent: _omit, ...fetchInit } = init;
+  return withIdempotentRetry(
+    async () => {
+      const response = await fetch(input, fetchInit);
+      if (RETRYABLE_STATUSES.has(response.status) && idempotent) {
+        // Consume body lightly so the connection can close; throw for retry.
+        try { await response.arrayBuffer(); } catch { /* ignore */ }
+        const error = new Error(`HTTP_${response.status}: transient gateway/transport failure`);
+        (error as Error & { status?: number }).status = response.status;
+        throw error;
+      }
+      return response;
+    },
+    { ...options, idempotent },
+  );
+}

package/src/runtime/shared/json-files.ts

@@ -0,0 +1,43 @@
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { randomUUID } from 'crypto';
+
+export function ensureParent(path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+}
+
+export function readJsonFile<T>(path: string, fallback?: T): T {
+  const hasFallback = arguments.length >= 2;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch (error) {
+    if (hasFallback) return fallback as T;
+    throw error;
+  }
+}
+
+export function writeJsonAtomic(path: string, value: unknown): void {
+  ensureParent(path);
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  renameSync(temporary, path);
+}
+
+export function appendJsonLine(path: string, value: unknown): void {
+  ensureParent(path);
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(path, 'a');
+    writeFileSync(descriptor, `${JSON.stringify(value)}\n`, 'utf8');
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+export function removeFile(path: string): void {
+  rmSync(path, { force: true });
+}
+
+export function sanitizeFileComponent(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'unknown';
+}