@ericsanchezok/synergy-plugin 2.3.0 → 2.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 `@ericsanchezok/synergy-plugin` is the authoring SDK for Synergy plugins.
 
-Plugins extend the Synergy server runtime and can also contribute Web UI surfaces through `plugin.json`. The current API is intentionally strict: a plugin module exports an object descriptor with a canonical `id` and an `init()` method. The descriptor id, `plugin.json.name`, registry id, lockfile key, and approval key must all be the same canonical plugin id.
+Plugins extend the Synergy server runtime and can also contribute Web UI surfaces through `plugin.json`. A plugin module exports an object descriptor with a canonical `id` and an `init()` method. The descriptor id, `plugin.json.name`, registry id, lockfile key, and approval key must all be the same canonical plugin id.
 
 Plugin authors should use `@ericsanchezok/synergy-plugin-kit` and this SDK from a standalone plugin project. Cloning the Synergy source repository is only needed when changing or debugging the plugin platform itself.
 
@@ -59,13 +59,13 @@ export const plugin: PluginDescriptor = {
 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.
+`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:
+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:
 
 ```ts
 return {
@@ -121,7 +121,53 @@ tool({
 })
 ```
 
-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.
+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.
+
+## 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
 

package/dist/index.d.ts

@@ -82,6 +82,8 @@ export interface PluginAgent {
     mode?: "subagent" | "primary" | "all";
     /** Model override in "providerID/modelID" format */
     model?: string;
+    /** Model role to resolve when model is not set */
+    modelRole?: "vision" | "nano" | "mini" | "mid" | "thinking" | "long" | "creative";
     temperature?: number;
     topP?: number;
     /** Maximum agentic iterations */
@@ -226,6 +228,18 @@ export type ProviderProfileHook = {
     aliases?: string[];
     description?: string;
     signupUrl?: string;
+    recommendation?: {
+        level: "featured" | "recommended" | "standard";
+        rank?: number;
+        headline?: string;
+        reason?: string;
+        cta?: {
+            kind: "external";
+            label: string;
+            url: string;
+        };
+        defaultModel?: string;
+    };
     env?: string[];
     baseURL?: string;
     modelsURL?: string;

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<{
@@ -120,6 +124,8 @@ export declare const PluginManifest: 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<{
@@ -198,6 +204,17 @@ export declare const PluginManifest: z.ZodObject<{
                 all: "all";
             }>>;
             model: z.ZodOptional<z.ZodString>;
+            modelRole: z.ZodOptional<z.ZodEnum<{
+                vision: "vision";
+                nano: "nano";
+                mini: "mini";
+                mid: "mid";
+                thinking: "thinking";
+                long: "long";
+                creative: "creative";
+            }>>;
+            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<{
@@ -347,6 +364,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<{

package/dist/manifest.js

@@ -109,6 +109,20 @@ const ToolExposureDef = z.discriminatedUnion("mode", [
         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({
@@ -169,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 */
@@ -291,6 +306,9 @@ export const PluginManifest = z
             description: z.string(),
             mode: z.enum(["subagent", "primary", "all"]).default("subagent"),
             model: z.string().optional(),
+            modelRole: z.enum(["vision", "nano", "mini", "mid", "thinking", "long", "creative"]).optional(),
+            hidden: z.boolean().optional(),
+            permission: z.record(z.string(), z.any()).optional(),
         }))
             .optional(),
         mcp: z

package/dist/tool.d.ts

@@ -13,7 +13,67 @@ 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[];
@@ -45,6 +105,8 @@ export type ToolExposure = {
     mode: "search";
     title?: string;
     keywords?: string[];
+} | {
+    mode: "internal";
 };
 export declare function tool<Args extends z.ZodRawShape>(input: {
     description: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@ericsanchezok/synergy-plugin",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "type": "module",
   "license": "MIT",
   "repository": {