@pellux/goodvibes-sdk 0.18.14 → 0.18.15

package/dist/_internal/platform/control-plane/approval-broker.js

@@ -0,0 +1,270 @@
+import { randomUUID } from 'node:crypto';
+import { PersistentStore } from '@pellux/goodvibes-sdk/platform/state/persistent-store';
+function sortApprovals(records) {
+    return [...records].sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id));
+}
+function buildAudit(action, actor, actorSurface, note) {
+    return {
+        id: `apra-${randomUUID().slice(0, 8)}`,
+        action,
+        actor,
+        actorSurface,
+        createdAt: Date.now(),
+        ...(note ? { note } : {}),
+    };
+}
+export class ApprovalBroker {
+    store;
+    approvals = new Map();
+    pendingResolvers = new Map();
+    listeners = new Set();
+    publisher = null;
+    loaded = false;
+    constructor(options) {
+        if (!options.store && !options.storePath) {
+            throw new Error('ApprovalBroker requires an explicit store or storePath.');
+        }
+        const storePath = options.storePath;
+        this.store = options.store ?? new PersistentStore(storePath);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    setPublisher(publisher) {
+        this.publisher = publisher;
+    }
+    async start() {
+        if (this.loaded)
+            return;
+        const snapshot = await this.store.load();
+        this.approvals.clear();
+        for (const approval of snapshot?.approvals ?? []) {
+            this.approvals.set(approval.id, approval);
+        }
+        this.loaded = true;
+    }
+    listApprovals(limit = 100) {
+        return sortApprovals(this.approvals.values()).slice(0, Math.max(1, limit));
+    }
+    getApproval(approvalId) {
+        return this.approvals.get(approvalId) ?? null;
+    }
+    async requestApproval(input) {
+        await this.start();
+        const now = Date.now();
+        const approval = {
+            id: `approval-${randomUUID().slice(0, 8)}`,
+            callId: input.request.callId,
+            sessionId: input.sessionId,
+            routeId: input.routeId,
+            status: 'pending',
+            request: input.request,
+            createdAt: now,
+            updatedAt: now,
+            metadata: input.metadata ?? {},
+            audit: [buildAudit('created', 'approval-broker', 'service')],
+        };
+        const pendingDecision = new Promise((resolve) => {
+            const timer = input.timeoutMs && input.timeoutMs > 0
+                ? setTimeout(() => {
+                    void this.expireApproval(approval.id, `timed out after ${input.timeoutMs}ms`);
+                }, input.timeoutMs)
+                : undefined;
+            this.pendingResolvers.set(approval.id, { resolve, timer });
+        });
+        this.approvals.set(approval.id, approval);
+        try {
+            await this.persist();
+        }
+        catch (error) {
+            const pending = this.pendingResolvers.get(approval.id);
+            if (pending) {
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                this.pendingResolvers.delete(approval.id);
+            }
+            this.approvals.delete(approval.id);
+            throw error;
+        }
+        this.publish(approval);
+        if (input.localPrompt) {
+            void input.localPrompt(input.request)
+                .then((decision) => this.resolveApproval(approval.id, {
+                approved: decision.approved,
+                remember: decision.remember,
+                actor: 'tui-local',
+                actorSurface: 'tui',
+            }))
+                .catch(() => { });
+        }
+        return pendingDecision;
+    }
+    async claimApproval(approvalId, actor, actorSurface = 'web', note) {
+        await this.start();
+        const approval = this.approvals.get(approvalId);
+        if (!approval)
+            return null;
+        if (approval.status !== 'pending' && approval.status !== 'claimed')
+            return approval;
+        const updated = {
+            ...approval,
+            status: 'claimed',
+            claimedBy: actor,
+            claimedAt: Date.now(),
+            updatedAt: Date.now(),
+            audit: [...approval.audit, buildAudit('claimed', actor, actorSurface, note)],
+        };
+        this.approvals.set(approvalId, updated);
+        await this.persist();
+        this.publish(updated);
+        return updated;
+    }
+    async resolveApproval(approvalId, input) {
+        await this.start();
+        const approval = this.approvals.get(approvalId);
+        if (!approval)
+            return null;
+        if (approval.status === 'approved' || approval.status === 'denied' || approval.status === 'cancelled' || approval.status === 'expired') {
+            return approval;
+        }
+        const updated = {
+            ...approval,
+            status: input.approved ? 'approved' : 'denied',
+            updatedAt: Date.now(),
+            resolvedAt: Date.now(),
+            resolvedBy: input.actor,
+            decision: {
+                approved: input.approved,
+                ...(input.remember !== undefined ? { remember: input.remember } : {}),
+            },
+            audit: [
+                ...approval.audit,
+                buildAudit(input.approved ? 'approved' : 'denied', input.actor, input.actorSurface, input.note),
+            ],
+        };
+        this.approvals.set(approvalId, updated);
+        await this.persist();
+        this.publish(updated);
+        const pending = this.pendingResolvers.get(approvalId);
+        if (pending) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.resolve(updated.decision ?? { approved: input.approved });
+            this.pendingResolvers.delete(approvalId);
+        }
+        return updated;
+    }
+    async recordRemoteUpdate(approvalId, input) {
+        await this.start();
+        const approval = this.approvals.get(approvalId);
+        if (!approval)
+            return null;
+        const updated = {
+            ...approval,
+            updatedAt: Date.now(),
+            metadata: {
+                ...approval.metadata,
+                ...(input.metadata ?? {}),
+            },
+            audit: [...approval.audit, buildAudit('updated', input.actor, input.actorSurface, input.note)],
+        };
+        this.approvals.set(approvalId, updated);
+        await this.persist();
+        this.publish(updated);
+        return updated;
+    }
+    async cancelApproval(approvalId, actor, actorSurface = 'web', note) {
+        await this.start();
+        const approval = this.approvals.get(approvalId);
+        if (!approval)
+            return null;
+        if (approval.status === 'approved' || approval.status === 'denied' || approval.status === 'cancelled' || approval.status === 'expired') {
+            return approval;
+        }
+        const updated = {
+            ...approval,
+            status: 'cancelled',
+            updatedAt: Date.now(),
+            resolvedAt: Date.now(),
+            resolvedBy: actor,
+            decision: { approved: false, remember: false },
+            audit: [...approval.audit, buildAudit('cancelled', actor, actorSurface, note)],
+        };
+        this.approvals.set(approvalId, updated);
+        await this.persist();
+        this.publish(updated);
+        const pending = this.pendingResolvers.get(approvalId);
+        if (pending) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.resolve({ approved: false, remember: false });
+            this.pendingResolvers.delete(approvalId);
+        }
+        return updated;
+    }
+    async expireApproval(approvalId, note) {
+        const approval = this.approvals.get(approvalId);
+        if (!approval)
+            return;
+        if (approval.status !== 'pending' && approval.status !== 'claimed')
+            return;
+        const updated = {
+            ...approval,
+            status: 'expired',
+            updatedAt: Date.now(),
+            resolvedAt: Date.now(),
+            resolvedBy: 'approval-broker',
+            decision: { approved: false, remember: false },
+            audit: [...approval.audit, buildAudit('expired', 'approval-broker', 'service', note)],
+        };
+        this.approvals.set(approvalId, updated);
+        await this.persist();
+        this.publish(updated);
+        const pending = this.pendingResolvers.get(approvalId);
+        if (pending) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.resolve({ approved: false, remember: false });
+            this.pendingResolvers.delete(approvalId);
+        }
+    }
+    async persist() {
+        await this.store.persist({
+            approvals: sortApprovals(this.approvals.values()),
+        });
+    }
+    publish(approval) {
+        this.publisher?.publishEvent('approval-update', {
+            approval,
+            createdAt: Date.now(),
+        });
+        this.publisher?.publishSurfaceMessage({
+            surface: 'web',
+            title: approval.status === 'pending' || approval.status === 'claimed' ? 'Approval required' : 'Approval resolved',
+            body: `${approval.request.tool}: ${approval.request.analysis.summary}`,
+            level: approval.status === 'approved'
+                ? 'success'
+                : approval.status === 'denied' || approval.status === 'expired'
+                    ? 'warn'
+                    : 'info',
+            metadata: {
+                approvalId: approval.id,
+                status: approval.status,
+                callId: approval.callId,
+                sessionId: approval.sessionId,
+                routeId: approval.routeId,
+            },
+        });
+        for (const listener of this.listeners) {
+            try {
+                listener(approval);
+            }
+            catch {
+                // Best-effort observer channel.
+            }
+        }
+    }
+}

