@ericsanchezok/synergy-plugin 1.2.17 → 1.2.18

package/dist/example.d.ts

@@ -1,3 +1,3 @@
-import { Plugin } from "./index";
+import type { Plugin } from "./index";
 export declare const ExamplePlugin: Plugin;
 export default ExamplePlugin;

package/dist/example.js

@@ -26,63 +26,69 @@ function preview(text, limit = 160) {
         return singleLine;
     return `${singleLine.slice(0, limit - 1)}…`;
 }
-export const ExamplePlugin = async (ctx) => {
-    const logger = ctx.$.env({ SYNERGY_LOG_LEVEL: "warn" });
-    return {
-        tool: {
-            workspace_summary: tool({
-                description: "Summarize the active Synergy plugin runtime context",
-                args: {
-                    includeDirectorySample: tool.schema.boolean().optional().describe("Include a short directory listing sample"),
-                },
-                async execute(args, context) {
-                    const lines = [
-                        `scope: ${ctx.scope.type}:${ctx.scope.id}`,
-                        `directory: ${ctx.directory}`,
-                        `worktree: ${ctx.worktree}`,
-                        `server: ${ctx.serverUrl.toString()}`,
-                        `session: ${context.sessionID}`,
-                        `agent: ${context.agent}`,
-                    ];
-                    if (args.includeDirectorySample) {
-                        const result = await logger `ls`;
-                        const sample = result
-                            .text()
-                            .split("\n")
-                            .map((line) => line.trim())
-                            .filter(Boolean)
-                            .slice(0, 10);
-                        if (sample.length > 0) {
-                            lines.push(`entries: ${sample.join(", ")}`);
+export const ExamplePlugin = {
+    id: "example",
+    name: "Example Plugin",
+    async init(ctx) {
+        const logger = ctx.$.env({ SYNERGY_LOG_LEVEL: "warn" });
+        return {
+            tool: {
+                workspace_summary: tool({
+                    description: "Summarize the active Synergy plugin runtime context",
+                    args: {
+                        includeDirectorySample: tool.schema
+                            .boolean()
+                            .optional()
+                            .describe("Include a short directory listing sample"),
+                    },
+                    async execute(args, context) {
+                        const lines = [
+                            `scope: ${ctx.scope.type}:${ctx.scope.id}`,
+                            `directory: ${ctx.directory}`,
+                            `worktree: ${ctx.worktree}`,
+                            `server: ${ctx.serverUrl.toString()}`,
+                            `session: ${context.sessionID}`,
+                            `agent: ${context.agent}`,
+                        ];
+                        if (args.includeDirectorySample) {
+                            const result = await logger `ls`;
+                            const sample = result
+                                .text()
+                                .split("\n")
+                                .map((line) => line.trim())
+                                .filter(Boolean)
+                                .slice(0, 10);
+                            if (sample.length > 0) {
+                                lines.push(`entries: ${sample.join(", ")}`);
+                            }
                         }
-                    }
-                    return lines.join("\n");
-                },
-            }),
-        },
-        async "session.turn.after"(input) {
-            const status = input.error ? "error" : (input.finish ?? "unknown");
-            const summary = {
-                sessionID: input.sessionID,
-                assistantMessageID: input.assistantMessageID,
-                agent: input.assistant.agent,
-                finish: status,
-            };
-            console.info("[example-plugin] session.turn.after", summary);
-        },
-        async "note.create.before"(_, output) {
-            output.note.title = output.note.title.trim() || "Untitled note";
-            output.note.tags = mergeTags(output.note.tags);
-            if (!output.note.contentText?.trim()) {
-                output.note.contentText = preview(output.note.title);
-            }
-        },
-        async "engram.memory.search.after"(input, output) {
-            output.results = output.results
-                .slice()
-                .sort((left, right) => right.similarity - left.similarity)
-                .slice(0, input.topK);
-        },
-    };
+                        return lines.join("\n");
+                    },
+                }),
+            },
+            async "session.turn.after"(input) {
+                const status = input.error ? "error" : (input.finish ?? "unknown");
+                console.info("[example-plugin] session.turn.after", {
+                    sessionID: input.sessionID,
+                    assistantMessageID: input.assistantMessageID,
+                    agent: input.assistant.agent,
+                    finish: status,
+                });
+            },
+            async "note.create.before"(_, output) {
+                output.note.title = output.note.title.trim() || "Untitled note";
+                output.note.tags = mergeTags(output.note.tags);
+                if (!output.note.contentText?.trim()) {
+                    output.note.contentText = preview(output.note.title);
+                }
+            },
+            async "engram.memory.search.after"(input, output) {
+                output.results = output.results
+                    .slice()
+                    .sort((left, right) => right.similarity - left.similarity)
+                    .slice(0, input.topK);
+            },
+        };
+    },
 };
 export default ExamplePlugin;

package/dist/index.d.ts

@@ -1,38 +1,59 @@
 import type { AgendaItem, AgendaRunLog, CortexTask, Event, createSynergyClient, MemoryCategory, MemoryRecallMode, MemorySearchResult, Model, NoteCreateInput, NoteInfo, NotePatchInput, Provider, PermissionRequest, UserMessage, Message, Part, Auth, Config } from "@ericsanchezok/synergy-sdk";
 import type { BunShell } from "./shell";
-import { type ToolDefinition } from "./tool";
+import type { ToolDefinition, ToolResult } from "./tool";
 export * from "./tool";
+export type { ToolResult };
+export interface PluginConfigAccessor {
+    /** Get the plugin's full config object */
+    get(): Promise<Record<string, any>>;
+    /** Set one or more config values (deep-merged into the plugin's namespace) */
+    set(values: Record<string, any>): Promise<void>;
+}
+export interface PluginAuthStore {
+    /** Read a credential by key */
+    get(key: string): Promise<string | undefined>;
+    /** Persist a credential (encrypted at rest) */
+    set(key: string, value: string): Promise<void>;
+    /** Remove a credential */
+    delete(key: string): Promise<void>;
+    /** Check if a credential exists */
+    has(key: string): Promise<boolean>;
+}
+export interface PluginCacheStore {
+    /** Read a cached value */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Write a cached value with optional TTL in milliseconds */
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    /** Remove a cached value */
+    delete(key: string): Promise<void>;
+    /** Absolute path to this plugin's cache directory */
+    directory: string;
+}
+export interface PluginCLICommand {
+    description: string;
+    options?: Record<string, {
+        type: "string" | "boolean" | "number";
+        description?: string;
+        required?: boolean;
+    }>;
+    execute(args: Record<string, any>): Promise<string | void>;
+}
+export interface PluginCLIGroup {
+    description: string;
+    subcommands: Record<string, PluginCLICommand>;
+}
+export type PluginCLIEntry = PluginCLICommand | PluginCLIGroup;
+export interface PluginSkill {
+    name: string;
+    description: string;
+    content: string;
+    references?: Record<string, string>;
+}
 export type ProviderContext = {
     source: "env" | "config" | "custom" | "api";
     info: Provider;
     options: Record<string, any>;
 };
-export type PluginInput = {
-    client: ReturnType<typeof createSynergyClient>;
-    scope: {
-        type: "global" | "project";
-        id: string;
-        directory: string;
-        worktree: string;
-        vcs?: "git";
-        name?: string;
-        icon?: {
-            url?: string;
-            color?: string;
-        };
-        sandboxes?: string[];
-        time?: {
-            created: number;
-            updated: number;
-            initialized?: number;
-        };
-    };
-    directory: string;
-    worktree: string;
-    serverUrl: URL;
-    $: BunShell;
-};
-export type Plugin = (input: PluginInput) => Promise<Hooks>;
 export type AuthHook = {
     provider: string;
     loader?: (auth: () => Promise<Auth>, provider: Provider) => Promise<Record<string, any>>;
@@ -120,19 +141,61 @@ export type AuthOuathResult = {
         type: "failed";
     }>;
 });
-export interface Hooks {
-    event?: (input: {
-        event: Event;
-    }) => Promise<void>;
-    config?: (input: Config) => Promise<void>;
-    tool?: {
-        [key: string]: ToolDefinition;
+export type PluginInput = {
+    client: ReturnType<typeof createSynergyClient>;
+    scope: {
+        type: "global" | "project";
+        id: string;
+        directory: string;
+        worktree: string;
+        vcs?: "git";
+        name?: string;
+        icon?: {
+            url?: string;
+            color?: string;
+        };
+        sandboxes?: string[];
+        time?: {
+            created: number;
+            updated: number;
+            initialized?: number;
+        };
     };
+    directory: string;
+    worktree: string;
+    serverUrl: URL;
+    $: BunShell;
+    config: PluginConfigAccessor;
+    auth: PluginAuthStore;
+    cache: PluginCacheStore;
+};
+export interface Plugin {
+    /** Unique identifier for this plugin (used as config/auth/cache namespace) */
+    id: string;
+    /** Human-readable display name */
+    name?: string;
+    /** Initialize the plugin and return hooks */
+    init(input: PluginInput): Promise<PluginHooks>;
+}
+export interface PluginHooks {
+    /** Called when the plugin is being unloaded (e.g. runtime reload) */
+    dispose?(): Promise<void>;
+    /** Register CLI commands under `synergy <pluginId> ...` */
+    cli?: Record<string, PluginCLIEntry>;
+    /** Register skills that become available when this plugin is loaded */
+    skills?: PluginSkill[];
+    /** Register custom tools */
+    tool?: Record<string, ToolDefinition>;
+    /** Provider auth integration */
     auth?: AuthHook;
-    /**
-     * Called when a new message is received
-     */
-    "chat.message"?: (input: {
+    /** Observe runtime bus events */
+    event?(input: {
+        event: Event;
+    }): Promise<void>;
+    /** Observe the loaded runtime config */
+    config?(input: Config): Promise<void>;
+    /** Rewrite incoming user messages */
+    "chat.message"?(input: {
         sessionID: string;
         agent?: string;
         model?: {
@@ -144,11 +207,9 @@ export interface Hooks {
     }, output: {
         message: UserMessage;
         parts: Part[];
-    }) => Promise<void>;
-    /**
-     * Modify parameters sent to LLM
-     */
-    "chat.params"?: (input: {
+    }): Promise<void>;
+    /** Modify LLM parameters */
+    "chat.params"?(input: {
         sessionID: string;
         agent: string;
         model: Model;
@@ -159,18 +220,21 @@ export interface Hooks {
         topP: number;
         topK: number;
         options: Record<string, any>;
-    }) => Promise<void>;
-    "permission.ask"?: (input: PermissionRequest, output: {
+    }): Promise<void>;
+    /** Override permission decisions */
+    "permission.ask"?(input: PermissionRequest, output: {
         status: "ask" | "deny" | "allow";
-    }) => Promise<void>;
-    "tool.execute.before"?: (input: {
+    }): Promise<void>;
+    /** Rewrite tool args before execution */
+    "tool.execute.before"?(input: {
         tool: string;
         sessionID: string;
         callID: string;
     }, output: {
         args: any;
-    }) => Promise<void>;
-    "tool.execute.after"?: (input: {
+    }): Promise<void>;
+    /** Rewrite tool output after execution */
+    "tool.execute.after"?(input: {
         tool: string;
         sessionID: string;
         callID: string;
@@ -178,48 +242,48 @@ export interface Hooks {
         title: string;
         output: string;
         metadata: any;
-    }) => Promise<void>;
-    "experimental.chat.messages.transform"?: (input: {}, output: {
+    }): Promise<void>;
+    /** Rewrite chat message history sent to model */
+    "experimental.chat.messages.transform"?(input: {}, output: {
         messages: {
             info: Message;
             parts: Part[];
         }[];
-    }) => Promise<void>;
-    "experimental.chat.system.transform"?: (input: {}, output: {
+    }): Promise<void>;
+    /** Rewrite the assembled system prompt */
+    "experimental.chat.system.transform"?(input: {}, output: {
         system: string[];
-    }) => Promise<void>;
-    /**
-     * Called before session compaction starts. Allows plugins to customize
-     * the compaction prompt.
-     *
-     * - `context`: Additional context strings appended to the default prompt
-     * - `prompt`: If set, replaces the default compaction prompt entirely
-     */
-    "experimental.session.compacting"?: (input: {
+    }): Promise<void>;
+    /** Customize session compaction */
+    "experimental.session.compacting"?(input: {
         sessionID: string;
     }, output: {
         context: string[];
         prompt?: string;
-    }) => Promise<void>;
-    "experimental.text.complete"?: (input: {
+    }): Promise<void>;
+    /** Rewrite text completion output */
+    "experimental.text.complete"?(input: {
         sessionID: string;
         messageID: string;
         partID: string;
     }, output: {
         text: string;
-    }) => Promise<void>;
-    "session.turn.after"?: (input: {
+    }): Promise<void>;
+    /** Observe completed assistant turns */
+    "session.turn.after"?(input: {
         sessionID: string;
         userMessageID: string;
         assistantMessageID: string;
         assistant: Message;
         finish?: string;
         error?: unknown;
-    }, output: {}) => Promise<void>;
-    "cortex.task.after"?: (input: {
+    }, output: {}): Promise<void>;
+    /** Observe completed Cortex tasks */
+    "cortex.task.after"?(input: {
         task: CortexTask;
-    }, output: {}) => Promise<void>;
-    "agenda.run.before"?: (input: {
+    }, output: {}): Promise<void>;
+    /** Skip or rewrite agenda run */
+    "agenda.run.before"?(input: {
         signal: {
             type: string;
             source: string;
@@ -231,8 +295,9 @@ export interface Hooks {
     }, output: {
         skip: boolean;
         item: AgendaItem;
-    }) => Promise<void>;
-    "agenda.run.after"?: (input: {
+    }): Promise<void>;
+    /** Observe successful agenda runs */
+    "agenda.run.after"?(input: {
         signal: {
             type: string;
             source: string;
@@ -242,8 +307,9 @@ export interface Hooks {
         item: AgendaItem;
         run: AgendaRunLog;
         scopeID: string;
-    }, output: {}) => Promise<void>;
-    "agenda.run.error"?: (input: {
+    }, output: {}): Promise<void>;
+    /** Observe failed agenda runs */
+    "agenda.run.error"?(input: {
         signal: {
             type: string;
             source: string;
@@ -254,32 +320,37 @@ export interface Hooks {
         scopeID: string;
         error: string;
         sessionID?: string;
-    }, output: {}) => Promise<void>;
-    "note.create.before"?: (input: {
+    }, output: {}): Promise<void>;
+    /** Rewrite note creation input */
+    "note.create.before"?(input: {
         scopeID: string;
     }, output: {
         note: NoteCreateInput;
-    }) => Promise<void>;
-    "note.create.after"?: (input: {
+    }): Promise<void>;
+    /** Observe created notes */
+    "note.create.after"?(input: {
         scopeID: string;
         noteID: string;
     }, output: {
         note: NoteInfo;
-    }) => Promise<void>;
-    "note.update.before"?: (input: {
+    }): Promise<void>;
+    /** Rewrite note update patches */
+    "note.update.before"?(input: {
         scopeID: string;
         noteID: string;
         current: NoteInfo;
     }, output: {
         patch: NotePatchInput;
-    }) => Promise<void>;
-    "note.update.after"?: (input: {
+    }): Promise<void>;
+    /** Observe updated notes */
+    "note.update.after"?(input: {
         scopeID: string;
         noteID: string;
     }, output: {
         note: NoteInfo;
-    }) => Promise<void>;
-    "note.search.before"?: (input: {
+    }): Promise<void>;
+    /** Rewrite note search filters */
+    "note.search.before"?(input: {
         scopeID: string;
     }, output: {
         pattern: string;
@@ -288,28 +359,32 @@ export interface Hooks {
         before?: string;
         tags?: string[];
         pinned?: boolean;
-    }) => Promise<void>;
-    "note.search.after"?: (input: {
+    }): Promise<void>;
+    /** Filter or reorder note search results */
+    "note.search.after"?(input: {
         scopeID: string;
         pattern: string;
     }, output: {
         notes: NoteInfo[];
-    }) => Promise<void>;
-    "engram.memory.search.before"?: (input: {}, output: {
+    }): Promise<void>;
+    /** Rewrite memory search query */
+    "engram.memory.search.before"?(input: {}, output: {
         query: string;
         vector?: number[];
         topK?: number;
         categories?: MemoryCategory[];
         recallModes?: MemoryRecallMode[];
         rerank?: boolean;
-    }) => Promise<void>;
-    "engram.memory.search.after"?: (input: {
+    }): Promise<void>;
+    /** Filter or reorder memory results */
+    "engram.memory.search.after"?(input: {
         query: string;
         topK: number;
     }, output: {
         results: MemorySearchResult[];
-    }) => Promise<void>;
-    "engram.experience.encode.after"?: (input: {
+    }): Promise<void>;
+    /** Observe experience encoding outcomes */
+    "engram.experience.encode.after"?(input: {
         sessionID: string;
         userMessageID: string;
     }, output: {
@@ -317,5 +392,5 @@ export interface Hooks {
         skipped: boolean;
         duplicateOf?: string;
         experienceID?: string;
-    }) => Promise<void>;
+    }): Promise<void>;
 }

package/dist/tool.d.ts

@@ -5,14 +5,19 @@ export type ToolContext = {
     agent: string;
     abort: AbortSignal;
 };
+export interface ToolResult {
+    title?: string;
+    output: string;
+    metadata?: Record<string, any>;
+}
 export declare function tool<Args extends z.ZodRawShape>(input: {
     description: string;
     args: Args;
-    execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string>;
+    execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string | ToolResult>;
 }): {
     description: string;
     args: Args;
-    execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string>;
+    execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string | ToolResult>;
 };
 export declare namespace tool {
     var schema: typeof z;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@ericsanchezok/synergy-plugin",
-  "version": "1.2.17",
+  "version": "1.2.18",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,7 @@
     "dist"
   ],
   "dependencies": {
-    "@ericsanchezok/synergy-sdk": "1.2.17",
+    "@ericsanchezok/synergy-sdk": "1.2.18",
     "zod": "4.1.8"
   },
   "devDependencies": {