agent-nuvira 3.3.1 → 3.3.4

package/README.md

@@ -158,13 +158,19 @@ This table highlights core capabilities for quick machine parsing and comparison
 - **Memory compression & pruning** — automatic trajectory summarization with configurable retention policies
 - **VS Code extension** — Chat Panel with streaming responses, slash commands, and session history;
   Diagnostic → AI Fix from lightbulb menu; Code Lens actions (Test/Review/Explain/Fix) above functions
-  and classes; 9 commands, inline code suggestions, diff viewer, agent progress panel
+  and classes; 13 commands, inline code suggestions, diff viewer, agent progress panel; three
+  language-model tools so Copilot Chat can delegate to this engine (`#reviewFileWithAgentNuvira`,
+  `#explainWithAgentNuvira`, `#executeGoalWithAgentNuvira`) and a small programmatic API
+  (`openChat`, `executeGoal`, `getActiveModel`, `getQuotaStatus`). **[Full usage guide → docs/VSCODE_EXTENSION.md](docs/VSCODE_EXTENSION.md)**
 - **22-platform multi-channel gateway** — `agent-nuvira gateway start / send / status / alias` runs the agent from Telegram, Discord, Slack, WhatsApp (Cloud API + Baileys personal bridge), Email, Signal, DingTalk, Feishu, WeCom, Mattermost, Matrix, generic Webhook, BlueBubbles (iMessage), ntfy, Teams, Google Chat, Weixin, SMS (Twilio), IRC (two-way), SimpleX (two-way),  and Home Assistant — all opt-in via standard env vars per platform, with a guaranteed delivery ledger (auto-retry on `agent-nuvira gateway start`), the dashboard Channels send-test, and a `X/22 platforms configured` status line
 - **Remote agent federation** — multi-machine collaboration with protocol, server, and client
 - **Web UI dashboard** — React dashboard with DAG visualization, model health, cost charts, and history browser
 - **Hybrid model routing** — intelligent model selection based on task complexity, cost, and availability
 - **Team collaboration** — Git-synced shared config, memory, and review pipelines
-- **Agent SDK** — `@agent-nuvira/sdk` npm package for building custom agents with scaffolding CLI
+- **Agent SDK** — `@agent-nuvira/sdk` npm package for building, testing and registering custom
+  agents: a provider-agnostic `Agent` base class, `defineAgent()` descriptors that fail at
+  definition time rather than at plan time, ten testing helpers that need no key and no network, and
+  scaffolding in three shapes. **[Full guide, with examples and an explicit depth statement → docs/AGENT_SDK.md](docs/AGENT_SDK.md)**
 - **Provider CLI** — `agent-nuvira provider list` with color-coded status table, `agent-nuvira provider health` with per-provider diagnostics
 - **Provider fallback routing** — automatic failover between providers with circuit breaker and configurable chain
 - **Startup progress feedback** — first launch never looks like a silent hang: a live spinner reports each startup phase (plugins → history & search → semantic index) as it runs
@@ -226,12 +232,8 @@ This table highlights core capabilities for quick machine parsing and comparison
 # Install globally
 npm install -g agent-nuvira
 
-# Or clone and build from source
-git clone https://github.com/imdheerajKube/agent-nuvira.git buff
-cd agent-nuvira
-npm install
-npm run build
-npm link
+# Or run it without installing anything globally
+npx agent-nuvira chat
 ```
 
 ### One-command setup for new users (recommended)
@@ -2166,9 +2168,10 @@ agent-nuvira chat --provider anthropic
 
 ### Setup
 
+The source is not published — npm is the distribution channel. This section is kept for the
+people already working on the private tree.
+
 ```bash
