@openacp/plugin-sdk 2026.41.1

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+export type { ConfigFieldDef, DoctorReport, PendingFix } from '@openacp/cli';
+export { DoctorEngine, getSafeFields, resolveOptions, getConfigValue, isHotReloadable } from '@openacp/cli';

package/dist/config.js

@@ -0,0 +1 @@
+export { DoctorEngine, getSafeFields, resolveOptions, getConfigValue, isHotReloadable } from '@openacp/cli';

package/dist/formatting.d.ts

@@ -0,0 +1,2 @@
+export type { DisplayVerbosity, ToolCallMeta, ToolUpdateMeta, ViewerLinks } from '@openacp/cli';
+export { STATUS_ICONS, KIND_ICONS, progressBar, formatTokens, truncateContent, stripCodeFences, splitMessage, extractContentText, formatToolSummary, formatToolTitle, resolveToolIcon, } from '@openacp/cli';

package/dist/formatting.js

@@ -0,0 +1 @@
+export { STATUS_ICONS, KIND_ICONS, progressBar, formatTokens, truncateContent, stripCodeFences, splitMessage, extractContentText, formatToolSummary, formatToolTitle, resolveToolIcon, } from '@openacp/cli';

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export type { OpenACPPlugin, PluginContext, PluginPermission, PluginStorage, InstallContext, MigrateContext, TerminalIO, SettingsAPI, } from '@openacp/cli';
+export type { CommandDef, CommandArgs, CommandResponse, MenuOption, ListItem, } from '@openacp/cli';
+export type { SecurityService, FileServiceInterface, NotificationService, UsageService, TunnelServiceInterface, ContextService, } from '@openacp/cli';
+export type { TTSProvider, TTSOptions, TTSResult, STTProvider, STTOptions, STTResult, SpeechServiceInterface, } from './speech-types.js';
+export type { IChannelAdapter, AdapterCapabilities, OutgoingMessage, PermissionRequest, PermissionOption, NotificationMessage, AgentCommand, MessagingAdapterConfig, IRenderer, RenderedMessage, } from '@openacp/cli';
+export { MessagingAdapter, StreamAdapter, BaseRenderer } from '@openacp/cli';
+export { SendQueue, DraftManager, ToolCallTracker, ActivityTracker } from '@openacp/cli';
+export { ToolStateMap, ThoughtBuffer } from '@openacp/cli';
+export { DisplaySpecBuilder } from '@openacp/cli';
+export { OutputModeResolver } from '@openacp/cli';
+export { ToolCardState } from '@openacp/cli';
+export type { OpenACPCore, Session, SessionEvents, SessionManager, CommandRegistry, Attachment, PlanEntry, StopReason, SessionStatus, ConfigOption, UsageRecord, InstallProgress, DisplayVerbosity, ToolCallMeta, ToolUpdateMeta, ViewerLinks, TelegramPlatformData, } from '@openacp/cli';
+export type { ToolDisplaySpec, ThoughtDisplaySpec, ToolEntry, OutputMode, ToolCardSnapshot, ToolCardStateConfig, } from '@openacp/cli';
+export { log, createChildLogger } from '@openacp/cli';
+export { PRODUCT_GUIDE } from '@openacp/cli';
+export type { ConfigFieldDef, DoctorReport, PendingFix } from './config.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+// ============================================================
+// @openacp/plugin-sdk — main entry point
+//
+// Sub-path imports available:
+//   @openacp/plugin-sdk/formatting — format utils, icons
+//   @openacp/plugin-sdk/config     — config utils, doctor engine
+//   @openacp/plugin-sdk/testing    — test helpers, conformance tests
+// ============================================================
+// --- Adapter base classes (runtime) ---
+export { MessagingAdapter, StreamAdapter, BaseRenderer } from '@openacp/cli';
+// --- Adapter primitives (runtime) ---
+export { SendQueue, DraftManager, ToolCallTracker, ActivityTracker } from '@openacp/cli';
+export { ToolStateMap, ThoughtBuffer } from '@openacp/cli';
+export { DisplaySpecBuilder } from '@openacp/cli';
+export { OutputModeResolver } from '@openacp/cli';
+export { ToolCardState } from '@openacp/cli';
+// --- Logging (runtime) ---
+export { log, createChildLogger } from '@openacp/cli';
+// --- Data (runtime) ---
+export { PRODUCT_GUIDE } from '@openacp/cli';

package/dist/speech-types.d.ts

