@company-semantics/contracts 0.86.0 → 0.88.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -77,7 +77,7 @@
     "guard:test": "vitest run scripts/ci/__tests__",
     "release": "npx tsx scripts/release.ts",
     "prepublishOnly": "echo 'ERROR: Publishing is CI-only via tag push. Use pnpm release instead.' && exit 1",
-    "test": "vitest run scripts/ci/__tests__"
+    "test": "vitest run"
   },
   "packageManager": "pnpm@10.25.0",
   "engines": {

package/src/api/http/routes/ai-chat.ts

@@ -0,0 +1,37 @@
+/**
+ * AI Chat Route — Tool Discovery API Contract
+ *
+ * Shared helper for building tool discovery responses with optional
+ * capability graph inclusion via ?include=graph query parameter.
+ *
+ * Backend implementation: company-semantics-backend/src/api/http/routes/capabilities.ts
+ *
+ * Consumer usage:
+ *   import { buildCapabilityGraph } from '@company-semantics/contracts'
+ */
+
+import { buildCapabilityGraph } from '../../../mcp/capability-graph'
+import type {
+  MCPToolDescriptor,
+  ToolDiscoveryResponse,
+  CapabilityGraph,
+} from '../../../mcp/index'
+
+/**
+ * Build a ToolDiscoveryResponse, optionally including the capability graph.
+ *
+ * When include=graph query parameter is present, the response includes
+ * the graph derived from tool resource flow metadata.
+ *
+ * @param tools - Tool descriptors to include in response
+ * @param includeGraph - Whether to include the capability graph (from ?include=graph)
+ */
+export function buildToolDiscoveryResponse(
+  tools: MCPToolDescriptor[],
+  includeGraph: boolean,
+): ToolDiscoveryResponse {
+  return {
+    tools,
+    ...(includeGraph && { graph: buildCapabilityGraph(tools) }),
+  }
+}

package/src/execution/__tests__/lifecycle.test.ts

@@ -0,0 +1,262 @@
+import { describe, it, expect } from 'vitest'
+import type { ExecutionState } from '../status.js'
+import {
+  VALID_TRANSITIONS,
+  TERMINAL_STATES,
+  EFFECTIVE_TERMINAL_STATES,
+  assertValidTransition,
+} from '../status.js'
+import { LIFECYCLE_DECISIONS, applyIntent } from '../lifecycle.js'
+import type { ExecutionErrorCode } from '../errors.js'
+import { ExecutionError } from '../errors.js'
+import { parseExpiresAt, isConfirmationExpired } from '../expiry.js'
+
+const ALL_STATES: ExecutionState[] = [
+  'pending_confirmation',
+  'blocked_pending_approval',
+  'ready',
+  'executing',
+  'completed',
+  'completed_with_rollbacks',
+  'failed_retryable',
+  'failed_terminal',
+  'failed_with_partial_execution',
+  'cancelled',
+  'expired',
+  'undone',
+]
+
+// ---------------------------------------------------------------------------
+// 1. EXHAUSTIVE TRANSITION MATRIX
+// ---------------------------------------------------------------------------
+describe('exhaustive transition matrix', () => {
+  for (const from of ALL_STATES) {
+    for (const to of ALL_STATES) {
+      const allowed = VALID_TRANSITIONS[from].includes(to)
+      it(`${from} -> ${to} should be ${allowed ? 'valid' : 'invalid'}`, () => {
+        if (allowed) {
+          expect(() => assertValidTransition(from, to)).not.toThrow()
+        } else {
+          expect(() => assertValidTransition(from, to)).toThrow(
+            `Invalid execution state transition: ${from} -> ${to}`,
+          )
+        }
+      })
+    }
+  }
+})
+
+// ---------------------------------------------------------------------------
+// 2. TERMINAL_STATES CONSISTENCY
+// ---------------------------------------------------------------------------
+describe('TERMINAL_STATES consistency', () => {
+  it('contains exactly the states with empty transition arrays', () => {
+    const expectedTerminal = ALL_STATES.filter(
+      (s) => VALID_TRANSITIONS[s].length === 0,
+    )
+    expect(expectedTerminal.length).toBeGreaterThan(0)
+    for (const state of expectedTerminal) {
+      expect(TERMINAL_STATES.has(state)).toBe(true)
+    }
+    expect(TERMINAL_STATES.size).toBe(expectedTerminal.length)
+  })
+
+  it('does not contain states with non-empty transition arrays', () => {
+    const nonTerminal = ALL_STATES.filter(
+      (s) => VALID_TRANSITIONS[s].length > 0,
+    )
+    for (const state of nonTerminal) {
+      expect(TERMINAL_STATES.has(state)).toBe(false)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 3. EFFECTIVE_TERMINAL_STATES
+// ---------------------------------------------------------------------------
+describe('EFFECTIVE_TERMINAL_STATES', () => {
+  it('contains all TERMINAL_STATES', () => {
+    for (const state of TERMINAL_STATES) {
+      expect(EFFECTIVE_TERMINAL_STATES.has(state)).toBe(true)
+    }
+  })
+
+  it('contains completed', () => {
+    expect(EFFECTIVE_TERMINAL_STATES.has('completed')).toBe(true)
+  })
+
+  it('has size equal to TERMINAL_STATES + 1 (completed)', () => {
+    expect(EFFECTIVE_TERMINAL_STATES.size).toBe(TERMINAL_STATES.size + 1)
+  })
+
+  it('does not contain non-terminal, non-completed states', () => {
+    const nonEffectiveTerminal = ALL_STATES.filter(
+      (s) => !TERMINAL_STATES.has(s) && s !== 'completed',
+    )
+    for (const state of nonEffectiveTerminal) {
+      expect(EFFECTIVE_TERMINAL_STATES.has(state)).toBe(false)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 4. DECISION TABLE KEY CONSISTENCY
+// ---------------------------------------------------------------------------
+describe('decision table key consistency', () => {
+  it('LIFECYCLE_DECISIONS.confirm keys match VALID_TRANSITIONS keys', () => {
+    const transitionKeys = Object.keys(VALID_TRANSITIONS).sort()
+    const decisionKeys = Object.keys(LIFECYCLE_DECISIONS.confirm).sort()
+    expect(decisionKeys).toEqual(transitionKeys)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 5. APPROVE-TRANSITION DRIFT
+// ---------------------------------------------------------------------------
+describe('approve-transition drift', () => {
+  it('every state with approve decision can transition to ready', () => {
+    for (const state of ALL_STATES) {
+      if (LIFECYCLE_DECISIONS.confirm[state] === 'approve') {
+        expect(
+          VALID_TRANSITIONS[state].includes('ready'),
+        ).toBe(true)
+      }
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 6. APPLY_INTENT UNIT TESTS
+// ---------------------------------------------------------------------------
+describe('applyIntent', () => {
+  it('pending_confirmation + confirm = approve', () => {
+    expect(applyIntent('pending_confirmation', 'confirm')).toBe('approve')
+  })
+
+  it('expired + confirm = expired', () => {
+    expect(applyIntent('expired', 'confirm')).toBe('expired')
+  })
+
+  it('cancelled + confirm = conflict', () => {
+    expect(applyIntent('cancelled', 'confirm')).toBe('conflict')
+  })
+
+  it('ready + confirm = already_confirmed', () => {
+    expect(applyIntent('ready', 'confirm')).toBe('already_confirmed')
+  })
+
+  it('blocked_pending_approval + confirm = awaiting_approval', () => {
+    expect(applyIntent('blocked_pending_approval', 'confirm')).toBe(
+      'awaiting_approval',
+    )
+  })
+
+  it('failed_terminal + confirm = conflict', () => {
+    expect(applyIntent('failed_terminal', 'confirm')).toBe('conflict')
+  })
+
+  it('undone + confirm = conflict', () => {
+    expect(applyIntent('undone', 'confirm')).toBe('conflict')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 7. EXECUTION_ERROR TESTS
+// ---------------------------------------------------------------------------
+describe('ExecutionError', () => {
+  it('has correct name', () => {
+    const err = new ExecutionError('execution_expired', 'test', 410)
+    expect(err.name).toBe('ExecutionError')
+  })
+
+  it('has correct code', () => {
+    const err = new ExecutionError('execution_invalid_transition', 'bad transition', 409)
+    expect(err.code).toBe('execution_invalid_transition')
+  })
+
+  it('has correct message', () => {
+    const err = new ExecutionError('execution_not_found', 'not found', 404)
+    expect(err.message).toBe('not found')
+  })
+
+  it('has correct httpStatus', () => {
+    const err = new ExecutionError('execution_forbidden', 'forbidden', 403)
+    expect(err.httpStatus).toBe(403)
+  })
+
+  it('httpStatus is optional', () => {
+    const err = new ExecutionError('execution_expired', 'expired')
+    expect(err.httpStatus).toBeUndefined()
+  })
+
+  it('instanceof Error works', () => {
+    const err = new ExecutionError('execution_expired', 'expired', 410)
+    expect(err).toBeInstanceOf(Error)
+  })
+
+  it('instanceof ExecutionError works', () => {
+    const err = new ExecutionError('execution_expired', 'expired', 410)
+    expect(err).toBeInstanceOf(ExecutionError)
+  })
+
+  it('supports all error codes', () => {
+    const codes: ExecutionErrorCode[] = [
+      'execution_expired',
+      'execution_already_confirmed',
+      'execution_awaiting_approval',
+      'execution_not_found',
+      'execution_forbidden',
+      'execution_invalid_transition',
+    ]
+    for (const code of codes) {
+      const err = new ExecutionError(code, `msg-${code}`)
+      expect(err.code).toBe(code)
+      expect(err.name).toBe('ExecutionError')
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 8. EXPIRY HELPER TESTS
+// ---------------------------------------------------------------------------
+describe('parseExpiresAt', () => {
+  it('returns undefined for undefined input', () => {
+    expect(parseExpiresAt(undefined)).toBeUndefined()
+  })
+
+  it('returns undefined for invalid date string', () => {
+    expect(parseExpiresAt('invalid')).toBeUndefined()
+  })
+
+  it('returns correct epoch ms for valid ISO string', () => {
+    const result = parseExpiresAt('2026-01-01T00:00:00Z')
+    expect(result).toBe(new Date('2026-01-01T00:00:00Z').getTime())
+  })
+
+  it('returns undefined for empty string', () => {
+    expect(parseExpiresAt('')).toBeUndefined()
+  })
+})
+
+describe('isConfirmationExpired', () => {
+  it('returns false for undefined expiresAtMs', () => {
+    expect(isConfirmationExpired(undefined)).toBe(false)
+  })
+
+  it('returns true for past timestamp', () => {
+    const pastMs = Date.now() - 60_000
+    expect(isConfirmationExpired(pastMs)).toBe(true)
+  })
+
+  it('returns false for future timestamp', () => {
+    const futureMs = Date.now() + 60_000
+    expect(isConfirmationExpired(futureMs)).toBe(false)
+  })
+
+  it('works with custom now parameter', () => {
+    const expiresAtMs = 1000
+    expect(isConfirmationExpired(expiresAtMs, 999)).toBe(false)
+    expect(isConfirmationExpired(expiresAtMs, 1000)).toBe(true)
+    expect(isConfirmationExpired(expiresAtMs, 1001)).toBe(true)
+  })
+})

package/src/execution/errors.ts

@@ -0,0 +1,18 @@
+export type ExecutionErrorCode =
+  | 'execution_expired'
+  | 'execution_already_confirmed'
+  | 'execution_awaiting_approval'
+  | 'execution_not_found'
+  | 'execution_forbidden'
+  | 'execution_invalid_transition';
+
+export class ExecutionError extends Error {
+  constructor(
+    public readonly code: ExecutionErrorCode,
+    message: string,
+    public readonly httpStatus?: number,
+  ) {
+    super(message);
+    this.name = 'ExecutionError';
+  }
+}

package/src/execution/expiry.ts

@@ -0,0 +1,34 @@
+/**
+ * Centralized expiry check helpers for execution confirmations.
+ *
+ * Expiry logic lives here instead of inline in the confirm endpoint,
+ * the background job, and the client timer. Centralizing prevents drift.
+ *
+ * Uses pre-parsed epoch ms (number) instead of re-parsing ISO strings
+ * to avoid repeated Date construction.
+ */
+
+/**
+ * Parses an ISO 8601 string to epoch ms.
+ * Returns undefined if the input is undefined or an invalid date (NaN guard).
+ * Called once at creation time; the result is compared cheaply thereafter.
+ */
+export function parseExpiresAt(
+  expiresAt: string | undefined,
+): number | undefined {
+  if (expiresAt === undefined) return undefined
+  const ms = new Date(expiresAt).getTime()
+  return Number.isFinite(ms) ? ms : undefined
+}
+
+/**
+ * Compares pre-parsed epoch ms to determine if a confirmation has expired.
+ * Defaults `now` to Date.now(). Returns false if expiresAtMs is undefined.
+ */
+export function isConfirmationExpired(
+  expiresAtMs: number | undefined,
+  now?: number,
+): boolean {
+  if (expiresAtMs === undefined) return false
+  return (now ?? Date.now()) >= expiresAtMs
+}

package/src/execution/index.ts

@@ -72,6 +72,40 @@ export type { ExecutionKind } from './kinds'
 
 export type { ExecutionState } from './status'
 
+export {
+  VALID_TRANSITIONS,
+  TERMINAL_STATES,
+  EFFECTIVE_TERMINAL_STATES,
+  assertValidTransition,
+} from './status'
+
+// =============================================================================
+// Lifecycle Decision Engine
+// =============================================================================
+
+export type {
+  ExecutionIntent as LifecycleIntent,
+  LifecycleDecision,
+} from './lifecycle'
+
+export {
+  LIFECYCLE_DECISIONS,
+  applyIntent,
+} from './lifecycle'
+
+// =============================================================================
+// Expiry Helpers
+// =============================================================================
+
+export { parseExpiresAt, isConfirmationExpired } from './expiry'
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+export type { ExecutionErrorCode } from './errors'
+export { ExecutionError } from './errors'
+
 // =============================================================================
 // Definition Types
 // =============================================================================

package/src/execution/lifecycle.ts

@@ -0,0 +1,39 @@
+import type { ExecutionState } from './status';
+
+export type ExecutionIntent = 'confirm';
+
+export type LifecycleDecision =
+  | 'approve'
+  | 'already_confirmed'
+  | 'awaiting_approval'
+  | 'expired'
+  | 'conflict';
+
+type DecisionTable = Record<
+  ExecutionIntent,
+  Record<ExecutionState, LifecycleDecision>
+>;
+
+export const LIFECYCLE_DECISIONS: DecisionTable = {
+  confirm: {
+    pending_confirmation: 'approve',
+    expired: 'expired',
+    cancelled: 'conflict',
+    blocked_pending_approval: 'awaiting_approval',
+    ready: 'already_confirmed',
+    executing: 'already_confirmed',
+    completed: 'already_confirmed',
+    completed_with_rollbacks: 'already_confirmed',
+    failed_retryable: 'conflict',
+    failed_terminal: 'conflict',
+    failed_with_partial_execution: 'conflict',
+    undone: 'conflict',
+  },
+};
+
+export function applyIntent(
+  state: ExecutionState,
+  intent: ExecutionIntent,
+): LifecycleDecision {
+  return LIFECYCLE_DECISIONS[intent][state];
+}

package/src/execution/status.ts

@@ -41,6 +41,17 @@
  * bigint), not timestamps. UNIQUE(execution_id, event_sequence) enforced
  * at database level. event_sequence for ordering, created_at for duration —
  * distinct concerns.
+ *
+ * ## Execution Invariants
+ *
+ * - **INV-EXEC-1**: Events are append-only. No UPDATE/DELETE on execution_events.
+ * - **INV-EXEC-2**: Current state = stateAfter of latest event (by event_sequence).
+ *   execution_audit.state is a denormalized cache.
+ * - **INV-EXEC-3**: All transitions must satisfy VALID_TRANSITIONS[from].includes(to).
+ * - **INV-EXEC-4**: Transition validation + event insertion within same
+ *   advisory-locked transaction.
+ * - **INV-EXEC-5**: failed_retryable -> ready loop bounded by executor retry budget.
+ *   Retry events must include retryAttempt in metadata.
  */
 export type ExecutionState =
   | 'pending_confirmation'
@@ -55,3 +66,39 @@ export type ExecutionState =
   | 'cancelled'
   | 'expired'
   | 'undone';
+
+export const VALID_TRANSITIONS: Record<ExecutionState, readonly ExecutionState[]> = {
+  pending_confirmation: ['ready', 'blocked_pending_approval', 'cancelled', 'expired'],
+  blocked_pending_approval: ['ready', 'cancelled', 'expired'],
+  ready: ['executing'],
+  executing: [
+    'completed', 'completed_with_rollbacks',
+    'failed_retryable', 'failed_terminal',
+    'failed_with_partial_execution', 'cancelled',
+  ],
+  completed: ['undone'],
+  completed_with_rollbacks: [],
+  failed_retryable: ['ready'],
+  failed_terminal: [],
+  failed_with_partial_execution: [],
+  cancelled: [],
+  expired: [],
+  undone: [],
+};
+
+export const TERMINAL_STATES: ReadonlySet<ExecutionState> = new Set(
+  (Object.entries(VALID_TRANSITIONS) as [ExecutionState, readonly ExecutionState[]][])
+    .filter(([, targets]) => targets.length === 0)
+    .map(([state]) => state)
+);
+
+export const EFFECTIVE_TERMINAL_STATES: ReadonlySet<ExecutionState> = new Set([
+  ...TERMINAL_STATES,
+  'completed',
+]);
+
+export function assertValidTransition(from: ExecutionState, to: ExecutionState): void {
+  if (!VALID_TRANSITIONS[from].includes(to)) {
+    throw new Error(`Invalid execution state transition: ${from} -> ${to}`);
+  }
+}

package/src/index.ts

@@ -282,12 +282,14 @@ export type {
   ToolComplexity,
   // Resource flow types (PRD-00265)
   ResourceType,
-  // Capability graph stubs (PRD-00265, implementation in PRD-00268)
+  // Capability graph types (PRD-00265 types, PRD-00268 implementation)
   CapabilityGraph,
   CapabilityGraphEdge,
   ToolWorkflow,
 } from './mcp/index'
 
+export { buildCapabilityGraph } from './mcp/index'
+
 // Message part types and builder functions
 // @see ADR-2026-01-022 for design rationale
 export type {

package/src/interfaces/mcp/tools/help.ts

@@ -0,0 +1,76 @@
+/**
+ * Help Tool Enrichment — Workflow Summaries & Domain Groupings
+ *
+ * Pure formatting functions for enriching cs_help output with
+ * workflow summaries and domain groupings derived from the
+ * capability graph.
+ *
+ * These functions accept MCPToolDescriptor[] (the shape returned
+ * by getToolHandlers() or getToolDefinitions() in the backend)
+ * and produce formatted text sections.
+ *
+ * @see company-semantics-backend/src/interfaces/mcp/tools/system/help.ts
+ */
+
+import type { MCPToolDescriptor } from '../../../mcp/index'
+import { buildCapabilityGraph } from '../../../mcp/capability-graph'
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+/**
+ * Build workflow summary text from tool descriptors.
+ *
+ * Derives workflows via buildCapabilityGraph() and formats them
+ * for the "Available workflows" section of cs_help output.
+ *
+ * Usage:
+ *   const descriptors = getToolDefinitions() // or from getToolHandlers()
+ *   const section = formatWorkflowSummaries(descriptors)
+ */
+export function formatWorkflowSummaries(
+  descriptors: MCPToolDescriptor[],
+): string {
+  const graph = buildCapabilityGraph(descriptors)
+  if (graph.workflows.length === 0) return ''
+
+  const lines = graph.workflows.map((w) => {
+    const displayName = capitalize(w.name.replace(/_/g, ' '))
+    const steps = w.steps.map((s) => s.replace(/^cs_/, '')).join(' → ')
+    return `  ${displayName}: ${steps}`
+  })
+
+  return '\nAvailable workflows:\n' + lines.join('\n')
+}
+
+/**
+ * Build domain grouping text from tool descriptors.
+ *
+ * Groups tools by their `domain` field and formats as the
+ * "Tool domains" section of cs_help output.
+ *
+ * Usage:
+ *   const descriptors = getToolDefinitions() // or from getToolHandlers()
+ *   const section = formatDomainGroupings(descriptors)
+ */
+export function formatDomainGroupings(
+  descriptors: MCPToolDescriptor[],
+): string {
+  const domainGroups = new Map<string, string[]>()
+
+  for (const tool of descriptors) {
+    const domain = tool.domain ?? 'unknown'
+    if (!domainGroups.has(domain)) domainGroups.set(domain, [])
+    domainGroups.get(domain)!.push(
+      tool.name.replace(/^cs_/, '').replace(/_/g, ' '),
+    )
+  }
+
+  const lines = [...domainGroups.entries()].map(
+    ([domain, tools]) =>
+      `  ${capitalize(domain)} (${tools.length}): ${tools.join(', ')}`,
+  )
+
+  return '\nTool domains:\n' + lines.join('\n')
+}

package/src/mcp/__tests__/capability-graph.test.ts

@@ -0,0 +1,421 @@
+import { describe, it, expect } from 'vitest'
+import { buildCapabilityGraph } from '../capability-graph'
+import type { MCPToolDescriptor } from '../index'
+
+/**
+ * Helper to create minimal MCPToolDescriptor for testing.
+ * Only id, name, and resource fields matter for graph derivation.
+ */
+function makeTool(
+  overrides: Partial<MCPToolDescriptor> & { id: string; name: string },
+): MCPToolDescriptor {
+  return {
+    category: 'system',
+    description: '',
+    effectClass: 'pure',
+    invocationMode: 'manual',
+    visibility: 'user',
+    requiresConfirmation: false,
+    domain: 'system',
+    risk: 'none',
+    intent: 'read',
+    stability: 'stable',
+    complexity: 'trivial',
+    schemaVersion: 1,
+    ...overrides,
+  }
+}
+
+describe('buildCapabilityGraph', () => {
+  it('returns empty graph for empty tools array', () => {
+    const graph = buildCapabilityGraph([])
+    expect(graph.edges).toEqual([])
+    expect(graph.workflows).toEqual([])
+  })
+
+  it('produces no edges for tools with no produces/consumes', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a' }),
+      makeTool({ id: 'b', name: 'b' }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.edges).toEqual([])
+  })
+
+  it('creates one edge for single producer → consumer with correct domain', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a', produces: ['integration.connection'] }),
+      makeTool({ id: 'b', name: 'b', consumes: ['integration.connection'] }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.edges).toHaveLength(1)
+    expect(graph.edges[0]).toEqual({
+      from: 'a',
+      to: 'b',
+      resource: 'integration.connection',
+      domain: 'integration',
+    })
+  })
+
+  it('creates multiple edges for multiple producers of same resource', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a', produces: ['integration.connection'] }),
+      makeTool({ id: 'b', name: 'b', produces: ['integration.connection'] }),
+      makeTool({ id: 'c', name: 'c', consumes: ['integration.connection'] }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.edges).toHaveLength(2)
+    expect(graph.edges).toContainEqual({
+      from: 'a',
+      to: 'c',
+      resource: 'integration.connection',
+      domain: 'integration',
+    })
+    expect(graph.edges).toContainEqual({
+      from: 'b',
+      to: 'c',
+      resource: 'integration.connection',
+      domain: 'integration',
+    })
+  })
+
+  it('derives workflow for linear chain > 2 steps', () => {
+    const tools = [
+      makeTool({
+        id: 'step1',
+        name: 'step1',
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'step2',
+        name: 'step2',
+        consumes: ['integration.connection'],
+        produces: ['slack.channel'],
+      }),
+      makeTool({
+        id: 'step3',
+        name: 'step3',
+        consumes: ['slack.channel'],
+        produces: ['slack.channel_scope'],
+      }),
+      makeTool({
+        id: 'step4',
+        name: 'step4',
+        consumes: ['slack.channel_scope'],
+      }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.workflows).toHaveLength(1)
+    expect(graph.workflows[0].steps).toEqual([
+      'step1',
+      'step2',
+      'step3',
+      'step4',
+    ])
+  })
+
+  it('does NOT derive workflow for short chain (2 steps, 1 edge)', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a', produces: ['integration.connection'] }),
+      makeTool({ id: 'b', name: 'b', consumes: ['integration.connection'] }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.workflows).toEqual([])
+  })
+
+  it('does not form single workflow from branching nodes', () => {
+    const tools = [
+      makeTool({
+        id: 'root',
+        name: 'root',
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'branch1',
+        name: 'branch1',
+        consumes: ['integration.connection'],
+        produces: ['slack.channel'],
+      }),
+      makeTool({
+        id: 'branch2',
+        name: 'branch2',
+        consumes: ['integration.connection'],
+        produces: ['slack.coverage'],
+      }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    // root has 2 outgoing edges → not a linear chain
+    expect(graph.workflows).toEqual([])
+  })
+
+  describe('full 17-tool integration test', () => {
+    const allTools: MCPToolDescriptor[] = [
+      // Organization
+      makeTool({
+        id: 'cs_get_org_status',
+        name: 'cs_get_org_status',
+        domain: 'organization',
+        produces: ['org.status'],
+      }),
+      makeTool({
+        id: 'cs_update_org',
+        name: 'cs_update_org',
+        domain: 'organization',
+        intent: 'mutate',
+      }),
+      // Identity
+      makeTool({
+        id: 'cs_update_profile',
+        name: 'cs_update_profile',
+        domain: 'identity',
+        intent: 'mutate',
+      }),
+      // Integrations
+      makeTool({
+        id: 'cs_start_slack_auth',
+        name: 'cs_start_slack_auth',
+        domain: 'integrations',
+        integrations: ['slack'],
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_start_google_auth',
+        name: 'cs_start_google_auth',
+        domain: 'integrations',
+        integrations: ['google'],
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_start_zoom_auth',
+        name: 'cs_start_zoom_auth',
+        domain: 'integrations',
+        integrations: ['zoom'],
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_list_connections',
+        name: 'cs_list_connections',
+        domain: 'integrations',
+        produces: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_cleanup_connections',
+        name: 'cs_cleanup_connections',
+        domain: 'integrations',
+        consumes: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_propose_integration_action',
+        name: 'cs_propose_integration_action',
+        domain: 'integrations',
+        consumes: ['integration.connection'],
+      }),
+      // Discovery
+      makeTool({
+        id: 'cs_discover_slack',
+        name: 'cs_discover_slack',
+        domain: 'discovery',
+        integrations: ['slack'],
+        produces: ['slack.channel'],
+        consumes: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_get_slack_coverage',
+        name: 'cs_get_slack_coverage',
+        domain: 'discovery',
+        integrations: ['slack'],
+        produces: ['slack.coverage'],
+        consumes: ['integration.connection'],
+      }),
+      makeTool({
+        id: 'cs_list_fingerprints',
+        name: 'cs_list_fingerprints',
+        domain: 'discovery',
+        produces: ['knowledge.fingerprint'],
+      }),
+      // Ingestion
+      makeTool({
+        id: 'cs_manage_channel_scope',
+        name: 'cs_manage_channel_scope',
+        domain: 'ingestion',
+        integrations: ['slack'],
+        produces: ['slack.channel_scope'],
+        consumes: ['slack.channel'],
+      }),
+      makeTool({
+        id: 'cs_ingest_slack_channel',
+        name: 'cs_ingest_slack_channel',
+        domain: 'ingestion',
+        integrations: ['slack'],
+        produces: ['ingestion.job'],
+        consumes: ['slack.channel_scope'],
+      }),
+      makeTool({
+        id: 'cs_get_ingestion_status',
+        name: 'cs_get_ingestion_status',
+        domain: 'ingestion',
+        produces: ['ingestion.job'],
+        consumes: ['ingestion.job'],
+      }),
+      // System
+      makeTool({
+        id: 'cs_system_status',
+        name: 'cs_system_status',
+        domain: 'system',
+        produces: ['system.status'],
+      }),
+      makeTool({
+        id: 'cs_help',
+        name: 'cs_help',
+        domain: 'system',
+      }),
+    ]
+
+    it('includes Slack ingestion chain edges', () => {
+      const graph = buildCapabilityGraph(allTools)
+
+      expect(graph.edges).toContainEqual({
+        from: 'cs_start_slack_auth',
+        to: 'cs_discover_slack',
+        resource: 'integration.connection',
+        domain: 'integration',
+      })
+      expect(graph.edges).toContainEqual({
+        from: 'cs_discover_slack',
+        to: 'cs_manage_channel_scope',
+        resource: 'slack.channel',
+        domain: 'slack',
+      })
+      expect(graph.edges).toContainEqual({
+        from: 'cs_manage_channel_scope',
+        to: 'cs_ingest_slack_channel',
+        resource: 'slack.channel_scope',
+        domain: 'slack',
+      })
+      expect(graph.edges).toContainEqual({
+        from: 'cs_ingest_slack_channel',
+        to: 'cs_get_ingestion_status',
+        resource: 'ingestion.job',
+        domain: 'ingestion',
+      })
+    })
+
+    it('produces correct total edge count', () => {
+      const graph = buildCapabilityGraph(allTools)
+      // integration.connection: 4 producers × 4 consumers = 16 edges
+      // slack.channel: 1 edge (discover_slack → manage_channel_scope)
+      // slack.channel_scope: 1 edge (manage_channel_scope → ingest_slack_channel)
+      // ingestion.job: 2 edges (ingest → status, status → status self-loop)
+      expect(graph.edges).toHaveLength(20)
+    })
+
+    it('does not derive workflows from branching graph', () => {
+      const graph = buildCapabilityGraph(allTools)
+      // With all 17 tools, auth tools have 4 outgoing edges each (branching),
+      // and consumers like discover_slack have 4 incoming edges.
+      // No linear chain starts are walkable → no workflows.
+      expect(graph.workflows).toEqual([])
+    })
+  })
+
+  describe('slack_ingestion workflow derivation', () => {
+    it('derives slack_ingestion workflow from Slack chain tools', () => {
+      // Isolated Slack chain without branching from other auth tools
+      const slackChainTools = [
+        makeTool({
+          id: 'cs_start_slack_auth',
+          name: 'cs_start_slack_auth',
+          integrations: ['slack'],
+          produces: ['integration.connection'],
+        }),
+        makeTool({
+          id: 'cs_discover_slack',
+          name: 'cs_discover_slack',
+          integrations: ['slack'],
+          produces: ['slack.channel'],
+          consumes: ['integration.connection'],
+        }),
+        makeTool({
+          id: 'cs_manage_channel_scope',
+          name: 'cs_manage_channel_scope',
+          integrations: ['slack'],
+          produces: ['slack.channel_scope'],
+          consumes: ['slack.channel'],
+        }),
+        makeTool({
+          id: 'cs_ingest_slack_channel',
+          name: 'cs_ingest_slack_channel',
+          integrations: ['slack'],
+          consumes: ['slack.channel_scope'],
+        }),
+      ]
+      const graph = buildCapabilityGraph(slackChainTools)
+      expect(graph.workflows).toHaveLength(1)
+      expect(graph.workflows[0].name).toBe('slack_ingestion')
+      expect(graph.workflows[0].steps).toEqual([
+        'cs_start_slack_auth',
+        'cs_discover_slack',
+        'cs_manage_channel_scope',
+        'cs_ingest_slack_channel',
+      ])
+      expect(graph.workflows[0].description).toContain('start_slack_auth')
+      expect(graph.workflows[0].description).toContain('ingest_slack_channel')
+    })
+
+    it('extends Slack chain through cs_get_ingestion_status when isolated', () => {
+      const slackChainWithStatus = [
+        makeTool({
+          id: 'cs_start_slack_auth',
+          name: 'cs_start_slack_auth',
+          integrations: ['slack'],
+          produces: ['integration.connection'],
+        }),
+        makeTool({
+          id: 'cs_discover_slack',
+          name: 'cs_discover_slack',
+          integrations: ['slack'],
+          produces: ['slack.channel'],
+          consumes: ['integration.connection'],
+        }),
+        makeTool({
+          id: 'cs_manage_channel_scope',
+          name: 'cs_manage_channel_scope',
+          integrations: ['slack'],
+          produces: ['slack.channel_scope'],
+          consumes: ['slack.channel'],
+        }),
+        makeTool({
+          id: 'cs_ingest_slack_channel',
+          name: 'cs_ingest_slack_channel',
+          integrations: ['slack'],
+          produces: ['ingestion.job'],
+          consumes: ['slack.channel_scope'],
+        }),
+        makeTool({
+          id: 'cs_get_ingestion_status',
+          name: 'cs_get_ingestion_status',
+          produces: ['ingestion.job'],
+          consumes: ['ingestion.job'],
+        }),
+      ]
+      const graph = buildCapabilityGraph(slackChainWithStatus)
+
+      expect(graph.workflows).toHaveLength(1)
+      // Chain stops at cs_ingest_slack_channel because cs_get_ingestion_status
+      // has 2 incoming edges (from ingest + self-loop)
+      expect(graph.workflows[0].steps).toContain('cs_start_slack_auth')
+      expect(graph.workflows[0].steps).toContain('cs_discover_slack')
+      expect(graph.workflows[0].steps).toContain('cs_manage_channel_scope')
+      expect(graph.workflows[0].steps).toContain('cs_ingest_slack_channel')
+    })
+  })
+
+  it('extracts domain from resource namespace prefix', () => {
+    const tools = [
+      makeTool({ id: 'a', name: 'a', produces: ['slack.channel'] }),
+      makeTool({ id: 'b', name: 'b', consumes: ['slack.channel'] }),
+    ]
+    const graph = buildCapabilityGraph(tools)
+    expect(graph.edges[0].domain).toBe('slack')
+  })
+})

package/src/mcp/capability-graph.ts

@@ -0,0 +1,113 @@
+import type {
+  MCPToolDescriptor,
+  CapabilityGraph,
+  CapabilityGraphEdge,
+  ToolWorkflow,
+} from './index'
+
+/**
+ * Build a capability graph from tool resource flow metadata.
+ *
+ * Pure function — no I/O, no database, no side effects.
+ * Derives edges from produces/consumes matching on MCPToolDescriptor.
+ *
+ * For each tool's `consumes` array, finds all tools whose `produces`
+ * includes that ResourceType and creates a CapabilityGraphEdge.
+ */
+export function buildCapabilityGraph(tools: MCPToolDescriptor[]): CapabilityGraph {
+  const edges: CapabilityGraphEdge[] = []
+
+  for (const consumer of tools) {
+    for (const resourceType of consumer.consumes ?? []) {
+      const producers = tools.filter(t => t.produces?.includes(resourceType))
+      for (const producer of producers) {
+        edges.push({
+          from: producer.id,
+          to: consumer.id,
+          resource: resourceType,
+          domain: resourceType.split('.')[0],
+        })
+      }
+    }
+  }
+
+  const workflows = deriveWorkflows(tools, edges)
+  return { edges, workflows }
+}
+
+/**
+ * Derive named workflows from capability graph edges.
+ *
+ * Conservative: only linear chains with > 2 steps are reported.
+ * Branching nodes (multiple incoming or outgoing edges) break chains.
+ *
+ * Internal to capability-graph.ts — not exported.
+ */
+function deriveWorkflows(
+  tools: MCPToolDescriptor[],
+  edges: CapabilityGraphEdge[],
+): ToolWorkflow[] {
+  // Build adjacency: tool ID → outgoing edges, tool ID → incoming edges
+  const outgoing = new Map<string, CapabilityGraphEdge[]>()
+  const incoming = new Map<string, CapabilityGraphEdge[]>()
+
+  for (const edge of edges) {
+    if (!outgoing.has(edge.from)) outgoing.set(edge.from, [])
+    outgoing.get(edge.from)!.push(edge)
+    if (!incoming.has(edge.to)) incoming.set(edge.to, [])
+    incoming.get(edge.to)!.push(edge)
+  }
+
+  // Find chain start nodes: have outgoing edges, no incoming edges
+  const startNodes = [...outgoing.keys()].filter(
+    id => !incoming.has(id) || incoming.get(id)!.length === 0,
+  )
+
+  const workflows: ToolWorkflow[] = []
+  const visited = new Set<string>()
+
+  for (const start of startNodes) {
+    if (visited.has(start)) continue
+
+    const chain: string[] = [start]
+    visited.add(start)
+    let current = start
+
+    // Walk forward: follow single outgoing edge while next node has single incoming edge
+    while (true) {
+      const outs = outgoing.get(current)
+      if (!outs || outs.length !== 1) break
+
+      const next = outs[0].to
+      const ins = incoming.get(next)
+      if (!ins || ins.length !== 1) break
+
+      if (visited.has(next)) break
+      visited.add(next)
+      chain.push(next)
+      current = next
+    }
+
+    // Only emit workflows with > 2 steps
+    if (chain.length > 2) {
+      const toolMap = new Map(tools.map(t => [t.id, t]))
+      const chainTools = chain.map(id => toolMap.get(id)).filter(Boolean)
+
+      // Derive name from common integration or domain
+      const integrations = chainTools
+        .flatMap(t => t!.integrations ?? [])
+        .filter((v, i, a) => a.indexOf(v) === i)
+      const name =
+        integrations.length === 1
+          ? `${integrations[0]}_ingestion`
+          : `workflow_${chain[0]}`
+
+      const steps = chain.map(s => s.replace(/^cs_/, ''))
+      const description = `Workflow: ${steps.join(' → ')}`
+
+      workflows.push({ name: name, description: description, steps: chain })
+    }
+  }
+
+  return workflows
+}

package/src/mcp/failure-context.ts

@@ -0,0 +1,48 @@
+/**
+ * FailureContext — Structured Recovery for MCP Tool Failures
+ *
+ * When an MCP tool fails, the system emits a FailureContext that constrains
+ * the agent's next action to registered recovery actions only.
+ *
+ * INVARIANTS:
+ * - recoveryActions is exhaustive — the LLM cannot invent alternatives
+ * - 'cancel' is always implicitly available (not declared in recoveryActions)
+ * - No UI strings — labels/hints are the app layer's responsibility
+ * - depth tracks recovery chain length (1 = first failure)
+ * - At most one FailureContext is active at a time (no stacking)
+ */
+
+/**
+ * Structured recovery context emitted when an MCP tool call fails.
+ * Constrains the agent's next action to registered recovery options.
+ */
+export interface FailureContext {
+  /** MCP tool name that failed (e.g., 'cs_post_slack_message') */
+  tool: string;
+  /** Machine-readable error code from the error code registry */
+  reason: string;
+  /** Whether the same call might succeed on retry */
+  retryable: boolean;
+  /**
+   * Exhaustive list of allowed recovery actions.
+   * The agent MUST only invoke tools from this list until resolved.
+   * Empty array = cancel-only (no tool-based recovery available).
+   */
+  recoveryActions: RecoveryAction[];
+  /**
+   * Recovery chain depth. Starts at 1 on first failure.
+   * Incremented when a recovery action itself fails.
+   * When depth exceeds MAX_RECOVERY_DEPTH, only pure (read-only) tools remain available.
+   */
+  depth: number;
+}
+
+/**
+ * A recovery action the agent may take.
+ *
+ * Discriminated union — 'retry' is distinct from calling the same tool.
+ * Retry implies: arguments may change, timing may change, reason awareness.
+ */
+export type RecoveryAction =
+  | { type: 'retry' }
+  | { type: 'tool'; tool: string };

package/src/mcp/index.ts

@@ -1,5 +1,7 @@
 import type { ResourceType } from './resources'
 export type { ResourceType } from './resources'
+export { buildCapabilityGraph } from './capability-graph'
+export type { FailureContext, RecoveryAction } from './failure-context'
 
 /**
  * MCP Tool Discovery Types
@@ -130,6 +132,7 @@ export type ToolIntegration = 'slack' | 'google' | 'zoom' | (string & {})
  * Discovery uses: id, name, description, category
  * Invocation uses: id, requiresConfirmation, invocationMode, effectClass
  */
+// @vocabulary-exempt reason: MCPToolDescriptor is a single cohesive descriptor consumed by multiple repos; splitting would break consumers
 export interface MCPToolDescriptor {
   /** Unique identifier (matches MCP tool name, e.g., 'cs_help') */
   id: string

package/src/message-parts/confirmation.ts

@@ -67,6 +67,8 @@ export interface ConfirmationData {
   risk: ConfirmationRiskLevel;
   /** Lifecycle record ID — must exist before confirmation part is emitted */
   executionId: string;
+  /** ISO 8601 deadline for confirmation window. Absent for legacy messages. */
+  expiresAt?: string;
 }
 
 /**