Files
waggle-os/packages/agent/src/connector-sdk.ts
shumeiko.it b734c1d3d2 refactor: remove KVARK, enterprise packs and the compliance subsystem (P1.4, P1.6)
KVARK is the commercial enterprise product and is not part of the community
edition. The agent's KVARK tools were never wired into the server, so
removing them changes no runtime behaviour beyond the routes listed here.

- agent: delete kvark-tools; CombinedRetrieval and formatCombinedResult now
  merge workspace and personal memory only (no KVARK lane, no source
  conflict note); connector substrate is always 'waggle'
- agent: promote_skill stops at workspace scope; team and enterprise scopes
  answer "not available in this edition" instead of an upgrade prompt
- server: delete src/kvark and GET /api/marketplace/enterprise-packs
- marketplace: delete ENTERPRISE_PACKS
- compliance (EU AI Act dashboard, its templates and the KVARK template
  seeded on every boot): delete core/src/compliance, the /api/compliance/*
  routes, agent compliance-pdf and the Cockpit compliance panel. The
  ai_interactions table lives in the memory substrate and goes with P1.5.
2026-10-20 00:27:16 +02:00

137 lines
5.2 KiB
TypeScript

/**
* Connector SDK — runtime interface for external integrations.
*
* WaggleConnector is the server-side executable counterpart to the
* serializable ConnectorDefinition (from @waggle/shared). Each connector
* implementation provides actions that become agent tools when connected.
*/
import type { ConnectorDefinition, ConnectorHealth, ConnectorStatus, ConnectorActionMeta } from '@waggle/shared';
import type { VaultStore } from '@waggle/core';
/** Full action definition with input/output schemas (runtime-only) */
export interface ConnectorAction {
name: string;
description: string;
inputSchema: Record<string, unknown>; // JSON Schema
outputSchema?: Record<string, unknown>; // JSON Schema
riskLevel: 'low' | 'medium' | 'high';
}
/** Result from executing a connector action */
export interface ConnectorResult {
success: boolean;
data?: unknown;
error?: string;
}
/**
* Runtime connector interface. Implementations live in connectors/ directory.
* Each connector provides vault-based auth, health checks, and executable actions.
*/
export interface WaggleConnector {
/** Unique connector ID (e.g., 'github', 'slack') */
readonly id: string;
/** Display name */
readonly name: string;
/** What this connector does */
readonly description: string;
/** Which service it connects to */
readonly service: string;
/** Auth method required */
readonly authType: 'bearer' | 'oauth2' | 'api_key' | 'basic';
/** Available actions when connected */
readonly actions: ConnectorAction[];
/**
* Opt-in for the PRO `connector_fetch` auto-harvest loop: a SAFE, read-only,
* no-required-param action (+ optional default params) whose result is folded
* into memory on a schedule. Connectors without it are skipped by auto-fetch.
*/
readonly harvestAction?: { action: string; params?: Record<string, unknown> };
/** Which substrate manages this connector */
readonly substrate: 'waggle';
/** CDN URL for SVG logo */
readonly logoUrl?: string;
/** Connector category */
readonly category?: 'productivity' | 'development' | 'crm' | 'data' | 'communication' | 'storage' | 'integration';
/** Setup guide — what credential is needed and where to get it */
readonly setupGuide?: string;
/** Initialize connector with vault credentials */
connect(vault: VaultStore): Promise<void>;
/** Check if connection is healthy */
healthCheck(): Promise<ConnectorHealth>;
/** Execute an action by name */
execute(action: string, params: Record<string, unknown>): Promise<ConnectorResult>;
/** Map to the serializable ConnectorDefinition (for REST API / UI) */
toDefinition(status: ConnectorStatus): ConnectorDefinition;
}
/**
* Base class for connectors that provides common toDefinition() logic.
* Concrete connectors extend this and implement connect/healthCheck/execute.
*/
export abstract class BaseConnector implements WaggleConnector {
abstract readonly id: string;
abstract readonly name: string;
abstract readonly description: string;
abstract readonly service: string;
abstract readonly authType: 'bearer' | 'oauth2' | 'api_key' | 'basic';
abstract readonly actions: ConnectorAction[];
abstract readonly substrate: 'waggle';
readonly logoUrl?: string;
readonly category?: 'productivity' | 'development' | 'crm' | 'data' | 'communication' | 'storage' | 'integration';
readonly setupGuide?: string;
abstract connect(vault: VaultStore): Promise<void>;
abstract healthCheck(): Promise<ConnectorHealth>;
abstract execute(action: string, params: Record<string, unknown>): Promise<ConnectorResult>;
/** Derive capabilities from action risk levels */
protected deriveCapabilities(): ('read' | 'write' | 'search')[] {
const caps = new Set<'read' | 'write' | 'search'>();
for (const action of this.actions) {
if (action.riskLevel === 'low') caps.add('read');
if (action.riskLevel === 'medium' || action.riskLevel === 'high') caps.add('write');
if (action.name.includes('search') || action.name.includes('find') || action.name.includes('list')) {
caps.add('search');
}
}
return [...caps];
}
/** Safely extract and truncate API error text (defense-in-depth against large/leaky error responses) */
protected async safeErrorText(res: Response, prefix: string): Promise<string> {
try {
const text = await res.text();
const truncated = text.length > 500 ? text.slice(0, 500) + '...[truncated]' : text;
return `${prefix} ${res.status}: ${truncated}`;
} catch {
return `${prefix} ${res.status}`;
}
}
toDefinition(status: ConnectorStatus): ConnectorDefinition {
const actionMeta: ConnectorActionMeta[] = this.actions.map(a => ({
name: a.name,
description: a.description,
riskLevel: a.riskLevel,
}));
return {
id: this.id,
name: this.name,
description: this.description,
service: this.service,
authType: this.authType,
status,
capabilities: this.deriveCapabilities(),
substrate: this.substrate,
tools: this.actions.map(a => `connector_${this.id}_${a.name}`),
actions: actionMeta,
...(this.logoUrl && { logoUrl: this.logoUrl }),
...(this.category && { category: this.category }),
...(this.setupGuide && { setupGuide: this.setupGuide }),
};
}
}