@@ -0,0 +1,36 @@
+export interface TTSOptions {
+    language?: string;
+    voice?: string;
+    model?: string;
+}
+export interface TTSResult {
+    audioBuffer: Buffer;
+    mimeType: string;
+}
+export interface STTOptions {
+    language?: string;
+    model?: string;
+}
+export interface STTResult {
+    text: string;
+    language?: string;
+    duration?: number;
+}
+export interface TTSProvider {
+    readonly name: string;
+    synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
+}
+export interface STTProvider {
+    readonly name: string;
+    transcribe(audioBuffer: Buffer, mimeType: string, options?: STTOptions): Promise<STTResult>;
+}
+export interface SpeechServiceInterface {
+    registerTTSProvider(name: string, provider: TTSProvider): void;
+    unregisterTTSProvider(name: string): void;
+    registerSTTProvider(name: string, provider: STTProvider): void;
+    unregisterSTTProvider?(name: string): void;
+    isTTSAvailable(): boolean;
+    isSTTAvailable(): boolean;
+    synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
+    transcribe(audioBuffer: Buffer, mimeType: string, options?: STTOptions): Promise<STTResult>;
+}

package/dist/speech-types.js

@@ -0,0 +1,4 @@
+// Speech provider types for use by OpenACP plugins.
+// These are stable interfaces that plugins can rely on without depending
+// on @openacp/cli internals.
+export {};

package/dist/testing/adapter-conformance.d.ts

@@ -0,0 +1,2 @@
+import type { IChannelAdapter } from '@openacp/cli';
+export declare function runAdapterConformanceTests(createAdapter: () => IChannelAdapter | Promise<IChannelAdapter>, cleanup?: () => Promise<void>): void;

package/dist/testing/adapter-conformance.js

@@ -0,0 +1,64 @@
+import { describe, it, expect, afterEach } from 'vitest';
+export function runAdapterConformanceTests(createAdapter, cleanup) {
+    let adapter;
+    afterEach(async () => {
+        await cleanup?.();
+    });
+    describe('IChannelAdapter conformance', () => {
+        it('has a name', async () => {
+            adapter = await createAdapter();
+            expect(typeof adapter.name).toBe('string');
+            expect(adapter.name.length).toBeGreaterThan(0);
+        });
+        it('declares capabilities correctly', async () => {
+            adapter = await createAdapter();
+            const caps = adapter.capabilities;
+            expect(typeof caps.streaming).toBe('boolean');
+            expect(typeof caps.richFormatting).toBe('boolean');
+            expect(typeof caps.threads).toBe('boolean');
+            expect(typeof caps.reactions).toBe('boolean');
+            expect(typeof caps.fileUpload).toBe('boolean');
+            expect(typeof caps.voice).toBe('boolean');
+        });
+        it('sends text messages without error', async () => {
+            adapter = await createAdapter();
+            await expect(adapter.sendMessage('test-session', { type: 'text', text: 'hello' })).resolves.not.toThrow();
+        });
+        it('sends tool_call messages without error', async () => {
+            adapter = await createAdapter();
+            await expect(adapter.sendMessage('test-session', {
+                type: 'tool_call',
+                text: 'Read',
+                metadata: { id: 't1', name: 'Read', kind: 'read' },
+            })).resolves.not.toThrow();
+        });
+        it('sends usage messages without error', async () => {
+            adapter = await createAdapter();
+            await expect(adapter.sendMessage('test-session', {
+                type: 'usage',
+                text: '',
+                metadata: { tokensUsed: 1000, contextSize: 200000 },
+            })).resolves.not.toThrow();
+        });
+        it('sends error messages without error', async () => {
+            adapter = await createAdapter();
+            await expect(adapter.sendMessage('test-session', { type: 'error', text: 'something failed' })).resolves.not.toThrow();
+        });
+        it('handles session_end without error', async () => {
+            adapter = await createAdapter();
+            await expect(adapter.sendMessage('test-session', { type: 'session_end', text: 'finished' })).resolves.not.toThrow();
+        });
+        it('handles unknown message types gracefully', async () => {
+            adapter = await createAdapter();
+            await expect(adapter.sendMessage('test-session', { type: 'unknown_type', text: '' })).resolves.not.toThrow();
+        });
+        it('sendNotification does not throw', async () => {
+            adapter = await createAdapter();
+            await expect(adapter.sendNotification({
+                sessionId: 'test',
+                type: 'completed',
+                summary: 'done',
+            })).resolves.not.toThrow();
+        });
+    });
+}

