@ericsanchezok/synergy-plugin 2.2.2 → 2.4.0

package/README.md

@@ -61,6 +61,114 @@ export default plugin
 
 There is no compatibility layer for legacy descriptor shapes. `plugin.json.name` must match `plugin.id`; Synergy fails validation or loading if they differ.
 
+## Tool Results And Attachments
+
+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 should appear as the main answer instead of a tool card, set `metadata.display.presentation` to `artifact-only` and list the attachment ids to promote:
+
+```ts
+return {
+  output: "",
+  metadata: {
+    display: {
+      presentation: "artifact-only",
+      primaryAttachmentIds: [partId],
+    },
+  },
+  attachments: [
+    {
+      id: partId,
+      sessionID: context.sessionID,
+      messageID: context.messageID,
+      type: "file",
+      mime: "image/svg+xml",
+      filename: "result.svg",
+      url: uploaded.url,
+    },
+  ],
+}
+```
+
+Running and failed tool states still render normally, so progress, approvals, and errors remain visible.
+
+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:
+
+```ts
+const mediaDisplay = {
+  kind: "media-generation",
+  visibility: "media",
+  presentation: "artifact-only",
+  media: {
+    type: "image",
+    actionLabel: "Create image",
+    pendingTitle: "Generating image",
+    pendingDescription: "Preparing the image...",
+    promptField: "prompt",
+    aspectRatio: "1:1",
+  },
+} as const
+
+tool({
+  description: "Generate an image",
+  display: mediaDisplay,
+  args: {
+    prompt: tool.schema.string(),
+  },
+  async execute(args, context) {
+    // Upload the generated image, then return metadata.display with primaryAttachmentIds.
+  },
+})
+```
+
+Use `visibility: "media"` for tools whose running and completed success states should be represented by the media surface instead of the ordinary tool transcript. Error states still fall back to normal tool cards.
+
+## Internal Tools And Delegated Tasks
+
+Plugins can register helper tools that are only available to a controlled delegated task by setting `exposure: { mode: "internal" }`. Internal tools are not visible to the primary agent, resident tool lists, grouped tools, or `search_tools`; Synergy can still enable them explicitly for a delegated subagent run.
+
+```ts
+tool({
+  description: "Validate a private planning result",
+  exposure: { mode: "internal" },
+  args: {
+    choice: tool.schema.string(),
+  },
+  async execute(args) {
+    return { output: JSON.stringify({ choice: args.choice }) }
+  },
+})
+```
+
+Use `context.task.run()` when a public plugin tool needs Synergy's existing Cortex delegation flow. The host always fills `parentSessionID`, `parentMessageID`, and `executionRole: "delegated_subagent"`; plugins cannot forge those fields.
+
+```ts
+const plan = await context.task?.run({
+  subagent: "my-plugin-planner",
+  description: "Plan the plugin result",
+  prompt: "Choose a valid plan and return JSON.",
+  tools: {
+    "*": false,
+    "plugin__my-plugin__private_helper": true,
+  },
+  visibility: "hidden",
+  timeoutMs: 30_000,
+  output: {
+    mode: "structured",
+    schema: {
+      type: "object",
+      required: ["choice"],
+      properties: {
+        choice: { type: "string" },
+      },
+    },
+    maxRepairTurns: 3,
+  },
+})
+```
+
+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`.
+
 ## Plugin Input
 
 `init(input)` receives runtime services scoped to the active Synergy Scope:
@@ -107,6 +215,9 @@ Each distributable plugin has a root `plugin.json`:
         "name": "greet",
         "title": "Greet",
         "description": "Greet a user by name",
+        "display": {
+          "kind": "default",
+        },
         "capabilities": {
           "filesystem": "none",
           "network": false,

package/dist/display.d.ts

@@ -0,0 +1,15 @@
+export interface ToolMediaDisplay {
+    type: "image" | "video" | "audio";
+    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";
+    media?: ToolMediaDisplay;
+    primaryAttachmentIds?: string[];
+}

package/dist/hooks.js

@@ -11,6 +11,12 @@ export const HOOKS = [
         mutatesOutput: false,
         summary: "Add provider auth methods and auth loaders",
     },
+    {
+        name: "provider",
+        category: "core",
+        mutatesOutput: false,
+        summary: "Register provider catalog/runtime profiles",
+    },
     {
         name: "config",
         category: "core",

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import type { AgendaItem, AgendaRunLog, CortexTask, Event, createSynergyClient,
 import type { BunShell } from "./shell";
 import type { ToolDefinition, ToolResult } from "./tool";
 export * from "./tool";
+export type { ToolDisplay, ToolMediaDisplay } from "./display";
 export type { ToolResult };
 export * from "./manifest";
 export type { BunShell, BunShellOutput, BunShellPromise, ShellExpression, ShellFunction } from "./shell";
@@ -150,8 +151,43 @@ export type AuthHook = {
         } | {
             type: "failed";
         }>;
+    } | {
+        type: "import";
+        label: string;
+        prompts?: Array<{
+            type: "text";
+            key: string;
+            message: string;
+            placeholder?: string;
+            validate?: (value: string) => string | undefined;
+            condition?: (inputs: Record<string, string>) => boolean;
+        } | {
+            type: "select";
+            key: string;
+            message: string;
+            options: Array<{
+                label: string;
+                value: string;
+                hint?: string;
+            }>;
+            condition?: (inputs: Record<string, string>) => boolean;
+        }>;
+        import(inputs?: Record<string, string>): Promise<AuthImportResult>;
     })[];
 };
+export type AuthImportResult = ({
+    type: "success";
+    provider?: string;
+} & ({
+    refresh: string;
+    access: string;
+    expires: number;
+} | {
+    key: string;
+})) | {
+    type: "failed";
+    message?: string;
+};
 export type AuthOuathResult = {
     url: string;
     instructions: string;
@@ -184,6 +220,88 @@ export type AuthOuathResult = {
         type: "failed";
     }>;
 });
+export type ProviderProfileHook = {
+    id: string;
+    name: string;
+    aliases?: string[];
+    description?: string;
+    signupUrl?: string;
+    env?: string[];
+    baseURL?: string;
+    modelsURL?: string;
+    apiMode?: "chat_completions" | "responses" | "anthropic_messages" | "codex_responses" | "external_process";
+    authKind?: "api_key" | "oauth" | "oauth_external" | "copilot" | "wellknown" | "none";
+    aiSdkPackage?: string;
+    modelFactory?: "languageModel" | "openaiResponses" | "openaiChat" | "openaiResponsesUnlessCompletionUrls" | "call" | "copilotAuto" | "anthropicMessages";
+    modelsDevProviderID?: string;
+    fallbackModels?: string[];
+    defaultAuxModel?: string;
+    usageKind?: "codex" | "anthropic-oauth" | "openrouter" | "unsupported";
+    healthCheck?: "models" | "none";
+    requestQuirks?: string[];
+    autoload?: (input: {
+        providerID: string;
+        auth?: Auth;
+        provider?: Provider;
+    }) => Promise<boolean>;
+    resolveAuth?: (input: {
+        providerID: string;
+        auth?: Auth;
+        provider?: Provider;
+    }) => Promise<Auth | undefined>;
+    refreshAuth?: (input: {
+        providerID: string;
+        auth?: Auth;
+        provider?: Provider;
+    }) => Promise<Auth | undefined>;
+    buildHeaders?: (input: {
+        providerID: string;
+        auth?: Auth;
+        url: string;
+        headers: Headers;
+        body?: unknown;
+    }) => Promise<Record<string, string> | Headers | undefined>;
+    rewriteBody?: (input: {
+        providerID: string;
+        auth?: Auth;
+        url: string;
+        headers: Headers;
+        body?: unknown;
+    }) => Promise<unknown>;
+    modelOptions?: (input: {
+        providerID: string;
+        auth?: Auth;
+        provider?: Provider;
+    }) => Promise<Record<string, any>>;
+    classifyError?: (input: {
+        providerID: string;
+        status?: number;
+        error?: unknown;
+        body?: unknown;
+    }) => {
+        code: string;
+        retryable: boolean;
+        reloginRequired?: boolean;
+        exhausted?: boolean;
+        cooldownUntil?: number;
+        resetAt?: number;
+    } | undefined;
+    runtimeOptions?: (input: {
+        providerID: string;
+        auth?: Auth;
+        provider?: Provider;
+    }) => Promise<Record<string, any>>;
+    getModel?: (input: {
+        sdk: any;
+        modelID: string;
+        options?: Record<string, any>;
+    }) => Promise<any>;
+    fetchModels?: (input: {
+        auth?: Auth;
+        fetch?: typeof fetch;
+        baseURL?: string;
+    }) => Promise<string[]>;
+};
 export type PluginInput = {
     client: ReturnType<typeof createSynergyClient>;
     scope: {
@@ -235,6 +353,8 @@ export interface PluginHooks {
     tool?: Record<string, ToolDefinition>;
     /** Provider auth integration */
     auth?: AuthHook;
+    /** Provider runtime/catalog profiles */
+    provider?: ProviderProfileHook | ProviderProfileHook[];
     /** Observe runtime bus events */
     event?(input: {
         event: Event;

package/dist/manifest.d.ts

@@ -38,6 +38,10 @@ export declare const PluginManifest: z.ZodObject<{
                 invoke: "invoke";
                 spawn: "spawn";
             }>>;
+            task: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                maxRuntimeMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>]>>;
         }, z.core.$strip>>;
         data: z.ZodOptional<z.ZodObject<{
             session: z.ZodDefault<z.ZodEnum<{
@@ -53,6 +57,7 @@ export declare const PluginManifest: z.ZodObject<{
             config: z.ZodDefault<z.ZodEnum<{
                 plugin: "plugin";
                 global: "global";
+                none: "none";
             }>>;
             secrets: z.ZodDefault<z.ZodEnum<{
                 none: "none";
@@ -107,6 +112,54 @@ export declare const PluginManifest: z.ZodObject<{
             icon: z.ZodOptional<z.ZodString>;
             category: z.ZodOptional<z.ZodString>;
             kind: z.ZodOptional<z.ZodString>;
+            exposure: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                mode: z.ZodLiteral<"resident">;
+            }, z.core.$strict>, z.ZodObject<{
+                mode: z.ZodLiteral<"group">;
+                group: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+                whenToExpand: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                mode: z.ZodLiteral<"search">;
+                title: z.ZodOptional<z.ZodString>;
+                keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>, z.ZodObject<{
+                mode: z.ZodLiteral<"internal">;
+            }, z.core.$strict>], "mode">>;
+            display: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodOptional<z.ZodEnum<{
+                    default: "default";
+                    "media-generation": "media-generation";
+                }>>;
+                visibility: z.ZodOptional<z.ZodEnum<{
+                    default: "default";
+                    media: "media";
+                    "hidden-unless-error": "hidden-unless-error";
+                }>>;
+                presentation: z.ZodOptional<z.ZodEnum<{
+                    default: "default";
+                    "artifact-only": "artifact-only";
+                }>>;
+                media: z.ZodOptional<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        image: "image";
+                        video: "video";
+                        audio: "audio";
+                    }>;
+                    actionLabel: z.ZodOptional<z.ZodString>;
+                    pendingTitle: z.ZodOptional<z.ZodString>;
+                    pendingDescription: z.ZodOptional<z.ZodString>;
+                    promptField: z.ZodOptional<z.ZodString>;
+                    aspectRatio: z.ZodOptional<z.ZodEnum<{
+                        "1:1": "1:1";
+                        "4:3": "4:3";
+                        "16:9": "16:9";
+                        auto: "auto";
+                    }>>;
+                }, z.core.$strict>>;
+                primaryAttachmentIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
             capabilities: z.ZodOptional<z.ZodObject<{
                 filesystem: z.ZodOptional<z.ZodEnum<{
                     read: "read";
@@ -151,6 +204,8 @@ export declare const PluginManifest: z.ZodObject<{
                 all: "all";
             }>>;
             model: z.ZodOptional<z.ZodString>;
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            permission: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         }, z.core.$strip>>>>;
         mcp: z.ZodOptional<z.ZodOptional<z.ZodObject<{
             defaults: z.ZodOptional<z.ZodObject<{
@@ -300,6 +355,10 @@ export declare const PluginManifest: z.ZodObject<{
                     invoke: "invoke";
                     spawn: "spawn";
                 }>>;
+                task: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                    agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    maxRuntimeMs: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>]>>;
             }, z.core.$strip>>;
             data: z.ZodOptional<z.ZodObject<{
                 session: z.ZodDefault<z.ZodEnum<{
@@ -315,6 +374,7 @@ export declare const PluginManifest: z.ZodObject<{
                 config: z.ZodDefault<z.ZodEnum<{
                     plugin: "plugin";
                     global: "global";
+                    none: "none";
                 }>>;
                 secrets: z.ZodDefault<z.ZodEnum<{
                     none: "none";

package/dist/manifest.js

@@ -87,6 +87,62 @@ const UICommandDef = z
     icon: z.string().optional(),
 })
     .strict();
+const ToolExposureDef = z.discriminatedUnion("mode", [
+    z
+        .object({
+        mode: z.literal("resident"),
+    })
+        .strict(),
+    z
+        .object({
+        mode: z.literal("group"),
+        group: z.string().min(1),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        whenToExpand: z.string().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        mode: z.literal("search"),
+        title: z.string().optional(),
+        keywords: z.array(z.string()).optional(),
+    })
+        .strict(),
+    z
+        .object({
+        mode: z.literal("internal"),
+    })
+        .strict(),
+]);
+const TaskPermissionDef = z.union([
+    z.boolean(),
+    z
+        .object({
+        agents: z.array(z.string().min(1)).optional(),
+        maxRuntimeMs: z.number().int().positive().optional(),
+    })
+        .strict(),
+]);
+const ToolDisplayDef = z
+    .object({
+    kind: z.enum(["default", "media-generation"]).optional(),
+    visibility: z.enum(["default", "media", "hidden-unless-error"]).optional(),
+    presentation: z.enum(["default", "artifact-only"]).optional(),
+    media: z
+        .object({
+        type: z.enum(["image", "video", "audio"]),
+        actionLabel: z.string().min(1).max(80).optional(),
+        pendingTitle: z.string().min(1).max(120).optional(),
+        pendingDescription: z.string().min(1).max(200).optional(),
+        promptField: z.string().min(1).max(64).optional(),
+        aspectRatio: z.enum(["1:1", "4:3", "16:9", "auto"]).optional(),
+    })
+        .strict()
+        .optional(),
+    primaryAttachmentIds: z.array(z.string().min(1)).optional(),
+})
+    .strict();
 const UIContribution = z
     .object({
     entry: z
@@ -127,6 +183,7 @@ const PluginPermissionsSchema = z
         }, z.enum(["none", "read", "write"]).default("none")),
         network: z.boolean().default(false),
         mcp: z.enum(["none", "invoke", "spawn"]).default("none"),
+        task: TaskPermissionDef.optional(),
     })
         .optional(),
     /** Data access */
@@ -134,7 +191,7 @@ const PluginPermissionsSchema = z
         .object({
         session: z.enum(["none", "metadata", "read"]).default("none"),
         workspace: z.enum(["none", "metadata", "read"]).default("none"),
-        config: z.enum(["plugin", "global"]).default("plugin"),
+        config: z.enum(["none", "plugin", "global"]).default("plugin"),
         secrets: z.enum(["none", "own"]).default("none"),
     })
         .optional(),
@@ -221,6 +278,8 @@ export const PluginManifest = z
             icon: z.string().optional(),
             category: z.string().optional(),
             kind: z.string().optional(),
+            exposure: ToolExposureDef.optional(),
+            display: ToolDisplayDef.optional(),
             capabilities: z
                 .object({
                 filesystem: z.enum(["none", "read", "write"]).optional(),
@@ -247,6 +306,8 @@ export const PluginManifest = z
             description: z.string(),
             mode: z.enum(["subagent", "primary", "all"]).default("subagent"),
             model: z.string().optional(),
+            hidden: z.boolean().optional(),
+            permission: z.record(z.string(), z.any()).optional(),
         }))
             .optional(),
         mcp: z

package/dist/tool.d.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import type { ToolDisplay } from "./display";
+export type { ToolDisplay, ToolMediaDisplay } from "./display";
 export type ToolContext = {
     sessionID: string;
     messageID: string;
@@ -11,11 +13,75 @@ export type ToolContext = {
         patterns: string[];
         metadata?: Record<string, any>;
     }): Promise<void>;
+    /** Run a Synergy delegated subagent task from inside this tool. */
+    task?: ToolTaskService;
+    /** Invoke another visible/explicitly-allowed Synergy tool from inside this tool. */
+    tools?: ToolInvokeService;
+};
+export type ToolTaskVisibility = "visible" | "hidden";
+export type ToolTaskOutput = {
+    mode?: "summary";
+} | {
+    mode: "final_response";
+} | {
+    mode: "structured";
+    schema: Record<string, unknown>;
+    maxRepairTurns?: 0 | 1 | 2 | 3;
+};
+export type ToolTaskOutputResult = {
+    mode: "final_response";
+    text: string;
+} | {
+    mode: "structured";
+    status: "valid" | "invalid";
+    source?: "structured_tool" | "final_response";
+    data?: unknown;
+    text?: string;
+    repairTurns: number;
+    error?: string;
+    validationErrors?: string[];
+};
+export interface ToolTaskRunInput {
+    subagent: string;
+    description: string;
+    prompt: string;
+    tools?: Record<string, boolean>;
+    visibility?: ToolTaskVisibility;
+    timeoutMs?: number;
+    output?: ToolTaskOutput;
+    category?: string;
+    model?: {
+        providerID: string;
+        modelID: string;
+    };
+}
+export interface ToolTaskRunResult {
+    taskId: string;
+    sessionId: string;
+    status: "pending" | "queued" | "running" | "completed" | "error" | "cancelled" | "timeout";
+    output: string;
+    outputResult?: ToolTaskOutputResult;
+    error?: string;
+}
+export interface ToolTaskService {
+    run(input: ToolTaskRunInput): Promise<ToolTaskRunResult>;
+}
+export interface ToolInvokeInput {
+    tool: string;
+    args?: unknown;
+    timeoutMs?: number;
+}
+export interface ToolInvokeService {
+    invoke(input: ToolInvokeInput): Promise<ToolResult>;
+}
+export type ToolResultMetadata = Record<string, any> & {
+    display?: ToolDisplay;
+    primaryAttachmentIds?: string[];
 };
 export interface ToolResult {
     title?: string;
     output: string;
-    metadata?: Record<string, any>;
+    metadata?: ToolResultMetadata;
     attachments?: Array<{
         type: "file";
         id: string;
@@ -27,12 +93,31 @@ export interface ToolResult {
         localPath?: string;
     }>;
 }
+export type ToolExposure = {
+    mode: "resident";
+} | {
+    mode: "group";
+    group: string;
+    title?: string;
+    description?: string;
+    whenToExpand?: string;
+} | {
+    mode: "search";
+    title?: string;
+    keywords?: string[];
+} | {
+    mode: "internal";
+};
 export declare function tool<Args extends z.ZodRawShape>(input: {
     description: string;
+    exposure?: ToolExposure;
+    display?: ToolDisplay;
     args: Args;
     execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string | ToolResult>;
 }): {
     description: string;
+    exposure?: ToolExposure;
+    display?: ToolDisplay;
     args: Args;
     execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string | ToolResult>;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@ericsanchezok/synergy-plugin",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,10 @@
       "import": "./dist/tool.js",
       "types": "./dist/tool.d.ts"
     },
+    "./display": {
+      "import": "./dist/display.js",
+      "types": "./dist/display.d.ts"
+    },
     "./hooks": {
       "import": "./dist/hooks.js",
       "types": "./dist/hooks.d.ts"