synapsexcoder 6.0.0

package/dist/sdk/api.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Plugin SDK — Public API Surface
+ *
+ * Stable, documented API that SynapseXcoder exposes to third-party plugins.
+ * Provides controlled access to core services: Knowledge Vault, agent modes,
+ * agent listings, execution pipeline, and team collaboration.
+ *
+ * This is the ONLY API surface guaranteed to maintain backward compatibility
+ * across minor versions.
+ *
+ * @module sdk/api
+ */
+/** Standard API response wrapper */
+export interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/** Knowledge vault search result entry (public subset) */
+export interface VaultResult {
+    id: string;
+    title: string;
+    topic: string;
+    tags: string[];
+    summary?: string;
+}
+/** Agent mode descriptor */
+export interface ModeDescriptor {
+    id: string;
+    label: string;
+    description: string;
+    isBuiltIn: boolean;
+}
+/** Agent descriptor */
+export interface AgentDescriptor {
+    name: string;
+    description: string;
+}
+/**
+ * Stable public API for third-party plugins.
+ * All methods return `ApiResponse<T>` wrappers with typed results.
+ */
+export declare class PluginSdkApi {
+    private vaultSearchFn?;
+    private getModeFn?;
+    private listAgentsFn?;
+    private executeAgentFn?;
+    /**
+     * Configure internal API bindings (called by SDK host, not plugins).
+     */
+    configure(options: {
+        vaultSearch?: (query: string, limit?: number) => Promise<unknown[]>;
+        getMode?: (modeId: string) => unknown;
+        listAgents?: () => string[];
+        executeAgent?: (agentName: string, prompt: string) => Promise<string>;
+    }): void;
+    /**
+     * Search the SynapseXcoder Knowledge Vault.
+     * Returns matching entries with metadata.
+     */
+    vaultSearch(query: string, limit?: number): Promise<ApiResponse<VaultResult[]>>;
+    /**
+     * Get details about a specific processing mode.
+     */
+    getMode(modeId: string): ApiResponse<ModeDescriptor>;
+    /**
+     * List all available agents.
+     */
+    listAgents(): ApiResponse<AgentDescriptor[]>;
+    /**
+     * Execute a prompt using a named agent.
+     */
+    executeAgent(agentName: string, prompt: string): Promise<ApiResponse<string>>;
+    /**
+     * Check if the SDK API is fully initialized.
+     */
+    isReady(): boolean;
+    /**
+     * Get the set of available API capabilities.
+     */
+    getCapabilities(): string[];
+}
+/** Singleton instance of the Plugin SDK API */
+export declare const sdkApi: PluginSdkApi;
+//# sourceMappingURL=api.d.ts.map

package/dist/sdk/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/sdk/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,oCAAoC;AACpC,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,uBAAuB;AACvB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;GAGG;AACH,qBAAa,YAAY;IAEvB,OAAO,CAAC,aAAa,CAAC,CAAwD;IAC9E,OAAO,CAAC,SAAS,CAAC,CAA8B;IAChD,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,cAAc,CAAC,CAAyD;IAEhF;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE;QACjB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QACpE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QACtC,UAAU,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;KACvE,GAAG,IAAI;IASR;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;IAwBjF;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,cAAc,CAAC;IAoBpD;;OAEG;IACH,UAAU,IAAI,WAAW,CAAC,eAAe,EAAE,CAAC;IAqB5C;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAiBnF;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,eAAe,IAAI,MAAM,EAAE;CAQ5B;AAED,+CAA+C;AAC/C,eAAO,MAAM,MAAM,cAAqB,CAAC"}

package/dist/sdk/api.js