package/dist/testing/mock-services.d.ts

@@ -0,0 +1,14 @@
+import type { SecurityService, FileServiceInterface, NotificationService, UsageService, SpeechServiceInterface, TunnelServiceInterface, ContextService } from '@openacp/cli';
+/**
+ * Factory functions that create mock implementations of OpenACP service interfaces.
+ * Each returns an object matching the service contract with sensible defaults.
+ */
+export declare const mockServices: {
+    security(overrides?: Partial<SecurityService>): SecurityService;
+    fileService(overrides?: Partial<FileServiceInterface>): FileServiceInterface;
+    notifications(overrides?: Partial<NotificationService>): NotificationService;
+    usage(overrides?: Partial<UsageService>): UsageService;
+    speech(overrides?: Partial<SpeechServiceInterface>): SpeechServiceInterface;
+    tunnel(overrides?: Partial<TunnelServiceInterface>): TunnelServiceInterface;
+    context(overrides?: Partial<ContextService>): ContextService;
+};

package/dist/testing/mock-services.js

@@ -0,0 +1,74 @@
+/**
+ * Factory functions that create mock implementations of OpenACP service interfaces.
+ * Each returns an object matching the service contract with sensible defaults.
+ */
+export const mockServices = {
+    security(overrides) {
+        return {
+            async checkAccess() { return { allowed: true }; },
+            async checkSessionLimit() { return { allowed: true }; },
+            async getUserRole() { return 'user'; },
+            ...overrides,
+        };
+    },
+    fileService(overrides) {
+        return {
+            async saveFile(_sessionId, fileName, _data, mimeType) {
+                return { type: 'file', filePath: `/tmp/${fileName}`, fileName, mimeType, size: 0 };
+            },
+            async resolveFile() { return null; },
+            async readTextFileWithRange() { return ''; },
+            extensionFromMime() { return '.bin'; },
+            async convertOggToWav(data) { return data; },
+            ...overrides,
+        };
+    },
+    notifications(overrides) {
+        return {
+            async notify() { },
+            async notifyAll() { },
+            ...overrides,
+        };
+    },
+    usage(overrides) {
+        return {
+            async trackUsage() { },
+            async checkBudget() { return { ok: true, percent: 0 }; },
+            ...overrides,
+        };
+    },
+    speech(overrides) {
+        return {
+            async textToSpeech() { return Buffer.alloc(0); },
+            async speechToText() { return ''; },
+            registerTTSProvider() { },
+            registerSTTProvider() { },
+            ...overrides,
+        };
+    },
+    tunnel(overrides) {
+        return {
+            getPublicUrl() { return 'http://localhost:0'; },
+            async start() { return 'http://localhost:0'; },
+            async stop() { },
+            getStore() {
+                return {
+                    storeFile() { return null; },
+                    storeDiff() { return null; },
+                    storeOutput() { return null; },
+                };
+            },
+            fileUrl(id) { return `http://localhost:0/file/${id}`; },
+            diffUrl(id) { return `http://localhost:0/diff/${id}`; },
+            outputUrl(id) { return `http://localhost:0/output/${id}`; },
+            ...overrides,
+        };
+    },
+    context(overrides) {
+        return {
+            async buildContext() { return ''; },
+            registerProvider() { },
+            ...overrides,
+        };
+    },
+};

package/dist/testing/test-context.d.ts

@@ -0,0 +1,36 @@
+import type { PluginContext, CommandDef, CommandResponse, OutgoingMessage } from '@openacp/cli';
+export interface TestContextOpts {
+    pluginName: string;
+    pluginConfig?: Record<string, unknown>;
+    permissions?: string[];
+    services?: Record<string, unknown>;
+    instanceRoot?: string;
+}
+export interface TestPluginContext extends PluginContext {
+    /** Services registered via registerService() */
+    registeredServices: Map<string, unknown>;
+    /** Commands registered via registerCommand() */
+    registeredCommands: Map<string, CommandDef>;
+    /** Middleware registered via registerMiddleware() */
+    registeredMiddleware: Array<{
+        hook: string;
+        opts: unknown;
+    }>;
+    /** Events emitted via emit() */
+    emittedEvents: Array<{
+        event: string;
+        payload: unknown;
+    }>;
+    /** Messages sent via sendMessage() */
+    sentMessages: Array<{
+        sessionId: string;
+        content: OutgoingMessage;
+    }>;
+    /** Dispatch a registered command by name */
+    executeCommand(name: string, args?: Partial<import('@openacp/cli').CommandArgs>): Promise<CommandResponse | void>;
+}
+/**
+ * Creates a test-friendly PluginContext for unit-testing plugins.
+ * All state is in-memory, logger is silent, services are pre-populated.
+ */
+export declare function createTestContext(opts: TestContextOpts): TestPluginContext;

