agent-nuvira 1.14.0

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

@@ -0,0 +1,243 @@
+/**
+ * @agent-nuvira/sdk/testing — Testing utilities for building and testing custom agents.
+ *
+ * Provides:
+ * - {@link createMockContext} — Build a fully typed {@link AgentContext} for tests
+ * - {@link createMockLLM} — Create a mock LLM function that returns controlled responses
+ * - {@link runAgentTest} — Convenience wrapper for executing an agent in a test
+ * - {@link assertAgentSuccess} / {@link assertAgentFailure} — Result assertions
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { describe, it, expect } from 'vitest';
+ * import { MyAgent } from './my-agent.js';
+ * import {
+ *   createMockContext,
+ *   createMockLLM,
+ *   runAgentTest,
+ *   assertAgentSuccess,
+ * } from '@agent-nuvira/sdk/testing';
+ *
+ * describe('MyAgent', () => {
+ *   it('should process files correctly', async () => {
+ *     const context = createMockContext({
+ *       goal: 'Format all TypeScript files',
+ *       artifacts: [{ path: 'src/index.ts', content: 'const x=1', description: 'Source file' }],
+ *     });
+ *     const callLLM = createMockLLM('Formatted code content');
+ *
+ *     const result = await runAgentTest(new MyAgent(), context, callLLM);
+ *
+ *     assertAgentSuccess(result);
+ *     expect(result.summary).toContain('Formatted');
+ *     expect(context.fileChanges).toHaveLength(1);
+ *   });
+ * });
+ * ```
+ *
+ * @module @agent-nuvira/sdk/testing
+ */
+/**
+ * Create a fully typed mock {@link AgentContext} for testing agents.
+ *
+ * @example
+ * ```ts
+ * const ctx = createMockContext({
+ *   goal: 'Add error handling to server.ts',
+ *   artifacts: [{ path: 'server.ts', content: '...', description: 'Main server' }],
+ * });
+ * ```
+ */
+export function createMockContext(options = {}) {
+    return {
+        goal: options.goal || 'Test goal',
+        workingDirectory: options.workingDirectory || process.cwd(),
+        taskPlan: options.taskPlan || [],
+        artifacts: options.artifacts || [],
+        fileChanges: options.fileChanges || [],
+        conversations: options.conversations || [],
+        metadata: options.metadata || {},
+        onRateLimit: options.onRateLimit
+            ? async () => ({ action: 'retry' })
+            : undefined,
+    };
+}
+/**
+ * Create a mock LLM function that returns a fixed response.
+ * Useful for testing agent logic without making real API calls.
+ *
+ * Also provides a `prompts` array on the returned function that records all
+ * prompts sent to it (when `trackPrompts` is enabled).
+ *
+ * @example
+ * ```ts
+ * const callLLM = createMockLLM('Some LLM response');
+ * const result = await callLLM('Some prompt');
+ * // result === 'Some LLM response'
+ * // callLLM.prompts[0] === { prompt: 'Some prompt', options: undefined }
+ * ```
+ */
+export function createMockLLM(response = '', options = {}) {
+    const trackPrompts = options.trackPrompts !== false;
+    const prompts = [];
+    const fn = async (prompt, opts) => {
+        if (trackPrompts) {
+            prompts.push({ prompt, options: opts });
+        }
+        return response;
+    };
+    fn.prompts = prompts;
+    return fn;
+}
+/**
+ * Create a mock LLM function that throws an error.
+ * Useful for testing error handling in agents.
+ *
+ * @example
+ * ```ts
+ * const callLLM = createFailingMockLLM(new Error('API rate limit'));
+ * await expect(agent.execute(ctx, callLLM)).resolves.toMatchObject({ success: false });
+ * ```
+ */
+export function createFailingMockLLM(error = new Error('Mock LLM error')) {
+    return async () => {
+        throw error;
+    };
+}
+/**
+ * Create a mock LLM function that returns different responses in sequence.
+ * Useful for testing agents that need multiple LLM calls.
+ *
+ * @example
+ * ```ts
+ * const callLLM = createSequentialMockLLM(['First response', 'Second response']);
+ * const r1 = await callLLM('prompt 1'); // 'First response'
+ * const r2 = await callLLM('prompt 2'); // 'Second response'
+ * ```
+ */
+export function createSequentialMockLLM(responses) {
+    let index = 0;
+    return async () => {
+        if (index >= responses.length) {
+            throw new Error(`Sequential mock exhausted: no more responses (called ${index + 1} times)`);
+        }
+        return responses[index++];
+    };
+}
+// ─── Test Runner ────────────────────────────────────────────────────────────
+/**
+ * Execute an agent in a test context and return the result.
+ * Automatically calls `validate()` before execution and `cleanup()` after.
+ *
+ * @example
+ * ```ts
+ * const result = await runAgentTest(new MyAgent(), context, callLLM);
+ * ```
+ */
+export async function runAgentTest(agent, context, callLLM = createMockLLM()) {
+    // Validate
+    const validationResult = agent.validate(context);
+    if (validationResult !== true) {
+        return {
+            success: false,
+            summary: 'Validation failed',
+            error: validationResult,
+        };
+    }
+    // Execute
+    let result;
+    try {
+        result = await agent.execute(context, callLLM);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        result = { success: false, summary: 'Agent threw an error', error: msg };
+    }
+    finally {
+        // Cleanup (runs even if execute throws)
+        try {
+            agent.cleanup();
+        }
+        catch {
+            // Best-effort cleanup
+        }
+    }
+    return result;
+}
+// ─── Assertion Helpers ───────────────────────────────────────────────────────
+/**
+ * Assert that an agent result indicates success.
+ * Throws a descriptive error if the result is falsy or has `success: false`.
+ *
+ * @example
+ * ```ts
+ * assertAgentSuccess(result);
+ * ```
+ */
+export function assertAgentSuccess(result) {
+    if (!result) {
+        throw new Error('Expected agent result, but got ' + String(result));
+    }
+    if (!result.success) {
+        const summary = result.summary || '(no summary)';
+        const error = result.error ? `\n  Error: ${result.error}` : '';
+        throw new Error(`Agent failed unexpectedly: ${summary}${error}`);
+    }
+}
+/**
+ * Assert that an agent result indicates failure with an optional error match.
+ *
+ * @example
+ * ```ts
+ * assertAgentFailure(result, 'rate limit');
+ * ```
+ */
+export function assertAgentFailure(result, expectedErrorSubstring) {
+    if (!result) {
+        throw new Error('Expected agent result, but got ' + String(result));
+    }
+    if (result.success) {
+        throw new Error(`Agent succeeded unexpectedly: ${result.summary}`);
+    }
+    if (expectedErrorSubstring && result.error) {
+        if (!result.error.toLowerCase().includes(expectedErrorSubstring.toLowerCase())) {
+            throw new Error(`Expected error to contain "${expectedErrorSubstring}", but got: ${result.error}`);
+        }
+    }
+}
+// ─── Context Helpers ────────────────────────────────────────────────────────
+/**
+ * Add a file artifact to a context for testing.
+ *
+ * @example
+ * ```ts
+ * addArtifact(ctx, 'src/index.ts', 'console.log("hello")', 'Entry point');
+ * ```
+ */
+export function addArtifact(context, path, content, description) {
+    context.artifacts.push({ path, content, description });
+}
+/**
+ * Add a task step to a context's task plan.
+ *
+ * @example
+ * ```ts
+ * addTaskStep(ctx, 'step-1', 'writer', 'Write the main file', []);
+ * ```
+ */
+export function addTaskStep(context, id, agentType, description, dependsOn = [], status = 'pending') {
+    context.taskPlan.push({ id, description, agentType, dependsOn, status });
+}
+/**
+ * Add a file change to a context.
+ *
+ * @example
+ * ```ts
+ * addFileChange(ctx, 'src/index.ts', 'console.log("hello")', undefined, 'created');
+ * ```
+ */
+export function addFileChange(context, path, newContent, originalContent, status = 'modified') {
+    context.fileChanges.push({ path, originalContent, newContent, status });
+}
+//# sourceMappingURL=testing.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../../src/agent-sdk/src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAqCH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA8B,EAAE;IAChE,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW;QACjC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,EAAE;QAC3D,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;QAChC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE;QAClC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;QACtC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,EAAE;QAC1C,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;QAChC,WAAW,EAAE,OAAO,CAAC,WAAW;YAC9B,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YACnC,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC;AAcD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,WAAmB,EAAE,EACrB,UAA0B,EAAE;IAE5B,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,KAAK,KAAK,CAAC;IACpD,MAAM,OAAO,GAA0D,EAAE,CAAC;IAE1E,MAAM,EAAE,GAAG,KAAK,EAAE,MAAc,EAAE,IAAuB,EAAmB,EAAE;QAC5E,IAAI,YAAY,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IAEF,EAAE,CAAC,OAAO,GAAG,OAAO,CAAC;IACrB,OAAO,EAA6C,CAAC;AACvD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAe,IAAI,KAAK,CAAC,gBAAgB,CAAC;IAC7E,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,KAAK,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAmB;IACzD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,IAAI,EAAE;QAChB,IAAI,KAAK,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,wDAAwD,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9F,CAAC;QACD,OAAO,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5B,CAAC,CAAC;AACJ,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAY,EACZ,OAAqB,EACrB,UAAqB,aAAa,EAAE;IAEpC,WAAW;IACX,MAAM,gBAAgB,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjD,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC9B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,mBAAmB;YAC5B,KAAK,EAAE,gBAAgB;SACxB,CAAC;IACJ,CAAC;IAED,UAAU;IACV,IAAI,MAAmB,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACjD,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,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC3E,CAAC;YAAS,CAAC;QACT,wCAAwC;QACxC,IAAI,CAAC;YACH,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAmB;IACpD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,cAAc,CAAC;QACjD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAmB,EACnB,sBAA+B;IAE/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,iCAAiC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,sBAAsB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAC/E,MAAM,IAAI,KAAK,CACb,8BAA8B,sBAAsB,eAAe,MAAM,CAAC,KAAK,EAAE,CAClF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,OAAqB,EACrB,IAAY,EACZ,OAAe,EACf,WAAmB;IAEnB,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,OAAqB,EACrB,EAAU,EACV,SAAiB,EACjB,WAAmB,EACnB,YAAsB,EAAE,EACxB,SAAqB,SAAS;IAE9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAqB,EACrB,IAAY,EACZ,UAAkB,EAClB,eAAwB,EACxB,SAA+B,UAAU;IAEzC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;AAC1E,CAAC"}

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