@@ -0,0 +1,155 @@
+/**
+ * Plugin SDK — Public API Surface
+ *
+ * Stable, documented API that SynapseXcoder exposes to third-party plugins.
+ * Provides controlled access to core services: Knowledge Vault, agent modes,
+ * agent listings, execution pipeline, and team collaboration.
+ *
+ * This is the ONLY API surface guaranteed to maintain backward compatibility
+ * across minor versions.
+ *
+ * @module sdk/api
+ */
+// ========================================================================
+// Plugin SDK API Class
+// ========================================================================
+/**
+ * Stable public API for third-party plugins.
+ * All methods return `ApiResponse<T>` wrappers with typed results.
+ */
+export class PluginSdkApi {
+    // -- Internal references (set by SDK integration layer) --
+    vaultSearchFn;
+    getModeFn;
+    listAgentsFn;
+    executeAgentFn;
+    /**
+     * Configure internal API bindings (called by SDK host, not plugins).
+     */
+    configure(options) {
+        if (options.vaultSearch)
+            this.vaultSearchFn = options.vaultSearch;
+        if (options.getMode)
+            this.getModeFn = options.getMode;
+        if (options.listAgents)
+            this.listAgentsFn = options.listAgents;
+        if (options.executeAgent)
+            this.executeAgentFn = options.executeAgent;
+    }
+    // ── Knowledge Vault ──
+    /**
+     * Search the SynapseXcoder Knowledge Vault.
+     * Returns matching entries with metadata.
+     */
+    async vaultSearch(query, limit = 10) {
+        if (!this.vaultSearchFn) {
+            return { success: false, error: "Knowledge Vault is not available" };
+        }
+        try {
+            const raw = await this.vaultSearchFn(query, limit);
+            const results = raw.map((entry) => ({
+                id: String(entry.id ?? ""),
+                title: String(entry.title ?? ""),
+                topic: String(entry.topic ?? ""),
+                tags: Array.isArray(entry.tags) ? entry.tags.map(String) : [],
+                summary: entry.summary ? String(entry.summary) : undefined,
+            }));
+            return { success: true, data: results };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown vault search error",
+            };
+        }
+    }
+    // ── Modes ──
+    /**
+     * Get details about a specific processing mode.
+     */
+    getMode(modeId) {
+        if (!this.getModeFn) {
+            return { success: false, error: "Mode system is not available" };
+        }
+        try {
+            const mode = this.getModeFn(modeId);
+            if (!mode) {
+                return { success: false, error: `Mode "${modeId}" not found` };
+            }
+            return { success: true, data: mode };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error getting mode",
+            };
+        }
+    }
+    // ── Agents ──
+    /**
+     * List all available agents.
+     */
+    listAgents() {
+        if (!this.listAgentsFn) {
+            return { success: false, error: "Agent system is not available" };
+        }
+        try {
+            const names = this.listAgentsFn();
+            const agents = names.map((name) => ({
+                name,
+                description: `${name} agent`,
+            }));
+            return { success: true, data: agents };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error listing agents",
+            };
+        }
+    }
+    // ── Execution ──
+    /**
+     * Execute a prompt using a named agent.
+     */
+    async executeAgent(agentName, prompt) {
+        if (!this.executeAgentFn) {
+            return { success: false, error: "Agent execution is not available" };
+        }
+        try {
+            const result = await this.executeAgentFn(agentName, prompt);
+            return { success: true, data: result };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown agent execution error",
+            };
+        }
+    }
+    // ── Health ──
+    /**
+     * Check if the SDK API is fully initialized.
+     */
+    isReady() {
+        return this.vaultSearchFn !== undefined;
+    }
+    /**
+     * Get the set of available API capabilities.
+     */
+    getCapabilities() {
+        const caps = [];
+        if (this.vaultSearchFn)
+            caps.push("vault:search");
+        if (this.getModeFn)
+            caps.push("modes:read");
+        if (this.listAgentsFn)
+            caps.push("agents:list");
+        if (this.executeAgentFn)
+            caps.push("agents:execute");
+        return caps;
+    }
+}
+/** Singleton instance of the Plugin SDK API */
+export const sdkApi = new PluginSdkApi();
+//# sourceMappingURL=api.js.map