package/dist/testing/test-context.js

@@ -0,0 +1,114 @@
+/**
+ * Creates a test-friendly PluginContext for unit-testing plugins.
+ * All state is in-memory, logger is silent, services are pre-populated.
+ */
+export function createTestContext(opts) {
+    const storageData = new Map();
+    const eventHandlers = new Map();
+    const registeredServices = new Map();
+    const registeredCommands = new Map();
+    const registeredMiddleware = [];
+    const emittedEvents = [];
+    const sentMessages = [];
+    // Pre-populate services from opts
+    if (opts.services) {
+        for (const [name, impl] of Object.entries(opts.services)) {
+            registeredServices.set(name, impl);
+        }
+    }
+    const storage = {
+        async get(key) {
+            return storageData.get(key);
+        },
+        async set(key, value) {
+            storageData.set(key, value);
+        },
+        async delete(key) {
+            storageData.delete(key);
+        },
+        async list() {
+            return Array.from(storageData.keys());
+        },
+        getDataDir() {
+            return '/tmp/openacp-test-data';
+        },
+    };
+    const silentLog = {
+        trace() { },
+        debug() { },
+        info() { },
+        warn() { },
+        error() { },
+        fatal() { },
+        child() { return silentLog; },
+    };
+    const ctx = {
+        pluginName: opts.pluginName,
+        pluginConfig: opts.pluginConfig ?? {},
+        instanceRoot: opts.instanceRoot ?? '/tmp/openacp-test',
+        // Events
+        on(event, handler) {
+            if (!eventHandlers.has(event)) {
+                eventHandlers.set(event, new Set());
+            }
+            eventHandlers.get(event).add(handler);
+        },
+        off(event, handler) {
+            eventHandlers.get(event)?.delete(handler);
+        },
+        emit(event, payload) {
+            emittedEvents.push({ event, payload });
+            const handlers = eventHandlers.get(event);
+            if (handlers) {
+                for (const handler of handlers) {
+                    handler(payload);
+                }
+            }
+        },
+        // Actions
+        registerMiddleware(hook, opts) {
+            registeredMiddleware.push({ hook, opts });
+        },
+        registerService(name, implementation) {
+            registeredServices.set(name, implementation);
+        },
+        getService(name) {
+            return registeredServices.get(name);
+        },
+        registerCommand(def) {
+            registeredCommands.set(def.name, def);
+        },
+        storage,
+        log: silentLog,
+        async sendMessage(sessionId, content) {
+            sentMessages.push({ sessionId, content });
+        },
+        // Kernel access stubs
+        sessions: {},
+        config: {},
+        eventBus: {},
+        core: {},
+        // Test-specific
+        registeredServices,
+        registeredCommands,
+        registeredMiddleware,
+        emittedEvents,
+        sentMessages,
+        async executeCommand(name, args) {
+            const cmd = registeredCommands.get(name);
+            if (!cmd) {
+                throw new Error(`Command not found: ${name}`);
+            }
+            const defaultArgs = {
+                raw: '',
+                sessionId: null,
+                channelId: 'test',
+                userId: 'test-user',
+                async reply() { },
+                ...args,
+            };
+            return cmd.handler(defaultArgs);
+        },
+    };
+    return ctx;
+}

package/dist/testing/test-install-context.d.ts

@@ -0,0 +1,20 @@
+import type { InstallContext } from '@openacp/cli';
+export interface TestInstallContextOpts {
+    pluginName: string;
+    legacyConfig?: Record<string, unknown>;
+    terminalResponses?: Record<string, unknown[]>;
+}
+interface TerminalCall {
+    method: string;
+    args: unknown;
+}
+/**
+ * Creates a test-friendly InstallContext for unit-testing plugin install/configure/uninstall.
+ * Terminal prompts are auto-answered from the provided responses map.
+ * Settings are stored in-memory.
+ */
+export declare function createTestInstallContext(opts: TestInstallContextOpts): InstallContext & {
+    terminalCalls: TerminalCall[];
+    settingsData: Map<string, unknown>;
+};
+export {};