@@ -0,0 +1,202 @@
+/**
+ * @agent-nuvira/sdk/types — Core type definitions for building custom agents.
+ *
+ * These types mirror the types used in the Agent-Nuvira orchestration system.
+ * Agents communicate through a shared {@link AgentContext} bus managed by the
+ * {@link Orchestrator}.
+ *
+ * @module @agent-nuvira/sdk/types
+ */
+/** Status of a single task step within the execution plan */
+export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed';
+/** A single step in the ordered execution plan produced by the PlannerAgent */
+export interface TaskStep {
+    /** Unique identifier for this step (e.g. 'step-1', 'step-2') */
+    id: string;
+    /** Human-readable description of what this step does */
+    description: string;
+    /** The type of agent that should execute this step (e.g. 'writer', 'runner') */
+    agentType: string;
+    /** IDs of steps that must complete before this one can start */
+    dependsOn: string[];
+    /** Current execution status */
+    status: TaskStatus;
+    /** Optional result/summary text after execution */
+    result?: string;
+}
+/** A file artifact discovered or produced during agent execution */
+export interface Artifact {
+    /** Relative or absolute path to the file */
+    path: string;
+    /** Full file content */
+    content: string;
+    /** Human-readable description of why this file is relevant */
+    description: string;
+}
+/** A file change proposed or applied by an agent */
+export interface FileChange {
+    /** Relative or absolute path to the file */
+    path: string;
+    /** The original file content (undefined if file doesn't exist yet) */
+    originalContent?: string;
+    /** The new file content (undefined if file is being deleted) */
+    newContent?: string;
+    /** Whether the file is being created, modified, or deleted */
+    status: 'created' | 'modified' | 'deleted';
+}
+/** A message exchanged between agents via the shared context bus */
+export interface AgentMessage {
+    /** Name of the sending agent */
+    from: string;
+    /** Name of the receiving agent */
+    to: string;
+    /** Message content */
+    content: string;
+    /** Unix timestamp when the message was sent */
+    timestamp: number;
+}
+/**
+ * Options passed to the LLM generation call.
+ * Mirrors {@link InferenceOptions} from the main package.
+ */
+export interface InferenceOptions {
+    /** Temperature for response randomness (0.0–2.0) */
+    temperature?: number;
+    /** Maximum tokens in the generated response */
+    maxTokens?: number;
+    /** Model identifier override */
+    model?: string;
+    /** Stop sequences */
+    stop?: string[];
+    /** Top-p nucleus sampling */
+    topP?: number;
+}
+/**
+ * Function signature that agents use to invoke the LLM.
+ * The orchestrator injects this so it can control which provider/model
+ * each agent uses.
+ */
+export type LLMCallFn = (prompt: string, options?: InferenceOptions) => Promise<string>;
+/** Information about a rate-limit error, passed to the onRateLimit callback */
+export interface RateLimitInfo {
+    /** How long to wait before retrying, in milliseconds */
+    retryAfterMs: number;
+    /** Name of the model that was being used */
+    modelName?: string;
+    /** Provider identifier */
+    provider?: string;
+    /** Name of the agent that hit the limit */
+    agentName: string;
+    /** The original error message */
+    errorMessage: string;
+}
+/** Actions the orchestrator/user can take when a rate limit is hit */
+export type RateLimitAction = 
+/** Wait the suggested time and retry with the current model */
+{
+    action: 'retry';
+}
+/** Gracefully skip this step (return soft success) */
+ | {
+    action: 'skip';
+}
+/** Fail immediately and stop the pipeline */
+ | {
+    action: 'abort';
+}
+/** Retry with a different model */
+ | {
+    action: 'switch-model';
+    callLLM: LLMCallFn;
+};
+/** Callback used by agents to ask the orchestrator/user what to do on rate limit */
+export type OnRateLimit = (info: RateLimitInfo) => Promise<RateLimitAction>;
+/**
+ * The shared context bus that all agents read from and write to.
+ * This is the single source of truth for inter-agent communication.
+ * Each agent receives this context and can read inputs, write outputs,
+ * and exchange messages with other agents.
+ */
+export interface AgentContext {
+    /** The original user goal / task description */
+    goal: string;
+    /** Absolute path to the working directory (project root) */
+    workingDirectory: string;
+    /** Ordered task plan produced by the PlannerAgent */
+    taskPlan: TaskStep[];
+    /** File artifacts discovered (context) or produced (output) */
+    artifacts: Artifact[];
+    /** Agent-to-agent conversation log */
+    conversations: AgentMessage[];
+    /** File changes proposed by the WriterAgent */
+    fileChanges: FileChange[];
+    /** Arbitrary metadata for extensibility (key-value store) */
+    metadata: Record<string, unknown>;
+    /**
+     * Optional callback invoked when a rate-limit (429) error is detected.
+     * If provided, the agent should call this instead of auto-retrying.
+     * The orchestrator sets this to prompt the user for their preferred action.
+     */
+    onRateLimit?: OnRateLimit;
+}
+/** The result returned by an agent after execution */
+export interface AgentResult {
+    /** Whether the agent completed its task successfully */
+    success: boolean;
+    /** One-line summary of what happened */
+    summary: string;
+    /** Optional detailed output (runner stdout, file lists, etc.) */
+    details?: string;
+    /** Error message if the agent failed */
+    error?: string;
+}
+/** Configuration options for an orchestration session */
+export interface OrchestratorOptions {
+    /** Inference provider type (e.g. 'groq', 'gemini', 'local') */
+    provider?: string;
+    /** Model override */
+    model?: string;
+    /** Whether to write files to disk (false = dry-run) */
+    dryRun?: boolean;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Agent-specific model overrides */
+    agentModels?: Partial<Record<string, string>>;
+    /** Enable persistent memory (trajectory storage and retrieval) */
+    useMemory?: boolean;
+    /** Auto-create a review bundle instead of applying changes directly */
+    reviewMode?: boolean;
+    /** Auto-route each agent to its recommended model */
+    autoRouteModels?: boolean;
+    /** Pre-built task plan to use instead of calling the PlannerAgent */
+    prefillPlan?: TaskStep[];
+}
+/** The final result of an orchestration session */
+export interface OrchestrationResult {
+    /** Overall success */
+    success: boolean;
+    /** The original user goal */
+    goal: string;
+    /** Summary of what was accomplished */
+    summary: string;
+    /** Number of tasks completed vs total */
+    tasksCompleted: number;
+    tasksTotal: number;
+    /** Detailed results from each agent */
+    agentResults: Array<{
+        agent: string;
+        success: boolean;
+        summary: string;
+    }>;
+    /** File change summary */
+    fileChanges: string;
+    /** Runner output (from executed commands) */
+    runOutput?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Memory trajectory ID if stored */
+    trajectoryId?: string;
+    /** Review bundle ID if review mode was enabled */
+    reviewId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * @agent-nuvira/sdk/types — Core type definitions for building custom agents.
+ *
+ * These types mirror the types used in the Agent-Nuvira orchestration system.
+ * Agents communicate through a shared {@link AgentContext} bus managed by the
+ * {@link Orchestrator}.
+ *
+ * @module @agent-nuvira/sdk/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agent-sdk/src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/agents/agent.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Agent interfaces and abstract base class for the multi-agent orchestration system.
+ *
+ * Each agent is a specialized unit that performs a specific role in the pipeline
+ * (planning, context gathering, writing, reviewing, etc.). Agents communicate
+ * through a shared {@link AgentContext} bus managed by the Orchestrator.
+ */
+import type { InferenceOptions } from '../config/types.js';
+/** Status of a single task step within the execution plan */
+export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed';
+/** A single step in the ordered execution plan produced by the PlannerAgent */
+export interface TaskStep {
+    id: string;
+    description: string;
+    agentType: string;
+    dependsOn: string[];
+    status: TaskStatus;
+    result?: string;
+}
+/** A file artifact discovered or produced during agent execution */
+export interface Artifact {
+    path: string;
+    content: string;
+    description: string;
+}
+/** A message exchanged between agents via the context bus */
+export interface AgentMessage {
+    from: string;
+    to: string;
+    content: string;
+    timestamp: number;
+}
+/** A file change proposed or applied by an agent */
+export interface FileChange {
+    path: string;
+    originalContent?: string;
+    newContent?: string;
+    status: 'created' | 'modified' | 'deleted';
+}
+/**
+ * The shared context bus that all agents read from and write to.
+ * This is the single source of truth for inter-agent communication.
+ */
+export interface AgentContext {
+    /** The original user goal / task description */
+    goal: string;
+    /** Absolute path to the working directory (project root) */
+    workingDirectory: string;
+    /** Ordered task plan produced by PlannerAgent */
+    taskPlan: TaskStep[];
+    /** File artifacts discovered (context) or produced (output) */
+    artifacts: Artifact[];
+    /** Agent-to-agent conversation log */
+    conversations: AgentMessage[];
+    /** File changes proposed by WriterAgent */
+    fileChanges: FileChange[];
+    /** Arbitrary metadata for extensibility */
+    metadata: Record<string, unknown>;
+    /**
+     * Optional callback invoked when a rate-limit (429) error is detected.
+     * If provided, the agent will call this instead of auto-retrying.
+     * The orchestrator sets this to prompt the user for their preferred action.
+     */
+    onRateLimit?: OnRateLimit;
+}
+/** The result returned by an agent after execution */
+export interface AgentResult {
+    success: boolean;
+    summary: string;
+    details?: string;
+    error?: string;
+}
+/**
+ * Information about a rate-limit error, passed to onRateLimit callback.
+ */
+export interface RateLimitInfo {
+    retryAfterMs: number;
+    modelName?: string;
+    provider?: string;
+    agentName: string;
+    errorMessage: string;
+}
+/**
+ * Actions the orchestrator/user can take when a rate limit is hit.
+ * - 'retry': wait the suggested time and retry with the current model
+ * - 'skip': gracefully skip this step (return soft success)
+ * - 'abort': fail immediately and stop the pipeline
+ * - 'switch-model': retry with a different model (callback provides new callLLM)
+ */
+export type RateLimitAction = {
+    action: 'retry';
+} | {
+    action: 'skip';
+} | {
+    action: 'abort';
+} | {
+    action: 'switch-model';
+    callLLM: LLMCallFn;
+};
+/**
+ * Callback used by agents to ask the orchestrator/user what to do on rate limit.
+ * If not set, the agent uses its built-in retry logic (auto-wait + retry).
+ */
+export type OnRateLimit = (info: RateLimitInfo) => Promise<RateLimitAction>;
+/**
+ * Callback type that agents use to invoke the LLM.
+ * The orchestrator injects this so it can control provider/model per agent.
+ */
+export type LLMCallFn = (prompt: string, options?: InferenceOptions) => Promise<string>;
+/**
+ * Base class for all specialized agents.
+ *
+ * To create a new agent:
+ * 1. Extend this class
+ * 2. Set `name` and `description`
+ * 3. Implement `execute(context, callLLM)`
+ */
+export declare abstract class Agent {
+    /** Human-readable agent name (e.g. "Planner", "Writer") */
+    abstract readonly name: string;
+    /** Short description of what this agent does */
+    abstract readonly description: string;
+    /**
+     * Execute the agent's specialized task.
+     *
+     * @param context  Shared context bus — read inputs, write outputs
+     * @param callLLM  Function to call the LLM with a prompt
+     * @returns        Result indicating success/failure + summary
+     */
+    abstract execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult>;
+}
+//# sourceMappingURL=agent.d.ts.map

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

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

package/dist/agents/agent.js

@@ -0,0 +1,19 @@
+/**
+ * Agent interfaces and abstract base class for the multi-agent orchestration system.
+ *
+ * Each agent is a specialized unit that performs a specific role in the pipeline
+ * (planning, context gathering, writing, reviewing, etc.). Agents communicate
+ * through a shared {@link AgentContext} bus managed by the Orchestrator.
+ */
+// ─── Abstract Agent ─────────────────────────────────────────────────────────
+/**
+ * Base class for all specialized agents.
+ *
+ * To create a new agent:
+ * 1. Extend this class
+ * 2. Set `name` and `description`
+ * 3. Implement `execute(context, callLLM)`
+ */
+export class Agent {
+}
+//# sourceMappingURL=agent.js.map

package/dist/agents/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agents/agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2HH,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,OAAgB,KAAK;CAe1B"}