-git clone https://github.com/imdheerajKube/agent-nuvira.git
-cd agent-nuvira
 npm install
 ```
 
@@ -2279,6 +2282,8 @@ npx tsc --noEmit
 
 > 🛠️ **Complete CLI reference:** [docs/COMMANDS.md](./docs/COMMANDS.md) — every command with objective, exact syntax and examples, plus the first-run expectations. [docs/COMMANDS_SURFACE.md](./docs/COMMANDS_SURFACE.md) — the same surface, generated from the live command tree and drift-guarded in CI.
 >
+> 🧩 **Building your own agent:** [docs/AGENT_SDK.md](./docs/AGENT_SDK.md) — install, the full agent contract, `defineAgent()`'s failure modes, the ten testing helpers, scaffolding, registration, and an explicit **what you get / what you do not get**.  💻 **In the editor:** [docs/VSCODE_EXTENSION.md](./docs/VSCODE_EXTENSION.md) — all 13 commands mapped to the CLI verb each one runs, settings, keybindings, the three language-model tools, the programmatic API, and the same depth statement.
+
 > 📊 **Architecture, strategy & contribution materials:** [ARCHITECTURE.md](./ARCHITECTURE.md) — Modular execution engine design with 7 module specifications, extensibility/observability systems, and phased migration plan. [ARCHITECTURE_DIAGRAMS.md](./ARCHITECTURE_DIAGRAMS.md) — Mermaid-rendered versions of all architecture diagrams (Module Architecture, Extensibility, Safe Execution, Data Flow, Observability Bus). [PRODUCT_STRATEGY.md](./PRODUCT_STRATEGY.md) — Competitive landscape, positioning map, OKR framework, and risk register. [PITCH_DECK.md](./PITCH_DECK.md) — 10-slide investor presentation outline with talking points and data. [CONTRIBUTING.md](./CONTRIBUTING.md) — Quick-reference contributor guide with docs map, dev setup, and contribution workflow. [GATEWAY.md](./docs/GATEWAY.md) — Complete user guide for the 22-platform multi-channel gateway: what it offers, CLI + dashboard setup for every platform, channel aliases, guaranteed delivery, natural-language task dispatch, security, and troubleshooting.
 
 | Phase | Feature | Status |
@@ -2300,7 +2305,7 @@ npx tsc --noEmit
 | 2.5 | Provider health dashboard — `agent-nuvira doctor` | ✅ Complete |
 | 2.6 | Memory compression & pruning — trajectory summarization | ✅ Complete |
 | **Phase 3: Major Upgrades** | | |
-| 3.1 | VS Code extension — 9 commands, inline suggestions, diff viewer, agent progress panel | ✅ Complete |
+| 3.1 | VS Code extension — 13 commands, inline suggestions, diff viewer, agent progress panel | ✅ Complete |
 | 3.2 | **B1: Chat Panel** — Multi-turn chat with streaming, 6 slash commands, session history, file context | ✅ Complete (v1.33.0) |
 | 3.3 | **B3: Diagnostic → AI Fix** — "Fix with Agent-Nuvira" in lightbulb menu on red squiggles | ✅ Complete (v1.33.0) |
 | 3.4 | **B5: Code Lens Actions** — Test/Review/Explain/Fix actions above functions and classes | ✅ Complete (v1.34.0) |
@@ -2486,12 +2491,12 @@ npx tsc --noEmit
 ### Phase 3: Major Upgrades — Advanced Agent Systems
 | Feature | Description |
 |---------|-------------|
-| **VS Code Extension** | Chat Panel (streaming, slash commands), Diagnostic→AI Fix, Code Lens actions, 9 commands, inline suggestions, diff viewer, agent progress panel |
+| **VS Code Extension** | Chat Panel (streaming, slash commands), Diagnostic→AI Fix, Code Lens actions, 13 commands, inline suggestions, diff viewer, agent progress panel |
 | **Agent Federation** | Multi-machine collaboration via A2A protocol, server, and client |
 | **Web Dashboard** | React + Recharts + DAG visualization, model health, cost charts |
 | **Hybrid Model Routing** | Complexity-based model selection with cost optimization |
 | **Team Collaboration** | Git-synced shared config, memory, and review pipelines |
-| **Agent SDK** | `@agent-nuvira/sdk` npm package with scaffolding CLI |
+| **Agent SDK** | [`@agent-nuvira/sdk`](docs/AGENT_SDK.md) npm package with scaffolding CLI |
 | **Provider CLI** | `agent-nuvira provider list/health` with per-provider diagnostics |
 | **Provider Fallback** | Auto-failover with circuit breaker and configurable chain |
 | **Security Scanner** | Detects PII, prompt injections, and dangerous code patterns |

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

@@ -114,5 +114,7 @@ export interface AgentDescriptor {
     tags?: string;
     /** Agent type identifier used in task plans (defaults to kebab-case of name) */
     agentType?: string;
+    /** Optional emoji/icon used by the CLI and progress UI (e.g. "🧩") */
+    icon?: string;
 }
 //# sourceMappingURL=agent.d.ts.map

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

@@ -1 +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"}
+{"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;IACnB,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

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

@@ -0,0 +1,64 @@
+/**
+ * @agent-nuvira/sdk/define — Ergonomic agent descriptor helper.
+ *
+ * Hand-writing an `agentDescriptor` object is where custom agents most often go
+ * subtly wrong: the `agentType` drifts from the class name, a kebab-case typo
+ * silently never matches a plan step, or the name/description disagree with the
+ * class they describe. `defineAgent()` removes the duplication — it reads the
+ * agent's own `name`/`description`, derives a kebab-case `agentType` when one is
+ * not supplied, and validates the result at definition time so a broken
+ * descriptor fails where it is written rather than at plan time.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { Agent, defineAgent, type AgentContext, type AgentResult, type LLMCallFn } from '@agent-nuvira/sdk';
+ *
+ * class CodeFormatter extends Agent {
+ *   readonly name = 'CodeFormatter';
+ *   readonly description = 'Formats source code according to project conventions';
+ *   async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+ *     return { success: true, summary: 'Formatted' };
+ *   }
+ * }
+ *
+ * export const agentDescriptor = defineAgent({ AgentClass: CodeFormatter, tags: 'code, format' });
+ * ```
+ *
+ * @module @agent-nuvira/sdk/define
+ */
+import type { Agent, AgentDescriptor } from './agent.js';
+/** Input to {@link defineAgent}. Only `AgentClass` is required. */
+export interface DefineAgentInput<T extends Agent> {
+    /** The agent class (its no-arg constructor is called once to read metadata). */
+    AgentClass: new () => T;
+    /** Agent type used in task plans. Defaults to kebab-case of the agent name. */
+    agentType?: string;
+    /** Comma-separated tags for categorization. */
+    tags?: string;
+    /** Emoji/icon for the agent, used by the CLI and progress UI. */
+    icon?: string;
+    /** Override the name (defaults to the instance's `name`). */
+    name?: string;
+    /** Override the description (defaults to the instance's `description`). */
+    description?: string;
+}
+/**
+ * A descriptor with every field resolved. Unlike {@link AgentDescriptor},
+ * `name`, `description` and `agentType` are guaranteed present.
+ */
+export interface DefinedAgent extends AgentDescriptor {
+    name: string;
+    description: string;
+    agentType: string;
+}
+/** "CodeFormatter" → "code-formatter"; "HTTPClient" → "http-client". */
+export declare function toKebabCase(pascal: string): string;
+/**
+ * Build a validated agent descriptor from an agent class.
+ *
+ * @throws If the agent declares no name/description, if an explicit `agentType`
+ *   is not kebab-case, or if the class cannot be instantiated.
+ */
+export declare function defineAgent<T extends Agent>(input: DefineAgentInput<T>): DefinedAgent;
+//# sourceMappingURL=define.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/agent-sdk/src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIzD,mEAAmE;AACnE,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,KAAK;IAC/C,gFAAgF;IAChF,UAAU,EAAE,UAAU,CAAC,CAAC;IACxB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKlD;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,KAAK,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,YAAY,CAiCrF"}

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