package/dist/testing/test-install-context.js

@@ -0,0 +1,111 @@
+/**
+ * Creates a test-friendly InstallContext for unit-testing plugin install/configure/uninstall.
+ * Terminal prompts are auto-answered from the provided responses map.
+ * Settings are stored in-memory.
+ */
+export function createTestInstallContext(opts) {
+    const settingsData = new Map();
+    const terminalCalls = [];
+    const responseQueues = new Map();
+    // Deep-copy response queues so we don't mutate caller's arrays
+    if (opts.terminalResponses) {
+        for (const [method, responses] of Object.entries(opts.terminalResponses)) {
+            responseQueues.set(method, [...responses]);
+        }
+    }
+    function getNextResponse(method, args) {
+        terminalCalls.push({ method, args });
+        const queue = responseQueues.get(method);
+        if (queue && queue.length > 0) {
+            return queue.shift();
+        }
+        // Default responses by method type
+        switch (method) {
+            case 'text': return '';
+            case 'password': return '';
+            case 'confirm': return false;
+            case 'select': return undefined;
+            case 'multiselect': return [];
+            default: return undefined;
+        }
+    }
+    const terminal = {
+        async text(promptOpts) {
+            return getNextResponse('text', promptOpts);
+        },
+        async select(promptOpts) {
+            return getNextResponse('select', promptOpts);
+        },
+        async confirm(promptOpts) {
+            return getNextResponse('confirm', promptOpts);
+        },
+        async password(promptOpts) {
+            return getNextResponse('password', promptOpts);
+        },
+        async multiselect(promptOpts) {
+            return getNextResponse('multiselect', promptOpts);
+        },
+        log: {
+            info() { },
+            success() { },
+            warning() { },
+            error() { },
+            step() { },
+        },
+        spinner() {
+            return {
+                start() { },
+                stop() { },
+                fail() { },
+            };
+        },
+        note() { },
+        cancel() { },
+    };
+    const settings = {
+        async get(key) {
+            return settingsData.get(key);
+        },
+        async set(key, value) {
+            settingsData.set(key, value);
+        },
+        async getAll() {
+            return Object.fromEntries(settingsData);
+        },
+        async setAll(allSettings) {
+            settingsData.clear();
+            for (const [k, v] of Object.entries(allSettings)) {
+                settingsData.set(k, v);
+            }
+        },
+        async delete(key) {
+            settingsData.delete(key);
+        },
+        async clear() {
+            settingsData.clear();
+        },
+        async has(key) {
+            return settingsData.has(key);
+        },
+    };
+    const silentLog = {
+        trace() { },
+        debug() { },
+        info() { },
+        warn() { },
+        error() { },
+        fatal() { },
+        child() { return silentLog; },
+    };
+    return {
+        pluginName: opts.pluginName,
+        terminal,
+        settings,
+        legacyConfig: opts.legacyConfig,
+        dataDir: '/tmp/openacp-test-data',
+        log: silentLog,
+        // Test-specific
+        terminalCalls,
+        settingsData,
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,6 @@
+export { createTestContext } from './testing/test-context.js';
+export type { TestPluginContext, TestContextOpts } from './testing/test-context.js';
+export { createTestInstallContext } from './testing/test-install-context.js';
+export type { TestInstallContextOpts } from './testing/test-install-context.js';
+export { mockServices } from './testing/mock-services.js';
+export { runAdapterConformanceTests } from '@openacp/cli/testing';

package/dist/testing.js

@@ -0,0 +1,4 @@
+export { createTestContext } from './testing/test-context.js';
+export { createTestInstallContext } from './testing/test-install-context.js';
+export { mockServices } from './testing/mock-services.js';
+export { runAdapterConformanceTests } from '@openacp/cli/testing';

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@openacp/plugin-sdk",
+  "version": "2026.41.1",
+  "description": "SDK for building OpenACP plugins — types, base classes, and testing utilities",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./formatting": {
+      "types": "./dist/formatting.d.ts",
+      "import": "./dist/formatting.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@openacp/cli": ">=0.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Open-ACP/OpenACP",
+    "directory": "packages/plugin-sdk"
+  },
+  "homepage": "https://github.com/Open-ACP/OpenACP",
+  "keywords": [
+    "openacp",
+    "plugin",
+    "sdk",
+    "testing"
+  ],
+  "license": "MIT"
+}