@company-semantics/contracts 87.0.0 → 88.0.1

package/src/mcp/README.md

@@ -19,25 +19,25 @@ Type vocabulary for MCP (Model Context Protocol) tool discovery, invocation meta
 
 ## Public API
 
-- `CapabilityGraph` _(type)_
-- `CapabilityGraphEdge` _(type)_
+- `CapabilityGraph` _(type)_ — Capability graph derived from tool resource flow metadata.
+- `CapabilityGraphEdge` _(type)_ — Edge in the capability graph connecting two tools via a resource.
 - `FailureContext` _(type)_ — Structured recovery context emitted when an MCP tool call fails.
-- `MCPToolDescriptor` _(type)_
+- `MCPToolDescriptor` _(type)_ — Complete tool descriptor for discovery and invocation.
 - `RecoveryAction` _(type)_ — A recovery action the agent may take.
 - `ResourceType` _(type)_ — Resource type vocabulary for MCP tool resource flow.
 - `ToolCategory` _(type)_
-- `ToolComplexity` _(type)_
+- `ToolComplexity` _(type)_ — Tool computational complexity classification.
 - `ToolDiscoveryResponse` _(type)_
-- `ToolDomain` _(type)_
-- `ToolEffectClass` _(type)_
-- `ToolIntegration` _(type)_
-- `ToolIntent` _(type)_
-- `ToolInvocationMode` _(type)_
+- `ToolDomain` _(type)_ — Tool domain taxonomy.
+- `ToolEffectClass` _(type)_ — Tool effect classification.
+- `ToolIntegration` _(type)_ — Integration provider tag for tools.
+- `ToolIntent` _(type)_ — Tool intent classification.
+- `ToolInvocationMode` _(type)_ — How the tool can be invoked. - manual: User must explicitly request - assistant: AI can invoke proactively -…
 - `ToolListDataPart` _(type)_
 - `ToolListMessagePart` _(type)_
-- `ToolStability` _(type)_
-- `ToolVisibility` _(type)_
-- `ToolWorkflow` _(type)_
+- `ToolStability` _(type)_ — Tool lifecycle stability classification. - experimental: May change or be removed without notice - stable…
+- `ToolVisibility` _(type)_ — Tool visibility levels.
+- `ToolWorkflow` _(type)_ — Named workflow derived from capability graph paths.
 - `buildCapabilityGraph` — Build a capability graph from tool resource flow metadata.
 
 <!-- END GENERATED: readme-public-api -->

package/src/mcp/capability-graph.ts

@@ -3,7 +3,7 @@ import type {
   CapabilityGraph,
   CapabilityGraphEdge,
   ToolWorkflow,
-} from "./index";
+} from "./tool-descriptor";
 
 /**
  * Build a capability graph from tool resource flow metadata.

package/src/mcp/index.ts

@@ -1,7 +1,22 @@
-import type { ResourceType } from "./resources";
+import type { CapabilityGraph, MCPToolDescriptor } from "./tool-descriptor";
 export type { ResourceType } from "./resources";
 export { buildCapabilityGraph } from "./capability-graph";
 export type { FailureContext, RecoveryAction } from "./failure-context";
+export type {
+  ToolCategory,
+  ToolDomain,
+  ToolVisibility,
+  ToolInvocationMode,
+  ToolEffectClass,
+  ToolIntent,
+  ToolStability,
+  ToolComplexity,
+  ToolIntegration,
+  MCPToolDescriptor,
+  CapabilityGraphEdge,
+  ToolWorkflow,
+  CapabilityGraph,
+} from "./tool-descriptor";
 
 /**
  * MCP Tool Discovery Types
@@ -22,249 +37,6 @@ export type { FailureContext, RecoveryAction } from "./failure-context";
  * @see company-semantics-backend/src/interfaces/mcp/ for implementation
  */
 