package/dist/sdk/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/sdk/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoCH,2EAA2E;AAC3E,uBAAuB;AACvB,2EAA2E;AAE3E;;;GAGG;AACH,MAAM,OAAO,YAAY;IACvB,2DAA2D;IACnD,aAAa,CAAyD;IACtE,SAAS,CAA+B;IACxC,YAAY,CAAkB;IAC9B,cAAc,CAA0D;IAEhF;;OAEG;IACH,SAAS,CAAC,OAKT;QACC,IAAI,OAAO,CAAC,WAAW;YAAE,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC;QAClE,IAAI,OAAO,CAAC,OAAO;YAAE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;QACtD,IAAI,OAAO,CAAC,UAAU;YAAE,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;QAC/D,IAAI,OAAO,CAAC,YAAY;YAAE,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IACvE,CAAC;IAED,wBAAwB;IAExB;;;OAGG;IACH,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,KAAK,GAAG,EAAE;QACzC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kCAAkC,EAAE,CAAC;QACvE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACnD,MAAM,OAAO,GAAmB,GAAa,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC5D,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;gBAC1B,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;gBAChC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;gBAChC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;gBAC7D,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;aAC3D,CAAC,CAAC,CAAC;YACJ,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,4BAA4B;aACzE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,cAAc;IAEd;;OAEG;IACH,OAAO,CAAC,MAAc;QACpB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC;QACnE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAA+B,CAAC;YAClE,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,MAAM,aAAa,EAAE,CAAC;YACjE,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACvC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,4BAA4B;aACzE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,eAAe;IAEf;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,+BAA+B,EAAE,CAAC;QACpE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YAClC,MAAM,MAAM,GAAsB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACrD,IAAI;gBACJ,WAAW,EAAE,GAAG,IAAI,QAAQ;aAC7B,CAAC,CAAC,CAAC;YACJ,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,8BAA8B;aAC3E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,kBAAkB;IAElB;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,SAAiB,EAAE,MAAc;QAClD,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kCAAkC,EAAE,CAAC;QACvE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC5D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,+BAA+B;aAC5E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,eAAe;IAEf;;OAEG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,aAAa,KAAK,SAAS,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,eAAe;QACb,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,aAAa;YAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAClD,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC5C,IAAI,IAAI,CAAC,YAAY;YAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAChD,IAAI,IAAI,CAAC,cAAc;YAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC"}

