@wingman-ai/gateway 0.2.1 → 0.2.2

package/.wingman/agents/README.md

@@ -116,6 +116,7 @@ Agents can have their own subagents, allowing you to create hierarchical agent s
 
 - **Maximum nesting level: 1** - Only top-level agents can have subagents
 - **Subagents cannot have their own subagents** - This prevents excessive nesting and keeps the architecture manageable
+- **Subagent names must be unique and must not match the parent agent name** - Avoids ambiguous delegation routing
 
 ### Example: Agent with Subagents
 

package/.wingman/agents/coding/agent.md

@@ -1,6 +1,6 @@
 ---
 name: coding
-description: Lead coding orchestrator that plans, parallelizes, and reviews work delegated to a focused coding subagent.
+description: Lead coding orchestrator that plans, sequences, parallelizes, and reviews work delegated to focused implementation subagents.
 tools:
   - think
   - code_search
@@ -12,8 +12,8 @@ subAgents:
   - name: researcher
     description: Research subagent
     promptFile: ../researcher/agent.md
-  - name: coding
-    description: Executes assigned coding tasks with strict scope control and reports results clearly.
+  - name: implementor
+    description: Implements assigned coding chunks with strict scope control and concise verification output.
     tools:
       - command_execute
       - think
@@ -23,13 +23,26 @@ subAgents:
 ---
 
 You are the lead coding agent collaborating with the user as their Wingman.
-You plan and orchestrate work, delegate parallelizable chunks to the coding subagent, and then review everything against the plan before finalizing.
+You plan and orchestrate work, sequence dependent chunks, delegate parallelizable chunks to the implementor subagent, and then review everything against the plan before finalizing.
 Use memories to preserve key context, decisions, and assumptions for future turns.
 Only provide code examples if the user explicitly asks for an "example" or "snippet".
 Any code examples must use GitHub-flavored Markdown with a language specifier.
 
 **CRITICAL - Always use file paths relative to the current working directory**
 
+# Completion Contract (Non-Negotiable)
+- Your objective is full task completion, not partial progress.
+- Do NOT stop after completing one chunk if the user asked for broader scope.
+- Keep iterating through plan items until all requested outcomes are done or you hit a real blocker.
+- If blocked, report exactly what is blocked, what you already tried, and the smallest user decision needed to unblock.
+
+# Definition of Done (Before Final Response)
+- All explicitly requested outcomes are implemented.
+- All planned chunks are complete, or any incomplete chunk is explicitly marked with blocker + owner.
+- Relevant tests/builds are run and results are reported.
+- Cross-cutting checks are done for types, configs, docs, and integration points touched by the change.
+- If capability/behavior changed significantly, update relevant docs and requirements notes.
+
 # Memory Discipline
 - At the start, check for relevant memories and incorporate them into your plan
 - Store key decisions, constraints, and open questions in memory
@@ -63,15 +76,34 @@ Any code examples must use GitHub-flavored Markdown with a language specifier.
 - Prefer chunking by non-overlapping files or modules
 - Avoid assigning the same file to multiple subagents unless coordination is explicit
 - If dependencies require sequencing, run those chunks serially
+- Track plan status explicitly (`pending`, `in_progress`, `done`) and keep driving unfinished items to completion
+
+# Dependency-Aware Sequencing
+- Build a dependency map before delegation:
+  - `prerequisite` chunks: unblock architecture/tooling/foundations
+  - `parallel` chunks: independent implementation streams
+  - `dependent` chunks: require outputs from earlier chunks
+- Execute in waves:
+  1. Complete prerequisite chunks first
+  2. Run independent chunks in parallel
+  3. Run dependent/integration chunks after prerequisites are done
+  4. Finalize with verification and documentation updates
+- Never start a dependent chunk until required prerequisite chunks are `done`.
+- If a prerequisite chunk is blocked, immediately pause impacted downstream chunks, re-plan, and surface the blocker if unresolved.
 
 # Delegation Rules
-- Use the **coding** subagent for all code changes beyond trivial edits
+- Use the **implementor** subagent for all code changes beyond trivial edits
 - Use the **researcher** subagent for external docs or API research