-/**
- * @deprecated Use ToolDomain instead. ToolCategory is too coarse —
- * 'data' conflates discovery, ingestion, and coverage.
- */
-export type ToolCategory =
-  "system" | "data" | "connections" | "automation" | "developer";
-
-/**
- * Tool domain taxonomy.
- *
- * Each value maps to a distinct domain boundary in the system architecture.
- * Replaces ToolCategory which was too coarse for resource flow reasoning.
- *
- * - organization: Org settings, membership, billing queries
- * - identity: User profile, auth state, preferences
- * - integrations: OAuth connections, provider management
- * - ingestion: Data import, sync jobs, source configuration
- * - discovery: Search, exploration, content queries
- * - knowledge: Fingerprints, embeddings, knowledge graph
- * - system: Health, status, runtime diagnostics
- */
-export type ToolDomain =
-  | "organization"
-  | "identity"
-  | "integrations"
-  | "ingestion"
-  | "discovery"
-  | "knowledge"
-  | "system";
-
-/**
- * Tool visibility levels.
- * Controls who can see the tool in discovery.
- */
-export type ToolVisibility = "user" | "admin";
-
-/**
- * How the tool can be invoked.
- * - manual: User must explicitly request
- * - assistant: AI can invoke proactively
- * - hybrid: Both manual and assistant invocation
- */
-export type ToolInvocationMode = "manual" | "assistant" | "hybrid";
-
-/**
- * Tool effect classification.
- * Effect classification is orthogonal to requiresConfirmation and requiresApproval.
- * - effectClass: "Does this tool mutate state?"
- * - requiresConfirmation: "Does the user need to approve before execution?"
- * - requiresApproval: "Does this need cross-principal authorization?"
- * An effectful tool may auto-execute (requiresConfirmation: false) for low-risk operations.
- * An effectful tool may require approval without confirmation.
- */
-export type ToolEffectClass = "pure" | "effectful";
-
-/**
- * Tool intent classification.
- *
- * Classifies what the tool does to the system:
- * - read: Pure data retrieval (no side effects)
- * - mutate: State change (creates, updates, deletes)
- * - analysis: Computation over data without mutation (aggregation, scoring)
- *
- * Note: 'control' was removed — system-level operations (health, status,
- * runtime) use 'read' intent in the 'system' domain. Control is a domain
- * classification, not an intent.
- *
- * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
- * Enforced in backend tool registration, typed here for documentation.
- */
-export type ToolIntent = "read" | "mutate" | "analysis";
-
-/**
- * Tool lifecycle stability classification.
- *
- * - experimental: May change or be removed without notice
- * - stable: Production-ready with backward compatibility guarantees
- * - deprecated: Scheduled for removal, consumers should migrate
- */
-export type ToolStability = "experimental" | "stable" | "deprecated";
-
-/**
- * Tool computational complexity classification.
- *
- * Classifies the cost and latency profile of a tool invocation:
- * - trivial: Sub-100ms, in-memory or single DB lookup
- * - moderate: 100ms-5s, may involve external API calls
- * - heavy: 5s+, batch processing, large data transfers, long-running ops
- */
-export type ToolComplexity = "trivial" | "moderate" | "heavy";
-
-/**
- * Integration provider tag for tools.
- *
- * Known values correspond to registered OAuth providers.
- * Extensible via (string & {}) — new integrations do not require
- * a contracts release, but known values get autocomplete.
- */
-export type ToolIntegration = "slack" | "google" | "zoom" | (string & {});
-
-/**
- * Complete tool descriptor for discovery and invocation.
- *
- * 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;
-  /** Human-readable name for display */
-  name: string;
-  /** User-facing description (what it does, not how) */
-  description: string;
-  /** Grouping category for UI organization */
-  category: ToolCategory;
-  /** Whether user confirmation is required before execution */
-  requiresConfirmation: boolean;
-  /**
-   * Whether this tool causes durable state change.
-   * Effectful = any tool that can cause durable state change (DB writes, external API calls, background job enqueue).
-   * Pure = read-only operations, URL generation, status queries.
-   *
-   * Orthogonal to requiresConfirmation — an effectful tool may auto-execute
-   * for low-risk operations, and a pure tool never needs confirmation.
-   * The bridge enforces: effectful tools must return previewResponse()
-   * with ExecutionIntent, never direct side effects.
-   */
-  effectClass: ToolEffectClass;
-  /** How the tool can be triggered */
-  invocationMode: ToolInvocationMode;
-  /** Who can see this tool */
-  visibility: ToolVisibility;
-
-  // --- New fields (PRD-00265) ---
-
-  /** Domain taxonomy classification. Replaces category for routing and grouping. */
-  domain: ToolDomain;
-  /**
-   * Integration providers this tool interacts with.
-   * Empty or omitted for tools that don't touch external integrations.
-   */
-  integrations?: ToolIntegration[];
-  /**
-   * User-impact risk classification.
-   * - none: Read-only, no side effects
-   * - low: Reversible mutation (can be undone)
-   * - moderate: User-visible side effect (notification sent, state changed)
-   * - high: Destructive or irreversible (data deletion, external action)
-   *
-   * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
-   */
-  risk: "none" | "low" | "moderate" | "high";
-  /** What the tool does to the system (read, mutate, analysis). */
-  intent: ToolIntent;
-  /** Lifecycle stability classification. */
-  stability: ToolStability;
-  /** Computational complexity and latency profile. */
-  complexity: ToolComplexity;
-  /**
-   * Input schema version number.
-   * Disambiguates input schema versioning from tool behavior versioning.
-   * Increment when the tool's input schema changes shape.
-   */
-  schemaVersion: number;
-  /**
-   * Authorization scopes required to invoke this tool.
-   * References scope strings from trust/scopes.ts.
-   * Omit for tools with no specific scope requirements.
-   */
-  scopes?: string[];
-  /**
-   * Resource types this tool produces (creates or outputs).
-   * Used for capability graph derivation — enables workflow ordering
-   * via resource flow instead of explicit `requires` fields.
-   */
-  produces?: ResourceType[];
-  /**
-   * Resource types this tool consumes (requires as input).
-   * Used for capability graph derivation — a tool that consumes
-   * 'integration.connection' can only run after a tool that produces it.
-   */
-  consumes?: ResourceType[];
-  /**
-   * Mutation-capability gate (ADR-BE-241). When present, the tool is locked
-   * unless the viewer's resolved capabilities permit it — the SINGLE source of
-   * truth consumed by BOTH the backend execution gate and the frontend tool-lock
-   * UI (replacing the previously triplicated ACTION_TOOL_GATES / FIELD_GATES /
-   * ACTION_GATES maps).
-   * - kind 'field': `path` addresses a FieldCapability in CapabilitiesResponse
-   *   (e.g. 'org.name', 'profile.fullName'); locked unless state === 'editable'.
-   * - kind 'action': `path` addresses an ActionCapability under `.actions`
-   *   (e.g. 'members.invite', 'orgAdmins.manage'); locked unless 'allowed'.
-   * Absent ⇒ ungated (gating is additive).
-   */
-  capabilityGate?: { kind: "field" | "action"; path: string };
-}
-
-/**
- * Edge in the capability graph connecting two tools via a resource.
- * A tool that produces a resource connects to tools that consume it.
- *
- * @see capability-graph.ts for buildCapabilityGraph() implementation
- */
-export interface CapabilityGraphEdge {
-  /** Tool ID that produces the resource */
-  from: string;
-  /** Tool ID that consumes the resource */
-  to: string;
-  /** Resource type flowing between tools */
-  resource: ResourceType;
-  /** Resource domain (extracted from resource namespace prefix, e.g., 'slack' from 'slack.channel') */
-  domain?: string;
-}
-
-/**
- * Named workflow derived from capability graph paths.
- * Represents a common multi-tool sequence (e.g., "Connect Slack → Ingest → Query").
- *
- * @see capability-graph.ts for buildCapabilityGraph() implementation
- */
-export interface ToolWorkflow {
-  /** Workflow name (e.g., "Slack Onboarding") */
-  name: string;
-  /** Human-readable description of the workflow */
-  description: string;
-  /** Ordered list of tool IDs in this workflow */
-  steps: string[];
-}
-
-/**
- * Capability graph derived from tool resource flow metadata.
- * Built from produces/consumes fields on MCPToolDescriptor.
- *
- * @see capability-graph.ts for buildCapabilityGraph() implementation
- */
-export interface CapabilityGraph {
-  /** Resource flow edges between tools */
-  edges: CapabilityGraphEdge[];
-  /** Named workflows derived from graph paths */
-  workflows: ToolWorkflow[];
-}
-
 /**
  * Response shape for tool discovery endpoint.
  * Used by GET /api/capabilities/tools

package/src/mcp/tool-descriptor.ts

@@ -0,0 +1,244 @@
+import type { ResourceType } from "./resources";
+
+/**
+ * @deprecated Use ToolDomain instead. ToolCategory is too coarse —
+ * 'data' conflates discovery, ingestion, and coverage.
+ */
+export type ToolCategory =
+  "system" | "data" | "connections" | "automation" | "developer";
+
+/**
+ * Tool domain taxonomy.
+ *
+ * Each value maps to a distinct domain boundary in the system architecture.
+ * Replaces ToolCategory which was too coarse for resource flow reasoning.
+ *
+ * - organization: Org settings, membership, billing queries
+ * - identity: User profile, auth state, preferences
+ * - integrations: OAuth connections, provider management
+ * - ingestion: Data import, sync jobs, source configuration
+ * - discovery: Search, exploration, content queries
+ * - knowledge: Fingerprints, embeddings, knowledge graph
+ * - system: Health, status, runtime diagnostics
+ */
+export type ToolDomain =
+  | "organization"
+  | "identity"
+  | "integrations"
+  | "ingestion"
+  | "discovery"
+  | "knowledge"
+  | "system";
+
+/**
+ * Tool visibility levels.
+ * Controls who can see the tool in discovery.
+ */
+export type ToolVisibility = "user" | "admin";
+
+/**
+ * How the tool can be invoked.
+ * - manual: User must explicitly request
+ * - assistant: AI can invoke proactively
+ * - hybrid: Both manual and assistant invocation
+ */
+export type ToolInvocationMode = "manual" | "assistant" | "hybrid";
+
+/**
+ * Tool effect classification.
+ * Effect classification is orthogonal to requiresConfirmation and requiresApproval.
+ * - effectClass: "Does this tool mutate state?"
+ * - requiresConfirmation: "Does the user need to approve before execution?"
+ * - requiresApproval: "Does this need cross-principal authorization?"
+ * An effectful tool may auto-execute (requiresConfirmation: false) for low-risk operations.
+ * An effectful tool may require approval without confirmation.
+ */
+export type ToolEffectClass = "pure" | "effectful";
+
+/**
+ * Tool intent classification.
+ *
+ * Classifies what the tool does to the system:
+ * - read: Pure data retrieval (no side effects)
+ * - mutate: State change (creates, updates, deletes)
+ * - analysis: Computation over data without mutation (aggregation, scoring)
+ *
+ * Note: 'control' was removed — system-level operations (health, status,
+ * runtime) use 'read' intent in the 'system' domain. Control is a domain
+ * classification, not an intent.
+ *
+ * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
+ * Enforced in backend tool registration, typed here for documentation.
+ */
+export type ToolIntent = "read" | "mutate" | "analysis";
+
+/**
+ * Tool lifecycle stability classification.
+ *
+ * - experimental: May change or be removed without notice
+ * - stable: Production-ready with backward compatibility guarantees
+ * - deprecated: Scheduled for removal, consumers should migrate
+ */
+export type ToolStability = "experimental" | "stable" | "deprecated";
+
+/**
+ * Tool computational complexity classification.
+ *
+ * Classifies the cost and latency profile of a tool invocation:
+ * - trivial: Sub-100ms, in-memory or single DB lookup
+ * - moderate: 100ms-5s, may involve external API calls
+ * - heavy: 5s+, batch processing, large data transfers, long-running ops
+ */
+export type ToolComplexity = "trivial" | "moderate" | "heavy";
+
+/**
+ * Integration provider tag for tools.
+ *
+ * Known values correspond to registered OAuth providers.
+ * Extensible via (string & {}) — new integrations do not require
+ * a contracts release, but known values get autocomplete.
+ */
+export type ToolIntegration = "slack" | "google" | "zoom" | (string & {});
+
+/**
+ * Complete tool descriptor for discovery and invocation.
+ *
+ * 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;
+  /** Human-readable name for display */
+  name: string;
+  /** User-facing description (what it does, not how) */
+  description: string;
+  /** Grouping category for UI organization */
+  category: ToolCategory;
+  /** Whether user confirmation is required before execution */
+  requiresConfirmation: boolean;
+  /**
+   * Whether this tool causes durable state change.
+   * Effectful = any tool that can cause durable state change (DB writes, external API calls, background job enqueue).
+   * Pure = read-only operations, URL generation, status queries.
+   *
+   * Orthogonal to requiresConfirmation — an effectful tool may auto-execute
+   * for low-risk operations, and a pure tool never needs confirmation.
+   * The bridge enforces: effectful tools must return previewResponse()
+   * with ExecutionIntent, never direct side effects.
+   */
+  effectClass: ToolEffectClass;
+  /** How the tool can be triggered */
+  invocationMode: ToolInvocationMode;
+  /** Who can see this tool */
+  visibility: ToolVisibility;
+
+  // --- New fields (PRD-00265) ---
+
+  /** Domain taxonomy classification. Replaces category for routing and grouping. */
+  domain: ToolDomain;
+  /**
+   * Integration providers this tool interacts with.
+   * Empty or omitted for tools that don't touch external integrations.
+   */
+  integrations?: ToolIntegration[];
+  /**
+   * User-impact risk classification.
+   * - none: Read-only, no side effects
+   * - low: Reversible mutation (can be undone)
+   * - moderate: User-visible side effect (notification sent, state changed)
+   * - high: Destructive or irreversible (data deletion, external action)
+   *
+   * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
+   */
+  risk: "none" | "low" | "moderate" | "high";
+  /** What the tool does to the system (read, mutate, analysis). */
+  intent: ToolIntent;
+  /** Lifecycle stability classification. */
+  stability: ToolStability;
+  /** Computational complexity and latency profile. */
+  complexity: ToolComplexity;
+  /**
+   * Input schema version number.
+   * Disambiguates input schema versioning from tool behavior versioning.
+   * Increment when the tool's input schema changes shape.
+   */
+  schemaVersion: number;
+  /**
+   * Authorization scopes required to invoke this tool.
+   * References scope strings from trust/scopes.ts.
+   * Omit for tools with no specific scope requirements.
+   */
+  scopes?: string[];
+  /**
+   * Resource types this tool produces (creates or outputs).
+   * Used for capability graph derivation — enables workflow ordering
+   * via resource flow instead of explicit `requires` fields.
+   */
+  produces?: ResourceType[];
+  /**
+   * Resource types this tool consumes (requires as input).
+   * Used for capability graph derivation — a tool that consumes
+   * 'integration.connection' can only run after a tool that produces it.
+   */
+  consumes?: ResourceType[];
+  /**
+   * Mutation-capability gate (ADR-BE-241). When present, the tool is locked
+   * unless the viewer's resolved capabilities permit it — the SINGLE source of
+   * truth consumed by BOTH the backend execution gate and the frontend tool-lock
+   * UI (replacing the previously triplicated ACTION_TOOL_GATES / FIELD_GATES /
+   * ACTION_GATES maps).
+   * - kind 'field': `path` addresses a FieldCapability in CapabilitiesResponse
+   *   (e.g. 'org.name', 'profile.fullName'); locked unless state === 'editable'.
+   * - kind 'action': `path` addresses an ActionCapability under `.actions`
+   *   (e.g. 'members.invite', 'orgAdmins.manage'); locked unless 'allowed'.
+   * Absent ⇒ ungated (gating is additive).
+   */
+  capabilityGate?: { kind: "field" | "action"; path: string };
+}
+
+/**
+ * Edge in the capability graph connecting two tools via a resource.
+ * A tool that produces a resource connects to tools that consume it.
+ *
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
+ */
+export interface CapabilityGraphEdge {
+  /** Tool ID that produces the resource */
+  from: string;
+  /** Tool ID that consumes the resource */
+  to: string;
+  /** Resource type flowing between tools */
+  resource: ResourceType;
+  /** Resource domain (extracted from resource namespace prefix, e.g., 'slack' from 'slack.channel') */
+  domain?: string;
+}
+
+/**
+ * Named workflow derived from capability graph paths.
+ * Represents a common multi-tool sequence (e.g., "Connect Slack → Ingest → Query").
+ *
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
+ */
+export interface ToolWorkflow {
+  /** Workflow name (e.g., "Slack Onboarding") */
+  name: string;
+  /** Human-readable description of the workflow */
+  description: string;
+  /** Ordered list of tool IDs in this workflow */
+  steps: string[];
+}
+
+/**
+ * Capability graph derived from tool resource flow metadata.
+ * Built from produces/consumes fields on MCPToolDescriptor.
+ *
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
+ */
+export interface CapabilityGraph {
+  /** Resource flow edges between tools */
+  edges: CapabilityGraphEdge[];
+  /** Named workflows derived from graph paths */
+  workflows: ToolWorkflow[];
+}