@@ -0,0 +1,76 @@
+/**
+ * @agent-nuvira/sdk/define — Ergonomic agent descriptor helper.
+ *
+ * Hand-writing an `agentDescriptor` object is where custom agents most often go
+ * subtly wrong: the `agentType` drifts from the class name, a kebab-case typo
+ * silently never matches a plan step, or the name/description disagree with the
+ * class they describe. `defineAgent()` removes the duplication — it reads the
+ * agent's own `name`/`description`, derives a kebab-case `agentType` when one is
+ * not supplied, and validates the result at definition time so a broken
+ * descriptor fails where it is written rather than at plan time.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { Agent, defineAgent, type AgentContext, type AgentResult, type LLMCallFn } from '@agent-nuvira/sdk';
+ *
+ * class CodeFormatter extends Agent {
+ *   readonly name = 'CodeFormatter';
+ *   readonly description = 'Formats source code according to project conventions';
+ *   async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+ *     return { success: true, summary: 'Formatted' };
+ *   }
+ * }
+ *
+ * export const agentDescriptor = defineAgent({ AgentClass: CodeFormatter, tags: 'code, format' });
+ * ```
+ *
+ * @module @agent-nuvira/sdk/define
+ */
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/** "CodeFormatter" → "code-formatter"; "HTTPClient" → "http-client". */
+export function toKebabCase(pascal) {
+    return pascal
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .toLowerCase();
+}
+// ─── defineAgent ────────────────────────────────────────────────────────────
+/**
+ * Build a validated agent descriptor from an agent class.
+ *
+ * @throws If the agent declares no name/description, if an explicit `agentType`
+ *   is not kebab-case, or if the class cannot be instantiated.
+ */
+export function defineAgent(input) {
+    if (!input || typeof input.AgentClass !== 'function') {
+        throw new Error('defineAgent: `AgentClass` is required and must be a class constructor.');
+    }
+    let instance;
+    try {
+        instance = new input.AgentClass();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`defineAgent: could not instantiate ${input.AgentClass.name || 'agent'} — ${msg}`);
+    }
+    const name = (input.name ?? instance.name ?? '').trim();
+    const description = (input.description ?? instance.description ?? '').trim();
+    if (!name)
+        throw new Error('defineAgent: agent must declare a non-empty `name`.');
+    if (!description)
+        throw new Error(`defineAgent: agent '${name}' must declare a non-empty \`description\`.`);
+    const agentType = input.agentType ?? toKebabCase(name);
+    if (!/^[a-z][a-z0-9-]*$/.test(agentType)) {
+        throw new Error(`defineAgent: agentType "${agentType}" must be kebab-case (lowercase letters, digits, hyphens).`);
+    }
+    return {
+        AgentClass: input.AgentClass,
+        name,
+        description,
+        agentType,
+        tags: input.tags,
+        icon: input.icon,
+    };
+}
+//# sourceMappingURL=define.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/agent-sdk/src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAgCH,+EAA+E;AAE/E,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM;SACV,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAkB,KAA0B;IACrE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IAED,IAAI,QAAW,CAAC;IAChB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,sCAAsC,KAAK,CAAC,UAAU,CAAC,IAAI,IAAI,OAAO,MAAM,GAAG,EAAE,CAAC,CAAC;IACrG,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,MAAM,WAAW,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7E,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAClF,IAAI,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,6CAA6C,CAAC,CAAC;IAE5G,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,2BAA2B,SAAS,4DAA4D,CACjG,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,IAAI;QACJ,WAAW;QACX,SAAS;QACT,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC;AACJ,CAAC"}

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