-- Provide each coding task with:
-  - Scope and goal (1-2 sentences)
-  - Exact files to edit or create
-  - Acceptance criteria and edge cases
-  - Tests to run (or ask the subagent to propose)
+- Never delegate code work without an explicit chunk assignment
+- Every implementor delegation MUST include this packet exactly:
+  - `chunk_id`: short unique id (e.g., `chunk-auth-01`)
+  - `goal`: 1-2 sentence objective
+  - `scope_paths`: exact files/packages allowed for edits
+  - `out_of_scope`: boundaries and files to avoid
+  - `acceptance_criteria`: behavior/result required
+  - `tests`: exact commands to run, or `propose-tests` when unknown
+- If file scope is unclear, gather context first (search/read) before delegating
+- Never ask the implementor to define its own chunk or select files
 - If a task expands beyond scope, pause and ask before proceeding
 
 # Review Responsibility (Top-Level Only)
@@ -79,6 +111,15 @@ Any code examples must use GitHub-flavored Markdown with a language specifier.
 - Check that every plan item is satisfied and nothing is missing
 - Re-scan for cross-cutting issues (types, configs, tests, docs)
 - Run or request any remaining tests/builds needed for confidence
+- If review finds gaps, reopen delegation and resolve them before finalizing
+
+# Verification Pipeline (End-to-End)
+- For complex tasks, complete verification in this order unless constraints force otherwise:
+  1. Update/add tests for changed behavior
+  2. Run targeted tests for touched modules
+  3. Run broader project tests as appropriate
+  4. Run build/typecheck and report outcomes
+- Do not mark completion until the required verification pipeline is either passing or explicitly blocked with evidence.
 
 # Output Format Standards
 
@@ -87,10 +128,31 @@ Any code examples must use GitHub-flavored Markdown with a language specifier.
 - Include column for precise locations: `src/utils.ts:42:15`
 
 ## Response Structure
+- Use GitHub-flavored Markdown for user-facing responses
 - Lead with the most important information
 - Use flat bullet lists, avoid nesting
 - Code samples in fenced blocks with language specifier
-- Keep explanations brief - show, don't tell
+- Keep explanations brief by default; expand only when complexity or risk justifies it
+
+## Markdown Overview Mode
+- Provide a structured markdown overview when any of these are true:
+  - Multi-file or cross-cutting changes
+  - Behavior changes that can cause regressions
+  - Test/build failures or partial verification
+  - The user asks for detail, rationale, or review depth
+- Use this section order for rich feedback:
+  1. `Overview` (what changed and why)
+  2. `Changes` (key files and decisions)
+  3. `Validation` (tests/build/commands + results)
+  4. `Risks` (known gaps, assumptions, follow-ups)
+- For simple, low-risk tasks, use concise mode (short summary + validation line)
+
+## Completion Reporting
+- In final responses for non-trivial tasks, include:
+  - `Scope Status`: requested items mapped to `done` or `blocked`
+  - `Validation`: exact commands run + outcome
+  - `Outstanding`: only true blockers or follow-ups (if none, state `None`)
+- Never present an in-progress checkpoint as a final completion response
 
 ## Code Reviews (when reviewing)
 1. **Findings** (severity-ordered with file:line references)
@@ -106,13 +168,13 @@ Choose your approach based on task complexity:
 - Keep it efficient and avoid unnecessary delegation
 
 **MODERATE tasks** (new features, refactors, 50-200 lines):
-- Create a brief plan, then delegate chunks to **coding**
+- Create a brief plan, then delegate chunks to **implementor**
 - Parallelize by file/module when possible
 - Perform the final review yourself
 
 **COMPLEX tasks** (major features, architecture changes, > 200 lines):
 - ALWAYS create a detailed plan with parallel workstreams
-- Delegate each stream to **coding** with clear scopes
+- Delegate each stream to **implementor** with clear scopes
 - Perform a comprehensive top-level review before finalizing
 
 **Important**:
@@ -131,7 +193,7 @@ Choose your approach based on task complexity:
 7. When unexpected results occur, focus on solutions rather than apologies
 8. NEVER output code to the USER, unless requested
 9. When providing code examples, consistently use GitHub-flavored fenced markdown, specifying the appropriate programming language for syntax highlighting
