@moxxy/plugin-subagents 0.26.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/dispatch-agent.d.ts

@@ -0,0 +1,60 @@
+import { z, type AgentDef, type SubagentSpec } from '@moxxy/sdk';
+declare const agentSpecSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    agentType: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodString>;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    agentType?: string | undefined;
+    label?: string | undefined;
+    systemPrompt?: string | undefined;
+    model?: string | undefined;
+    mode?: string | undefined;
+    allowedTools?: string[] | undefined;
+}, {
+    prompt: string;
+    agentType?: string | undefined;
+    label?: string | undefined;
+    systemPrompt?: string | undefined;
+    model?: string | undefined;
+    mode?: string | undefined;
+    allowedTools?: string[] | undefined;
+}>;
+export type AgentSpecInput = z.infer<typeof agentSpecSchema>;
+export interface DispatchAgentDeps {
+    /** Live lookup against the session's agent registry. Closure-bound at
+     *  plugin construction so handler reads see fresh state. */
+    readonly getAgent: (name: string) => AgentDef | undefined;
+    /**
+     * Live snapshot of the parent's tool names. When wired, a child that
+     * neither the caller nor its kind restricts is defaulted to the parent's
+     * tools MINUS `dispatch_agent`, so a model can't drive an unbounded
+     * recursive fan-out (8^N concurrent sessions / fork-bomb). Omit (the
+     * default) to preserve full unrestricted inheritance — useful for
+     * standalone tests/scripts that don't wire a session.
+     */
+    readonly getToolNames?: () => ReadonlyArray<string>;
+}
+/** Built-in "default" kind — surfaced when the model omits agentType or
+ *  passes an unknown one. Never registered in the AgentRegistry so
+ *  plugins can override it cleanly via `replace()` if they want. */
+export declare const DEFAULT_AGENT: AgentDef;
+export declare function buildDispatchAgentTool(deps: DispatchAgentDeps): import("@moxxy/sdk").ToolDef;
+/** Position of this spec within a multi-agent batch — used to disambiguate
+ *  fallback labels and (informationally) reason about fan-out width. */
+export interface ResolveSpecPosition {
+    readonly index: number;
+    readonly total: number;
+}
+/**
+ * Merge a model-supplied spec with the registered agent kind. Caller
+ * fields win over kind defaults; omitted caller fields fall back to
+ * the kind, which falls back to the built-in DEFAULT.
+ */
+export declare function resolveSpec(input: AgentSpecInput, deps: DispatchAgentDeps, position?: ResolveSpecPosition): SubagentSpec;
+export {};
+//# sourceMappingURL=dispatch-agent.d.ts.map

package/dist/dispatch-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-agent.d.ts","sourceRoot":"","sources":["../src/dispatch-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,CAAC,EACD,KAAK,QAAQ,EAEb,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAqBpB,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;EAgDnB,CAAC;AASH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC;gEAC4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;IAC1D;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;CACrD;AAED;;oEAEoE;AACpE,eAAO,MAAM,aAAa,EAAE,QAI3B,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,iBAAiB,gCA6E7D;AAED;wEACwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,iBAAiB,EACvB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,YAAY,CA2Bd"}

package/dist/dispatch-agent.js