@@ -24,10 +24,19 @@
  * - `@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)
+ * - `@agent-nuvira/sdk/register` — Register/unregister a custom agent with the orchestrator
+ * - `@agent-nuvira/sdk/scaffold` — Scaffold a new custom agent project
+ * - `@agent-nuvira/sdk/define` — `defineAgent()` descriptor helper
  *
  * @module @agent-nuvira/sdk
  */
 export { Agent } from './agent.js';
 export type { AgentDescriptor } from './agent.js';
+export { registerAgent, unregisterAgent } from './register.js';
+export type { RegisterOptions, RegisterResult } from './register.js';
+export { scaffold, listTemplates } from './scaffold.js';
+export type { ScaffoldOptions, ScaffoldTemplate } from './scaffold.js';
+export { defineAgent, toKebabCase } from './define.js';
+export type { DefineAgentInput, DefinedAgent } from './define.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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent-sdk/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIrE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIvE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIlE,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

@@ -24,9 +24,18 @@
  * - `@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)
+ * - `@agent-nuvira/sdk/register` — Register/unregister a custom agent with the orchestrator
+ * - `@agent-nuvira/sdk/scaffold` — Scaffold a new custom agent project
+ * - `@agent-nuvira/sdk/define` — `defineAgent()` descriptor helper
  *
  * @module @agent-nuvira/sdk
  */
 // ─── Agent Base Class ───────────────────────────────────────────────────────
 export { Agent } from './agent.js';
+// ─── Registration ───────────────────────────────────────────────────────────
+export { registerAgent, unregisterAgent } from './register.js';
+// ─── Scaffolding ────────────────────────────────────────────────────────────
+export { scaffold, listTemplates } from './scaffold.js';
+// ─── Descriptor Helper ──────────────────────────────────────────────────────
+export { defineAgent, toKebabCase } from './define.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent-sdk/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,+EAA+E;AAE/E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,+EAA+E;AAE/E,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAG/D,+EAA+E;AAE/E,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGxD,+EAA+E;AAE/E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

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

