@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/recovery/actions.ts

@@ -0,0 +1,158 @@
+import type { RecoveryActionDescriptor } from './types';
+
+export const RECOVERY_ACTIONS = {
+  probeAgain: {
+    id: 'recovery.probe_again',
+    title: 'Run capability probe again',
+    description: 'Run the read-only recovery probe again and compare evidence.',
+    class: 'unknown',
+    risk: 'readonly',
+    confirmation: 'none',
+    localOnly: true,
+    boundedTo: [],
+  },
+  refreshRepository: {
+    id: 'recovery.refresh_repository',
+    title: 'Refresh repository metadata',
+    description: 'Refresh registered repository and checkout metadata.',
+    class: 'local_recoverable',
+    risk: 'low',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['registered_repository'],
+  },
+  rebuildProjection: {
+    id: 'recovery.rebuild_projection',
+    title: 'Rebuild runtime projection',
+    description: 'Rebuild materialized forge runtime projection from durable state.',
+    class: 'stale_runtime_state',
+    risk: 'low',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['forge_runtime_storage'],
+  },
+  reconcileJobs: {
+    id: 'recovery.reconcile_jobs',
+    title: 'Reconcile jobs and leases',
+    description: 'Run a bounded maintenance pass for stale local jobs, leases, and runtime state.',
+    class: 'local_jobs_reconciliation_required',
+    risk: 'medium',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['forge_runtime_storage'],
+  },
+  localJobsReconcile: {
+    id: 'recovery.local_jobs_reconcile',
+    title: 'Reconcile Local Jobs',
+    description: 'Terminalize stale active Local Jobs and rebuild the Local Bridge active index without using repository_command_execute.',
+    class: 'local_jobs_reconciliation_required',
+    risk: 'low',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['forge_runtime_storage', 'local_jobs_metadata'],
+  },
+  quarantineUnreadableLocalJobs: {
+    id: 'recovery.local_jobs_quarantine_unreadable',
+    title: 'Quarantine unreadable Local Jobs',
+    description: 'Move malformed or missing Local Job metadata into forge quarantine so runtime storage can continue safely.',
+    class: 'local_jobs_unreadable',
+    risk: 'low',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['forge_runtime_storage', 'local_jobs_quarantine'],
+  },
+  finalizeRuntimeStorageRelocation: {
+    id: 'recovery.runtime_storage_finalize_relocation',
+    title: 'Finalize runtime storage relocation',
+    description: 'Retry forge runtime storage binding after bounded maintenance removes local metadata blockers.',
+    class: 'runtime_storage_not_ready',
+    risk: 'low',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['forge_runtime_storage'],
+  },
+  cleanupPreview: {
+    id: 'recovery.cleanup_preview',
+    title: 'Preview runtime cleanup',
+    description: 'Preview stale forge temp dirs, terminal local jobs, and historical attention cleanup candidates.',
+    class: 'local_recoverable',
+    risk: 'readonly',
+    confirmation: 'none',
+    localOnly: true,
+    boundedTo: ['forge_runtime_storage'],
+  },
+  cleanupApply: {
+    id: 'recovery.cleanup_apply',
+    title: 'Apply runtime cleanup',
+    description: 'Apply safe forge runtime cleanup candidates after explicit authorization. Does not kill processes or touch source files.',
+    class: 'local_recoverable',
+    risk: 'medium',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['forge_runtime_storage', 'forge_temp_dirs'],
+  },
+  stageAndActivateRuntimeRelease: {
+    id: 'recovery.stage_and_activate_runtime_release',
+    title: 'Stage and activate canonical Runtime release',
+    description: 'Build one immutable Runtime release from the selected registered repository, then hand lifecycle activation to the standalone Recovery transaction.',
+    class: 'stale_runtime_state',
+    risk: 'medium',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['registered_repository', 'runtime_release_storage', 'external_runtime_lifecycle'],
+  },
+  restartPrimaryConnector: {
+    id: 'recovery.restart_primary_connector',
+    title: 'Restart primary Connector',
+    description: 'Restart only the explicitly configured primary OAuth/Connector launchd service through standalone Recovery after local Canonical Runtime verification.',
+    class: 'stale_runtime_state',
+    risk: 'medium',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['primary_connector_service', 'external_runtime_lifecycle'],
+  },
+  createPatchHandoff: {
+    id: 'recovery.create_patch_handoff',
+    title: 'Create patch handoff',
+    description: 'Create a safe patch handoff artifact when client-side tool calls are blocked.',
+    class: 'platform_blocked',
+    risk: 'medium',
+    confirmation: 'authorization',
+    localOnly: true,
+    boundedTo: ['forge_artifact_storage'],
+  },
+  workspaceAuthLoginPrepare: {
+    id: 'recovery.workspace_auth_login_prepare',
+    title: 'Prepare Workspace auth login',
+    description: 'Prepare a non-secret Gmail/Google Workspace login handoff when plugin auth is missing.',
+    class: 'auth_required',
+    risk: 'readonly',
+    confirmation: 'none',
+    localOnly: true,
+    boundedTo: ['google_workspace_auth_handoff'],
+  },
+  browserDomainAccessPreview: {
+    id: 'recovery.browser_domain_access_preview',
+    title: 'Preview browser domain grant',
+    description: 'Preview a domain-key browser grant instead of retrying arbitrary URLs.',
+    class: 'browser_domain_grant_required',
+    risk: 'readonly',
+    confirmation: 'none',
+    localOnly: true,
+    boundedTo: ['browser_allowed_domains'],
+  },
+  externalFilesystemGrantPreview: {
+    id: 'recovery.external_filesystem_grant_preview',
+    title: 'Preview external filesystem grant',
+    description: 'Preview a narrow external filesystem target grant instead of retrying absolute paths.',
+    class: 'external_filesystem_grant_required',
+    risk: 'readonly',
+    confirmation: 'none',
+    localOnly: true,
+    boundedTo: ['external_filesystem_grants'],
+  },
+} satisfies Record<string, RecoveryActionDescriptor>;
+
+export function recoveryActionById(actionId: string): RecoveryActionDescriptor | undefined {
+  return Object.values(RECOVERY_ACTIONS).find((action) => action.id === actionId);
+}