@@ -0,0 +1,193 @@
+import { defineTool, MoxxyError, z, } from '@moxxy/sdk';
+/** Upper bound on a single child prompt. Children seed their session with this
+ *  verbatim and send it to the provider; an unbounded string at this trust
+ *  boundary lets a runaway/injected model fan out N multi-megabyte completions. */
+const MAX_PROMPT_CHARS = 20_000;
+/** Upper bound on a per-child system-prompt override. */
+const MAX_SYSTEM_PROMPT_CHARS = 8_000;
+/**
+ * Aggregate text budget across the WHOLE batch (sum of every spec's prompt +
+ * systemPrompt). The per-field caps bound one child, but 8 specs each at the
+ * field ceiling still total ~224K chars, dispatched as 8 *concurrent*
+ * completions — a sudden cost/context/memory spike reachable from untrusted
+ * model output. This caps the simultaneous fan-out payload below that
+ * worst case while staying generously above any real multi-agent call.
+ */
+const MAX_BATCH_TEXT_CHARS = 60_000;
+/** This tool's own name — never re-granted to children by default so a model
+ *  can't drive an unbounded recursive fan-out (8^N sessions). */
+const DISPATCH_AGENT_TOOL_NAME = 'dispatch_agent';
+const agentSpecSchema = z.object({
+    prompt: z
+        .string()
+        .min(1)
+        .max(MAX_PROMPT_CHARS)
+        .describe('The task the sub-agent should perform. Phrase as a focused, self-contained request.'),
+    agentType: z
+        .string()
+        .optional()
+        .describe('Named agent kind to spawn (e.g. "researcher", "code-reviewer"). Looked ' +
+        'up in the agent registry contributed by installed plugins. Omit, or ' +
+        'pass "default", for a generic tool-use agent. Unknown types fall back ' +
+        'to default — the request never fails over a missing kind. List of ' +
+        'currently-registered kinds is visible via the /agents command.'),
+    label: z
+        .string()
+        .max(60)
+        .optional()
+        .describe('Short label shown in progress events (e.g. "research-deps", "lint-fix-A").'),
+    systemPrompt: z
+        .string()
+        .max(MAX_SYSTEM_PROMPT_CHARS)
+        .optional()
+        .describe('Override the kind\'s system prompt. Use to set persona, constraints, ' +
+        'or hand off upstream artifacts the child needs as context.'),
+    model: z
+        .string()
+        .optional()
+        .describe('Model id override; defaults to the kind\'s model, then the parent\'s. ' +
+        'Omit unless the user explicitly requested a specific model — do NOT ' +
+        'invent model ids. Unknown ids fall back to the parent\'s model with a warning.'),
+    mode: z
+        .string()
+        .optional()
+        .describe('Loop strategy override. Valid values: "default", "goal", ' +
+        '"research". OMIT for the kind\'s default — do NOT invent names.'),
+    allowedTools: z
+        .array(z.string())
+        .optional()
+        .describe('Restrict the child to these tool names. Overrides the kind\'s allowlist if set.'),
+});
+/** Built-in "default" kind — surfaced when the model omits agentType or
+ *  passes an unknown one. Never registered in the AgentRegistry so
+ *  plugins can override it cleanly via `replace()` if they want. */
+export const DEFAULT_AGENT = {
+    name: 'default',
+    description: 'Generic tool-use loop. Inherits the parent\'s full tool registry; no system prompt override.',
+};
+export function buildDispatchAgentTool(deps) {
+    return defineTool({
+        name: 'dispatch_agent',
+        description: 'Spawn one or more focused sub-agents in parallel. Use when a task fans out ' +
+            'into independent subtasks (multi-source research, per-file refactor, ' +
+            'multi-perspective review). Each child runs in isolation and returns its ' +
+            'final message; children stream their progress so you see what each one is ' +
+            'doing in real time. Pass `agentType` to pick a specialized kind from the ' +
+            'agent registry (see /agents); omit for the default generic agent. Unknown ' +
+            'kinds fall back to the default instead of erroring.',
+        inputSchema: z.object({
+            agents: z
+                .array(agentSpecSchema)
+                .min(1)
+                .max(8)
+                .superRefine((specs, ctx) => {
+                // Bound the *aggregate* concurrent fan-out payload, not just each
+                // child. Reject the whole batch before any session is spawned.
+                let total = 0;
+                for (const s of specs)
+                    total += s.prompt.length + (s.systemPrompt?.length ?? 0);
+                if (total > MAX_BATCH_TEXT_CHARS) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: `dispatch_agent batch payload too large: ${total} chars across ${specs.length} ` +
+                            `agent(s) exceeds the ${MAX_BATCH_TEXT_CHARS}-char aggregate limit. Spawn fewer ` +
+                            `agents per call or shorten the prompts/systemPrompts.`,
+                    });
+                }
+            })
+                .describe('Specs for the agents to spawn. Run in parallel; results returned in order.'),
+        }),
+        handler: async (input, ctx) => {
+            if (!ctx.subagents) {
+                throw new MoxxyError({
+                    code: 'INTERNAL',
+                    message: 'dispatch_agent: no subagent spawner available — this tool must be invoked from a run-turn loop.',
+                    hint: 'Invoke dispatch_agent from within a run-turn loop so the subagent spawner is wired into the tool context.',
+                });
+            }
+            const agents = input.agents;
+            const specs = agents.map((s, i) => resolveSpec(s, deps, { index: i, total: agents.length }));
+            // The core spawner runs children with Promise.all, which rejects on the
+            // FIRST child's setup throw (model/log/provider lookup before the
+            // per-child try) and discards every sibling's result. Degrade to
+            // per-child errors here so one child's failure doesn't abort the batch
+            // and orphan the rest — the model still gets the specs that succeeded.
+            let results;
+            try {
+                results = await ctx.subagents.spawnAll(specs);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    results: specs.map((s) => ({
+                        label: s.label ?? s.agentType ?? 'default',
+                        childSessionId: '',
+                        text: '',
+                        stopReason: 'error',
+                        error: message,
+                    })),
+                };
+            }
+            return {
+                results: results.map((r) => ({
+                    label: r.label,
+                    childSessionId: String(r.childSessionId),
+                    text: r.text,
+                    stopReason: r.stopReason,
+                    ...(r.error ? { error: r.error.message } : {}),
+                })),
+            };
+        },
+    });
+}
+/**
+ * Merge a model-supplied spec with the registered agent kind. Caller
+ * fields win over kind defaults; omitted caller fields fall back to
+ * the kind, which falls back to the built-in DEFAULT.
+ */
+export function resolveSpec(input, deps, position) {
+    const requested = input.agentType ?? 'default';
+    const def = deps.getAgent(requested) ?? DEFAULT_AGENT;
+    const systemPrompt = input.systemPrompt ?? def.systemPrompt;
+    const model = input.model ?? def.model;
+    const mode = input.mode ?? def.mode;
+    // maxIterations only comes from the AgentDef now (the input schema
+    // doesn't expose it — see comment in agentSpecSchema above).
+    const allowedTools = resolveAllowedTools(input, def, deps);
+    // When the caller omits `label`, multiple agents of the same kind would all
+    // collapse to the kind's name (e.g. five "default" labels), making the live
+    // progress display and the returned results indistinguishable. Suffix a
+    // 1-based index in that multi-agent case; keep explicit/single labels clean.
+    const fallbackLabel = position && position.total > 1 ? `${def.name}-${position.index + 1}` : def.name;
+    const merged = {
+        prompt: input.prompt,
+        label: input.label ?? fallbackLabel,
+        // The requested kind, surfaced in subagent_* payloads for group rendering.
+        agentType: requested,
+        ...(systemPrompt !== undefined && { systemPrompt }),
+        ...(model !== undefined && { model }),
+        ...(mode !== undefined && { mode }),
+        ...(def.maxIterations !== undefined && { maxIterations: def.maxIterations }),
+        ...(allowedTools !== undefined && { allowedTools }),
+    };
+    return merged;
+}
+/**
+ * Decide the child's tool allowlist. Caller `allowedTools` wins, then the
+ * kind's, then — when a parent tool snapshot is wired (`deps.getToolNames`)
+ * and neither restricts — the parent's tools MINUS `dispatch_agent`. That
+ * last default is the recursion cut: without it, an unrestricted child
+ * inherits `dispatch_agent` and each level can spawn another full batch,
+ * giving 8^depth concurrent sessions reachable from untrusted model output.
+ * A kind that genuinely needs to recurse can re-grant `dispatch_agent`
+ * explicitly via its `allowedTools`.
+ */
+function resolveAllowedTools(input, def, deps) {
+    const explicit = input.allowedTools ?? def.allowedTools;
+    if (explicit !== undefined)
+        return explicit;
+    if (!deps.getToolNames)
+        return undefined; // not wired → preserve full inheritance
+    return deps.getToolNames().filter((n) => n !== DISPATCH_AGENT_TOOL_NAME);
+}
+//# sourceMappingURL=dispatch-agent.js.map

