@company-semantics/contracts 0.84.0 → 0.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.84.0",
+  "version": "0.85.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/execution/kinds.ts

@@ -27,3 +27,6 @@ export type ExecutionKind =
   | 'integration.disconnect'
   | 'profile.update'
   | 'slack.send'
+  | 'data.ingest'
+  | 'data.scope'
+  | 'system.cleanup'

package/src/execution/registry.ts

@@ -118,6 +118,69 @@ export const EXECUTION_KINDS = {
       templateId: 'slack.send',
     },
   },
+  'data.ingest': {
+    kind: 'data.ingest',
+    domain: 'data',
+    display: {
+      label: 'Import Channel',
+      pastTenseLabel: 'Channel imported',
+      icon: 'send',
+    },
+    governance: {
+      visibility: 'user',
+      requiresAdmin: false,
+    },
+    ui: {
+      showInAdmin: true,
+      showInTimeline: true,
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: 'data-ingest',
+    },
+  },
+  'data.scope': {
+    kind: 'data.scope',
+    domain: 'data',
+    display: {
+      label: 'Update Channel Scope',
+      pastTenseLabel: 'Channel scope updated',
+      icon: 'pencil',
+    },
+    governance: {
+      visibility: 'admin',
+      requiresAdmin: true,
+    },
+    ui: {
+      showInAdmin: true,
+      showInTimeline: true,
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: 'data-scope',
+    },
+  },
+  'system.cleanup': {
+    kind: 'system.cleanup',
+    domain: 'system',
+    display: {
+      label: 'Cleanup Connections',
+      pastTenseLabel: 'Connections cleaned up',
+      icon: 'unlink',
+    },
+    governance: {
+      visibility: 'admin',
+      requiresAdmin: true,
+    },
+    ui: {
+      showInAdmin: true,
+      showInTimeline: false,
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: 'system-cleanup',
+    },
+  },
 } as const satisfies Record<ExecutionKind, ExecutionKindDefinition>
 
 // =============================================================================

package/src/index.ts

@@ -271,6 +271,7 @@ export type {
   ToolCategory,
   ToolVisibility,
   ToolInvocationMode,
+  ToolEffectClass,
   MCPToolDescriptor,
   ToolDiscoveryResponse,
   ToolListMessagePart,

package/src/mcp/index.ts

@@ -42,11 +42,22 @@ export type ToolVisibility = 'user' | 'admin'
  */
 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'
+
 /**
  * Complete tool descriptor for discovery and invocation.
  *
  * Discovery uses: id, name, description, category
- * Invocation uses: id, requiresConfirmation, invocationMode
+ * Invocation uses: id, requiresConfirmation, invocationMode, effectClass
  */
 export interface MCPToolDescriptor {
   /** Unique identifier (matches MCP tool name, e.g., 'cs_help') */
@@ -59,6 +70,17 @@ export interface MCPToolDescriptor {
   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 */

package/src/message-parts/confirmation.ts

@@ -40,6 +40,9 @@ export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
   'integration.disconnect': 'Disconnect Integration',
   'profile.update': 'Update Profile',
   'slack.send': 'Send Slack Message',
+  'data.ingest': 'Import Channel',
+  'data.scope': 'Update Scope',
+  'system.cleanup': 'Cleanup Connections',
 };
 
 /**