package/src/runtime/recovery/audit.ts

@@ -0,0 +1,38 @@
+import { createHash } from 'crypto';
+import type { RecoveryActionDescriptor, RecoveryAuditRecord, RecoveryEvidence } from './types';
+
+export interface BuildRecoveryAuditRecordInput {
+  actor: string;
+  action: RecoveryActionDescriptor;
+  result: RecoveryAuditRecord['result'];
+  reason: string;
+  affectedPaths?: string[];
+  evidence?: RecoveryEvidence[];
+  at?: string;
+}
+
+export function buildRecoveryAuditRecord(input: BuildRecoveryAuditRecordInput): RecoveryAuditRecord {
+  const at = input.at ?? new Date().toISOString();
+  const identity = createHash('sha256')
+    .update(JSON.stringify({ at, actor: input.actor, actionId: input.action.id, result: input.result, reason: input.reason }))
+    .digest('hex')
+    .slice(0, 16);
+  return {
+    schemaVersion: 1,
+    id: `REC-${identity}`,
+    at,
+    actor: input.actor,
+    actionId: input.action.id,
+    risk: input.action.risk,
+    confirmation: input.action.confirmation,
+    result: input.result,
+    reason: input.reason,
+    affectedPaths: input.affectedPaths ?? [],
+    evidence: input.evidence ?? [],
+  };
+}
+
+export function assertRecoveryAuthorized(action: RecoveryActionDescriptor, authorization?: string): void {
+  if (action.confirmation === 'none') return;
+  if (authorization !== action.id) throw new Error(`RECOVERY_AUTHORIZATION_REQUIRED: ${action.id} requires ${action.confirmation}`);
+}

package/src/runtime/recovery/classifier.ts