package/dist/sdk/hooks.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Plugin SDK — Lifecycle Hooks
+ *
+ * Type-safe event system for plugin lifecycle hooks.
+ * Allows plugins to subscribe to SynapseXcoder lifecycle events
+ * (activation, deactivation, config changes, mode switches, etc.)
+ * with automatic cleanup on plugin deactivation.
+ *
+ * @module sdk/hooks
+ */
+/** All available lifecycle hooks */
+export type LifecycleHook = "plugin:activated" | "plugin:deactivated" | "config:changed" | "mode:switched" | "agent:beforeExecute" | "agent:afterExecute" | "session:created" | "session:ended" | "vault:beforeSearch" | "vault:afterSearch" | "vault:entryAdded" | "vault:entryRemoved" | "team:memberJoined" | "team:memberLeft" | "error:occurred" | "shutdown";
+/** Hook handler function type */
+export type HookHandler = (data?: unknown) => void | Promise<void>;
+/**
+ * Registry for lifecycle hooks.
+ *
+ * Supports:
+ * - Registering handlers with `on()`
+ * - One-shot handlers with `once()`
+ * - Emitting events with `emit()`
+ * - Unregistering with `off()` or the cleanup function returned by `on()`
+ * - Querying registered hooks with `listHandlers()`
+ */
+export declare class HookRegistry {
+    private handlers;
+    /**
+     * Register a handler for a lifecycle hook.
+     * Returns a cleanup function to unregister.
+     */
+    on(hook: LifecycleHook, handler: HookHandler): () => void;
+    /**
+     * Register a one-shot handler that fires once then auto-unregisters.
+     */
+    once(hook: LifecycleHook, handler: HookHandler): () => void;
+    /**
+     * Unregister a specific handler for a hook.
+     */
+    off(hook: LifecycleHook, handler: HookHandler): void;
+    /**
+     * Emit a lifecycle event, calling all registered handlers.
+     * Supports both sync and async handlers.
+     */
+    emit(hook: LifecycleHook, data?: unknown): Promise<void>;
+    /**
+     * List all registered handlers for a given hook.
+     */
+    listHandlers(hook: LifecycleHook): number;
+    /**
+     * List all hooks that have at least one handler registered.
+     */
+    listActiveHooks(): LifecycleHook[];
+    /**
+     * Remove all handlers for all hooks.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/sdk/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/sdk/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,oCAAoC;AACpC,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,oBAAoB,GACpB,gBAAgB,GAChB,eAAe,GACf,qBAAqB,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,eAAe,GACf,oBAAoB,GACpB,mBAAmB,GACnB,kBAAkB,GAClB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,UAAU,CAAC;AAEf,iCAAiC;AACjC,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAMnE;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAA0E;IAE1F;;;OAGG;IACH,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,IAAI;IAWzD;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,IAAI;IAW3D;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAWpD;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB9D;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM;IAIzC;;OAEG;IACH,eAAe,IAAI,aAAa,EAAE;IAUlC;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/sdk/hooks.js

@@ -0,0 +1,115 @@
+/**
+ * Plugin SDK — Lifecycle Hooks
+ *
+ * Type-safe event system for plugin lifecycle hooks.
+ * Allows plugins to subscribe to SynapseXcoder lifecycle events
+ * (activation, deactivation, config changes, mode switches, etc.)
+ * with automatic cleanup on plugin deactivation.
+ *
+ * @module sdk/hooks
+ */
+// ========================================================================
+// Hook Registry
+// ========================================================================
+/**
+ * Registry for lifecycle hooks.
+ *
+ * Supports:
+ * - Registering handlers with `on()`
+ * - One-shot handlers with `once()`
+ * - Emitting events with `emit()`
+ * - Unregistering with `off()` or the cleanup function returned by `on()`
+ * - Querying registered hooks with `listHandlers()`
+ */
+export class HookRegistry {
+    handlers = new Map();
+    /**
+     * Register a handler for a lifecycle hook.
+     * Returns a cleanup function to unregister.
+     */
+    on(hook, handler) {
+        if (!this.handlers.has(hook)) {
+            this.handlers.set(hook, new Set());
+        }
+        const entry = { handler, once: false };
+        this.handlers.get(hook).add(entry);
+        return () => {
+            this.handlers.get(hook)?.delete(entry);
+        };
+    }
+    /**
+     * Register a one-shot handler that fires once then auto-unregisters.
+     */
+    once(hook, handler) {
+        if (!this.handlers.has(hook)) {
+            this.handlers.set(hook, new Set());
+        }
+        const entry = { handler, once: true };
+        this.handlers.get(hook).add(entry);
+        return () => {
+            this.handlers.get(hook)?.delete(entry);
+        };
+    }
+    /**
+     * Unregister a specific handler for a hook.
+     */
+    off(hook, handler) {
+        const handlers = this.handlers.get(hook);
+        if (!handlers)
+            return;
+        for (const entry of handlers) {
+            if (entry.handler === handler) {
+                handlers.delete(entry);
+                break;
+            }
+        }
+    }
+    /**
+     * Emit a lifecycle event, calling all registered handlers.
+     * Supports both sync and async handlers.
+     */
+    async emit(hook, data) {
+        const handlers = this.handlers.get(hook);
+        if (!handlers)
+            return;
+        // Snapshot to avoid issues if handlers mutate the set during iteration
+        const snapshot = [...handlers];
+        for (const entry of snapshot) {
+            // Mark consumed before await to prevent double-fire in concurrent emits
+            if (entry.once) {
+                handlers.delete(entry);
+            }
+            try {
+                await entry.handler(data);
+            }
+            catch (err) {
+                console.error(`[HookRegistry] Handler error for hook "${hook}":`, err instanceof Error ? err.message : String(err));
+            }
+        }
+    }
+    /**
+     * List all registered handlers for a given hook.
+     */
+    listHandlers(hook) {
+        return this.handlers.get(hook)?.size ?? 0;
+    }
+    /**
+     * List all hooks that have at least one handler registered.
+     */
+    listActiveHooks() {
+        const active = [];
+        for (const [hook, handlers] of this.handlers) {
+            if (handlers.size > 0) {
+                active.push(hook);
+            }
+        }
+        return active;
+    }
+    /**
+     * Remove all handlers for all hooks.
+     */
+    clear() {
+        this.handlers.clear();
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/sdk/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/sdk/hooks.ts"],"names":[],"mappings":"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"}

package/dist/sdk/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Plugin SDK Module — Third-Party Extension SDK
+ *
+ * Provides a type-safe, ergonomic SDK for building third-party plugins.
+ * Wraps the core plugin system with stable APIs, lifecycle hooks,
+ * typed configuration, and backward compatibility guarantees.
+ *
+ * @module sdk
+ */
+export { BasePlugin } from "./plugin-base.js";
+export { PluginConfig } from "./plugin-base.js";
+export type { PluginMeta, PluginRuntimeContext, } from "./plugin-base.js";
+export { HookRegistry } from "./hooks.js";
+export type { LifecycleHook, HookHandler } from "./hooks.js";
+export { PluginSdkApi, sdkApi } from "./api.js";
+export type { ApiResponse, VaultResult, ModeDescriptor, AgentDescriptor, } from "./api.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EACV,UAAU,EACV,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,eAAe,GAChB,MAAM,UAAU,CAAC"}

package/dist/sdk/index.js

@@ -0,0 +1,14 @@
+/**
+ * Plugin SDK Module — Third-Party Extension SDK
+ *
+ * Provides a type-safe, ergonomic SDK for building third-party plugins.
+ * Wraps the core plugin system with stable APIs, lifecycle hooks,
+ * typed configuration, and backward compatibility guarantees.
+ *
+ * @module sdk
+ */
+export { BasePlugin } from "./plugin-base.js";
+export { PluginConfig } from "./plugin-base.js";
+export { HookRegistry } from "./hooks.js";
+export { PluginSdkApi, sdkApi } from "./api.js";
+//# sourceMappingURL=index.js.map

package/dist/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMhD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/sdk/plugin-base.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Plugin SDK — Base Plugin Class
+ *
+ * Provides a type-safe, ergonomic base class for third-party plugins.
+ * Wraps the lower-level plugin-system.ts with lifecycle hooks,
+ * typed configuration, and event-driven architecture.
+ *
+ * @module sdk/plugin-base
+ */
+import type { LifecycleHook } from "./hooks.js";
+import { HookRegistry } from "./hooks.js";
+/**
+ * Plugin metadata descriptor — used for registration and discovery.
+ */
+export interface PluginMeta {
+    /** Unique plugin ID (reverse-domain notation recommended) */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Semantic version */
+    version: string;
+    /** Short description */
+    description: string;
+    /** Author name or organization */
+    author: string;
+    /** Minimum SynapseXcoder version required */
+    minSynapseVersion?: string;
+    /** Plugin category */
+    category?: "agent" | "tool" | "integration" | "theme" | "data-source" | "utility";
+    /** URL for documentation/issues */
+    homepage?: string;
+    /** License identifier (SPDX) */
+    license?: string;
+}
+/**
+ * Typed plugin configuration wrapper.
+ * Provides get/set/reset with schema validation.
+ */
+export declare class PluginConfig<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+    private config;
+    private originalDefaults;
+    private schema;
+    constructor(defaults: TConfig, schema?: Record<keyof TConfig, {
+        type: string;
+        required?: boolean;
+        default?: unknown;
+    }>);
+    /** Get a configuration value */
+    get<K extends keyof TConfig>(key: K): TConfig[K];
+    /** Set a configuration value (with type validation if schema defined) */
+    set<K extends keyof TConfig>(key: K, value: TConfig[K]): void;
+    /** Get all configuration */
+    getAll(): TConfig;
+    /** Reset configuration to defaults (original values overlaid with schema defaults) */
+    reset(): void;
+    /** Validate configuration against schema */
+    validate(): string[];
+    private getDefaults;
+}
+/**
+ * Runtime context provided to every activated plugin.
+ * Provides access to SynapseXcoder services with a stable, documented API.
+ */
+export interface PluginRuntimeContext {
+    /** Plugin ID */
+    pluginId: string;
+    /** Logger scoped to this plugin */
+    logger: {
+        info: (msg: string, ...args: unknown[]) => void;
+        warn: (msg: string, ...args: unknown[]) => void;
+        error: (msg: string, ...args: unknown[]) => void;
+        debug: (msg: string, ...args: unknown[]) => void;
+    };
+    /** Storage API for persisting plugin data */
+    storage: {
+        get: <T>(key: string) => T | undefined;
+        set: <T>(key: string, value: T) => void;
+        delete: (key: string) => void;
+        clear: () => void;
+        getAll: () => Record<string, unknown>;
+    };
+    /** Hook registry for subscribing to lifecycle events */
+    hooks: HookRegistry;
+    /** API surface for interacting with SynapseXcoder core */
+    api: {
+        /** Search the knowledge vault */
+        vaultSearch: (query: string, limit?: number) => Promise<unknown[]>;
+        /** Get agent mode configuration */
+        getMode: (modeId: string) => unknown;
+        /** List available agents */
+        listAgents: () => string[];
+    };
+}
+/**
+ * Base plugin class that all third-party plugins should extend.
+ *
+ * Provides:
+ * - Lifecycle hooks (onActivate, onDeactivate, onConfigChange)
+ * - Typed configuration with validation
+ * - Logger scoped to plugin
+ * - Simple key-value storage
+ * - Access to SynapseXcoder API
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends BasePlugin<{ apiKey: string }> {
+ *   id = "com.example.my-plugin";
+ *   name = "My Plugin";
+ *   version = "1.0.0";
+ *   description = "Does amazing things";
+ *   author = "Example Corp";
+ *
+ *   configDefaults = { apiKey: "" };
+ *
+ *   async onActivate(ctx: PluginRuntimeContext): Promise<void> {
+ *     ctx.logger.info("Plugin activated!");
+ *     const apiKey = this.config.get("apiKey");
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BasePlugin<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly version: string;
+    abstract readonly description: string;
+    abstract readonly author: string;
+    readonly minSynapseVersion?: string;
+    readonly category?: PluginMeta["category"];
+    readonly homepage?: string;
+    readonly license?: string;
+    /** Default configuration values (override in subclass) */
+    configDefaults: TConfig;
+    /** Optional schema for config validation */
+    configSchema?: Record<keyof TConfig, {
+        type: string;
+        required?: boolean;
+        default?: unknown;
+    }>;
+    /** Typed configuration instance */
+    config: PluginConfig<TConfig>;
+    /** Runtime context set during activation */
+    context: PluginRuntimeContext | null;
+    /** Whether the plugin is currently active */
+    active: boolean;
+    /** When the plugin was last activated */
+    activatedAt: number | null;
+    private storage;
+    private hookCleanups;
+    /**
+     * Get plugin metadata object.
+     */
+    get meta(): PluginMeta;
+    /**
+     * Initialize the plugin — called by the SDK before activation.
+     * Sets up config and context.
+     */
+    initialize(): void;
+    /**
+     * Activate the plugin — called by the SDK when the plugin is loaded.
+     *
+     * @param context - Runtime context provided by the SDK
+     */
+    activate(context: PluginRuntimeContext): Promise<void>;
+    /**
+     * Deactivate the plugin — called by the SDK when the plugin is disabled.
+     */
+    deactivate(): Promise<void>;
+    /**
+     * Called when the plugin is activated.
+     * Override to set up resources, register hooks, start background tasks.
+     */
+    protected onActivate(_context: PluginRuntimeContext): Promise<void>;
+    /**
+     * Called when the plugin is deactivated.
+     * Override to clean up resources, close connections, save state.
+     */
+    protected onDeactivate(): Promise<void>;
+    /**
+     * Called when plugin configuration changes at runtime.
+     * Override to react to config updates (e.g., reconnect with new API key).
+     */
+    protected onConfigChange(_changes: Partial<TConfig>): void;
+    /**
+     * Subscribe to a lifecycle hook with automatic cleanup on deactivation.
+     */
+    protected onHook(hook: LifecycleHook, handler: () => void): void;
+    /**
+     * Convert this BasePlugin to the lower-level PluginModule interface
+     * used by plugin-system.ts for registration.
+     */
+    toPluginModule(): {
+        activate: (ctx: PluginRuntimeContext) => Promise<void>;
+        deactivate: () => Promise<void>;
+    };
+}
+//# sourceMappingURL=plugin-base.d.ts.map