@ericsanchezok/synergy-plugin 2.4.4 → 2.4.5

package/README.md

@@ -102,6 +102,7 @@ const mediaDisplay = {
   media: {
     type: "image",
     aspectRatio: "1:1",
+    size: "small",
   },
 } as const
 
@@ -165,6 +166,69 @@ const plan = await context.task?.run({
 
 When `output.mode` is `structured`, Cortex validates the child task result against the schema and may run repair turns before completing. Cortex still stores its normal task trajectory summary in `task.result`; the structured value is returned to the plugin call site as `plan.outputResult.data`.
 
+## Hooks
+
+Plugins return hooks from `init()`. Hook permissions are declared in `plugin.json` and Synergy only invokes permissioned hooks.
+
+### Event hook
+
+`event(input)` observes runtime bus events without mutating them. Declare event access under `permissions.hooks`:
+
+```jsonc
+{
+  "permissions": {
+    "hooks": {
+      "events": "selected",
+      "eventNames": ["session.*", "message.updated"],
+    },
+  },
+}
+```
+
+`events` is `"none"`, `"selected"`, or `"all"`. In selected mode, `eventNames` supports exact names, `*` for all events, and prefix wildcards ending in `.*` such as `session.*`.
+
+```ts
+event(input) {
+  console.log(input.event.type, input.event.properties)
+}
+```
+
+### Config hook
+
+`config(input, output)` observes a redacted runtime config snapshot at startup, plugin reload, and config reload. Declare `permissions.hooks.config: true`; this permission is separate from `permissions.data.config`.
+
+```jsonc
+{
+  "permissions": {
+    "hooks": {
+      "config": true,
+    },
+  },
+}
+```
+
+```ts
+config(input, output) {
+  console.log(input.source, input.changedFields)
+  console.log(output.config.model)
+}
+```
+
+`input.source` is `"startup"`, `"plugin_reload"`, or `"reload"`. Secret fields in `output.config` are replaced with Synergy's redacted sentinel before dispatch.
+
+### System prompt transform
+
+`experimental.chat.system.transform(input, output)` can rewrite the assembled system prompt when `permissions.hooks.promptTransform` is `true`. Synergy calls this hook in two phases: `input.phase === "budget"` before token budgeting and `input.phase === "final"` before the provider call. The input includes `sessionID`, `agent`, `model`, `messageID`, and `small` for final calls.
+
+```ts
+"experimental.chat.system.transform"(input, output) {
+  if (input.phase !== "final") return
+  output.system.push("Additional final-call instruction.")
+}
+```
+
+If a transform empties `output.system`, Synergy restores the original system prompt.
+
 ## Plugin Input
 
 `init(input)` receives runtime services scoped to the active Synergy Scope:

package/dist/display.d.ts

@@ -4,6 +4,7 @@ export interface ToolMediaDisplay {
     pendingTitle?: string;
     pendingDescription?: string;
     aspectRatio?: "1:1" | "4:3" | "16:9" | "auto";
+    size?: "small" | "medium" | "large";
 }
 export interface ToolDisplay {
     kind?: "default" | "media-generation";

package/dist/example.d.ts

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

package/dist/example.js

@@ -1,4 +1,4 @@
-import { tool } from "./tool";
+import { tool } from "./tool.js";
 const MAX_NOTE_TAGS = 8;
 const AUTO_TAG = "reference-plugin";
 function normalizeTag(value) {

package/dist/hooks.js

@@ -21,13 +21,13 @@ export const HOOKS = [
         name: "config",
         category: "core",
         mutatesOutput: false,
-        summary: "Observe the loaded runtime config",
+        summary: "Observe redacted runtime config snapshots at startup and config reload",
     },
     {
         name: "event",
         category: "core",
         mutatesOutput: false,
-        summary: "Observe runtime bus events",
+        summary: "Observe permitted runtime bus events by exact or wildcard event name",
     },
     {
         name: "chat.message",
@@ -153,7 +153,7 @@ export const HOOKS = [
         name: "experimental.chat.system.transform",
         category: "experimental",
         mutatesOutput: true,
-        summary: "Rewrite the assembled system prompt",
+        summary: "Rewrite the assembled system prompt during budget and final phases",
     },
     {
         name: "experimental.session.compacting",

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-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, ToolResult } from "./tool";
-export * from "./tool";
-export type { ToolDisplay, ToolMediaDisplay } from "./display";
+import type { AgendaItem, AgendaRunLog, CortexTask, createSynergyClient, MemoryCategory, MemoryRecallMode, MemorySearchResult, Model, NoteCreateInput, NoteInfo, NotePatchInput, Provider, PermissionRequest, UserMessage, Message, Part, Auth, Config } from "@ericsanchezok/synergy-sdk";
+import type { BunShell } from "./shell.js";
+import type { ToolDefinition, ToolResult } from "./tool.js";
+export * from "./tool.js";
+export type { ToolDisplay, ToolMediaDisplay } from "./display.js";
 export type { ToolResult };
-export * from "./manifest";
-export * from "./policy";
-export * from "./spec";
-export * from "./version";
-export * from "./artifact";
-export type { BunShell, BunShellOutput, BunShellPromise, ShellExpression, ShellFunction } from "./shell";
+export * from "./manifest.js";
+export * from "./policy.js";
+export * from "./spec.js";
+export * from "./version.js";
+export * from "./artifact.js";
+export type { BunShell, BunShellOutput, BunShellPromise, ShellExpression, ShellFunction } from "./shell.js";
 export interface PluginConfigAccessor {
     /** Get the plugin's full config object */
     get(): Promise<Record<string, any>>;
@@ -367,6 +367,33 @@ export interface PluginDescriptor {
     /** Initialize the plugin and return hooks */
     init(input: PluginInput): Promise<PluginHooks>;
 }
+export interface PluginEventHookInput {
+    event: {
+        type: string;
+        properties: unknown;
+    };
+}
+export interface PluginConfigHookInput {
+    source: "startup" | "reload" | "plugin_reload";
+    scopeID?: string;
+    scopeType?: string;
+    changedFields?: string[];
+    timestamp: number;
+}
+export interface PluginConfigHookOutput {
+    config: Config;
+}
+export interface PluginChatSystemTransformInput {
+    phase: "budget" | "final";
+    sessionID: string;
+    agent: string;
+    model: {
+        providerID: string;
+        modelID: string;
+    };
+    messageID?: string;
+    small?: boolean;
+}
 export interface PluginHooks {
     /** Called when the plugin is being unloaded (e.g. runtime reload) */
     dispose?(): Promise<void>;
@@ -383,11 +410,9 @@ export interface PluginHooks {
     /** Provider runtime/catalog profiles */
     provider?: ProviderProfileHook | ProviderProfileHook[];
     /** Observe runtime bus events */
-    event?(input: {
-        event: Event;
-    }): Promise<void>;
-    /** Observe the loaded runtime config */
-    config?(input: Config): Promise<void>;
+    event?(input: PluginEventHookInput): Promise<void>;
+    /** Observe a redacted runtime config snapshot */
+    config?(input: PluginConfigHookInput, output: PluginConfigHookOutput): Promise<void>;
     /** Rewrite incoming user messages */
     "chat.message"?(input: {
         sessionID: string;
@@ -445,7 +470,7 @@ export interface PluginHooks {
         }[];
     }): Promise<void>;
     /** Rewrite the assembled system prompt */
-    "experimental.chat.system.transform"?(input: {}, output: {
+    "experimental.chat.system.transform"?(input: PluginChatSystemTransformInput, output: {
         system: string[];
     }): Promise<void>;
     /** Customize session compaction */

package/dist/index.js

@@ -1,6 +1,6 @@
-export * from "./tool";
-export * from "./manifest";
-export * from "./policy";
-export * from "./spec";
-export * from "./version";
-export * from "./artifact";
+export * from "./tool.js";
+export * from "./manifest.js";
+export * from "./policy.js";
+export * from "./spec.js";
+export * from "./version.js";
+export * from "./artifact.js";

package/dist/manifest.d.ts

@@ -88,6 +88,7 @@ export declare const PluginManifest: z.ZodObject<{
                 selected: "selected";
             }>>;
             eventNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            config: z.ZodDefault<z.ZodBoolean>;
             toolExecute: z.ZodDefault<z.ZodEnum<{
                 all: "all";
                 none: "none";
@@ -151,6 +152,11 @@ export declare const PluginManifest: z.ZodObject<{
                         "16:9": "16:9";
                         auto: "auto";
                     }>>;
+                    size: z.ZodOptional<z.ZodEnum<{
+                        small: "small";
+                        medium: "medium";
+                        large: "large";
+                    }>>;
                 }, z.core.$strict>>;
             }, z.core.$strict>>;
             capabilities: z.ZodOptional<z.ZodObject<{
@@ -403,6 +409,7 @@ export declare const PluginManifest: z.ZodObject<{
                     selected: "selected";
                 }>>;
                 eventNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                config: z.ZodDefault<z.ZodBoolean>;
                 toolExecute: z.ZodDefault<z.ZodEnum<{
                     all: "all";
                     none: "none";

package/dist/manifest.js

@@ -142,6 +142,7 @@ const ToolDisplayDef = z
         pendingTitle: z.string().min(1).max(120).optional(),
         pendingDescription: z.string().min(1).max(200).optional(),
         aspectRatio: z.enum(["1:1", "4:3", "16:9", "auto"]).optional(),
+        size: z.enum(["small", "medium", "large"]).optional(),
     })
         .strict()
         .optional(),
@@ -228,6 +229,7 @@ const PluginPermissionsSchema = z
         .object({
         events: z.enum(["none", "selected", "all"]).default("selected"),
         eventNames: z.array(z.string()).default([]),
+        config: z.boolean().default(false),
         toolExecute: z.enum(["none", "own", "declared", "all"]).default("own"),
         permissionAsk: z.enum(["none", "own", "all"]).default("none"),
         promptTransform: z.boolean().default(false),

package/dist/permissions.d.ts

@@ -1,4 +1,4 @@
-import type { PluginManifest } from "./manifest";
+import type { PluginManifest } from "./manifest.js";
 import type { BridgeMethodPolicy, RegistryPermissionItem, SynergyCapabilityCategory, SynergyCapabilityDefinition, SynergyCapabilityPermissionItem, SynergyCapabilityRisk, SynergyCapabilityRiskScope, SynergyCapabilitySeverity } from "@ericsanchezok/synergy-util/capability";
 import { bridgeMethodPolicy as sharedBridgeMethodPolicy, capabilityNonBypassable, hasPublicTools, permissionCategoryForKey, permissionCapability, publicToolNames, stablePluginJson } from "@ericsanchezok/synergy-util/capability";
 export type PluginRisk = SynergyCapabilityRisk;
@@ -11,7 +11,7 @@ export type PluginBridgeMethodPolicy = BridgeMethodPolicy;
 export type { RegistryPermissionItem, SynergyCapabilityDefinition };
 export type ManifestTool = NonNullable<NonNullable<PluginManifest["contributes"]>["tools"]>[number];
 export declare const CAPABILITY_DETAILS: Record<string, SynergyCapabilityDefinition>;
-export declare const PROFILE_CAPABILITIES: readonly ["file_read", "file_write", "shell_read", "shell", "shell_remote_write", "shell_remote_publish", "shell_destructive", "shell_hardline", "file_external_read", "file_external_write", "network_read", "network_request", "mcp_invoke", "mcp_spawn", "session_data", "workspace_data", "config:read", "config:write", "secrets", "task", "prompt_transform", "compaction_transform", "tool_execution_hook", "permission_hook", "event_hook", "identity_act", "communication_email", "channel_outbound", "platform_control", "protected_op", "session_state", "browser_interact", "browser_inspect", "browser_eval_readonly", "browser_eval_trusted", "browser_clipboard", "browser_download", "browser_viewport"];
+export declare const PROFILE_CAPABILITIES: readonly ["file_read", "file_write", "shell_read", "shell", "shell_remote_write", "shell_remote_publish", "shell_destructive", "shell_hardline", "file_external_read", "file_external_write", "network_read", "network_request", "mcp_invoke", "mcp_spawn", "session_data", "workspace_data", "config:read", "config:write", "secrets", "task", "prompt_transform", "compaction_transform", "tool_execution_hook", "permission_hook", "event_hook", "config_hook", "identity_act", "communication_email", "channel_outbound", "platform_control", "protected_op", "session_state", "browser_interact", "browser_inspect", "browser_eval_readonly", "browser_eval_trusted", "browser_clipboard", "browser_download", "browser_viewport"];
 export declare const PERMISSION_CAPABILITY: Record<string, string>;
 export declare const PLUGIN_BRIDGE_METHOD_POLICY: {
     readonly "config.get": {
@@ -133,6 +133,7 @@ export declare function permissionsHashPayload(manifest: PluginManifest, capabil
             permissionAsk?: "none" | "own" | "all";
             events?: "none" | "selected" | "all";
             eventNames?: string[];
+            config?: boolean;
         };
         network?: {
             connectDomains?: string[];

package/dist/spec.d.ts

@@ -1,3 +1,3 @@
-import type { PluginManifest } from "./manifest";
+import type { PluginManifest } from "./manifest.js";
 export declare function entryCandidatesFromPluginDir(pluginDir: string, manifest: PluginManifest): string[];
 export declare function resolveEntryFromPluginDir(pluginDir: string, manifest: PluginManifest): string;

package/dist/tool.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import type { ToolDisplay } from "./display";
-import type { BunShell } from "./shell";
-export type { ToolDisplay, ToolMediaDisplay } from "./display";
+import type { ToolDisplay } from "./display.js";
+import type { BunShell } from "./shell.js";
+export type { ToolDisplay, ToolMediaDisplay } from "./display.js";
 export type ToolContext = {
     sessionID: string;
     messageID: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@ericsanchezok/synergy-plugin",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -18,68 +18,68 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./tool": {
-      "import": "./dist/tool.js",
-      "types": "./dist/tool.d.ts"
+      "types": "./dist/tool.d.ts",
+      "import": "./dist/tool.js"
     },
     "./display": {
-      "import": "./dist/display.js",
-      "types": "./dist/display.d.ts"
+      "types": "./dist/display.d.ts",
+      "import": "./dist/display.js"
     },
     "./hooks": {
-      "import": "./dist/hooks.js",
-      "types": "./dist/hooks.d.ts"
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js"
     },
     "./permissions": {
-      "import": "./dist/permissions.js",
-      "types": "./dist/permissions.d.ts"
+      "types": "./dist/permissions.d.ts",
+      "import": "./dist/permissions.js"
     },
     "./ids": {
-      "import": "./dist/ids.js",
-      "types": "./dist/ids.d.ts"
+      "types": "./dist/ids.d.ts",
+      "import": "./dist/ids.js"
     },
     "./policy": {
-      "import": "./dist/policy.js",
-      "types": "./dist/policy.d.ts"
+      "types": "./dist/policy.d.ts",
+      "import": "./dist/policy.js"
     },
     "./paths": {
-      "import": "./dist/paths.js",
-      "types": "./dist/paths.d.ts"
+      "types": "./dist/paths.d.ts",
+      "import": "./dist/paths.js"
     },
     "./artifact": {
-      "import": "./dist/artifact.js",
-      "types": "./dist/artifact.d.ts"
+      "types": "./dist/artifact.d.ts",
+      "import": "./dist/artifact.js"
     },
     "./market": {
-      "import": "./dist/market.js",
-      "types": "./dist/market.d.ts"
+      "types": "./dist/market.d.ts",
+      "import": "./dist/market.js"
     },
     "./spec": {
-      "import": "./dist/spec.js",
-      "types": "./dist/spec.d.ts"
+      "types": "./dist/spec.d.ts",
+      "import": "./dist/spec.js"
     },
     "./version": {
-      "import": "./dist/version.js",
-      "types": "./dist/version.d.ts"
+      "types": "./dist/version.d.ts",
+      "import": "./dist/version.js"
     },
     "./shell": {
-      "import": "./dist/shell.js",
-      "types": "./dist/shell.d.ts"
+      "types": "./dist/shell.d.ts",
+      "import": "./dist/shell.js"
     },
     "./ui": {
-      "import": "./dist/ui.js",
-      "types": "./dist/ui.d.ts"
+      "types": "./dist/ui.d.ts",
+      "import": "./dist/ui.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@ericsanchezok/synergy-sdk": "2.4.4",
-    "@ericsanchezok/synergy-util": "2.4.4"
+    "@ericsanchezok/synergy-sdk": "2.4.5",
+    "@ericsanchezok/synergy-util": "2.4.5"
   },
   "peerDependencies": {
     "zod": ">=4.0.0"