@moretea-labs/forge 1.8.0 → 1.8.1

package/adapters/mcp/runtime-gateway/automation-receipt-adapter.ts

@@ -0,0 +1,87 @@
+import type { CallToolResult, McpToolDefinition } from '../../../packages/protocols/mcp/tool-contract';
+import { getWorkflowSupervisorTask, recordWorkflowSupervisorAutomationReceipt } from '../../../supervisor/client';
+import { resolveWorkflowSupervisorForgeHome } from '../../../supervisor/paths';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+
+type AutomationStatus = 'working' | 'continue' | 'done' | 'needs_user';
+
+export const AUTOMATION_RECEIPT_CAPABILITY_PREFIX = 'automation.receipt:';
+
+const AUTOMATION_TOOL_PROPERTIES: Record<string, unknown> = {
+  automation_task_id: { type: 'string', description: 'Required with autonomous_continuation metadata; identifies the already-bound Workflow Supervisor task.' },
+  automation_type: { type: 'string', enum: ['autonomous_continuation'], description: 'Required on every Forge call made by a Supervisor-controlled autonomous ChatGPT turn.' },
+  automation_status: { type: 'string', enum: ['working', 'continue', 'done', 'needs_user'], description: 'Use working on intermediate calls; the final autonomous call records continue, done, or needs_user.' },
+};
+
+export function injectAutomationEnvelopeFields(definition: McpToolDefinition): McpToolDefinition {
+  const schema = definition.inputSchema as {
+    type?: unknown;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  if (!schema || schema.type !== 'object') return definition;
+  return {
+    ...definition,
+    inputSchema: {
+      ...schema,
+      properties: { ...(schema.properties ?? {}), ...AUTOMATION_TOOL_PROPERTIES },
+    },
+  };
+}
+
+function compatibilityAutomationMetadata(args: Record<string, unknown>): { status: AutomationStatus; taskId: string } | undefined {
+  const capabilityId = typeof args.capability_id === 'string' ? args.capability_id.trim() : '';
+  if (!capabilityId.startsWith(AUTOMATION_RECEIPT_CAPABILITY_PREFIX)) return undefined;
+  const payload = capabilityId.slice(AUTOMATION_RECEIPT_CAPABILITY_PREFIX.length);
+  const separator = payload.indexOf(':');
+  if (separator <= 0) throw new Error('AUTOMATION_RECEIPT_CAPABILITY_INVALID');
+  const status = payload.slice(0, separator);
+  const taskId = payload.slice(separator + 1).trim();
+  if (!['working', 'continue', 'done', 'needs_user'].includes(status)) throw new Error('AUTOMATION_STATUS_INVALID');
+  if (!taskId) throw new Error('AUTOMATION_TASK_ID_REQUIRED');
+  return { status: status as AutomationStatus, taskId };
+}
+
+export function isAutomationReceiptCompatibilityCall(args: Record<string, unknown>): boolean {
+  return typeof args.capability_id === 'string' && args.capability_id.trim().startsWith(AUTOMATION_RECEIPT_CAPABILITY_PREFIX);
+}
+
+export function automationReceiptControllerTypeAllowed(controllerType: MultiRepositoryMcpToolContext['controllerType']): boolean {
+  return controllerType === undefined || controllerType === 'chatgpt';
+}
+
+export function automationMetadata(args: Record<string, unknown>): { status: AutomationStatus; taskId: string } | undefined {
+  const type = args.automation_type;
+  const status = args.automation_status;
+  if (type === undefined && status === undefined) return compatibilityAutomationMetadata(args);
+  if (type !== 'autonomous_continuation') throw new Error('AUTOMATION_TYPE_INVALID');
+  if (typeof status !== 'string' || !['working', 'continue', 'done', 'needs_user'].includes(status)) throw new Error('AUTOMATION_STATUS_INVALID');
+  const taskId = typeof args.automation_task_id === 'string' ? args.automation_task_id.trim() : '';
+  if (!taskId) throw new Error('AUTOMATION_TASK_ID_REQUIRED');
+  return { status: status as AutomationStatus, taskId };
+}
+
+export async function persistAutomationReceipt(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  metadata: { status: AutomationStatus; taskId: string } | undefined,
+  outcome: CallToolResult | undefined,
+): Promise<void> {
+  if (!metadata || outcome?.isError) return;
+  // Some frozen ChatGPT connector transports predate request-scoped controllerType.
+  // An explicit non-ChatGPT identity is authoritative and must fail closed, but an
+  // absent compatibility field must not override the stronger Supervisor authority
+  // below: exact task, bound conversation, and latest applied causal effect.
+  if (!automationReceiptControllerTypeAllowed(ctx.controllerType)) {
+    throw new Error('AUTOMATION_CONTROLLER_TYPE_INVALID');
+  }
+  const forgeHome = resolveWorkflowSupervisorForgeHome(ctx.controllerHome);
+  const task = await getWorkflowSupervisorTask(forgeHome, metadata.taskId);
+  if (!task) throw new Error('AUTOMATION_SUPERVISOR_TASK_REQUIRED: Copy the complete task id from the current Supervisor prompt, including its suffix, and retry the receipt. Do not create a replacement task.');
+  await recordWorkflowSupervisorAutomationReceipt(forgeHome, {
+    taskId: task.taskId,
+    conversationId: task.conversationId,
+    status: metadata.status,
+    receiptId: `${task.taskId}:${name}:${metadata.status}`,
+  });
+}

package/adapters/mcp/runtime-gateway/bounded-result-runtime.ts

@@ -0,0 +1,62 @@
+import { currentControllerInstanceId, startExecutionSession } from '../../../src/runtime/control-plane/execution/session-store';
+import { writeControllerResult } from '../../../src/runtime/evidence/result-store';
+
+const MAX_INLINE_DIRECT_RESULT_BYTES = 64 * 1024;
+
+export interface BoundedRuntimeResultScope {
+  controllerHome: string;
+  repoId?: string;
+  sessionId?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+  workId?: string;
+}
+
+/**
+ * Mechanical transport bounding for runtime-aware MCP adapters. Large values
+ * are persisted through the existing Result Store; no lifecycle or semantic
+ * completion authority is introduced here.
+ */
+export function boundedRuntimeResult(
+  scope: BoundedRuntimeResultScope,
+  value: unknown,
+): { value: unknown; externalized: boolean } {
+  const serialized = JSON.stringify(value, null, 2);
+  if (typeof serialized !== 'string' || Buffer.byteLength(serialized, 'utf8') <= MAX_INLINE_DIRECT_RESULT_BYTES) {
+    return { value, externalized: false };
+  }
+  const controllerInstanceId = scope.controllerInstanceId?.trim() || currentControllerInstanceId();
+  const principalId = scope.principalId?.trim() || `controller-issued:${controllerInstanceId}`;
+  const session = startExecutionSession(scope.controllerHome, {
+    sessionId: scope.sessionId?.trim() || undefined,
+    principalId,
+    controllerInstanceId,
+    capabilitySnapshotVersion: 1,
+  });
+  const stored = writeControllerResult({
+    controllerHome: scope.controllerHome,
+    repoId: scope.repoId,
+    sessionId: session.sessionId,
+    principalId: session.principalId,
+    workId: scope.workId,
+    kind: 'generic',
+    value,
+  });
+  return {
+    externalized: true,
+    value: {
+      externalized: true,
+      truncated: true,
+      byteLength: stored.byteLength,
+      resultRef: stored.resultRef,
+      resultId: stored.resultId,
+      sessionId: session.sessionId,
+      preview: serialized.slice(0, 4_096),
+      detailPointer: {
+        tool: 'result_read',
+        arguments: { session_id: session.sessionId, result_ref: stored.resultRef, limit: 16 },
+      },
+      next: 'Use result_read or result_search with this session_id/result_ref for additional bounded detail.',
+    },
+  };
+}

package/adapters/mcp/runtime-gateway/cognition-settlement.ts

@@ -0,0 +1,201 @@
+import type { CallToolResult, McpToolDefinition } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { parseControllerLearningSignalDrafts, CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS } from '../../../src/runtime/context/automatic-learning';
+import {
+  persistDirectControllerLearning,
+  recordDirectControllerLearningFeedback,
+  type DirectControllerLearningFeedbackDraft,
+} from '../../../src/runtime/context/direct-controller-learning';
+import { selected } from './shared-adapter';
+
+export const COGNITION_SETTLEMENT_PROPERTY = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    work_id: {
+      type: 'string',
+      description: 'Optional selected Work. Forge derives reachable Work/Requirement/Project/Workspace scope and provenance; this is not caller-authored authority.',
+    },
+    learning_signals: {
+      type: 'array',
+      maxItems: CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS,
+      items: { type: 'object' },
+      description: 'Optional model-authored reusable learning using the same LearningSignal contract as rh_work learning_record.',
+    },
+    learning_feedback: {
+      type: 'array',
+      maxItems: 32,
+      items: { type: 'object' },
+      description: 'Optional model-authored used/rejected feedback using the same contract as rh_work learning_feedback.',
+    },
+  },
+  description: 'Optional bounded advisory cognition settlement for a meaningful successful tool outcome. It creates no lifecycle and grants no authority.',
+} as const;
+
+/**
+ * Cognition settlement is transport metadata shared by every Controller tool.
+ * The detailed semantic contract remains owned by the canonical learning parser/writer;
+ * keeping this envelope compact avoids duplicating that schema across every tools/list entry.
+ */
+export function injectCognitionSettlementFields(definition: McpToolDefinition): McpToolDefinition {
+  const schema = definition.inputSchema as {
+    type?: unknown;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  if (!schema || schema.type !== 'object') return definition;
+  return {
+    ...definition,
+    inputSchema: {
+      ...schema,
+      properties: {
+        ...(schema.properties ?? {}),
+        cognition_settlement: COGNITION_SETTLEMENT_PROPERTY,
+      },
+    },
+  };
+}
+
+export interface CognitionSettlementReceipt {
+  recorded: boolean;
+  storedMemoryIds: string[];
+  observationIds: string[];
+}
+
+function parseFeedback(raw: unknown): DirectControllerLearningFeedbackDraft[] {
+  if (!Array.isArray(raw)) throw new Error('COGNITION_SETTLEMENT_FEEDBACK_INVALID');
+  if (raw.length === 0 || raw.length > 32) throw new Error('COGNITION_SETTLEMENT_FEEDBACK_ITEMS_INVALID');
+  return raw.map((rawItem, index) => {
+    if (!rawItem || typeof rawItem !== 'object' || Array.isArray(rawItem)) {
+      throw new Error(`COGNITION_SETTLEMENT_FEEDBACK_ITEM_INVALID: ${index}`);
+    }
+    const item = rawItem as Record<string, unknown>;
+    const memoryAddress = String(item.memory_address ?? '').trim();
+    const decision = String(item.decision ?? '').trim();
+    const reason = String(item.reason ?? '').trim();
+    const rejectionKind = typeof item.rejection_kind === 'string' ? item.rejection_kind.trim() : undefined;
+    if (!memoryAddress || !reason || !['used', 'rejected'].includes(decision)) {
+      throw new Error(`COGNITION_SETTLEMENT_FEEDBACK_ITEM_INVALID: ${index}`);
+    }
+    if (decision === 'rejected' && !['irrelevant', 'stale', 'contradicted'].includes(rejectionKind ?? '')) {
+      throw new Error(`COGNITION_SETTLEMENT_FEEDBACK_REJECTION_KIND_REQUIRED: ${index}`);
+    }
+    if (decision === 'used' && rejectionKind) {
+      throw new Error(`COGNITION_SETTLEMENT_FEEDBACK_REJECTION_KIND_UNEXPECTED: ${index}`);
+    }
+    return {
+      memoryAddress,
+      decision: decision as 'used' | 'rejected',
+      reason,
+      ...(rejectionKind ? { rejectionKind: rejectionKind as 'irrelevant' | 'stale' | 'contradicted' } : {}),
+    };
+  });
+}
+
+/** Mechanical settlement shared by ordinary successful MCP outcome boundaries. */
+export function settleCognitionEnvelope(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+): CognitionSettlementReceipt | undefined {
+  const raw = args.cognition_settlement;
+  if (raw === undefined) return undefined;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('COGNITION_SETTLEMENT_INVALID');
+  const envelope = raw as Record<string, unknown>;
+  const repository = selected(ctx, args);
+  const workId = typeof envelope.work_id === 'string' && envelope.work_id.trim()
+    ? envelope.work_id.trim()
+    : typeof args.work_id === 'string' && args.work_id.trim() ? args.work_id.trim() : undefined;
+
+  const storedMemoryIds: string[] = [];
+  const observationIds: string[] = [];
+
+  if (envelope.learning_signals !== undefined) {
+    const signals = parseControllerLearningSignalDrafts(envelope.learning_signals);
+    if (!signals.length) throw new Error('COGNITION_SETTLEMENT_SIGNALS_REQUIRED');
+    const learning = persistDirectControllerLearning({
+      controllerHome: ctx.controllerHome,
+      repository,
+      signals,
+      principalId: ctx.principalId,
+      sessionId: ctx.sessionId,
+      controllerInstanceId: ctx.controllerInstanceId,
+      controllerType: ctx.controllerType,
+      workId,
+    });
+    storedMemoryIds.push(...learning.storedMemoryIds);
+  }
+
+  if (envelope.learning_feedback !== undefined) {
+    const recorded = recordDirectControllerLearningFeedback({
+      controllerHome: ctx.controllerHome,
+      repository,
+      feedback: parseFeedback(envelope.learning_feedback),
+      principalId: ctx.principalId,
+      sessionId: ctx.sessionId,
+      controllerInstanceId: ctx.controllerInstanceId,
+      workId,
+    });
+    observationIds.push(...recorded.observationIds);
+  }
+
+  return {
+    recorded: storedMemoryIds.length > 0 || observationIds.length > 0,
+    storedMemoryIds,
+    observationIds,
+  };
+}
+
+function attachSettlementMetadata(
+  outcome: CallToolResult,
+  metadata: unknown,
+  warning?: string,
+): CallToolResult {
+  const structured = outcome.structuredContent;
+  if (!structured || typeof structured !== 'object' || Array.isArray(structured)) return outcome;
+  const current = structured as Record<string, unknown>;
+  const currentWarnings = Array.isArray(current.warnings)
+    ? current.warnings.filter((item): item is string => typeof item === 'string')
+    : [];
+  const structuredContent = {
+    ...current,
+    cognitionSettlement: metadata,
+    ...(warning ? { warnings: [...currentWarnings, warning] } : {}),
+  };
+  return {
+    ...outcome,
+    structuredContent,
+    content: outcome.content.map((block, index) => index === 0 && block.type === 'text'
+      ? { ...block, text: JSON.stringify(structuredContent) }
+      : block),
+  };
+}
+
+/**
+ * Settle advisory cognition only after the primary tool outcome succeeded.
+ * A settlement defect must never turn an already-applied repository/process/external effect
+ * into a failed tool call that a model might dangerously retry. Explicit learning_record /
+ * learning_feedback calls remain normal first-class operations and keep their own errors.
+ */
+export function settleCognitionAfterTool(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+  outcome: CallToolResult | undefined,
+): CallToolResult | undefined {
+  if (!outcome || outcome.isError || args.cognition_settlement === undefined) return outcome;
+  if (name === 'rh_work' && ['learning_record', 'learning_feedback'].includes(String(args.operation ?? ''))) {
+    return outcome;
+  }
+  try {
+    const receipt = settleCognitionEnvelope(ctx, args);
+    return receipt ? attachSettlementMetadata(outcome, receipt) : outcome;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)(?::|$)/.exec(message)?.[1] ?? 'COGNITION_SETTLEMENT_FAILED';
+    return attachSettlementMetadata(
+      outcome,
+      { recorded: false, error: { code, message } },
+      `COGNITION_SETTLEMENT_FAILED: ${message}`,
+    );
+  }
+}