@ericsanchezok/synergy-plugin 2.4.3 → 2.4.5

package/README.md

@@ -65,15 +65,14 @@ export default plugin
 
 Tools can return user-facing files through `attachments`. Use the generated SDK `asset.upload()` route or the public `/asset` endpoint to upload binary data, then return the resulting `asset://...` URL. Do not import Synergy internal asset modules from a plugin.
 
-For visual tools whose output belongs in the main answer area, set `metadata.display.presentation` to `artifact-only` and list the attachment ids to promote:
+For visual tools whose output belongs in the main answer area, hide the tool card and set presentation on the returned attachment:
 
 ```ts
 return {
   output: "",
   metadata: {
     display: {
-      presentation: "artifact-only",
-      primaryAttachmentIds: [partId],
+      toolCard: "hidden",
     },
   },
   attachments: [
@@ -81,31 +80,29 @@ return {
       id: partId,
       sessionID: context.sessionID,
       messageID: context.messageID,
-      type: "file",
+      type: "attachment",
       mime: "image/svg+xml",
       filename: "result.svg",
       url: uploaded.url,
+      presentation: { renderer: "image", size: "medium", crop: false },
+      model: { mode: "summary", summary: "Generated SVG result." },
     },
   ],
 }
 ```
 
-Running and failed tool states still render normally, so progress, approvals, and errors remain visible.
+Each attachment controls its own display with `presentation.hidden`, `presentation.renderer`, `presentation.size`, and `presentation.crop`. Omit `renderer` to let Synergy choose from the MIME type.
 
-For image, video, or audio generation tools, declare the display protocol on the tool definition as well. This lets Synergy show its built-in media generation placeholder as soon as the tool starts, then replace it with the promoted attachment when the tool completes:
+For image, video, or audio generation tools, declare the display protocol on the tool definition as well. This lets Synergy show its built-in media generation placeholder as soon as the tool starts, then replace it with the completed attachment in the original message order:
 
 ```ts
 const mediaDisplay = {
   kind: "media-generation",
-  visibility: "media",
-  presentation: "artifact-only",
+  toolCard: "hidden",
   media: {
     type: "image",
-    actionLabel: "Create image",
-    pendingTitle: "Generating image",
-    pendingDescription: "Preparing the image...",
-    promptField: "prompt",
     aspectRatio: "1:1",
+    size: "small",
   },
 } as const
 
@@ -116,12 +113,12 @@ tool({
     prompt: tool.schema.string(),
   },
   async execute(args, context) {
-    // Upload the generated image, then return metadata.display with primaryAttachmentIds.
+    // Upload the generated image, then return it with attachment-level presentation.
   },
 })
 ```
 
-Use `visibility: "media"` for tools whose running and completed success states belong on the media surface. Error states still fall back to normal tool cards.
+Use `toolCard: "hidden"` for tools whose running and completed states belong on a dedicated surface instead of a tool card. Optional media labels are for accessibility and host-specific status surfaces; Synergy does not show tool input parameters as transcript copy.
 
 ## Internal Tools And Delegated Tasks
 
