@ericsanchezok/synergy-plugin 2.4.2 → 2.4.4

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,30 +80,27 @@ 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",
   },
 } as const
@@ -116,12 +112,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 +148,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: {
@@ -188,7 +184,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 +196,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 +233,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 +299,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,10 @@ export interface ToolMediaDisplay {
     actionLabel?: string;
     pendingTitle?: string;
     pendingDescription?: string;
-    promptField?: string;
     aspectRatio?: "1:1" | "4:3" | "16:9" | "auto";
 }
 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/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

@@ -5,11 +5,15 @@ export * from "./tool";
 export type { ToolDisplay, ToolMediaDisplay } from "./display";
 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 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;

package/dist/index.js

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