@company-semantics/contracts 0.86.0 → 0.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.86.0",
+  "version": "0.87.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/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/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/index.ts

@@ -1,5 +1,6 @@
 import type { ResourceType } from './resources'
 export type { ResourceType } from './resources'
+export { buildCapabilityGraph } from './capability-graph'
 
 /**
  * MCP Tool Discovery Types
@@ -130,6 +131,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