@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/control-plane/facade/handoff-inbox-application.ts

@@ -0,0 +1,158 @@
+import { getControllerSession, releaseObservedControllerSession } from '../../../../packages/kernel/controller/api/index';
+import { getWorkContract, isTerminalWorkContractStatus } from '../../../../packages/kernel/work/api/index';
+import { listSchedules } from '../../../../packages/kernel/scheduler/api/index';
+import type { HandoffItem } from './types';
+import {
+  acknowledgeHandoffItem,
+  createHandoffItem,
+  dismissHandoffItem,
+  getHandoffItem,
+  listHandoffItems,
+  resolveHandoffItem,
+  type HandoffInboxStoreOptions,
+} from './handoff-inbox-store';
+
+export type HandoffInboxApplicationOperation = 'get' | 'list' | 'ack' | 'accept' | 'resolve' | 'dismiss' | 'create';
+
+export interface HandoffInboxApplicationInput {
+  operation: HandoffInboxApplicationOperation;
+  store: HandoffInboxStoreOptions & { controllerHome: string; repoId: string };
+  handoffId?: string;
+  limit?: number;
+  workId?: string;
+  title?: string;
+  reason?: string;
+  summary?: string;
+  attemptedActions?: string[];
+  blockingDecision?: string;
+  recommendedDecision?: string;
+  recommendedPrompt?: string;
+  recommendedContinuationPrompt?: string;
+  decision?: string;
+  resolver?: string;
+  controllerIdentity?: { principalId?: string; sessionId?: string };
+}
+
+export type HandoffContinuationOccurrence = { scheduleId: string; occurrenceId?: string; status?: string };
+
+export interface HandoffInboxApplicationPorts {
+  triggerResolvedContinuation(item: ReturnType<typeof resolveHandoffItem>): Promise<HandoffContinuationOccurrence[]>;
+}
+
+export type HandoffInboxApplicationRunner = (
+  input: HandoffInboxApplicationInput,
+) => ReturnType<typeof runHandoffInboxApplication>;
+
+export interface HandoffAttentionResolver {
+  workIsTerminal(workId: string): boolean | undefined;
+  scheduleIsEnabled(scheduleId: string): boolean | undefined;
+}
+
+/**
+ * Project durable Inbox history into current attention. Unknown lifecycle state
+ * remains visible; only canonical terminal/disabled authority can suppress an
+ * old pending record. Persistence is never mutated by this projection.
+ */
+export function handoffRequiresAttention(item: HandoffItem, resolver: HandoffAttentionResolver): boolean {
+  if (item.status !== 'pending') return false;
+  const workId = item.workId?.trim();
+  if (workId && resolver.workIsTerminal(workId) === true) return false;
+
+  const scheduleId = item.currentState.taskId?.trim();
+  const scheduleFailure = item.creationReason === 'repeated_infrastructure_failure'
+    && Boolean(scheduleId)
+    && (item.id.startsWith('schedule-failure-') || item.id.startsWith('schedule-'));
+  if (scheduleFailure && scheduleId && resolver.scheduleIsEnabled(scheduleId) === false) return false;
+  return true;
+}
+
+export function listHandoffAttentionItems(
+  store: HandoffInboxStoreOptions & { controllerHome: string; repoId: string },
+  limit = 50,
+): HandoffItem[] {
+  const candidates = listHandoffItems({ ...store, status: 'pending', limit: 100 });
+  const scheduleIds = new Set(candidates
+    .filter((item) => item.creationReason === 'repeated_infrastructure_failure'
+      && (item.id.startsWith('schedule-failure-') || item.id.startsWith('schedule-')))
+    .map((item) => item.currentState.taskId?.trim())
+    .filter((value): value is string => Boolean(value)));
+  const schedules = scheduleIds.size > 0
+    ? new Map(listSchedules(store.controllerHome, store.repoId).map((schedule) => [schedule.scheduleId, schedule.enabled] as const))
+    : new Map<string, boolean>();
+  const resolver: HandoffAttentionResolver = {
+    workIsTerminal: (workId) => {
+      const work = getWorkContract(store, workId);
+      return work ? isTerminalWorkContractStatus(work.status) : undefined;
+    },
+    scheduleIsEnabled: (scheduleId) => scheduleIds.has(scheduleId)
+      ? schedules.get(scheduleId) ?? false
+      : undefined,
+  };
+  const boundedLimit = Math.max(1, Math.min(Math.trunc(limit), 100));
+  return candidates.filter((item) => handoffRequiresAttention(item, resolver)).slice(0, boundedLimit);
+}
+
+/**
+ * Canonical application boundary for Inbox behavior. MCP adapters translate
+ * arguments/results only; Handoff persistence, continuation wake-up and exact
+ * Controller ownership release remain here.
+ */
+export async function runHandoffInboxApplication(input: HandoffInboxApplicationInput, ports: HandoffInboxApplicationPorts) {
+  const { store, operation } = input;
+  if (operation === 'get') return { operation, item: getHandoffItem(store, input.handoffId ?? '') };
+  if (operation === 'list') {
+    return { operation, items: listHandoffAttentionItems(store, input.limit ?? 50) };
+  }
+  if (operation === 'ack' || operation === 'accept') {
+    return { operation, item: acknowledgeHandoffItem(store, (input.handoffId ?? '').trim()) };
+  }
+  if (operation === 'resolve') {
+    const item = resolveHandoffItem(store, (input.handoffId ?? '').trim(), {
+      decision: input.decision ?? 'resolved',
+      resolver: input.resolver ?? 'chatgpt',
+    });
+    const continuationOccurrences = item.workId ? await ports.triggerResolvedContinuation(item) : [];
+    return { operation, item, continuationOccurrences };
+  }
+  if (operation === 'dismiss') {
+    const item = dismissHandoffItem(store, (input.handoffId ?? '').trim(), {
+      decision: input.decision ?? 'dismissed',
+      resolver: input.resolver ?? 'chatgpt',
+    });
+    return { operation, item };
+  }
+
+  const id = (input.handoffId ?? `hnd-${Date.now()}`).trim();
+  const item = createHandoffItem(store, {
+    id,
+    repoId: store.repoId,
+    workId: input.workId,
+    title: input.title ?? 'Controller handoff',
+    severity: 'needs_review',
+    creationReason: 'ambiguous_outcome',
+    reason: input.reason ?? 'ChatGPT or user judgement is required before continuing.',
+    summary: input.summary ?? 'A bounded controller handoff was recorded.',
+    currentState: { repoId: store.repoId, statusSummary: 'pending decision', workId: input.workId },
+    attemptedActions: input.attemptedActions ?? [],
+    evidenceRefs: [],
+    blockingDecision: input.blockingDecision,
+    recommendedDecision: input.recommendedDecision ?? 'Decide whether to continue, repair, or stop.',
+    recommendedPrompt: input.recommendedPrompt ?? `Continue from handoff ${id}.`,
+    recommendedContinuationPrompt: input.recommendedContinuationPrompt,
+    suggestedNextActions: [],
+  });
+  let ownershipReleased = false;
+  const principalId = input.controllerIdentity?.principalId?.trim();
+  const sessionId = input.controllerIdentity?.sessionId?.trim();
+  if (item.workId && principalId && sessionId) {
+    const owner = getControllerSession(store, item.workId);
+    if (owner && owner.controllerId === principalId && owner.sessionId === sessionId) {
+      ownershipReleased = releaseObservedControllerSession(store, {
+        workId: item.workId,
+        actor: `handoff-create:${principalId}`,
+        owner,
+      }).allowed;
+    }
+  }
+  return { operation, item, ownershipReleased };
+}