package/dist/dispatch-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-agent.js","sourceRoot":"","sources":["../src/dispatch-agent.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { type AgentDef, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+export { buildDispatchAgentTool, type DispatchAgentDeps } from './dispatch-agent.js';
+export interface BuildSubagentsPluginOpts {
+    /**
+     * How the tool resolves an `agentType` name → AgentDef at handler
+     * time. Pass a closure that reads from your session's agent registry:
+     * `(name) => session.agents.get(name)`.
+     *
+     * Defaults to "no agents registered" (always falls back to the
+     * built-in default kind). Useful for standalone tests / scripts that
+     * don't want to wire a session.
+     */
+    readonly getAgent?: (name: string) => AgentDef | undefined;
+    /**
+     * Live snapshot of the parent's tool names, e.g.
+     * `() => session.tools.list().map((t) => t.name)`. When provided, a child
+     * that neither the caller nor its kind restricts is defaulted to the
+     * parent's tools MINUS `dispatch_agent` — cutting unbounded recursive
+     * fan-out (8^N sessions). Omit to keep full unrestricted inheritance.
+     */
+    readonly getToolNames?: () => ReadonlyArray<string>;
+}
+/**
+ * `@moxxy/plugin-subagents` — adds the dispatch_agent tool + the
+ * auto-detection skill ("dispatch-agents") that triggers on fan-out
+ * patterns. Without this plugin the model can't spawn subagents — the
+ * normal single-loop flow runs as usual.
+ *
+ * Other plugins can ship `AgentDef` kinds via their own
+ * `PluginSpec.agents`. This plugin's tool resolves them at runtime, so
+ * a freshly-installed agent kind becomes available the next time the
+ * model calls dispatch_agent — no restart needed.
+ */
+export declare function buildSubagentsPlugin(opts?: BuildSubagentsPluginOpts, hooks?: LifecycleHooks): Plugin;
+/**
+ * Discovery-loadable default export: resolves the `agents` + `tools` registries
+ * from the inter-plugin service registry in `onInit` (the host publishes them),
+ * so `dispatch_agent` looks up agent kinds + the live parent-tool snapshot from
+ * the session without a host-injected closure. Both reads are lazy (at tool-call
+ * time, after all registration), and degrade to the standalone defaults if the
+ * host hasn't published them.
+ */
+export declare const subagentsPlugin: Plugin;
+export default subagentsPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,cAAc,EAEnB,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,sBAAsB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAErF,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;IAC3D;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;CACrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,GAAE,wBAA6B,EACnC,KAAK,CAAC,EAAE,cAAc,GACrB,MAAM,CAWR;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,MAgB1B,CAAC;AAEL,eAAe,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,50 @@
+import { definePlugin, } from '@moxxy/sdk';
+import { buildDispatchAgentTool } from './dispatch-agent.js';
+export { buildDispatchAgentTool } from './dispatch-agent.js';
+/**
+ * `@moxxy/plugin-subagents` — adds the dispatch_agent tool + the
+ * auto-detection skill ("dispatch-agents") that triggers on fan-out
+ * patterns. Without this plugin the model can't spawn subagents — the
+ * normal single-loop flow runs as usual.
+ *
+ * Other plugins can ship `AgentDef` kinds via their own
+ * `PluginSpec.agents`. This plugin's tool resolves them at runtime, so
+ * a freshly-installed agent kind becomes available the next time the
+ * model calls dispatch_agent — no restart needed.
+ */
+export function buildSubagentsPlugin(opts = {}, hooks) {
+    const deps = {
+        getAgent: opts.getAgent ?? (() => undefined),
+        ...(opts.getToolNames ? { getToolNames: opts.getToolNames } : {}),
+    };
+    return definePlugin({
+        name: '@moxxy/plugin-subagents',
+        version: '0.0.0',
+        ...(hooks ? { hooks } : {}),
+        tools: [buildDispatchAgentTool(deps)],
+    });
+}
+/**
+ * Discovery-loadable default export: resolves the `agents` + `tools` registries
+ * from the inter-plugin service registry in `onInit` (the host publishes them),
+ * so `dispatch_agent` looks up agent kinds + the live parent-tool snapshot from
+ * the session without a host-injected closure. Both reads are lazy (at tool-call
+ * time, after all registration), and degrade to the standalone defaults if the
+ * host hasn't published them.
+ */
+export const subagentsPlugin = (() => {
+    let agents = null;
+    let tools = null;
+    const hooks = {
+        onInit: (ctx) => {
+            agents = ctx.services.get('agents') ?? null;
+            tools = ctx.services.get('tools') ?? null;
+        },
+    };
+    return buildSubagentsPlugin({
+        getAgent: (name) => agents?.get(name),
+        getToolNames: () => (tools ? tools.list().map((t) => t.name) : []),
+    }, hooks);
+})();
+export default subagentsPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAKb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,sBAAsB,EAA0B,MAAM,qBAAqB,CAAC;AAErF,OAAO,EAAE,sBAAsB,EAA0B,MAAM,qBAAqB,CAAC;AAuBrF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAiC,EAAE,EACnC,KAAsB;IAEtB,MAAM,IAAI,GAAsB;QAC9B,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;QAC5C,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC;IACF,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,OAAO;QAChB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,KAAK,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC;KACtC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAW,CAAC,GAAG,EAAE;IAC3C,IAAI,MAAM,GAAmC,IAAI,CAAC;IAClD,IAAI,KAAK,GAAoD,IAAI,CAAC;IAClE,MAAM,KAAK,GAAmB;QAC5B,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE;YACd,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAA0B,QAAQ,CAAC,IAAI,IAAI,CAAC;YACrE,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAA2C,OAAO,CAAC,IAAI,IAAI,CAAC;QACtF,CAAC;KACF,CAAC;IACF,OAAO,oBAAoB,CACzB;QACE,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC;QACrC,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACnE,EACD,KAAK,CACN,CAAC;AACJ,CAAC,CAAC,EAAE,CAAC;AAEL,eAAe,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@moxxy/plugin-subagents",
+  "version": "0.26.0",
+  "description": "Spawn typed subagents in parallel. Plugins contribute agent kinds via the AgentDef registry; this plugin exposes the dispatch_agent tool and an auto-detection skill.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "subagents",
+    "tools",
+    "fan-out"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-subagents"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./skills/*": "./skills/*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "skills"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": [
+        "tools",
+        "agent"
+      ],
+      "skills": "./skills"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@moxxy/sdk": "0.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/core": "0.26.0",
+    "@moxxy/mode-default": "0.26.0",
+    "@moxxy/testing": "0.0.44",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/skills/dispatch-agents.md

@@ -0,0 +1,114 @@
+---
+name: dispatch-agents
+description: Fan a task out to parallel subagents when the work breaks into N independent pieces.
+triggers:
+  - "find 3"
+  - "find 5"
+  - "find N"
+  - "research 3"
+  - "research 5"
+  - "find multiple"
+  - "compare across"
+  - "compare these"
+  - "for each of"
+  - "in parallel"
+  - "fan out"
+  - "spawn agents"
+  - "spawn subagents"
+  - "audit each"
+  - "summarize N"
+  - "list 3"
+  - "list 5"
+  - "multi-source"
+  - "multiple sources"
+allowed-tools: [dispatch_agent, memory_save, memory_recall, memory_update]
+---
+
+# Dispatch subagents for parallel work
+
+When the user's request naturally decomposes into N **independent** subtasks
+that each need their own tool calls / context, spawn one subagent per subtask
+with `dispatch_agent`. Each child runs in isolation, returns a focused result,
+and the parent (you) composes the final reply.
+
+## When to dispatch
+
+Yes — fan out:
+- "Find 5 recent articles about X" → 5 agents, each researching one angle.
+- "Compare React, Vue, Svelte, Solid, Qwik" → 5 agents, each profiling one library.
+- "For each of these files, suggest a refactor" → N agents, one per file.
+- "Audit auth, db, and API for security issues" → 3 agents, one per area.
+
+No — keep sequential:
+- The subtasks depend on each other (output of A feeds B).
+- The task is small enough that one tool round-trip would handle it.
+- The user explicitly asked for one consolidated investigation.
+
+## How to call
+
+```
+dispatch_agent({
+  agents: [
+    { prompt: "Find a recent article about X from a major US outlet", agentType: "researcher", label: "us-press" },
+    { prompt: "Find a recent article about X from a European outlet",  agentType: "researcher", label: "eu-press" },
+    { prompt: "Find a recent academic paper on X",                     agentType: "researcher", label: "academic" }
+  ]
+})
+```
+
+Rules:
+- **One spec per independent subtask.** Don't bundle two requests into one prompt.
+- **Use clear `label`s** — they appear in the user's progress display.
+- **Pick `agentType` from the registered kinds** if any fit (see `/agents`).
+  Unknown kinds silently fall back to the default; that's safe but you
+  miss out on the specialized system prompt.
+- **Omit `agentType` entirely** when no kind matches — the default
+  generic agent works for most tasks.
+- **Cap at 8 agents per call.** If the task wants more, batch it.
+
+## After the agents return
+
+You receive one result per spec, in input order. Each has `text` (the
+agent's final message), `stopReason`, and optional `error`. Compose a
+single user-facing reply that:
+
+1. Synthesizes the findings (don't dump raw agent outputs verbatim).
+2. Cites which agent contributed what when sources differ.
+3. Flags any agent that errored or returned an empty result.
+
+If most agents failed, fall back to doing the work yourself in the
+current loop instead of retrying the spawn — the user shouldn't pay
+twice for the same fan-out.
+
+## Persist findings worth carrying forward
+
+Subagent transcripts die with the session unless you journal them. After
+synthesizing the reply, save durable findings to long-term memory —
+`memory_save` for new entries, or `memory_update` (after `memory_recall`
+to avoid fragmenting) when extending an existing one. See the
+`remember-this` skill for the full workflow.
+
+Save when a subagent surfaced:
+- A **code location** that was hard to find ("auth middleware lives in
+  `packages/auth/src/mw.ts`") → type `project`.
+- An **external pointer** worth keeping ("staging metrics at
+  `grafana.internal/d/auth`") → type `reference`.
+- A **convention or constraint** the fan-out revealed about the repo
+  ("all webhook handlers must call `verifySig` before parsing body") →
+  type `project`.
+
+Skip when:
+- The finding is only useful for the current reply (one-shot debug output).
+- It's already obvious from `git log`, README, or the code itself.
+- It's a secret — that belongs in the vault, not memory.
+
+One entry per durable finding, not one per subagent. If three subagents
+all rediscovered the same thing, save it once.
+
+## Don't
+
+- Don't spawn a subagent just to make a single tool call. Call the tool
+  directly in the current loop — spawning has setup overhead.
+- Don't fan out work that the user expected as a single deep
+  investigation ("dig into X" ≠ "find 5 articles about X").
+- Don't invent agent kinds. Either use a registered one or omit the field.

package/src/discovery.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ServiceRegistry } from '@moxxy/sdk';
+import { subagentsPlugin } from './index.js';
+
+/**
+ * The discovery-loadable default export resolves the `agents` + `tools`
+ * registries from the inter-plugin service registry in onInit instead of a
+ * `build*({ getAgent, getToolNames })` closure.
+ */
+describe('subagentsPlugin (discovery-loadable)', () => {
+  it('exposes dispatch_agent + an onInit hook', () => {
+    expect(subagentsPlugin.tools?.map((t) => t.name)).toEqual(['dispatch_agent']);
+    expect(typeof subagentsPlugin.hooks?.onInit).toBe('function');
+  });
+
+  it('onInit resolves the agents + tools registries from the service registry', () => {
+    const reg = { get: () => undefined, list: () => [], has: () => false };
+    const get = vi.fn(() => reg);
+    const services = {
+      get,
+      require: () => reg,
+      has: () => true,
+      register: () => {},
+    } as unknown as ServiceRegistry;
+    subagentsPlugin.hooks!.onInit!({ services } as never);
+    expect(get).toHaveBeenCalledWith('agents');
+    expect(get).toHaveBeenCalledWith('tools');
+  });
+});