@@ -152,7 +149,7 @@ const plan = await context.task?.run({
     "plugin__my-plugin__private_helper": true,
   },
   visibility: "hidden",
-  timeoutMs: 30_000,
+  timeoutMs: 120_000,
   output: {
     mode: "structured",
     schema: {
@@ -169,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:
@@ -188,7 +248,7 @@ type PluginInput = {
 }
 ```
 
-For isolated worker/process plugins, these services are proxied through the host bridge and checked against the plugin approval record.
+For isolated worker/process plugins, these services are proxied through the host bridge and checked against the plugin approval record. Workspace file and shell bridge calls require an active plugin tool context; read plugin package assets directly from `input.pluginDir`.
 
 ## Manifest
 
@@ -200,9 +260,11 @@ Each distributable plugin has a root `plugin.json`:
   "version": "0.1.0",
   "description": "Example Synergy plugin",
   "main": "./src/index.ts",
+  "engines": {
+    "synergy": ">=2.4.3",
+  },
   "permissions": {
     "tools": {
-      "invoke": true,
       "filesystem": "none",
       "network": false,
       "shell": false,
@@ -235,15 +297,50 @@ Each distributable plugin has a root `plugin.json`:
 
 `contributes.ui.entry` is a runtime-loadable JavaScript asset. Source files such as `src/ui.tsx` are only build inputs. `synergy-plugin build` uses the conventional UI source path and writes the compiled bundle to the declared entry.
 
+Session workbench UI uses `contributes.ui.workbenchPanels`. A workbench panel declares which surface it belongs to and how its tabs behave:
+
+```jsonc
+{
+  "contributes": {
+    "ui": {
+      "entry": "./dist/ui/index.js",
+      "workbenchPanels": [
+        {
+          "id": "build-log",
+          "label": "Build Log",
+          "icon": "terminal",
+          "exportName": "BuildLogPanel",
+          "surface": "bottom",
+          "cardinality": "multi",
+          "requiresSession": true,
+        },
+      ],
+    },
+  },
+  "permissions": {
+    "ui": {
+      "workbenchPanels": true,
+    },
+  },
+}
+```
+
+`surface` is `"side"` or `"bottom"`. `cardinality` is `"exclusive"` for one active panel on that surface, `"singleton"` for one tab per panel id, or `"multi"` for a new tab each time. `requiresSession` hides the panel until the user is in a concrete session. App panels remain separate under `contributes.ui.appPanels` and create top-level sidebar entries.
+
 ## UI Types
 
 UI contribution types are exported separately:
 
 ```ts
-import type { PluginToolRendererProps, PluginPanelProps } from "@ericsanchezok/synergy-plugin/ui"
+import type {
+  PluginToolRendererProps,
+  PluginWorkbenchPanel,
+  PluginPanelProps,
+  PluginMessageSlotProps,
+} from "@ericsanchezok/synergy-plugin/ui"
 ```
 
-Supported UI surfaces are tool renderers, part renderers, workspace panels, global panels, settings sections, chat components, themes, icons, routes, and commands. The Web client loads aggregated UI metadata with the generated SDK method `plugin.listUiContributions()`, which maps to `/plugin/ui/contributions`; plugin JS and assets are still loaded through browser-native asset URLs.
+Supported UI surfaces are tool renderers, part renderers, workbench panels, app panels, settings sections, message slots, themes, icons, app routes, and commands. The Web client loads aggregated UI metadata with the generated SDK method `plugin.listUiContributions()`, which maps to `/plugin/ui/contributions`; plugin JS and assets are still loaded through browser-native asset URLs.
 
 ## Runtime Modes
 
@@ -266,7 +363,7 @@ Worker and process plugins are started through Synergy's plugin runner. The runn
 - `dist/permissions.summary.json`
 - `dist/integrity.json`
 
-`synergy-plugin pack` archives `dist/` into `<name>-<version>.synergy-plugin.tgz`. `synergy-plugin sign` writes `<tarball>.sig`. `synergy-plugin publish-market` prepares the official marketplace submission by uploading or checking GitHub Release assets, writing a `SII-Holos/synergy-plugins` entry with the signer public key, regenerating the registry index, running registry validation, and opening a PR when `gh` is available.
+`synergy-plugin pack` archives `dist/` into `<name>-<version>.synergy-plugin.tgz`. `synergy-plugin sign` writes `<tarball>.sig`. `synergy-plugin publish-market` prepares the official marketplace submission by uploading or checking GitHub Release assets, writing a `SII-Holos/synergy-plugins` entry with the signer public key and `compatibility.synergy` from `plugin.json` `engines.synergy`, regenerating the registry index, running registry validation, and opening a PR when `gh` is available.
 
 For local marketplace UX testing, the Synergy runtime still provides `synergy plugin publish <tarball>` to publish into the local development registry.
 

package/dist/artifact.d.ts

@@ -0,0 +1,15 @@
+export declare namespace PluginArtifact {
+    const manifestFile = "plugin.json";
+    const normalizedManifestFile = "plugin.normalized.json";
+    const runtimeEntry = "runtime/index.js";
+    const integrityFile = "integrity.json";
+    const permissionsSummaryFile = "permissions.summary.json";
+    const requiredFiles: readonly ["plugin.json", "runtime/index.js", "integrity.json", "permissions.summary.json"];
+    const assetRoutePrefix = "/plugin/assets";
+    const allowedAssetRoots: readonly ["dist", "public", "assets", "ui", "themes", "icons"];
+}
+export declare function normalizePluginArtifactPath(filePath: string): string;
+export declare function normalizePluginArchiveEntry(entry: string): string | undefined;
+export declare function pluginArtifactAssetRoot(filePath: string): string;
+export declare function isAllowedPluginAssetPath(filePath: string): boolean;
+export declare function pluginAssetUrl(pluginId: string, versionHash: string, filePath: string): string;

package/dist/artifact.js

@@ -0,0 +1,52 @@
+export var PluginArtifact;
+(function (PluginArtifact) {
+    PluginArtifact.manifestFile = "plugin.json";
+    PluginArtifact.normalizedManifestFile = "plugin.normalized.json";
+    PluginArtifact.runtimeEntry = "runtime/index.js";
+    PluginArtifact.integrityFile = "integrity.json";
+    PluginArtifact.permissionsSummaryFile = "permissions.summary.json";
+    PluginArtifact.requiredFiles = [PluginArtifact.manifestFile, PluginArtifact.runtimeEntry, PluginArtifact.integrityFile, PluginArtifact.permissionsSummaryFile];
+    PluginArtifact.assetRoutePrefix = "/plugin/assets";
+    PluginArtifact.allowedAssetRoots = ["dist", "public", "assets", "ui", "themes", "icons"];
+})(PluginArtifact || (PluginArtifact = {}));
+export function normalizePluginArtifactPath(filePath) {
+    const normalized = filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!normalized || normalized === ".")
+        throw new Error("Plugin artifact path cannot be empty");
+    if (normalized.startsWith("/") || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(normalized)) {
+        throw new Error(`Plugin artifact path must be relative: ${filePath}`);
+    }
+    const parts = normalized.split("/").filter(Boolean);
+    if (parts.includes(".."))
+        throw new Error(`Plugin artifact path cannot escape the plugin root: ${filePath}`);
+    return parts.join("/");
+}
+export function normalizePluginArchiveEntry(entry) {
+    let normalized = entry.replace(/\r$/, "").replace(/\\/g, "/");
+    while (normalized.startsWith("./"))
+        normalized = normalized.slice(2);
+    normalized = normalized.replace(/\/+$/, "");
+    if (!normalized || normalized === ".")
+        return undefined;
+    return normalizePluginArtifactPath(normalized);
+}
+export function pluginArtifactAssetRoot(filePath) {
+    return normalizePluginArtifactPath(filePath).split("/")[0] ?? "";
+}
+export function isAllowedPluginAssetPath(filePath) {
+    try {
+        const root = pluginArtifactAssetRoot(filePath);
+        return PluginArtifact.allowedAssetRoots.includes(root);
+    }
+    catch {
+        return false;
+    }
+}
+export function pluginAssetUrl(pluginId, versionHash, filePath) {
+    const normalized = normalizePluginArtifactPath(filePath);
+    const encodedPath = normalized
+        .split("/")
+        .map((part) => encodeURIComponent(part))
+        .join("/");
+    return `${PluginArtifact.assetRoutePrefix}/${encodeURIComponent(pluginId)}/${encodeURIComponent(versionHash)}/${encodedPath}`;
+}

package/dist/display.d.ts

@@ -3,13 +3,11 @@ export interface ToolMediaDisplay {
     actionLabel?: string;
     pendingTitle?: string;
     pendingDescription?: string;
-    promptField?: string;
     aspectRatio?: "1:1" | "4:3" | "16:9" | "auto";
+    size?: "small" | "medium" | "large";
 }
 export interface ToolDisplay {
     kind?: "default" | "media-generation";
-    visibility?: "default" | "media" | "hidden-unless-error";
-    presentation?: "default" | "artifact-only";
+    toolCard?: "visible" | "hidden";
     media?: ToolMediaDisplay;
-    primaryAttachmentIds?: string[];
 }

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/ids.d.ts

@@ -0,0 +1,13 @@
+export declare namespace PluginToolId {
+    function format(pluginId: string, toolId: string): string;
+    function parse(id: string): {
+        pluginId: string;
+        toolId: string;
+    } | undefined;
+    function is(id: string): boolean;
+}
+export declare namespace PluginId {
+    function isValid(id: string): boolean;
+    function normalize(id: string): string;
+    function mcpServerKey(pluginId: string, serverKey: string): string;
+}

package/dist/ids.js

@@ -0,0 +1,33 @@
+export var PluginToolId;
+(function (PluginToolId) {
+    function format(pluginId, toolId) {
+        return `plugin__${pluginId}__${toolId}`;
+    }
+    PluginToolId.format = format;
+    function parse(id) {
+        const match = id.match(/^plugin__([^_]+(?:_[^_]+)*?)__([^_].*)$/);
+        if (!match)
+            return undefined;
+        return { pluginId: match[1], toolId: match[2] };
+    }
+    PluginToolId.parse = parse;
+    function is(id) {
+        return id.startsWith("plugin__");
+    }
+    PluginToolId.is = is;
+})(PluginToolId || (PluginToolId = {}));
+export var PluginId;
+(function (PluginId) {
+    function isValid(id) {
+        return /^[a-z][a-z0-9_-]*$/i.test(id);
+    }
+    PluginId.isValid = isValid;
+    function normalize(id) {
+        return id.trim().toLowerCase();
+    }
+    PluginId.normalize = normalize;
+    function mcpServerKey(pluginId, serverKey) {
+        return `${pluginId}::${serverKey}`;
+    }
+    PluginId.mcpServerKey = mcpServerKey;
+})(PluginId || (PluginId = {}));

package/dist/index.d.ts

@@ -1,15 +1,19 @@
-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 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>>;
-    /** Set one or more config values (deep-merged into the plugin's namespace) */
+    /** Replace the plugin's config namespace with these values */
     set(values: Record<string, any>): Promise<void>;
 }
 /**
@@ -310,6 +314,15 @@ export type ProviderProfileHook = {
         modelID: string;
         options?: Record<string, any>;
     }) => Promise<any>;
+    fetchModelCatalog?: (input: {
+        auth?: Auth;
+        fetch?: typeof fetch;
+        baseURL?: string;
+    }) => Promise<Array<{
+        id: string;
+        rank?: number;
+        model?: Partial<Model>;
+    }>>;
     fetchModels?: (input: {
         auth?: Auth;
         fetch?: typeof fetch;
@@ -354,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>;
@@ -370,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;
@@ -432,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,2 +1,6 @@
-export * from "./tool";
-export * from "./manifest";
+export * from "./tool.js";
+export * from "./manifest.js";
+export * from "./policy.js";
+export * from "./spec.js";
+export * from "./version.js";
+export * from "./artifact.js";