@@ -24,6 +24,17 @@ export interface ScaffoldOptions {
     /** Agent type identifier for task plans (default: kebab-case of agentName) */
     agentType?: string;
 }
+/**
+ * The SDK version a scaffolded project depends on.
+ *
+ * Kept as one constant, and deliberately in step with the SDK's own
+ * `package.json`: the scaffolded project is the first thing a consumer installs,
+ * and a template that pinned a stale major would build a project against an SDK
+ * that does not match the CLI which produced it — the exact mismatch that makes
+ * a custom agent fail to load. A test asserts the two agree, so a release that
+ * forgets this constant fails rather than shipping.
+ */
+export declare const SDK_VERSION = "3.3.4";
 /**
  * Scaffold a new custom agent project.
  *

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

@@ -1 +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"}
+{"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;AAmBD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AA+MnC;;;;;;;;;;;;;;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"}

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

@@ -23,6 +23,18 @@ function toKebabCase(pascal) {
 function toCamelCase(pascal) {
     return pascal.charAt(0).toLowerCase() + pascal.slice(1);
 }
+// ─── SDK version pin ────────────────────────────────────────────────────────
+/**
+ * The SDK version a scaffolded project depends on.
+ *
+ * Kept as one constant, and deliberately in step with the SDK's own
+ * `package.json`: the scaffolded project is the first thing a consumer installs,
+ * and a template that pinned a stale major would build a project against an SDK
+ * that does not match the CLI which produced it — the exact mismatch that makes
+ * a custom agent fail to load. A test asserts the two agree, so a release that
+ * forgets this constant fails rather than shipping.
+ */
+export const SDK_VERSION = '3.3.4';
 // ─── Templates ──────────────────────────────────────────────────────────────
 const PACKAGE_JSON_TEMPLATE = (opts) => `{
   "name": "${toKebabCase(opts.agentName)}-agent",
@@ -38,7 +50,7 @@ const PACKAGE_JSON_TEMPLATE = (opts) => `{
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-nuvira/sdk": "^1.0.0"
+    "@agent-nuvira/sdk": "^${SDK_VERSION}"
   },
   "devDependencies": {
     "typescript": "^5.3.0",
@@ -69,7 +81,7 @@ const AGENT_SRC_TEMPLATE = (opts) => {
  * Generated by \`nuvira sdk scaffold\`
  */
 
-import { Agent, type AgentContext, type AgentResult, type LLMCallFn } from '@agent-nuvira/sdk';
+import { Agent, defineAgent, type AgentContext, type AgentResult, type LLMCallFn } from '@agent-nuvira/sdk';
 
 export class ${opts.agentName} extends Agent {
   readonly name = '${opts.agentName}';
@@ -108,13 +120,11 @@ Please complete the task described in the goal.\`;
  * Agent descriptor for registering this agent in the system.
  * Export this to allow automatic registration.
  */
-export const agentDescriptor = {
+export const agentDescriptor = defineAgent({
   AgentClass: ${opts.agentName},
-  name: '${opts.agentName}',
-  description: '${opts.description}',
   agentType: '${agentType}',
   tags: 'custom',
-};
+});
 `;
 };
 const AGENT_INDEX_TEMPLATE = (opts) => `/**

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

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

package/dist/agents/agents/runner.d.ts

@@ -48,6 +48,15 @@ export interface RunResult {
     dependencyInstallTool?: string;
     /** Whether the tool itself had to be installed first (e.g. Homebrew) */
     dependencyInstallToolInstalled?: boolean;
+    /**
+     * True when the command exited 0 while provably doing nothing — `zip` matching
+     * none of its inputs, `git` with nothing to commit. A caller must not treat an
+     * exit code as evidence of a deliverable when this is set (
+     * see `artifact-verification.ts` for the live failure this came from).
+     */
+    producedNothing?: boolean;
+    /** Why the command is considered a no-op, for the trace and the user. */
+    noOpReason?: string;
 }
 /** A detected dependency-install plan for a project */
 export interface InstallPlan {

package/dist/agents/agents/runner.d.ts.map

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

package/dist/agents/agents/runner.js

@@ -29,6 +29,7 @@ import { SandboxManager } from '../../sandbox/manager.js';
 import { detectProjectImage } from '../../sandbox/images.js';
 import { getSandboxConfig } from '../../sandbox/types.js';
 import { referenceDocsFor } from '../reference-docs.js';
+import { detectNoOpCommand } from '../artifact-verification.js';
 import { isKnownSystemTool, manualInstallSteps, promptToolInstall, toolInstallCommand, } from '../../cli/tool-install-prompt.js';
 /** Maximum stdout/stderr length to store in context metadata */
 const MAX_OUTPUT_LENGTH = 10_000;
@@ -186,9 +187,15 @@ export class RunnerAgent extends Agent {
                 logger.info(`     Running (Docker): ${command}`);
             }
             const result = await sandboxManager.runCommand(containerId, command, timeoutMs);
-            // Build run result from sandbox result
+            // Build run result from sandbox result. Same question as the host path:
+            // a successful exit is not evidence that anything was produced.
+            const noOpReason = result.success
+                ? detectNoOpCommand(command, result.stdout, result.stderr)
+                : null;
             const runResult = {
                 success: result.success,
+                producedNothing: noOpReason !== null,
+                noOpReason: noOpReason ?? undefined,
                 command,
                 exitCode: result.exitCode,
                 stdout: result.stdout.slice(0, MAX_OUTPUT_LENGTH),
@@ -219,12 +226,15 @@ export class RunnerAgent extends Agent {
             // Clean up
             await sandboxManager.destroyContainer(containerId).catch(() => { });
             return {
-                success: result.exitCode === 0,
-                summary: result.exitCode === 0
-                    ? `✅ Command succeeded (Docker): ${command}`
-                    : `❌ Command failed (exit ${result.exitCode}): ${command}`,
+                // A command that matched nothing is not a completed step, even at exit 0.
+                success: result.exitCode === 0 && noOpReason === null,
+                summary: noOpReason !== null
+                    ? `⚠️ Command exited 0 but did nothing (Docker): ${noOpReason} — ${command}`
+                    : result.exitCode === 0
+                        ? `✅ Command succeeded (Docker): ${command}`
+                        : `❌ Command failed (exit ${result.exitCode}): ${command}`,
                 details: lines.join('\n'),
-                error: result.error || undefined,
+                error: noOpReason ?? (result.error || undefined),
             };
         }
         catch (err) {
@@ -888,8 +898,15 @@ export class RunnerAgent extends Agent {
                 }
             }
         }
+        // Exit code 0 answers "did the process fail?", not "did it do anything?".
+        // `zip` prints `zip warning: name not matched` for every input it could not
+        // find and still exits 0 — which is precisely how a 22-byte empty archive was
+        // recorded as a finished deliverable. Ask the output as well as the status.
+        const noOpReason = exitCode === 0 ? detectNoOpCommand(command, stdout, stderr) : null;
         const runResult = {
             success: exitCode === 0,
+            producedNothing: noOpReason !== null,
+            noOpReason: noOpReason ?? undefined,
             command,
             exitCode,
             stdout: stdout.slice(0, MAX_OUTPUT_LENGTH),
@@ -930,12 +947,17 @@ export class RunnerAgent extends Agent {
                 lines.push(`... (${stderr.length - 500} more chars)`);
         }
         return {
-            success: exitCode === 0,
-            summary: exitCode === 0
-                ? `✅ Command succeeded: ${command}`
-                : toolBlockError
-                    ? `❌ Required tool not available: ${command}`
-                    : `❌ Command failed (exit ${exitCode}): ${command}`,
+            // The step's outcome, not the process's. `zip` exits 0 after failing to
+            // find every input it was given, so an exit code alone would let a
+            // fabricated deliverable through as a success.
+            success: exitCode === 0 && noOpReason === null,
+            summary: noOpReason !== null
+                ? `⚠️ Command exited 0 but did nothing: ${noOpReason} — ${command}`
+                : exitCode === 0
+                    ? `✅ Command succeeded: ${command}`
+                    : toolBlockError
+                        ? `❌ Required tool not available: ${command}`
+                        : `❌ Command failed (exit ${exitCode}): ${command}`,
             details: lines.join('\n'),
             error: (toolBlockError || execError) && exitCode !== 0 ? (toolBlockError || execError) : undefined,
         };