-10. Keep responses concise and relevant, avoiding unnecessary details
+10. Keep responses concise and relevant by default, but provide rich markdown overviews when the task complexity warrants it
 
 # Information Gathering
 If you need more context to properly address the user's request:

package/.wingman/agents/coding/implementor.md

@@ -1,4 +1,18 @@
-You are the focused coding subagent. Your job is to implement the specific chunk assigned by the lead coding agent.
+You are the focused implementor subagent. Your job is to implement the specific chunk assigned by the lead coding agent.
+
+# Assignment Contract (Critical)
+You should receive a task packet with:
+- `chunk_id`
+- `goal`
+- `scope_paths`
+- `out_of_scope`
+- `acceptance_criteria`
+- `tests`
+
+If one or more fields are missing:
+- Infer missing non-critical fields from context and proceed
+- Ask for clarification only when both `goal` and `scope_paths` are missing
+- Ask at most once, then stop (do not loop on "no assignment" responses)
 
 # Scope Discipline (Critical)
 - Follow the lead's plan and scope exactly
@@ -6,6 +20,13 @@ You are the focused coding subagent. Your job is to implement the specific chunk
 - If you need additional files or scope changes, pause and ask the lead
 - Avoid overlapping edits with other subagents; surface conflicts immediately
 
+# Chunk Completion Standard
+- Treat each chunk as incomplete until all chunk acceptance criteria are satisfied.
+- Do not return early after partial edits if required tests/verification are still pending.
+- If verification fails, either fix the issue within scope or return a precise blocker with evidence.
+- Never hand back a chunk with vague status like "mostly done" or "ready for next step".
+- If blocked by unmet prerequisite work, return `Status: Blocked` and identify the blocking `chunk_id`.
+
 # Implementation Standards
 
 ## Code Quality
@@ -25,6 +46,7 @@ After implementation:
 1. Run tests requested by the lead
 2. If no tests were specified, propose the most relevant tests
 3. Note any tests you could not run and why
+4. Explicitly map each acceptance criterion to `pass` or `blocked`
 
 Your responsibilities:
 - Implement the assigned chunk precisely and systematically
@@ -42,13 +64,14 @@ Workflow:
 2. Implement changes following the lead's scope
 3. Ensure code follows existing conventions (imports, formatting, naming)
 4. Run relevant tests or validation commands when appropriate
-5. Summarize what was changed and why
+5. Summarize what was changed and why, grouped by `chunk_id`
 
 IMPORTANT:
 - Return summaries of changes made, NOT full file contents
 - Keep responses under 500 words - be concise
 - If you encounter issues or blockers, report them clearly
 - Don't add unnecessary features beyond the assigned task
+- End with a clear chunk status line: `Status: Done` or `Status: Blocked (<reason>)`
 
 Example summary format:
 "Modified [file]: [brief description of changes]

package/dist/agent/config/agentConfig.cjs

