Connectors, the connector SDK and registry, setup-connectors, provider-env, the LiteLLM runtime config and the sidecar's `vault` decoration only read and write secrets, so they now take the SecretStore interface. VaultStore is still constructed in the sidecar and the service startup, and its file format is unchanged. AGENTS.md now points at the interface.
137 lines
5.2 KiB
TypeScript
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 { SecretStore } 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: SecretStore): 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: SecretStore): 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 }),
|
|
};
|
|
}
|
|
}
|