@moretea-labs/forge 1.8.0 → 1.8.2

package/adapters/mcp/runtime-gateway/runtime-observation-adapter.ts

@@ -2,10 +2,11 @@ import { existsSync } from 'fs';
 import { collectRuntimePerformanceDiagnostics, inferLocalControllerProcess } from '../../../src/runtime/diagnostics/performance';
 import type { McpToolDefinition, CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
 import type { MultiRepositoryMcpToolContext } from '../multi-repository';
-import { allControllerToolDefinitions, controllerExposureSnapshot, controllerToolSurfaceStatus } from '../toolset';
+import { controllerExposureSnapshot, controllerToolSurfaceStatus } from '../toolset';
 import { boundedPluginArtifactImageContent, jsonPreview, result, resultWithPluginArtifactImages } from './result-adapter';
 import { expectedRevision, repositoryRootForRepoId, selected, stringList } from './shared-adapter';
-import { ageMs, callStatusInboxAdapter, controllerReadinessEvidence, GIT_IDENTITY_SAMPLE_TTL_MS, localControllerDiagnosticMatchesRuntime, probeLocalControllerHealth, runtimeSourceSnapshotStatus, summarizeInvalidActiveWorkCandidate, summarizeWorkListItem, type ControllerReadinessSignals } from './status-inbox-adapter';
+import { callStatusInboxAdapter, GIT_IDENTITY_SAMPLE_TTL_MS, summarizeInvalidActiveWorkCandidate, summarizeWorkListItem } from './status-inbox-adapter';
+import { ageMs, controllerReadinessEvidence, localControllerDiagnosticMatchesRuntime, probeLocalControllerHealth, runtimeSourceSnapshotStatus, type ControllerReadinessSignals } from './runtime-readiness-observation';
 import { listRepositories, repositorySummary, resolveRepositorySelection } from '../../../src/cli/repositories/registry';
 import { repositoryControllerRoot } from '../../../src/cli/repositories/controller-home';
 import { cancelExecutionJob, findExecutionJob, getExecutionJob, getExecutionJobByRequestId, listExecutionJobs } from '../../../src/runtime/execution/jobs/store';
@@ -26,15 +27,13 @@ import {
   type GradedObservation,
 } from '../../../src/runtime/health';
 import { ensureRepositoryRuntimeStorage } from '../../../src/cli/repositories/runtime-storage';
-import { assessWorkMode, parseExplicitTaskMode } from '../../../src/cli/controller/work-mode';
 import { projectBoard } from '../../../src/cli/controller/issue-store';
 import { buildControllerTaskLedgerProjection } from '../../../src/cli/controller/task-ledger';
-import { buildControllerContextPack, buildControllerContextPackAsync, CONTROLLER_CONTEXT_IMPACT_DOMAINS, type ControllerContextImpactDomain } from '../../../src/cli/controller/context-pack';
+import { CONTROLLER_CONTEXT_IMPACT_DOMAINS, type ControllerContextImpactDomain } from '../../../src/cli/controller/context/types';
 import { legacyIssueAuthorityRetired } from '../../../src/cli/controller/legacy-issue-cutover';
 import { buildControllerOperationalPlan } from '../../../src/cli/controller/operational-plan';
 import { listControllerChecks, readLatestControllerCheckEvidence } from '../../../src/cli/controller/check-runner';
 import { listActiveAgentJobSnapshots } from '../../../src/cli/agent-jobs/job-manager';
-import type { TaskRisk } from '../../../src/cli/controller/types';
 import {
   controllerContextPerformanceSnapshot,
   controllerContextProjectionAgeMs,
@@ -191,30 +190,6 @@ function summarizeRuntimeProjectionForReadiness<T extends { currentAttention?: u
  */
 
 
-function controllerContextAssessment(args: Record<string, unknown>) {
-  const description = typeof args.description === 'string' && args.description.trim()
-    ? args.description
-    : 'Inspect the selected repository context.';
-  return assessWorkMode({
-    description,
-    knownPaths: stringList(args.known_paths),
-    expectedFiles: typeof args.expected_files === 'number' ? args.expected_files : undefined,
-    expectedChangedLines: typeof args.expected_changed_lines === 'number' ? args.expected_changed_lines : undefined,
-    requiresInvestigation: args.requires_investigation === true,
-    requiresParallelism: args.requires_parallelism === true,
-    requiresLongRunningChecks: args.requires_long_running_checks === true,
-    needsDependencies: args.needs_dependencies === true,
-    requiresIndependentDeliverables: args.requires_independent_deliverables === true,
-    independentTaskCount: typeof args.independent_task_count === 'number' ? args.independent_task_count : undefined,
-    requiresRemoteWrite: args.requires_remote_write === true || args.remote_write === true,
-    requiresRecovery: args.requires_recovery === true,
-    agentRequested: args.agent_requested === true || args.requires_worker === true,
-    requiresWorkerIsolation: args.requires_worker_isolation === true,
-    risk: typeof args.risk === 'string' ? args.risk as TaskRisk : undefined,
-    explicitMode: parseExplicitTaskMode(args.mode) ?? (typeof args.description === 'string' && args.description.trim() ? undefined : 'direct'),
-  });
-}
-
 function compactContextTask(value: unknown): Record<string, unknown> {
   const task = contextRecord(value);
   return {
@@ -247,7 +222,6 @@ function compactControllerContextSummaryPayload(payload: Record<string, unknown>
   const activeRuns = Array.isArray(payload.activeRuns) ? payload.activeRuns : [];
   const attention = Array.isArray(ledger.attention) ? ledger.attention : [];
   const readyTasks = Array.isArray(ledger.readyTasks) ? ledger.readyTasks : [];
-  const recommendedExecution = contextRecord(payload.recommendedExecution);
   const runtimeIdentity = contextRecord(payload.runtimeIdentity);
   const runtime = contextRecord(payload.runtime);
   const repoId = String(payload.repoId ?? repository.repoId ?? '');
@@ -317,8 +291,6 @@ function compactControllerContextSummaryPayload(payload: Record<string, unknown>
     attention: attention.slice(0, 5).map(compactContextTask),
     readyTasks: readyTasks.slice(0, 5).map(compactContextTask),
     execution: {
-      recommendedMode: recommendedExecution.mode ?? recommendedExecution.recommendedMode ?? null,
-      executionPath: recommendedExecution.executionPath ?? recommendedExecution.path ?? null,
       requiredChecks: recommendedCheckIds,
     },
     runtime: {
@@ -388,7 +360,6 @@ function compactControllerContextSummaryPayload(payload: Record<string, unknown>
       const localBridge = contextRecord(payload.localBridge);
       return { reconciliation: localBridge.reconciliation };
     })(),
-    recommendedExecution: recommendedExecution,
     ...(payload.repository ? { repositorySummary: repository } : {}),
   };
   if (ready.health || ready.ready !== undefined) {
@@ -698,19 +669,6 @@ export async function callRuntimeObservationAdapter(ctx: MultiRepositoryMcpToolC
               };
               const repositoryStartedAt = performance.now();
               const repository = selected(ctx, args);
-              const recommendedExecution = controllerContextAssessment(args);
-              const modeContextPack = recommendedExecution.modeBehavior.structuralContext === 'required'
-                ? buildControllerContextPack(repository.canonicalRoot, ctx.policy, {
-                    description: typeof args.description === 'string' ? args.description : undefined,
-                    knownPaths: stringList(args.known_paths),
-                    structuralContext: 'required',
-                    maxFiles: 8,
-                    maxSnippets: 20,
-                    session: ctx.sessionId?.trim()
-                      ? { sessionId: ctx.sessionId.trim(), repoId: repository.repoId, checkoutId: repository.activeCheckoutId }
-                      : undefined,
-                  })
-                : undefined;
               markPhase('repositoryRouting', repositoryStartedAt);
               const variant = args.detail_level === 'detail' ? 'detail' as const : 'summary' as const;
               const runtimeRoot = repositoryControllerRoot(ctx.controllerHome, repository.repoId);
@@ -816,19 +774,11 @@ export async function callRuntimeObservationAdapter(ctx: MultiRepositoryMcpToolC
                 projectionRecord: typeof cached,
                 input: { cacheHit: boolean; stale: boolean; refreshJobId?: string },
               ): CallToolResult => {
-                const { modeContextPack: _cachedModeContextPack, ...basePayload } = payload;
-                const taskScopedPayload = {
-                  ...basePayload,
-                  ...(basePayload.detailLevel === 'summary' ? {
-                    execution: {
-                      ...contextRecord(basePayload.execution),
-                      recommendedMode: recommendedExecution.recommendedMode,
-                      executionPath: recommendedExecution.executionPath,
-                    },
-                  } : {}),
-                  recommendedExecution,
-                  ...(modeContextPack ? { modeContextPack } : {}),
-                };
+                const {
+                  modeContextPack: _legacyModeContextPack,
+                  recommendedExecution: _legacyRecommendedExecution,
+                  ...taskScopedPayload
+                } = payload;
                 if (!controllerContextProjectionPayloadMatchesSourceIdentity(taskScopedPayload, sourceIdentity)) {
                   const response = withRuntimeResponseMeta({
                     error: {
@@ -992,8 +942,6 @@ export async function callRuntimeObservationAdapter(ctx: MultiRepositoryMcpToolC
                   repoId: repository.repoId,
                   repository: repositorySummary(repository),
                   runtimeStorage,
-                  recommendedExecution,
-                  ...(modeContextPack ? { modeContextPack } : {}),
                   runtimeProjection,
                   runtimeProjectionState: {
                     stale: runtimeSnapshot.stale,
@@ -1093,14 +1041,15 @@ export async function callRuntimeObservationAdapter(ctx: MultiRepositoryMcpToolC
                   ? 'Raw job state is intentionally not returned through MCP. Use the bounded job summary, events, and get_artifact with artifactId (ART-...), not evidenceId (EVD-...).'
                   : jobSummary.terminal
                     ? String(jobSummary.summary ?? '')
-                    : 'Historical Job is still active. Continue independent work; read it only if an observation can change the next decision, and use work_wait only when this exact result becomes a dependency. Do not periodically poll.',
+                    : 'Historical Job is still active. Continue independent work; read it only if an observation can change the next decision, and join only the exact underlying managed process when this result becomes a dependency. Do not periodically poll.',
               }, jobSummary.phase === 'failed' || jobSummary.phase === 'timed_out');
             }
       case 'get_artifact': {
               const artifactId = String(args.artifact_id ?? '').trim();
-              const artifactRepoId = String(args.repo_id ?? '').trim();
+              const legacyArtifactRepoId = String(args.repo_id ?? '').trim() || undefined;
+              const artifactPrincipalId = ctx.principalId?.trim() || '__anonymous__';
               if (artifactId.startsWith('EVD-')) {
-                const evidence = readExecutionEvidence(ctx.controllerHome, artifactRepoId, artifactId);
+                const evidence = readExecutionEvidence(ctx.controllerHome, artifactId, { legacyRepoId: legacyArtifactRepoId, principalId: artifactPrincipalId });
                 return result({
                   referenceType: 'evidence',
                   evidenceId: evidence.evidenceId,
@@ -1121,11 +1070,11 @@ export async function callRuntimeObservationAdapter(ctx: MultiRepositoryMcpToolC
                     message: `Expected artifactId starting with ART- (got ${artifactId.slice(0, 40)}). evidenceId (EVD-...) is audit metadata; use get_job artifactRefs for content.`,
                   },
                   referenceType: 'unknown',
-                  next: 'Call get_job, read artifactRefs[].artifactId (ART-...), then get_artifact with that id and repo_id.',
+                  next: 'Call get_job, read artifactRefs[].artifactId (ART-...), then get_artifact with that id. repo_id is only a legacy adoption hint.',
                 }, true);
               }
               const maxBytes = typeof args.max_bytes === 'number' ? args.max_bytes : 64 * 1024;
-              const loaded = readExecutionArtifact(ctx.controllerHome, artifactRepoId, artifactId, maxBytes);
+              const loaded = readExecutionArtifact(ctx.controllerHome, artifactId, maxBytes, { legacyRepoId: legacyArtifactRepoId, principalId: artifactPrincipalId });
               // Do not re-attach controller/repository/runtime envelopes here; multi-repo layer already compact.
               return result({
                 referenceType: 'artifact',

package/adapters/mcp/runtime-gateway/runtime-readiness-observation.ts

@@ -0,0 +1,218 @@
+import type { MultiRepositoryMcpToolContext } from "../multi-repository";
+import { reconcileReadinessProjectionSource } from "../readiness-projection";
+import { listExecutionJobs } from "../../../src/runtime/execution/jobs/store";
+import { readForgeRuntimeStatus } from "../../../src/runtime/control-plane/runtime-status-client";
+import { readSchedulerHealthSnapshot } from "../../../src/runtime/control-plane/global-scheduler/scheduler";
+import { evaluateActiveRuntimeSourceDrift, type RuntimeSourceIdentity } from "../../../src/runtime/control-plane/runtime-generation";
+import { projectionObservation, readRepositoryProjectionSnapshot } from "../../../src/runtime/projections/materialized-view";
+import { buildRuntimeOperationalView, classifyRuntimeReadinessSemantics, evaluateRuntimeHealth, RUNTIME_HEALTH_THRESHOLDS, type RuntimeOperationalView, type GradedObservation } from "../../../src/runtime/health";
+import { buildControllerTaskLedgerProjection } from "../../../src/cli/controller/task-ledger";
+import { legacyIssueAuthorityRetired } from "../../../src/cli/controller/legacy-issue-cutover";
+import { FORGE_MCP_SCHEMA_VERSION, FORGE_TOOL_SURFACE, FORGE_VERSION } from "../../../src/cli/controller/runtime-config";
+import { resolveLocalBridgeSurface } from "../../../src/runtime/shared/local-bridge-surface";
+import { listHandoffItems } from "../../../src/runtime/control-plane/facade";
+
+export function ageMs(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? Math.max(0, Date.now() - parsed) : undefined;
+}
+
+export async function probeLocalControllerHealth(endpoint: string | undefined): Promise<Record<string, unknown> | null> {
+  if (!endpoint) return null;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1_500);
+  try {
+    const url = new URL(endpoint);
+    url.pathname = '/health';
+    url.search = '';
+    url.hash = '';
+    const response = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } });
+    if (!response.ok) return null;
+    return await response.json() as Record<string, unknown>;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function localControllerDiagnosticMatchesRuntime(
+  payload: Record<string, unknown> | null,
+  expected: { generation?: string } = {},
+): boolean {
+  return payload?.status === 'ok'
+    && payload.toolSurface === FORGE_TOOL_SURFACE
+    && payload.schemaVersion === FORGE_MCP_SCHEMA_VERSION
+    && payload.version === FORGE_VERSION
+    && (expected.generation === undefined || payload.generation === expected.generation);
+}
+
+export interface ControllerReadinessSignals {
+  externalEndpoint?: GradedObservation;
+  mcpHandshake?: GradedObservation;
+  sessionContinuity?: GradedObservation;
+}
+
+export async function controllerReadinessEvidence(
+  ctx: MultiRepositoryMcpToolContext,
+  repository = ctx.explicitRepository,
+  signals: ControllerReadinessSignals = {},
+) {
+  const daemon = readForgeRuntimeStatus(ctx.controllerHome);
+  const scheduler = readSchedulerHealthSnapshot(ctx.controllerHome);
+  const projectionSnapshot = repository ? readRepositoryProjectionSnapshot(ctx.controllerHome, repository.repoId) : undefined;
+  const projection = projectionSnapshot?.projection;
+  const taskLedger = repository && !legacyIssueAuthorityRetired(repository.canonicalRoot)
+    ? buildControllerTaskLedgerProjection(repository.canonicalRoot)
+    : undefined;
+  const projectionReconciliation = projectionSnapshot
+    ? reconcileReadinessProjectionSource(projectionSnapshot, taskLedger)
+    : undefined;
+  const localBridgeSurface = repository
+    ? resolveLocalBridgeSurface({
+      controllerHome: ctx.controllerHome,
+      repoRoot: repository.canonicalRoot,
+      allowProcessScan: false,
+    })
+    : undefined;
+  const localBridgeEndpoint = localBridgeSurface?.endpoint;
+  const shouldProbeLocalBridge = Boolean(
+    localBridgeSurface?.enabled
+    && localBridgeSurface.endpointConfigured
+    && localBridgeEndpoint
+    && localBridgeSurface.mode !== 'disabled',
+  );
+  const localBridgeLiveHealth = shouldProbeLocalBridge
+    ? await probeLocalControllerHealth(localBridgeEndpoint)
+    : null;
+  const localBridgeEndpointReachable = localBridgeLiveHealth !== null;
+  const localBridgeExpectedSurface = shouldProbeLocalBridge
+    ? localControllerDiagnosticMatchesRuntime(localBridgeLiveHealth, {
+      generation: localBridgeSurface?.generation,
+    })
+    : true;
+  const schedulerHeartbeatAgeMs = ageMs(scheduler.lastTickAt);
+  const dispatchHeartbeatAgeMs = ageMs(scheduler.lastDispatchAt);
+  const localBridgeObservation = {
+    enabled: localBridgeSurface?.enabled ?? false,
+    requiredForReadiness: localBridgeSurface?.requiredForReadiness ?? false,
+    mode: localBridgeSurface?.mode ?? ('disabled' as const),
+    endpoint: localBridgeEndpoint,
+    endpointReachable: shouldProbeLocalBridge ? localBridgeEndpointReachable : true,
+    expectedSurface: localBridgeExpectedSurface,
+    processAlive: localBridgeSurface?.processRunning,
+    runtimeStateFresh: localBridgeSurface?.source === 'service-runtime'
+      || localBridgeSurface?.source === 'repo-runtime',
+    error: localBridgeSurface?.error,
+  };
+  const runtimeHealth = evaluateRuntimeHealth({
+    daemon: {
+      status: daemon.status,
+      error: daemon.error,
+      // Scheduler ticks are emitted by the Canonical Forge Runtime process and provide
+      // its continuously refreshed heartbeat without introducing a second timer.
+      heartbeatAgeMs: schedulerHeartbeatAgeMs,
+    },
+    scheduler: {
+      status: daemon.degraded ? 'degraded' : daemon.status,
+      heartbeatAgeMs: schedulerHeartbeatAgeMs,
+      dispatchHeartbeatAgeMs,
+    },
+    workers: {
+      queueDepth: projection?.queueDepth,
+      runningWorkers: projection?.runningWorkers,
+      activeLeases: projection?.activeLeases,
+      activeAttentionCount: projection?.currentAttention.length,
+    },
+    projection: projectionSnapshot ? projectionObservation(projectionSnapshot, projectionReconciliation) : {
+      readable: true,
+      persisted: true,
+    },
+    localBridge: localBridgeObservation,
+    runtimeStorage: { readable: true, ready: true },
+    ...signals,
+  });
+  const operationalView: RuntimeOperationalView = buildRuntimeOperationalView({
+    health: runtimeHealth,
+    handoffs: repository
+      ? listHandoffItems({ controllerHome: ctx.controllerHome, repoId: repository.repoId, status: 'all', limit: 100 })
+      : [],
+    jobs: repository ? listExecutionJobs(ctx.controllerHome, repository.repoId, 100) : [],
+  });
+  const reasons: Array<{ code: string; message: string }> = runtimeHealth.activeBlockers.map((item) => ({
+    code: item.code === 'SCHEDULER_NOT_PROGRESSING'
+      ? 'DISPATCH_LOOP_STALLED'
+      : item.code === 'LEASE_WITHOUT_WORKER' || item.code === 'WORKER_NOT_RUNNING'
+        ? 'WORKER_NOT_RUNNING'
+        : item.code,
+    message: item.message,
+  }));
+  if (
+    reasons.some((item) => item.code === 'WORKER_NOT_RUNNING')
+    && (dispatchHeartbeatAgeMs === undefined || dispatchHeartbeatAgeMs > RUNTIME_HEALTH_THRESHOLDS.queueProgressStaleMs)
+  ) {
+    reasons.push({
+      code: 'QUEUE_NOT_PROGRESSING',
+      message: 'Queued Jobs have not received a recent dispatch heartbeat.',
+    });
+  }
+  const ready = runtimeHealth.ready;
+  return {
+    ready,
+    state: ready ? runtimeHealth.state === 'healthy' ? 'ready' as const : 'degraded' as const : daemon.status === 'ready' ? 'degraded' as const : 'not_ready' as const,
+    reasons,
+    warnings: runtimeHealth.warnings.map((item) => ({ code: item.code, message: item.message })),
+    health: runtimeHealth,
+    operationalView,
+    daemon,
+    durableScheduler: {
+      status: runtimeHealth.components.scheduler.ready ? 'ready' : daemon.status === 'ready' ? 'degraded' : 'not_ready',
+      loopStartedAt: scheduler.loopStartedAt,
+      lastTickAt: scheduler.lastTickAt,
+      lastDispatchAt: scheduler.lastDispatchAt,
+      lastReconcileAt: scheduler.lastReconcileAt,
+      heartbeatAgeMs: schedulerHeartbeatAgeMs,
+      dispatchHeartbeatAgeMs,
+    },
+    workerLoop: {
+      status: projection?.runningWorkers ? 'running' : projection?.queueDepth ? 'idle' : 'ready',
+      queueDepth: projection?.queueDepth ?? 0,
+      runningWorkers: projection?.runningWorkers ?? 0,
+      activeLeases: projection?.activeLeases ?? 0,
+      activeAttentionCount: projection?.currentAttention.length ?? 0,
+      consuming: (projection?.queueDepth ?? 0) === 0 || (projection?.runningWorkers ?? 0) > 0,
+    },
+    localBridge: repository ? {
+      running: Boolean(localBridgeSurface?.enabled)
+        && runtimeHealth.components.localBridge.ready
+        && (!shouldProbeLocalBridge || (localBridgeEndpointReachable && localBridgeExpectedSurface)),
+      endpoint: localBridgeEndpoint,
+      error: localBridgeSurface?.error,
+      inferredPid: localBridgeSurface?.pid,
+      statusSource: localBridgeSurface?.source ?? 'none',
+      health: runtimeHealth.components.localBridge,
+    } : undefined,
+    projection,
+    projectionSnapshot,
+    taskLedger,
+    projectionReconciliation,
+    semantics: classifyRuntimeReadinessSemantics(runtimeHealth),
+  };
+}
+
+export function runtimeSourceSnapshotStatus(
+  active: RuntimeSourceIdentity | undefined,
+  currentRuntimeRoot?: string,
+) {
+  const drift = evaluateActiveRuntimeSourceDrift(active, {
+    currentRuntimeRoot,
+  });
+  return {
+    current: drift.current,
+    restartRequired: drift.restartRequired,
+    reasons: drift.reasons,
+    code: drift.code,
+  };
+}
+