@openacp/plugin-sdk 2026.326.2

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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, SpeechServiceInterface, TunnelServiceInterface, ContextService, } from '@openacp/cli';
+export type { IChannelAdapter, OutgoingMessage, PermissionRequest, PermissionOption, NotificationMessage, AgentCommand, } from '@openacp/cli';
+export { MessagingAdapter, StreamAdapter, BaseRenderer } from '@openacp/cli';
+export { SendQueue, DraftManager, ToolCallTracker, ActivityTracker } from '@openacp/cli';

package/dist/index.js

@@ -0,0 +1,4 @@
+// Adapter base classes
+export { MessagingAdapter, StreamAdapter, BaseRenderer } from '@openacp/cli';
+// Adapter primitives
+export { SendQueue, DraftManager, ToolCallTracker, ActivityTracker } from '@openacp/cli';

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,75 @@
+/**
+ * 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 }; },
+            async getSummary() {
+                return { period: 'today', totalTokens: 0, totalCost: 0, currency: 'USD', sessionCount: 0, recordCount: 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; },
+                };
+            },
+            fileUrl(id) { return `http://localhost:0/file/${id}`; },
+            diffUrl(id) { return `http://localhost:0/diff/${id}`; },
+            ...overrides,
+        };
+    },
+    context(overrides) {
+        return {
+            async buildContext() { return ''; },
+            registerProvider() { },
+            ...overrides,
+        };
+    },
+};

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

@@ -0,0 +1,35 @@
+import type { PluginContext, CommandDef, CommandResponse, OutgoingMessage } from '@openacp/cli';
+export interface TestContextOpts {
+    pluginName: string;
+    pluginConfig?: Record<string, unknown>;
+    permissions?: string[];
+    services?: Record<string, unknown>;
+}
+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,113 @@
+/**
+ * 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 ?? {},
+        // 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,5 @@
+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';

package/dist/testing.js

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@openacp/plugin-sdk",
+  "version": "2026.0326.2",
+  "description": "SDK for building OpenACP plugins — types, base classes, and testing utilities",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.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"
+}