@@ -72,6 +72,35 @@ const BaseAgentConfigSchema = external_zod_namespaceObject.z.object({
 });
 const AgentConfigSchema = BaseAgentConfigSchema.extend({
     subAgents: external_zod_namespaceObject.z.array(BaseAgentConfigSchema).optional().describe("List of sub-agents that this agent can delegate to (each may include its own model override)")
+}).superRefine((config, ctx)=>{
+    if (!config.subAgents || 0 === config.subAgents.length) return;
+    const parentName = config.name.trim().toLowerCase();
+    const seenSubAgentNames = new Set();
+    for (const [index, subAgent] of config.subAgents.entries()){
+        const normalizedName = subAgent.name.trim().toLowerCase();
+        if (normalizedName === parentName) ctx.addIssue({
+            code: "custom",
+            path: [
+                "subAgents",
+                index,
+                "name"
+            ],
+            message: "Sub-agent name must be different from parent agent name"
+        });
+        if (seenSubAgentNames.has(normalizedName)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [
+                    "subAgents",
+                    index,
+                    "name"
+                ],
+                message: "Sub-agent names must be unique within the same parent agent"
+            });
+            continue;
+        }
+        seenSubAgentNames.add(normalizedName);
+    }
 });
 function validateAgentConfig(config) {
     try {

package/dist/agent/config/agentConfig.js

@@ -41,6 +41,35 @@ const BaseAgentConfigSchema = z.object({
 });
 const AgentConfigSchema = BaseAgentConfigSchema.extend({
     subAgents: z.array(BaseAgentConfigSchema).optional().describe("List of sub-agents that this agent can delegate to (each may include its own model override)")
+}).superRefine((config, ctx)=>{
+    if (!config.subAgents || 0 === config.subAgents.length) return;
+    const parentName = config.name.trim().toLowerCase();
+    const seenSubAgentNames = new Set();
+    for (const [index, subAgent] of config.subAgents.entries()){
+        const normalizedName = subAgent.name.trim().toLowerCase();
+        if (normalizedName === parentName) ctx.addIssue({
+            code: "custom",
+            path: [
+                "subAgents",
+                index,
+                "name"
+            ],
+            message: "Sub-agent name must be different from parent agent name"
+        });
+        if (seenSubAgentNames.has(normalizedName)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [
+                    "subAgents",
+                    index,
+                    "name"
+                ],
+                message: "Sub-agent names must be unique within the same parent agent"
+            });
+            continue;
+        }
+        seenSubAgentNames.add(normalizedName);
+    }
 });
 function validateAgentConfig(config) {
     try {

package/dist/agent/tests/agentConfig.test.cjs

@@ -69,6 +69,45 @@ const agentConfig_cjs_namespaceObject = require("../config/agentConfig.cjs");
             (0, external_vitest_namespaceObject.expect)(result.success).toBe(true);
             if (result.success) (0, external_vitest_namespaceObject.expect)(result.data.subAgents?.[0].model).toBe("openai:gpt-4o");
         });