@@ -0,0 +1,163 @@
+import type { RecoveryClass } from './types';
+
+const PLATFORM_BLOCK_PATTERNS = [
+  /blocked by openai/i,
+  /safety checks/i,
+  /tool call was blocked/i,
+  /平台.*拦截/i,
+  /安全检查.*屏蔽/i,
+];
+
+const AUTH_PATTERNS = [
+  /authorizationrequired/i,
+  /oauth authorization required/i,
+  /auth_required/i,
+  /login required/i,
+  /token missing/i,
+  /token refresh/i,
+  /access[_\s-]?token/i,
+  /client id and client secret/i,
+  /re-authorization required/i,
+];
+
+const USER_ACTION_PATTERNS = [
+  /you(?:'|’)ve hit your usage limit/i,
+  /usage limit/i,
+  /upgrade to pro/i,
+  /purchase more credits/i,
+  /try again at/i,
+  /user action required/i,
+];
+
+const RUNTIME_STORAGE_PATTERNS = [
+  /runtime_storage_not_ready/i,
+  /runtime storage.*not ready/i,
+  /readyforexecution.*false/i,
+  /storage relocation/i,
+  /runtime storage can be relocated/i,
+];
+
+const LOCAL_JOBS_UNREADABLE_PATTERNS = [
+  /unreadable local jobs?/i,
+  /malformed local jobs?/i,
+  /missing.*local jobs?.*job\.json/i,
+  /local jobs?.*metadata.*unreadable/i,
+];
+
+const LOCAL_JOBS_LEGACY_ACTIVE_PATTERNS = [
+  /legacy-active/i,
+  /active or unreadable local jobs?/i,
+  /local-jobs: active/i,
+  /local jobs must finish/i,
+  /local jobs?.*finish before runtime storage/i,
+];
+
+const BROWSER_GRANT_PATTERNS = [
+  /web_target_not_allowed/i,
+  /browser.*domain.*not allowed/i,
+  /allowed_domains/i,
+  /domain access.*required/i,
+  /browser domain grant/i,
+];
+
+const EXTERNAL_FILESYSTEM_GRANT_PATTERNS = [
+  /external filesystem/i,
+  /external_fs/i,
+  /external_filesystem_grant_required/i,
+  /target grant/i,
+  /selected_path_scope_denied/i,
+  /absolute paths are not allowed/i,
+  /path.*escapes.*repository/i,
+  /outside.*allowed_paths/i,
+  /outside.*repository/i,
+];
+
+const DIRTY_WORKTREE_CONFLICT_PATTERNS = [
+  /edit operations? failed precondition checks?/i,
+  /failed precondition checks?/i,
+  /dirty worktree/i,
+  /dirty paths?/i,
+  /would overwrite.*local changes/i,
+  /integration.*conflict/i,
+];
+
+const POLICY_PATTERNS = [
+  /policy denied/i,
+  /policy_denied/i,
+  /not allowed/i,
+  /forbidden by policy/i,
+  /confirmation required/i,
+  /denied/i,
+];
+
+const AGENT_RUNTIME_PATTERNS = [
+  /transport channel closed/i,
+  /worker quit/i,
+  /failed to initialize mcp/i,
+  /timeout waiting for child process/i,
+  /mcp startup failed/i,
+  /controller process \d+ is no longer running/i,
+  /response payload is not completed/i,
+  /contentlengtherror/i,
+  /not enough data to satisfy content length header/i,
+];
+
+const SUPERVISOR_PROBE_TIMEOUT_PATTERNS = [
+  /probe_timeout/i,
+  /supervisor.*(?:health|gateway).*timeout/i,
+  /operation was aborted/i,
+  /AbortError/i,
+];
+
+const SOURCE_DEFECT_PATTERNS = [
+  /typeerror/i,
+  /referenceerror/i,
+  /cannot read properties/i,
+  /assertion failed/i,
+  /identity mismatch/i,
+];
+
+export function classifyFailure(message: string | undefined): RecoveryClass {
+  const text = message ?? '';
+  if (!text.trim()) return 'unknown';
+  if (PLATFORM_BLOCK_PATTERNS.some((pattern) => pattern.test(text))) return 'platform_blocked';
+  if (LOCAL_JOBS_LEGACY_ACTIVE_PATTERNS.some((pattern) => pattern.test(text))) return 'local_jobs_legacy_active';
+  if (LOCAL_JOBS_UNREADABLE_PATTERNS.some((pattern) => pattern.test(text))) return 'local_jobs_unreadable';
+  if (RUNTIME_STORAGE_PATTERNS.some((pattern) => pattern.test(text))) return 'runtime_storage_not_ready';
+  if (AUTH_PATTERNS.some((pattern) => pattern.test(text))) return 'auth_required';
+  if (BROWSER_GRANT_PATTERNS.some((pattern) => pattern.test(text))) return 'browser_domain_grant_required';
+  if (EXTERNAL_FILESYSTEM_GRANT_PATTERNS.some((pattern) => pattern.test(text))) return 'external_filesystem_grant_required';
+  if (DIRTY_WORKTREE_CONFLICT_PATTERNS.some((pattern) => pattern.test(text))) return 'dirty_worktree_conflict';
+  if (USER_ACTION_PATTERNS.some((pattern) => pattern.test(text))) return 'user_action_required';
+  if (POLICY_PATTERNS.some((pattern) => pattern.test(text))) return 'policy_denied';
+  if (SUPERVISOR_PROBE_TIMEOUT_PATTERNS.some((pattern) => pattern.test(text))) return 'transient_probe_timeout';
+  if (AGENT_RUNTIME_PATTERNS.some((pattern) => pattern.test(text))) return 'agent_runtime_failure';
+  if (SOURCE_DEFECT_PATTERNS.some((pattern) => pattern.test(text))) return 'source_defect_suspected';
+  return 'unknown';
+}
+
+export function dominantRecoveryClass(classes: readonly RecoveryClass[]): RecoveryClass {
+  for (const value of [
+    'platform_blocked',
+    'auth_required',
+    'dirty_worktree_conflict',
+    'local_jobs_legacy_active',
+    'local_jobs_unreadable',
+    'runtime_storage_not_ready',
+    'browser_domain_grant_required',
+    'external_filesystem_grant_required',
+    'local_jobs_reconciliation_required',
+    'maintenance_executor_required',
+    'policy_denied',
+    'source_defect_suspected',
+    'stale_runtime_state',
+    'transient_probe_timeout',
+    'local_recoverable',
+    'agent_runtime_failure',
+    'plugin_configuration_error',
+    'user_action_required',
+  ] as const) {
+    if (classes.includes(value)) return value;
+  }
+  return 'unknown';
+}

package/src/runtime/recovery/index.ts

@@ -0,0 +1,9 @@
+export * from './actions';
+export * from './audit';
+export * from './classifier';
+export * from './patch-handoff';
+export * from './probe';
+export * from './types';
+export * from './store';
+export * from './maintenance-executor';
+export * from './local-jobs-repair';