package/dist/_internal/platform/control-plane/gateway.d.ts

@@ -0,0 +1,94 @@
+import type { RuntimeStore } from '../runtime/store/index.js';
+import type { RuntimeEventBus, RuntimeEventDomain } from '../runtime/events/index.js';
+import type { ControlPlaneClientDescriptor, ControlPlaneServerConfig, ControlPlaneSurfaceMessage } from '@pellux/goodvibes-sdk/platform/control-plane/types';
+export interface ControlPlaneGatewayConfig {
+    readonly runtimeBus?: RuntimeEventBus | null;
+    readonly runtimeStore?: RuntimeStore | null;
+    readonly server?: Partial<ControlPlaneServerConfig>;
+}
+export interface ControlPlaneEventStreamOptions {
+    readonly clientId?: string;
+    readonly clientKind?: 'tui' | 'web' | 'slack' | 'discord' | 'ntfy' | 'webhook' | 'telegram' | 'google-chat' | 'signal' | 'whatsapp' | 'imessage' | 'msteams' | 'bluebubbles' | 'mattermost' | 'matrix' | 'daemon';
+    readonly transport?: 'local' | 'http' | 'sse' | 'ws' | 'webhook';
+    readonly label?: string;
+    readonly domains?: readonly RuntimeEventDomain[];
+    readonly principalId?: string;
+    readonly principalKind?: 'user' | 'bot' | 'service' | 'token';
+    readonly scopes?: readonly string[];
+    readonly sessionId?: string;
+    readonly routeId?: string;
+    readonly surfaceId?: string;
+    readonly remoteAddress?: string;
+    readonly capabilities?: readonly string[];
+}
+export interface ControlPlaneRecentEvent {
+    readonly id: string;
+    readonly event: string;
+    readonly createdAt: number;
+    readonly payload: unknown;
+}
+interface LiveControlPlaneClient {
+    readonly clientId: string;
+    readonly kind: 'tui' | 'web' | 'slack' | 'discord' | 'ntfy' | 'webhook' | 'telegram' | 'google-chat' | 'signal' | 'whatsapp' | 'imessage' | 'msteams' | 'bluebubbles' | 'mattermost' | 'matrix' | 'daemon';
+    readonly surfaceId?: string;
+    readonly routeId?: string;
+    readonly send: (event: string, payload: unknown, id?: string) => void;
+}
+export declare class ControlPlaneGateway {
+    private runtimeBus;
+    private dispatch;
+    private readonly serverConfig;
+    private readonly clients;
+    private readonly liveClients;
+    private readonly websocketClients;
+    private readonly recentMessages;
+    private readonly recentEvents;
+    private requestCount;
+    private errorCount;
+    private lastRequestAt;
+    constructor(config?: ControlPlaneGatewayConfig);
+    attachRuntime(config: {
+        readonly runtimeBus?: RuntimeEventBus | null;
+        readonly runtimeStore?: RuntimeStore | null;
+    }): void;
+    listClients(): ControlPlaneClientDescriptor[];
+    getSnapshot(): Record<string, unknown>;
+    listSurfaceMessages(limit?: number): ControlPlaneSurfaceMessage[];
+    listRecentEvents(limit?: number): ControlPlaneRecentEvent[];
+    publishSurfaceMessage(input: Omit<ControlPlaneSurfaceMessage, 'id' | 'createdAt'>): ControlPlaneSurfaceMessage;
+    publishEvent(event: string, payload: unknown, filter?: {
+        readonly clientKind?: LiveControlPlaneClient['kind'];
+        readonly clientId?: string;
+        readonly routeId?: string;
+        readonly surfaceId?: string;
+    }): void;
+    recordApiRequest(input: {
+        readonly method: string;
+        readonly path: string;
+        readonly status: number;
+        readonly clientKind?: ControlPlaneEventStreamOptions['clientKind'];
+        readonly error?: string;
+    }): void;
+    setServerState(patch: Partial<ControlPlaneServerConfig>): void;
+    openWebSocketClient(options: ControlPlaneEventStreamOptions, send: (event: string, payload: unknown, id?: string) => void): {
+        clientId: string;
+        domains: readonly RuntimeEventDomain[];
+    };
+    touchWebSocketClient(clientId: string, metadata?: Record<string, unknown>): void;
+    authenticateClient(clientId: string, input: {
+        readonly principalId: string;
+        readonly principalKind?: 'user' | 'bot' | 'service' | 'token';
+        readonly scopes?: readonly string[];
+        readonly label?: string;
+        readonly capabilities?: readonly string[];
+    }): void;
+    subscribeWebSocketClient(clientId: string, domains: readonly RuntimeEventDomain[]): void;
+    unsubscribeWebSocketClient(clientId: string, domains?: readonly RuntimeEventDomain[]): void;
+    closeWebSocketClient(clientId: string, reason?: string): void;
+    private replayRecentTraffic;
+    createEventStream(request: Request, options?: ControlPlaneEventStreamOptions): Response;
+    renderWebUi(authTokenHint?: string): Response;
+    private rememberEvent;
+}
+export {};
+//# sourceMappingURL=gateway.d.ts.map

package/dist/_internal/platform/control-plane/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/control-plane/gateway.ts"],"names":[],"mappings":"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"}