@ericsanchezok/synergy-plugin 2.3.0 → 2.4.0

package/README.md

@@ -123,6 +123,52 @@ 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.
 
+## 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:

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,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<{
@@ -347,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<{

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,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

@@ -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.0",
   "type": "module",
   "license": "MIT",
   "repository": {