agent-nuvira 1.14.0

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

@@ -0,0 +1,291 @@
+/**
+ * @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
+ */
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+// ─── Agent Name Helpers ─────────────────────────────────────────────────────
+/** Convert PascalCase to kebab-case (e.g. "CodeFormatter" → "code-formatter") */
+function toKebabCase(pascal) {
+    return pascal
+        .replace(/([A-Z])/g, '-$1')
+        .toLowerCase()
+        .replace(/^-/, '');
+}
+/** Convert PascalCase to camelCase (e.g. "CodeFormatter" → "codeFormatter") */
+function toCamelCase(pascal) {
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+// ─── Templates ──────────────────────────────────────────────────────────────
+const PACKAGE_JSON_TEMPLATE = (opts) => `{
+  "name": "${toKebabCase(opts.agentName)}-agent",
+  "version": "0.1.0",
+  "description": "${opts.description}",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@agent-nuvira/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}`;
+const TS_CONFIG_TEMPLATE = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}`;
+const AGENT_SRC_TEMPLATE = (opts) => {
+    const agentType = opts.agentType || toKebabCase(opts.agentName);
+    return `/**
+ * ${opts.agentName} — ${opts.description}
+ *
+ * Generated by \`buff sdk scaffold\`
+ */
+
+import { Agent, type AgentContext, type AgentResult, type LLMCallFn } from '@agent-nuvira/sdk';
+
+export class ${opts.agentName} extends Agent {
+  readonly name = '${opts.agentName}';
+  readonly description = '${opts.description}';
+
+  async execute(context: AgentContext, callLLM: LLMCallFn): Promise<AgentResult> {
+    // ── Read inputs from context ───────────────────────────────────────
+    const goal = context.goal;
+    const files = context.artifacts;
+
+    // ── Build a prompt for the LLM ─────────────────────────────────────
+    const prompt = \`You are the ${opts.agentName} agent.
+Goal: \${goal}
+
+Files:
+\${files.map(f => \`- \${f.path}: \${f.description}\`).join('\\\\n') || '(No files provided)'}
+
+Please complete the task described in the goal.\`;
+
+    // ── Call the LLM ───────────────────────────────────────────────────
+    const response = await callLLM(prompt, {
+      temperature: 0.3,
+      maxTokens: 2048,
+    });
+
+    // ── Process and return results ─────────────────────────────────────
+    return {
+      success: true,
+      summary: \`\${this.name} completed: \${goal.slice(0, 60)}\`,
+      details: response,
+    };
+  }
+}
+
+/**
+ * Agent descriptor for registering this agent in the system.
+ * Export this to allow automatic registration.
+ */
+export const agentDescriptor = {
+  AgentClass: ${opts.agentName},
+  name: '${opts.agentName}',
+  description: '${opts.description}',
+  agentType: '${agentType}',
+  tags: 'custom',
+};
+`;
+};
+const AGENT_INDEX_TEMPLATE = (opts) => `/**
+ * ${opts.agentName} — Agent entry point.
+ * Generated by \`buff sdk scaffold\`
+ */
+
+export { ${opts.agentName}, agentDescriptor } from './${toCamelCase(opts.agentName)}.js';
+`;
+const VITEST_CONFIG_TEMPLATE = `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+  },
+});
+`;
+const AGENT_TEST_TEMPLATE = (opts) => `/**
+ * ${opts.agentName} — Unit tests.
+ * Generated by \`buff sdk scaffold\`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { ${opts.agentName} } from '../src/${toCamelCase(opts.agentName)}.js';
+import {
+  createMockContext,
+  createMockLLM,
+  createFailingMockLLM,
+  runAgentTest,
+  assertAgentSuccess,
+  assertAgentFailure,
+} from '@agent-nuvira/sdk/testing';
+
+describe('${opts.agentName}', () => {
+  const agent = new ${opts.agentName}();
+
+  it('should return success with summary', async () => {
+    const context = createMockContext({
+      goal: 'Test the agent',
+      artifacts: [
+        { path: 'src/index.ts', content: 'console.log("hello")', description: 'Source file' },
+      ],
+    });
+    const callLLM = createMockLLM('Task completed successfully');
+
+    const result = await runAgentTest(agent, context, callLLM);
+
+    assertAgentSuccess(result);
+    expect(result.summary).toBeTruthy();
+  });
+
+  it('should handle errors gracefully', async () => {
+    const context = createMockContext({ goal: 'Test error handling' });
+    const callLLM = createFailingMockLLM(new Error('API error'));
+
+    const result = await runAgentTest(agent, context, callLLM);
+
+    assertAgentFailure(result);
+    expect(result.error).toContain('API error');
+  });
+
+  it('should pass validation by default', () => {
+    const context = createMockContext();
+    const validation = agent.validate(context);
+    expect(validation).toBe(true);
+  });
+});
+`;
+const AGENT_PACK_TEMPLATE = `# Agent Packages
+
+This directory contains multiple custom agents that can be registered together.
+Use \`buff sdk register\` to register all agents in a package.
+
+## Adding an Agent
+
+1. Create a new directory with your agent name
+2. Add the agent source file extending \`Agent\`
+3. Export an \`agentDescriptor\` object
+4. Re-export from this package's \`index.ts\`
+`;
+const AGENT_PACK_INDEX_TEMPLATE = (opts) => `/**
+ * ${opts.agentName} — Agent package entry point.
+ * Generated by \`buff sdk scaffold\`
+ */
+
+// Re-export your custom agents here:
+// export { MyAgent, agentDescriptor as myAgentDescriptor } from './my-agent/index.js';
+// export { AnotherAgent, agentDescriptor as anotherAgentDescriptor } from './another-agent/index.js';
+`;
+// ─── File Writer ────────────────────────────────────────────────────────────
+function writeFile(outDir, filePath, content) {
+    const fullPath = join(outDir, filePath);
+    mkdirSync(join(outDir, dirname(filePath)), { recursive: true });
+    writeFileSync(fullPath, content, 'utf-8');
+    return fullPath;
+}
+function dirname(p) {
+    const idx = p.lastIndexOf('/');
+    return idx >= 0 ? p.slice(0, idx) : '.';
+}
+// ─── Scaffold Command ───────────────────────────────────────────────────────
+/**
+ * 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 function scaffold(options) {
+    const { outDir, agentName, description, template = 'full-agent', agentType, } = options;
+    if (!agentName || !agentName.match(/^[A-Z][a-zA-Z0-9]*$/)) {
+        throw new Error(`Invalid agent name "${agentName}". Must be in PascalCase (e.g. "CodeFormatter", "MyAgent").`);
+    }
+    if (existsSync(outDir)) {
+        throw new Error(`Output directory already exists: ${outDir}`);
+    }
+    const files = [];
+    switch (template) {
+        case 'basic-agent': {
+            files.push(writeFile(outDir, 'package.json', PACKAGE_JSON_TEMPLATE({ ...options, description })));
+            files.push(writeFile(outDir, 'tsconfig.json', TS_CONFIG_TEMPLATE));
+            files.push(writeFile(outDir, `src/${toCamelCase(agentName)}.ts`, AGENT_SRC_TEMPLATE({ ...options, description })));
+            files.push(writeFile(outDir, 'src/index.ts', AGENT_INDEX_TEMPLATE({ ...options, description })));
+            break;
+        }
+        case 'full-agent': {
+            files.push(writeFile(outDir, 'package.json', PACKAGE_JSON_TEMPLATE({ ...options, description })));
+            files.push(writeFile(outDir, 'tsconfig.json', TS_CONFIG_TEMPLATE));
+            files.push(writeFile(outDir, 'vitest.config.ts', VITEST_CONFIG_TEMPLATE));
+            files.push(writeFile(outDir, `src/${toCamelCase(agentName)}.ts`, AGENT_SRC_TEMPLATE({ ...options, description })));
+            files.push(writeFile(outDir, 'src/index.ts', AGENT_INDEX_TEMPLATE({ ...options, description })));
+            files.push(writeFile(outDir, `tests/${toCamelCase(agentName)}.test.ts`, AGENT_TEST_TEMPLATE({ ...options, description })));
+            break;
+        }
+        case 'agent-pack': {
+            files.push(writeFile(outDir, 'README.md', AGENT_PACK_TEMPLATE));
+            files.push(writeFile(outDir, 'src/index.ts', AGENT_PACK_INDEX_TEMPLATE({ ...options, description })));
+            break;
+        }
+        default: {
+            throw new Error(`Unknown template type: ${template}`);
+        }
+    }
+    return files;
+}
+/**
+ * List available scaffold templates with descriptions.
+ */
+export function listTemplates() {
+    return [
+        {
+            name: 'basic-agent',
+            description: 'Minimal agent with package.json, tsconfig, and source file',
+        },
+        {
+            name: 'full-agent',
+            description: 'Complete agent with package.json, tsconfig, vitest, source, and unit tests',
+        },
+        {
+            name: 'agent-pack',
+            description: 'Multi-agent package structure for distributing multiple agents together',
+        },
+    ];
+}
+//# sourceMappingURL=scaffold.js.map

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

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

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

@@ -0,0 +1,187 @@
+/**
+ * @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
+ */
+import type { AgentContext, AgentResult, Artifact, FileChange, InferenceOptions, LLMCallFn, TaskStep, TaskStatus, AgentMessage } from './types.js';
+import type { Agent } from './agent.js';
+/** Options for building a mock context via {@link createMockContext} */
+export interface MockContextOptions {
+    /** The user goal / task description (default: "Test goal") */
+    goal?: string;
+    /** Working directory (default: process.cwd()) */
+    workingDirectory?: string;
+    /** Pre-populated task plan (default: empty) */
+    taskPlan?: TaskStep[];
+    /** Pre-populated file artifacts (default: empty) */
+    artifacts?: Artifact[];
+    /** Pre-populated file changes (default: empty) */
+    fileChanges?: FileChange[];
+    /** Pre-populated agent messages (default: empty) */
+    conversations?: AgentMessage[];
+    /** Additional metadata key-value pairs (default: {}) */
+    metadata?: Record<string, unknown>;
+    /** Whether to set up an onRateLimit callback (default: undefined — not set) */
+    onRateLimit?: boolean;
+}
+/**
+ * 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 declare function createMockContext(options?: MockContextOptions): AgentContext;
+/** Options for {@link createMockLLM} */
+export interface MockLLMOptions {
+    /**
+     * If true, the mock will track all prompts received.
+     * Access them via the returned array's `.prompts` property.
+     * @default true
+     */
+    trackPrompts?: boolean;
+}
+/**
+ * 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 declare function createMockLLM(response?: string, options?: MockLLMOptions): LLMCallFn & {
+    prompts: Array<{
+        prompt: string;
+        options?: InferenceOptions;
+    }>;
+};
+/**
+ * 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 declare function createFailingMockLLM(error?: Error): LLMCallFn;
+/**
+ * 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 declare function createSequentialMockLLM(responses: string[]): LLMCallFn;
+/**
+ * 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 declare function runAgentTest(agent: Agent, context: AgentContext, callLLM?: LLMCallFn): Promise<AgentResult>;
+/**
+ * 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 declare function assertAgentSuccess(result: AgentResult): asserts result is AgentResult & {
+    success: true;
+};
+/**
+ * Assert that an agent result indicates failure with an optional error match.
+ *
+ * @example
+ * ```ts
+ * assertAgentFailure(result, 'rate limit');
+ * ```
+ */
+export declare function assertAgentFailure(result: AgentResult, expectedErrorSubstring?: string): asserts result is AgentResult & {
+    success: false;
+};
+/**
+ * Add a file artifact to a context for testing.
+ *
+ * @example
+ * ```ts
+ * addArtifact(ctx, 'src/index.ts', 'console.log("hello")', 'Entry point');
+ * ```
+ */
+export declare function addArtifact(context: AgentContext, path: string, content: string, description: string): void;
+/**
+ * Add a task step to a context's task plan.
+ *
+ * @example
+ * ```ts
+ * addTaskStep(ctx, 'step-1', 'writer', 'Write the main file', []);
+ * ```
+ */
+export declare function addTaskStep(context: AgentContext, id: string, agentType: string, description: string, dependsOn?: string[], status?: TaskStatus): void;
+/**
+ * Add a file change to a context.
+ *
+ * @example
+ * ```ts
+ * addFileChange(ctx, 'src/index.ts', 'console.log("hello")', undefined, 'created');
+ * ```
+ */
+export declare function addFileChange(context: AgentContext, path: string, newContent: string, originalContent?: string, status?: FileChange['status']): void;
+//# sourceMappingURL=testing.d.ts.map

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

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