agent-nuvira 1.14.0

package/dist/agent-sdk/src/agent.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @agent-nuvira/sdk/agent — Abstract base class for building custom agents.
+ *
+ * To create a custom agent:
+ * ```ts
+ * import { Agent, type AgentContext, type AgentResult } from '@agent-nuvira/sdk';
+ *
+ * export class MyAgent extends Agent {
+ *   readonly name = 'MyAgent';
+ *   readonly description = 'Does something useful';
+ *
+ *   async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+ *     // Read context artifacts, call the LLM, produce results
+ *     return { success: true, summary: 'Task completed' };
+ *   }
+ * }
+ * ```
+ *
+ * @module @agent-nuvira/sdk/agent
+ */
+import type { AgentContext, AgentResult, LLMCallFn } from './types.js';
+/**
+ * Abstract base class for all specialized agents.
+ *
+ * Every agent in the system extends this class. Agents are executed by the
+ * Orchestrator, which provides them with a shared {@link AgentContext} and an
+ * {@link LLMCallFn} for invoking the configured language model.
+ *
+ * ## Agent Lifecycle
+ *
+ * 1. **Construct** — The agent is created by the orchestrator's agent registry
+ * 2. **Validate** — {@link validate} is called (override to check prerequisites)
+ * 3. **Execute** — {@link execute} is called with the full context and LLM function
+ * 4. **Cleanup** — {@link cleanup} is called regardless of success/failure
+ *
+ * ## Example
+ *
+ * ```ts
+ * class CodeFormatterAgent extends Agent {
+ *   readonly name = 'CodeFormatter';
+ *   readonly description = 'Formats source code using project conventions';
+ *
+ *   async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+ *     const code = context.artifacts.find(a => a.path.endsWith('.ts'));
+ *     if (!code) {
+ *       return { success: false, summary: 'No TypeScript file found' };
+ *     }
+ *
+ *     const formatted = await callLLM(
+ *       `Format this code:\n\`\`\`\n${code.content}\n\`\`\``
+ *     );
+ *
+ *     context.fileChanges.push({
+ *       path: code.path,
+ *       originalContent: code.content,
+ *       newContent: formatted,
+ *       status: 'modified',
+ *     });
+ *
+ *     return { success: true, summary: `Formatted ${code.path}` };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Agent {
+    /** Human-readable agent name (e.g. "Planner", "Writer", "CodeFormatter") */
+    abstract readonly name: string;
+    /** Short description of what this agent does (used in planning and logging) */
+    abstract readonly description: string;
+    /**
+     * Execute the agent's specialized task.
+     *
+     * This is the main entry point. The agent should:
+     * 1. Read inputs from the shared context (`context.artifacts`, `context.goal`, etc.)
+     * 2. Call the LLM via `callLLM(prompt)` as needed
+     * 3. Write outputs to the shared context (`context.fileChanges`, `context.artifacts`)
+     * 4. Return an {@link AgentResult} indicating success/failure
+     *
+     * @param context  Shared context bus — read inputs, write outputs
+     * @param callLLM  Function to call the configured LLM with a prompt
+     * @returns        Result indicating success/failure + summary
+     */
+    abstract execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult>;
+    /**
+     * Validate that the agent can run with the given context.
+     * Override this to check prerequisites before execution.
+     *
+     * Default implementation returns `true` (no validation).
+     *
+     * @param context  The shared context bus
+     * @returns        `true` if the agent is ready to execute, or a string error message
+     */
+    validate(_context: AgentContext): true | string;
+    /**
+     * Cleanup hook called after execution, regardless of success or failure.
+     * Override this to release resources, close connections, etc.
+     *
+     * Default implementation does nothing.
+     */
+    cleanup(): void;
+}
+/**
+ * Metadata descriptor for registering an agent in the system.
+ * Used by {@link AgentRegistry} and the scaffolding tool.
+ */
+export interface AgentDescriptor {
+    /** Agent class constructor */
+    AgentClass: new () => Agent;
+    /** Human-readable name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Comma-separated tags for categorization (e.g. "code, analysis, format") */
+    tags?: string;
+    /** Agent type identifier used in task plans (defaults to kebab-case of name) */
+    agentType?: string;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent-sdk/src/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/agent-sdk/src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,8BAAsB,KAAK;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAEtC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IAEjF;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM;IAI/C;;;;;OAKG;IACH,OAAO,IAAI,IAAI;CAGhB;AAID;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,UAAU,EAAE,UAAU,KAAK,CAAC;IAC5B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/agent-sdk/src/agent.js

@@ -0,0 +1,88 @@
+/**
+ * @agent-nuvira/sdk/agent — Abstract base class for building custom agents.
+ *
+ * To create a custom agent:
+ * ```ts
+ * import { Agent, type AgentContext, type AgentResult } from '@agent-nuvira/sdk';
+ *
+ * export class MyAgent extends Agent {
+ *   readonly name = 'MyAgent';
+ *   readonly description = 'Does something useful';
+ *
+ *   async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+ *     // Read context artifacts, call the LLM, produce results
+ *     return { success: true, summary: 'Task completed' };
+ *   }
+ * }
+ * ```
+ *
+ * @module @agent-nuvira/sdk/agent
+ */
+// ─── Base Agent ─────────────────────────────────────────────────────────────
+/**
+ * Abstract base class for all specialized agents.
+ *
+ * Every agent in the system extends this class. Agents are executed by the
+ * Orchestrator, which provides them with a shared {@link AgentContext} and an
+ * {@link LLMCallFn} for invoking the configured language model.
+ *
+ * ## Agent Lifecycle
+ *
+ * 1. **Construct** — The agent is created by the orchestrator's agent registry
+ * 2. **Validate** — {@link validate} is called (override to check prerequisites)
+ * 3. **Execute** — {@link execute} is called with the full context and LLM function
+ * 4. **Cleanup** — {@link cleanup} is called regardless of success/failure
+ *
+ * ## Example
+ *
+ * ```ts
+ * class CodeFormatterAgent extends Agent {
+ *   readonly name = 'CodeFormatter';
+ *   readonly description = 'Formats source code using project conventions';
+ *
+ *   async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+ *     const code = context.artifacts.find(a => a.path.endsWith('.ts'));
+ *     if (!code) {
+ *       return { success: false, summary: 'No TypeScript file found' };
+ *     }
+ *
+ *     const formatted = await callLLM(
+ *       `Format this code:\n\`\`\`\n${code.content}\n\`\`\``
+ *     );
+ *
+ *     context.fileChanges.push({
+ *       path: code.path,
+ *       originalContent: code.content,
+ *       newContent: formatted,
+ *       status: 'modified',
+ *     });
+ *
+ *     return { success: true, summary: `Formatted ${code.path}` };
+ *   }
+ * }
+ * ```
+ */
+export class Agent {
+    /**
+     * Validate that the agent can run with the given context.
+     * Override this to check prerequisites before execution.
+     *
+     * Default implementation returns `true` (no validation).
+     *
+     * @param context  The shared context bus
+     * @returns        `true` if the agent is ready to execute, or a string error message
+     */
+    validate(_context) {
+        return true;
+    }
+    /**
+     * Cleanup hook called after execution, regardless of success or failure.
+     * Override this to release resources, close connections, etc.
+     *
+     * Default implementation does nothing.
+     */
+    cleanup() {
+        // Override to add cleanup logic
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent-sdk/src/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/agent-sdk/src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,OAAgB,KAAK;IAsBzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAsB;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACL,gCAAgC;IAClC,CAAC;CACF"}

package/dist/agent-sdk/src/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @agent-nuvira/sdk — Agent-Nuvira Software Development Kit
+ *
+ * Build custom agents for the Agent-Nuvira multi-agent orchestration system.
+ *
+ * ## Quick Start
+ *
+ * ```ts
+ * import { Agent, type AgentContext, type AgentResult, type LLMCallFn } from '@agent-nuvira/sdk';
+ *
+ * export class MyAgent extends Agent {
+ *   readonly name = 'MyAgent';
+ *   readonly description = 'Does something useful';
+ *
+ *   async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+ *     return { success: true, summary: 'Done!' };
+ *   }
+ * }
+ * ```
+ *
+ * ## Sub-modules
+ *
+ * - `@agent-nuvira/sdk` — Base Agent class + core types
+ * - `@agent-nuvira/sdk/agent` — Agent class only
+ * - `@agent-nuvira/sdk/types` — Type definitions only
+ * - `@agent-nuvira/sdk/testing` — Testing utilities (mock context, mock LLM, assertions)
+ *
+ * @module @agent-nuvira/sdk
+ */
+export { Agent } from './agent.js';
+export type { AgentDescriptor } from './agent.js';
+export type { TaskStatus, TaskStep, Artifact, FileChange, AgentMessage, LLMCallFn, InferenceOptions, RateLimitInfo, RateLimitAction, OnRateLimit, AgentContext, AgentResult, OrchestratorOptions, OrchestrationResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent-sdk/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent-sdk/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,YAAY,EAEV,UAAU,EACV,QAAQ,EAER,QAAQ,EACR,UAAU,EAEV,YAAY,EAEZ,SAAS,EACT,gBAAgB,EAEhB,aAAa,EACb,eAAe,EACf,WAAW,EAEX,YAAY,EACZ,WAAW,EAEX,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/agent-sdk/src/index.js

@@ -0,0 +1,32 @@
+/**
+ * @agent-nuvira/sdk — Agent-Nuvira Software Development Kit
+ *
+ * Build custom agents for the Agent-Nuvira multi-agent orchestration system.
+ *
+ * ## Quick Start
+ *
+ * ```ts
+ * import { Agent, type AgentContext, type AgentResult, type LLMCallFn } from '@agent-nuvira/sdk';
+ *
+ * export class MyAgent extends Agent {
+ *   readonly name = 'MyAgent';
+ *   readonly description = 'Does something useful';
+ *
+ *   async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+ *     return { success: true, summary: 'Done!' };
+ *   }
+ * }
+ * ```
+ *
+ * ## Sub-modules
+ *
+ * - `@agent-nuvira/sdk` — Base Agent class + core types
+ * - `@agent-nuvira/sdk/agent` — Agent class only
+ * - `@agent-nuvira/sdk/types` — Type definitions only
+ * - `@agent-nuvira/sdk/testing` — Testing utilities (mock context, mock LLM, assertions)
+ *
+ * @module @agent-nuvira/sdk
+ */
+// ─── Agent Base Class ───────────────────────────────────────────────────────
+export { Agent } from './agent.js';
+//# sourceMappingURL=index.js.map

package/dist/agent-sdk/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent-sdk/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,+EAA+E;AAE/E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/agent-sdk/src/register.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @agent-nuvira/sdk/register — Register a custom agent with the orchestrator.
+ *
+ * Modifies `src/agents/orchestrator.ts` to:
+ * 1. Add an import statement for the custom agent class
+ * 2. Add a `case` to the `createAgent()` switch statement
+ * 3. Add an icon to the `AGENT_ICONS` map
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { registerAgent } from '@agent-nuvira/sdk/register';
+ *
+ * const changes = registerAgent({
+ *   sourceModule: './agents/my-agent.js',
+ *   className: 'MyAgent',
+ *   agentType: 'my-agent',
+ * });
+ * ```
+ *
+ * @module @agent-nuvira/sdk/register
+ */
+/** Options for registering a custom agent */
+export interface RegisterOptions {
+    /** Absolute or relative path to the orchestrator source file (default: auto-detected) */
+    orchestratorPath?: string;
+    /** The import module path for the agent class, relative to orchestrator.ts dir. Example: './agents/my-agent.js' */
+    sourceModule: string;
+    /** The exported class name to import. Example: 'MyAgent' */
+    className: string;
+    /** The agent type string used in task plans and the switch case. Example: 'my-agent' */
+    agentType: string;
+    /** Optional emoji icon for the AGENT_ICONS map (default: 🧩) */
+    icon?: string;
+    /** Optional human-readable name (defaults to className) */
+    name?: string;
+}
+/** Result of a register/unregister operation */
+export interface RegisterResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Human-readable message describing what happened */
+    message: string;
+    /** Files that were modified */
+    modifiedFiles: string[];
+    /** The agent type that was operated on */
+    agentType: string;
+}
+/**
+ * Register a custom agent with the orchestrator.
+ *
+ * Reads the orchestrator source file, adds the import and switch case,
+ * and writes the file back.
+ */
+export declare function registerAgent(options: RegisterOptions): RegisterResult;
+/**
+ * Unregister a custom agent from the orchestrator.
+ *
+ * Removes the switch case and icon entry. If `className` is provided,
+ * also removes the matching import statement using an exact pattern
+ * (`import { className } from '...';`) to avoid accidentally removing
+ * built-in imports.
+ */
+export declare function unregisterAgent(options: {
+    orchestratorPath?: string;
+    agentType: string;
+    /** The exact exported class name. When provided, enables safe import removal. */
+    className?: string;
+}): RegisterResult;
+//# sourceMappingURL=register.d.ts.map

package/dist/agent-sdk/src/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/agent-sdk/src/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAWH,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mHAAmH;IACnH,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,CAsEtE;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,cAAc,CAqFjB"}

package/dist/agent-sdk/src/register.js

@@ -0,0 +1,181 @@
+/**
+ * @agent-nuvira/sdk/register — Register a custom agent with the orchestrator.
+ *
+ * Modifies `src/agents/orchestrator.ts` to:
+ * 1. Add an import statement for the custom agent class
+ * 2. Add a `case` to the `createAgent()` switch statement
+ * 3. Add an icon to the `AGENT_ICONS` map
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { registerAgent } from '@agent-nuvira/sdk/register';
+ *
+ * const changes = registerAgent({
+ *   sourceModule: './agents/my-agent.js',
+ *   className: 'MyAgent',
+ *   agentType: 'my-agent',
+ * });
+ * ```
+ *
+ * @module @agent-nuvira/sdk/register
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+// ─── Constants ──────────────────────────────────────────────────────────────
+const DEFAULT_ICON = '🧩';
+// ─── Registration Logic ─────────────────────────────────────────────────────
+/**
+ * Register a custom agent with the orchestrator.
+ *
+ * Reads the orchestrator source file, adds the import and switch case,
+ * and writes the file back.
+ */
+export function registerAgent(options) {
+    const { orchestratorPath: inputPath, sourceModule, className, agentType, icon = DEFAULT_ICON, name = className } = options;
+    const orchestratorPath = inputPath || resolve(process.cwd(), 'src/agents/orchestrator.ts');
+    if (!existsSync(orchestratorPath)) {
+        return { success: false, message: `Orchestrator file not found at: ${orchestratorPath}`, modifiedFiles: [], agentType };
+    }
+    const originalContent = readFileSync(orchestratorPath, 'utf-8');
+    // ── 1. Check if already registered ──────────────────────────────────
+    if (originalContent.includes(`case '${agentType}':`)) {
+        return { success: true, message: `Agent '${agentType}' is already registered. No changes made.`, modifiedFiles: [], agentType };
+    }
+    // ── 2. Add import statement ─────────────────────────────────────────
+    const importStatement = `import { ${className} } from '${sourceModule}';`;
+    let newContent = originalContent;
+    if (!originalContent.includes(importStatement)) {
+        const importLines = newContent.match(/^import .+;$/gm);
+        if (importLines && importLines.length > 0) {
+            const lastImport = importLines[importLines.length - 1];
+            const insertPos = newContent.lastIndexOf(lastImport) + lastImport.length;
+            newContent = newContent.slice(0, insertPos) + '\n' + importStatement + newContent.slice(insertPos);
+        }
+        else {
+            return { success: false, message: 'Could not find import section in orchestrator file.', modifiedFiles: [], agentType };
+        }
+    }
+    // ── 3. Add case to createAgent switch ───────────────────────────────
+    const caseBlock = `    case '${agentType}':\n      return new ${className}();`;
+    if (!newContent.includes(caseBlock)) {
+        const defaultPattern = 'default:\n      return null;';
+        const defaultIndex = newContent.lastIndexOf(defaultPattern);
+        if (defaultIndex >= 0) {
+            newContent = newContent.slice(0, defaultIndex) + caseBlock + '\n\n    ' + newContent.slice(defaultIndex);
+        }
+        else {
+            return { success: false, message: 'Could not find default case in createAgent switch.', modifiedFiles: [], agentType };
+        }
+    }
+    // ── 4. Add icon to AGENT_ICONS map ─────────────────────────────────
+    const iconLine = `  '${agentType}': '${icon}',`;
+    if (!newContent.includes(iconLine)) {
+        const iconsEndMarker = '};\n\nfunction createAgent';
+        const iconsEndIndex = newContent.lastIndexOf(iconsEndMarker);
+        if (iconsEndIndex >= 0) {
+            newContent = newContent.slice(0, iconsEndIndex) + iconLine + '\n' + newContent.slice(iconsEndIndex);
+        }
+    }
+    // ── 5. Write changes ────────────────────────────────────────────────
+    if (newContent === originalContent) {
+        return { success: true, message: `No changes needed for agent '${agentType}'. Already fully registered.`, modifiedFiles: [], agentType };
+    }
+    writeFileSync(orchestratorPath, newContent, 'utf-8');
+    const changes = [];
+    if (!originalContent.includes(importStatement))
+        changes.push('import');
+    if (!originalContent.includes(caseBlock))
+        changes.push('switch case');
+    if (!originalContent.includes(iconLine))
+        changes.push('icon');
+    return {
+        success: true,
+        message: `Registered agent '${agentType}' (${name}) with the orchestrator. Added: ${changes.join(', ') || 'nothing new'}.`,
+        modifiedFiles: [orchestratorPath],
+        agentType,
+    };
+}
+// ─── Unregistration Logic ───────────────────────────────────────────────────
+/**
+ * Unregister a custom agent from the orchestrator.
+ *
+ * Removes the switch case and icon entry. If `className` is provided,
+ * also removes the matching import statement using an exact pattern
+ * (`import { className } from '...';`) to avoid accidentally removing
+ * built-in imports.
+ */
+export function unregisterAgent(options) {
+    const { orchestratorPath: inputPath, agentType, className } = options;
+    const orchestratorPath = inputPath || resolve(process.cwd(), 'src/agents/orchestrator.ts');
+    if (!existsSync(orchestratorPath)) {
+        return { success: false, message: `Orchestrator file not found at: ${orchestratorPath}`, modifiedFiles: [], agentType };
+    }
+    const originalContent = readFileSync(orchestratorPath, 'utf-8');
+    if (!originalContent.includes(`case '${agentType}':`)) {
+        return { success: true, message: `Agent '${agentType}' is not registered. No changes needed.`, modifiedFiles: [], agentType };
+    }
+    let newContent = originalContent;
+    let changesMade = false;
+    // ── Remove the switch case block ──────────────────────────────────
+    // Matches the exact pattern added by registerAgent()
+    const caseRegex = new RegExp(`    case '${escapeRegex(agentType)}':\\n      return new \\w+\\(\\);\\n\\n    `, 'g');
+    const afterCase = newContent.replace(caseRegex, '');
+    if (afterCase !== newContent) {
+        newContent = afterCase;
+        changesMade = true;
+    }
+    else {
+        // Fallback: try without trailing indent (for last case in switch)
+        const fallbackRegex = new RegExp(`    case '${escapeRegex(agentType)}':\\n      return new \\w+\\(\\);\\n`, 'g');
+        const afterFallback = newContent.replace(fallbackRegex, '');
+        if (afterFallback !== newContent) {
+            newContent = afterFallback;
+            changesMade = true;
+        }
+    }
+    // ── Remove the icon line ──────────────────────────────────────────
+    const iconRegex = new RegExp(`  '${escapeRegex(agentType)}': '.[^']*',\\n`, 'g');
+    const afterIcon = newContent.replace(iconRegex, '');
+    if (afterIcon !== newContent) {
+        newContent = afterIcon;
+        changesMade = true;
+    }
+    // ── Remove the import (only with className for safety) ──────────────
+    let importRemoved = false;
+    if (className) {
+        const importRegex = new RegExp(`^import \\{ ${escapeRegex(className)} \\} from '[^']+';\n`, 'gm');
+        const afterImport = newContent.replace(importRegex, '');
+        // Collapse duplicate blank lines
+        const cleaned = afterImport.replace(/\n{3,}/g, '\n\n');
+        if (cleaned !== newContent) {
+            newContent = cleaned;
+            changesMade = true;
+            importRemoved = true;
+        }
+    }
+    if (!changesMade) {
+        return {
+            success: true,
+            message: `Could not auto-remove traces of '${agentType}'. Pass --class-name <Name> for import removal. Manual cleanup in src/agents/orchestrator.ts may be needed.`,
+            modifiedFiles: [],
+            agentType,
+        };
+    }
+    writeFileSync(orchestratorPath, newContent, 'utf-8');
+    const removed = ['switch case', 'icon'];
+    if (importRemoved)
+        removed.push('import');
+    return {
+        success: true,
+        message: `Unregistered agent '${agentType}' from the orchestrator. Removed: ${removed.join(', ')}.`,
+        modifiedFiles: [orchestratorPath],
+        agentType,
+    };
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/** Escape special regex characters in a string */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=register.js.map

package/dist/agent-sdk/src/register.js.map

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

package/dist/agent-sdk/src/scaffold.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @agent-nuvira/sdk/scaffold — Scaffolding command for creating custom agent projects.
+ *
+ * Generates a complete, ready-to-extend agent package with:
+ * - TypeScript configuration
+ * - A custom agent class extending {@link Agent}
+ * - Unit tests using the {@link testing} utilities
+ * - Package.json with build/test scripts
+ *
+ * @module @agent-nuvira/sdk/scaffold
+ */
+/** Template type to scaffold */
+export type ScaffoldTemplate = 'basic-agent' | 'full-agent' | 'agent-pack';
+/** Options for scaffolding */
+export interface ScaffoldOptions {
+    /** Output directory for the new agent project */
+    outDir: string;
+    /** Name of the agent class (PascalCase, e.g. "CodeFormatter") */
+    agentName: string;
+    /** Description of what the agent does */
+    description: string;
+    /** Template type (default: 'full-agent') */
+    template?: ScaffoldTemplate;
+    /** Agent type identifier for task plans (default: kebab-case of agentName) */
+    agentType?: string;
+}
+/**
+ * Scaffold a new custom agent project.
+ *
+ * @returns An array of file paths that were created.
+ *
+ * @example
+ * ```ts
+ * const files = scaffold({
+ *   outDir: './my-custom-agent',
+ *   agentName: 'CodeFormatter',
+ *   description: 'Formats source code according to project conventions',
+ * });
+ * console.log(\`Created \${files.length} files\`);
+ * ```
+ */
+export declare function scaffold(options: ScaffoldOptions): string[];
+/**
+ * List available scaffold templates with descriptions.
+ */
+export declare function listTemplates(): Array<{
+    name: string;
+    description: string;
+}>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/agent-sdk/src/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/agent-sdk/src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,gCAAgC;AAChC,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,YAAY,GAAG,YAAY,CAAC;AAE3E,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CAoD3D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAe5E"}