package/src/runtime/control-plane/facade/handoff-inbox-store.ts

@@ -161,6 +161,16 @@ export function listHandoffItems(options: ListHandoffOptions): HandoffItem[] {
     .slice(0, limit);
 }
 
+export function countHandoffItems(options: Omit<ListHandoffOptions, 'limit' | 'detailLevel'>): number {
+  const store = readHandoffInboxStore(options);
+  const status = options.status ?? 'pending';
+  return store.items.reduce((count, item) => {
+    if (status === 'all') return count + 1;
+    if (status === 'active') return count + (isTerminalHandoffStatus(item.status) ? 0 : 1);
+    return count + (item.status === status ? 1 : 0);
+  }, 0);
+}
+
 export function summarizeHandoffItem(item: HandoffItem): HandoffItemSummary {
   return {
     id: item.id,

package/src/runtime/control-plane/facade/index.ts

@@ -1,9 +1,9 @@
 export * from './types';
 export * from './handoff-inbox-store';
-export * from './work-contract-store';
+export * from '../../../../packages/kernel/work/api/index';
 export * from './work-task-projection';
 export * from './work-continuation';
-export * from './controller-session-store';
+export * from '../../../../packages/kernel/controller/api/index';
 export * from './plan-contract-store';
 export * from './semantic-admission';
 export * from './facade-result';
@@ -17,3 +17,5 @@ export * from './self-healing-loop';
 export * from './operation-digest';
 export * from './requirement-authority';
 export * from './repository-work-admission';
+
+export * from './handoff-inbox-application';

package/src/runtime/control-plane/facade/operation-digest.ts

@@ -7,19 +7,13 @@ import {
   type ExecutionChildReference,
 } from '../../execution/jobs/child-reference';
 import type { SuggestedNextAction } from './types';
+import {
+  classifyFailureCode,
+  classifyLegacyFailureMessage,
+  type FailureClass,
+} from '../../../../packages/protocols/failure';
 
-export type UserFacingErrorClass =
-  | 'controller_unavailable'
-  | 'connector_stale'
-  | 'infrastructure_failure'
-  | 'acceptance_failure'
-  | 'invalid_check_id'
-  | 'approval_required'
-  | 'handoff_required'
-  | 'timeout'
-  | 'policy_denied'
-  | 'not_found'
-  | 'unknown_failure';
+export type UserFacingErrorClass = FailureClass;
 
 export type UserFacingPhase =
   | 'queued'
@@ -92,54 +86,24 @@ export function classifyUserFacingError(input: {
   infrastructure?: boolean;
   acceptance?: boolean;
 }): UserFacingErrorClass {
-  const code = (input.code ?? '').toLowerCase();
-  const message = (input.message ?? '').toLowerCase();
-  const blob = `${code} ${message} ${input.status ?? ''}`;
-
   if (input.infrastructure && !input.acceptance) return 'infrastructure_failure';
-  if (input.acceptance || blob.includes('acceptance') || blob.includes('valid_fail') || blob.includes('check failed') || blob.includes('] failed') || blob.includes('expected ') && blob.includes(' got ')) {
-    return 'acceptance_failure';
-  }
-  if (blob.includes('invalid_check_id') || blob.includes('check not found') || blob.includes('check_id')) {
-    if (blob.includes('invalid') || blob.includes('not found') || blob.includes('not registered')) return 'invalid_check_id';
-  }
-  if (
-    blob.includes('approval_required')
-    || blob.includes('approval required')
-    || blob.includes('requires approval')
-    || blob.includes('waiting_for_approval')
-    || blob.includes('awaiting approval')
-    || blob.includes('authorization required')
-    || blob.includes('confirm authorization')
-  ) return 'approval_required';
-  if (blob.includes('handoff') || blob.includes('needs_review') || blob.includes('human_attention')) return 'handoff_required';
-  if (blob.includes('timed_out') || blob.includes('timed out') || blob.includes('timeout')) return 'timeout';
-  if (blob.includes('stale connector') || blob.includes('tool surface') || blob.includes('fingerprint') || blob.includes('reconnect')) {
-    return 'connector_stale';
-  }
-  if (
-    blob.includes('daemon')
-    || blob.includes('controller unavailable')
-    || blob.includes('not ready')
-    || blob.includes('econnrefused')
-  ) {
-    return 'controller_unavailable';
-  }
-  if (blob.includes('denied') || blob.includes('policy') || blob.includes('forbidden') || blob.includes('not allowed')) {
-    return 'policy_denied';
-  }
-  if (
-    blob.includes('infrastructure')
-    || blob.includes('runtime_storage')
-    || blob.includes('worker')
-    || blob.includes('spawn')
-    || blob.includes('enoent')
-  ) {
-    return 'infrastructure_failure';
+  if (input.acceptance) return 'acceptance_failure';
+
+  const structured = classifyFailureCode(input.code);
+  if (structured !== 'unknown_failure') return structured;
+
+  switch ((input.status ?? '').trim().toLowerCase()) {
+    case 'waiting_for_approval': return 'approval_required';
+    case 'human_attention_required':
+    case 'needs_review': return 'handoff_required';
+    case 'timed_out': return 'timeout';
+    default: break;
   }
-  if (blob.includes('not found') || blob.includes('not_found')) return 'not_found';
-  if (!code && !message.trim()) return 'unknown_failure';
-  return 'unknown_failure';
+
+  // Compatibility-only fallback for legacy producers that still emit prose
+  // without a stable failure code. Machine retry/authorization decisions never
+  // consume this presentation classifier.
+  return classifyLegacyFailureMessage(input.message);
 }
 
 export function phaseFromJobStatus(status: ExecutionJobStatus | string): UserFacingPhase {