+        (0, external_vitest_namespaceObject.it)("should fail when a sub-agent shares the same name as its parent", ()=>{
+            const config = {
+                name: "coding",
+                description: "Parent coding agent",
+                systemPrompt: "You are the parent coding agent",
+                subAgents: [
+                    {
+                        name: "coding",
+                        description: "Nested coding worker",
+                        systemPrompt: "You are a worker"
+                    }
+                ]
+            };
+            const result = (0, agentConfig_cjs_namespaceObject.validateAgentConfig)(config);
+            (0, external_vitest_namespaceObject.expect)(result.success).toBe(false);
+            if (!result.success) (0, external_vitest_namespaceObject.expect)(result.error).toContain("Sub-agent name must be different from parent agent name");
+        });
+        (0, external_vitest_namespaceObject.it)("should fail when sub-agent names are duplicated", ()=>{
+            const config = {
+                name: "parent-agent",
+                description: "Parent agent",
+                systemPrompt: "You are the parent agent",
+                subAgents: [
+                    {
+                        name: "implementor",
+                        description: "First implementor",
+                        systemPrompt: "You implement changes"
+                    },
+                    {
+                        name: "IMPLEMENTOR",
+                        description: "Duplicate implementor",
+                        systemPrompt: "You implement more changes"
+                    }
+                ]
+            };
+            const result = (0, agentConfig_cjs_namespaceObject.validateAgentConfig)(config);
+            (0, external_vitest_namespaceObject.expect)(result.success).toBe(false);
+            if (!result.success) (0, external_vitest_namespaceObject.expect)(result.error).toContain("Sub-agent names must be unique within the same parent agent");
+        });
         (0, external_vitest_namespaceObject.it)("should fail validation for missing required fields", ()=>{
             const config = {
                 name: "test-agent"

package/dist/agent/tests/agentConfig.test.js

@@ -67,6 +67,45 @@ describe("Agent Configuration Schema", ()=>{
             expect(result.success).toBe(true);
             if (result.success) expect(result.data.subAgents?.[0].model).toBe("openai:gpt-4o");
         });
+        it("should fail when a sub-agent shares the same name as its parent", ()=>{
+            const config = {
+                name: "coding",
+                description: "Parent coding agent",
+                systemPrompt: "You are the parent coding agent",
+                subAgents: [
+                    {
+                        name: "coding",
+                        description: "Nested coding worker",
+                        systemPrompt: "You are a worker"
+                    }
+                ]
+            };
+            const result = validateAgentConfig(config);
+            expect(result.success).toBe(false);
+            if (!result.success) expect(result.error).toContain("Sub-agent name must be different from parent agent name");
+        });
+        it("should fail when sub-agent names are duplicated", ()=>{
+            const config = {
+                name: "parent-agent",
+                description: "Parent agent",
+                systemPrompt: "You are the parent agent",
+                subAgents: [
+                    {
+                        name: "implementor",
+                        description: "First implementor",
+                        systemPrompt: "You implement changes"
+                    },
+                    {
+                        name: "IMPLEMENTOR",
+                        description: "Duplicate implementor",
+                        systemPrompt: "You implement more changes"
+                    }
+                ]
+            };
+            const result = validateAgentConfig(config);
+            expect(result.success).toBe(false);
+            if (!result.success) expect(result.error).toContain("Sub-agent names must be unique within the same parent agent");
+        });
         it("should fail validation for missing required fields", ()=>{
             const config = {
                 name: "test-agent"

package/dist/cli/core/agentInvoker.cjs

@@ -96,7 +96,9 @@ class AgentInvoker {
     async findAgent(name) {
         return await this.loader.loadAgent(name);
     }
-    async invokeAgent(agentName, prompt, sessionId, attachments) {
+    async invokeAgent(agentName, prompt, sessionId, attachments, options) {
+        let cancellationHandled = false;
+        const isCancelled = ()=>options?.signal?.aborted === true;
         try {
             const executionWorkspace = resolveExecutionWorkspace(this.workspace, this.workdir);
             const effectiveWorkdir = this.workdir ? executionWorkspace : null;
@@ -211,9 +213,29 @@ class AgentInvoker {
                     configurable: {
                         thread_id: sessionId
                     },
-                    version: "v2"
+                    version: "v2",
+                    signal: options?.signal
                 });
-                for await (const chunk of stream)this.outputManager.emitAgentStream(chunk);
+                for await (const chunk of stream){
+                    if (isCancelled()) {
+                        cancellationHandled = true;
+                        this.logger.info("Agent invocation cancelled");
+                        this.outputManager.emitAgentError("Request cancelled");
+                        if ("function" == typeof stream?.return) await stream.return();
+                        return {
+                            cancelled: true
+                        };
+                    }
+                    this.outputManager.emitAgentStream(chunk);
+                }
+                if (isCancelled()) {
+                    cancellationHandled = true;
+                    this.logger.info("Agent invocation cancelled");
+                    this.outputManager.emitAgentError("Request cancelled");
+                    return {
+                        cancelled: true
+                    };
+                }
                 this.logger.info("Agent streaming completed successfully");
                 this.outputManager.emitAgentComplete({
                     streaming: true
@@ -224,6 +246,14 @@ class AgentInvoker {
             }
             {
                 this.logger.debug("Using blocking invoke (no session manager)");
+                if (isCancelled()) {
+                    cancellationHandled = true;
+                    this.logger.info("Agent invocation cancelled");
+                    this.outputManager.emitAgentError("Request cancelled");
+                    return {
+                        cancelled: true
+                    };
+                }
                 const result = await standaloneAgent.invoke({
                     messages: [
                         {
@@ -232,13 +262,30 @@ class AgentInvoker {
                         }
                     ]
                 }, {
-                    recursionLimit: this.wingmanConfig.recursionLimit
+                    recursionLimit: this.wingmanConfig.recursionLimit,
+                    signal: options?.signal
                 });
+                if (isCancelled()) {
+                    cancellationHandled = true;
+                    this.logger.info("Agent invocation cancelled");
+                    this.outputManager.emitAgentError("Request cancelled");
+                    return {
+                        cancelled: true
+                    };
+                }
                 this.logger.info("Agent completed successfully");
                 this.outputManager.emitAgentComplete(result);
                 return result;
             }
         } catch (error) {
+            const abortError = isCancelled() || error instanceof Error && ("AbortError" === error.name || "CancelledError" === error.name || /abort|cancel/i.test(error.message));
+            if (abortError) {
+                if (!cancellationHandled) this.outputManager.emitAgentError("Request cancelled");
+                this.logger.info("Agent invocation cancelled");
+                return {
+                    cancelled: true
+                };
+            }
             this.logger.error(`Agent invocation failed: ${error instanceof Error ? error.message : String(error)}`);
             this.outputManager.emitAgentError(error);
             throw error;

package/dist/cli/core/agentInvoker.d.ts

@@ -12,6 +12,9 @@ export interface AgentInvokerOptions {
     workdir?: string | null;
     defaultOutputDir?: string | null;
 }
+export interface InvokeAgentOptions {
+    signal?: AbortSignal;
+}
 export type ImageAttachment = {
     kind?: "image";
     dataUrl: string;
@@ -99,7 +102,7 @@ export declare class AgentInvoker {
     /**
      * Invoke a specific agent directly (bypassing main orchestration)
      */
-    invokeAgent(agentName: string, prompt: string, sessionId?: string, attachments?: MediaAttachment[]): Promise<any>;
+    invokeAgent(agentName: string, prompt: string, sessionId?: string, attachments?: MediaAttachment[], options?: InvokeAgentOptions): Promise<any>;
     /**
      * List all available agents with their descriptions
      */

package/dist/cli/core/agentInvoker.js

@@ -62,7 +62,9 @@ class AgentInvoker {
     async findAgent(name) {
         return await this.loader.loadAgent(name);
     }
-    async invokeAgent(agentName, prompt, sessionId, attachments) {
+    async invokeAgent(agentName, prompt, sessionId, attachments, options) {
+        let cancellationHandled = false;
+        const isCancelled = ()=>options?.signal?.aborted === true;
         try {
             const executionWorkspace = resolveExecutionWorkspace(this.workspace, this.workdir);
             const effectiveWorkdir = this.workdir ? executionWorkspace : null;
@@ -177,9 +179,29 @@ class AgentInvoker {
                     configurable: {
                         thread_id: sessionId
                     },
-                    version: "v2"
+                    version: "v2",
+                    signal: options?.signal
                 });
-                for await (const chunk of stream)this.outputManager.emitAgentStream(chunk);
+                for await (const chunk of stream){
+                    if (isCancelled()) {
+                        cancellationHandled = true;
+                        this.logger.info("Agent invocation cancelled");
+                        this.outputManager.emitAgentError("Request cancelled");
+                        if ("function" == typeof stream?.return) await stream.return();
+                        return {
+                            cancelled: true
+                        };
+                    }
+                    this.outputManager.emitAgentStream(chunk);
+                }
+                if (isCancelled()) {
+                    cancellationHandled = true;
+                    this.logger.info("Agent invocation cancelled");
+                    this.outputManager.emitAgentError("Request cancelled");
+                    return {
+                        cancelled: true
+                    };
+                }
                 this.logger.info("Agent streaming completed successfully");
                 this.outputManager.emitAgentComplete({
                     streaming: true
@@ -190,6 +212,14 @@ class AgentInvoker {
             }
             {
                 this.logger.debug("Using blocking invoke (no session manager)");
+                if (isCancelled()) {
+                    cancellationHandled = true;
+                    this.logger.info("Agent invocation cancelled");
+                    this.outputManager.emitAgentError("Request cancelled");
+                    return {
+                        cancelled: true
+                    };
+                }
                 const result = await standaloneAgent.invoke({
                     messages: [
                         {
@@ -198,13 +228,30 @@ class AgentInvoker {
                         }
                     ]
                 }, {
-                    recursionLimit: this.wingmanConfig.recursionLimit
+                    recursionLimit: this.wingmanConfig.recursionLimit,
+                    signal: options?.signal
                 });
+                if (isCancelled()) {
+                    cancellationHandled = true;
+                    this.logger.info("Agent invocation cancelled");
+                    this.outputManager.emitAgentError("Request cancelled");
+                    return {
+                        cancelled: true
+                    };
+                }
                 this.logger.info("Agent completed successfully");
                 this.outputManager.emitAgentComplete(result);
                 return result;
             }
         } catch (error) {
+            const abortError = isCancelled() || error instanceof Error && ("AbortError" === error.name || "CancelledError" === error.name || /abort|cancel/i.test(error.message));
+            if (abortError) {
+                if (!cancellationHandled) this.outputManager.emitAgentError("Request cancelled");
+                this.logger.info("Agent invocation cancelled");
+                return {
+                    cancelled: true
+                };
+            }
             this.logger.error(`Agent invocation failed: ${error instanceof Error ? error.message : String(error)}`);
             this.outputManager.emitAgentError(error);
             throw error;