confused-ai-core 0.1.0

package/src/dx/agent.ts

@@ -0,0 +1,88 @@
+/**
+ * Minimal agent() — best DX: one import, one call.
+ *
+ * agent('You are helpful.')
+ * agent({ instructions: '...', model: 'openai:gpt-4o' })
+ */
+
+import type { CreateAgentResult } from '../create-agent.js';
+import type { CreateAgentOptions } from '../create-agent.js';
+import { createAgent } from '../create-agent.js';
+import { HttpClientTool } from '../tools/http-tool.js';
+import { BrowserTool } from '../tools/browser-tool.js';
+import { createDevLogger } from './dev-logger.js';
+import { createDevToolMiddleware } from './dev-logger.js';
+
+/** Minimal options when using agent({ ... }) */
+export type AgentMinimalOptions = Partial<
+    Omit<CreateAgentOptions, 'name' | 'instructions'> & {
+        /** System instructions (required unless using agent(instructions) form) */
+        instructions: string;
+        /** Agent name (default: 'Agent') */
+        name?: string;
+        /** Enable dev mode: console + tool logging */
+        dev?: boolean;
+    }
+>;
+
+/**
+ * Create an agent with the best DX: minimal surface, smart defaults.
+ *
+ * One-argument form (instructions only):
+ *   const runnable = agent('You are a helpful assistant.');
+ *
+ * Options form:
+ *   const runnable = agent({
+ *     instructions: 'You are helpful.',
+ *     model: 'openai:gpt-4o',
+ *     dev: true,
+ *   });
+ *
+ * Returns the same runnable as createAgent() (run, createSession, getSessionMessages).
+ */
+export function agent(instructionsOrOptions: string | AgentMinimalOptions): CreateAgentResult {
+    const isString = typeof instructionsOrOptions === 'string';
+    const options: CreateAgentOptions = isString
+        ? {
+              name: 'Agent',
+              instructions: instructionsOrOptions,
+              tools: [new HttpClientTool(), new BrowserTool()],
+          }
+        : {
+              name: instructionsOrOptions.name ?? 'Agent',
+              instructions: instructionsOrOptions.instructions ?? '',
+              model: instructionsOrOptions.model,
+              apiKey: instructionsOrOptions.apiKey,
+              baseURL: instructionsOrOptions.baseURL,
+              openRouter: instructionsOrOptions.openRouter,
+              llm: instructionsOrOptions.llm,
+              tools: instructionsOrOptions.tools ?? [new HttpClientTool(), new BrowserTool()],
+              toolMiddleware: instructionsOrOptions.toolMiddleware,
+              sessionStore: instructionsOrOptions.sessionStore,
+              guardrails: instructionsOrOptions.guardrails,
+              maxSteps: instructionsOrOptions.maxSteps,
+              timeoutMs: instructionsOrOptions.timeoutMs,
+              retry: instructionsOrOptions.retry,
+              logger: instructionsOrOptions.logger,
+              learningMode: instructionsOrOptions.learningMode,
+              userProfileStore: instructionsOrOptions.userProfileStore,
+              memoryStore: instructionsOrOptions.memoryStore,
+              ragEngine: instructionsOrOptions.ragEngine,
+              inputSchema: instructionsOrOptions.inputSchema,
+              outputSchema: instructionsOrOptions.outputSchema,
+          };
+
+    if (!options.instructions?.trim()) {
+        throw new Error('agent() requires instructions. Use agent("...") or agent({ instructions: "..." }).');
+    }
+
+    if (!isString && (instructionsOrOptions as AgentMinimalOptions).dev) {
+        options.logger = options.logger ?? createDevLogger();
+        options.toolMiddleware = [
+            ...(options.toolMiddleware ?? []),
+            createDevToolMiddleware(),
+        ];
+    }
+
+    return createAgent(options);
+}

package/src/dx/define-agent.ts

@@ -0,0 +1,183 @@
+/**
+ * Fluent agent builder — best DX: discoverable, chainable, typed.
+ *
+ * defineAgent()
+ *   .name('Assistant')
+ *   .instructions('You are helpful.')
+ *   .model('openai:gpt-4o')
+ *   .tools([new HttpClientTool()])
+ *   .withSession()
+ *   .dev()
+ *   .build()
+ */
+
+import type { CreateAgentOptions, CreateAgentResult } from '../create-agent.js';
+import type { SessionStore } from '../session/types.js';
+import type { GuardrailEngine } from '../guardrails/types.js';
+import type { z } from 'zod';
+import { createAgent } from '../create-agent.js';
+import { InMemorySessionStore } from '../session/index.js';
+import { HttpClientTool } from '../tools/http-tool.js';
+import { BrowserTool } from '../tools/browser-tool.js';
+import { createDevLogger } from './dev-logger.js';
+import { createDevToolMiddleware } from './dev-logger.js';
+
+export interface DefineAgentOptions
+    extends Pick<
+        CreateAgentOptions,
+        | 'name'
+        | 'instructions'
+        | 'model'
+        | 'apiKey'
+        | 'baseURL'
+        | 'openRouter'
+        | 'tools'
+        | 'toolMiddleware'
+        | 'sessionStore'
+        | 'guardrails'
+        | 'maxSteps'
+        | 'timeoutMs'
+        | 'retry'
+        | 'logger'
+        | 'learningMode'
+        | 'userProfileStore'
+        | 'memoryStore'
+        | 'ragEngine'
+        | 'inputSchema'
+        | 'outputSchema'
+    > {
+    /** Enable dev mode: console logger + tool call logging */
+    dev?: boolean;
+}
+
+/**
+ * Fluent builder for creating agents with best DX.
+ * Chain methods and call .build() to get a runnable agent.
+ */
+export function defineAgent(): AgentBuilder {
+    return new AgentBuilder({});
+}
+
+class AgentBuilder {
+    private options: Partial<DefineAgentOptions> = {};
+
+    constructor(options: Partial<DefineAgentOptions>) {
+        this.options = { ...options };
+    }
+
+    /** Set agent name */
+    name(name: string): AgentBuilder {
+        return new AgentBuilder({ ...this.options, name });
+    }
+
+    /** Set system instructions (required before build) */
+    instructions(instructions: string): AgentBuilder {
+        return new AgentBuilder({ ...this.options, instructions });
+    }
+
+    /** Set model: id or "provider:model_id" (e.g. openai:gpt-4o, ollama:llama3.2) */
+    model(model: string): AgentBuilder {
+        return new AgentBuilder({ ...this.options, model });
+    }
+
+    /** Set API key (overrides env) */
+    apiKey(apiKey: string): AgentBuilder {
+        return new AgentBuilder({ ...this.options, apiKey });
+    }
+
+    /** Set base URL (e.g. Ollama) */
+    baseURL(baseURL: string): AgentBuilder {
+        return new AgentBuilder({ ...this.options, baseURL });
+    }
+
+    /** Set OpenRouter config */
+    openRouter(config: { apiKey?: string; model?: string }): AgentBuilder {
+        return new AgentBuilder({ ...this.options, openRouter: config });
+    }
+
+    /** Set tools (array or registry). Omit for default HTTP + browser tools. */
+    tools(tools: CreateAgentOptions['tools']): AgentBuilder {
+        return new AgentBuilder({ ...this.options, tools });
+    }
+
+    /** Set session store. Call with no args for in-memory; pass store for DB. */
+    withSession(store?: SessionStore): AgentBuilder {
+        return new AgentBuilder({ ...this.options, sessionStore: store ?? new InMemorySessionStore() });
+    }
+
+    /** Set guardrails. Pass false to disable. */
+    withGuardrails(guardrails: GuardrailEngine | false): AgentBuilder {
+        return new AgentBuilder({ ...this.options, guardrails });
+    }
+
+    /** Max agentic steps */
+    maxSteps(n: number): AgentBuilder {
+        return new AgentBuilder({ ...this.options, maxSteps: n });
+    }
+
+    /** Run timeout in ms */
+    timeoutMs(ms: number): AgentBuilder {
+        return new AgentBuilder({ ...this.options, timeoutMs: ms });
+    }
+
+    /** Retry policy */
+    retry(policy: CreateAgentOptions['retry']): AgentBuilder {
+        return new AgentBuilder({ ...this.options, retry: policy });
+    }
+
+    /** Type-safe input schema (Zod) */
+    inputSchema<T>(schema: z.ZodType<T>): AgentBuilder {
+        return new AgentBuilder({ ...this.options, inputSchema: schema });
+    }
+
+    /** Type-safe output schema (Zod) */
+    outputSchema<T>(schema: z.ZodType<T>): AgentBuilder {
+        return new AgentBuilder({ ...this.options, outputSchema: schema });
+    }
+
+    /** Enable dev mode: console logger + tool call logging */
+    dev(): AgentBuilder {
+        return new AgentBuilder({ ...this.options, dev: true });
+    }
+
+    /** Build and return a runnable agent */
+    build(): CreateAgentResult {
+        const opts = this.options;
+        if (!opts.instructions?.trim()) {
+            throw new Error('defineAgent().build() requires instructions. Call .instructions("...") first.');
+        }
+
+        const createOpts: CreateAgentOptions = {
+            name: opts.name ?? 'Agent',
+            instructions: opts.instructions,
+            model: opts.model,
+            apiKey: opts.apiKey,
+            baseURL: opts.baseURL,
+            openRouter: opts.openRouter,
+            tools: opts.tools ?? [new HttpClientTool(), new BrowserTool()],
+            toolMiddleware: opts.toolMiddleware,
+            sessionStore: opts.sessionStore ?? new InMemorySessionStore(),
+            guardrails: opts.guardrails,
+            maxSteps: opts.maxSteps,
+            timeoutMs: opts.timeoutMs,
+            retry: opts.retry,
+            logger: opts.logger,
+            learningMode: opts.learningMode,
+            userProfileStore: opts.userProfileStore,
+            memoryStore: opts.memoryStore,
+            ragEngine: opts.ragEngine,
+            inputSchema: opts.inputSchema,
+            outputSchema: opts.outputSchema,
+        };
+
+        if (opts.dev) {
+            createOpts.logger = createOpts.logger ?? createDevLogger();
+            createOpts.toolMiddleware = [
+                ...(createOpts.toolMiddleware ?? []),
+                createDevToolMiddleware(),
+            ];
+        }
+
+        return createAgent(createOpts);
+    }
+}

package/src/dx/dev-logger.ts

@@ -0,0 +1,57 @@
+/**
+ * Dev-mode logger: tool calls, steps, and agent lifecycle for best DX.
+ */
+
+import type { Logger } from '../observability/types.js';
+
+const P = '[ConfusedAI]';
+
+function formatMeta(meta?: Record<string, unknown>): string {
+    if (!meta || Object.keys(meta).length === 0) return '';
+    return ' ' + JSON.stringify(meta);
+}
+
+/**
+ * Logger that prints tool calls, steps, and debug info in development.
+ * Use with createAgent({ dev: true }) or defineAgent().dev().build().
+ */
+export function createDevLogger(): Logger {
+    return {
+        debug(message: string, _context?: Partial<Record<string, unknown>>, metadata?: Record<string, unknown>) {
+            console.debug(`${P} ${message}${formatMeta(metadata)}`);
+        },
+        info(message: string, _context?: Partial<Record<string, unknown>>, metadata?: Record<string, unknown>) {
+            console.info(`${P} ${message}${formatMeta(metadata)}`);
+        },
+        warn(message: string, _context?: Partial<Record<string, unknown>>, metadata?: Record<string, unknown>) {
+            console.warn(`${P} ${message}${formatMeta(metadata)}`);
+        },
+        error(message: string, _context?: Partial<Record<string, unknown>>, metadata?: Record<string, unknown>) {
+            console.error(`${P} ${message}${formatMeta(metadata)}`);
+        },
+        fatal(message: string, _context?: Partial<Record<string, unknown>>, metadata?: Record<string, unknown>) {
+            console.error(`${P} [FATAL] ${message}${formatMeta(metadata)}`);
+        },
+        child(_additionalContext: Partial<Record<string, unknown>>) {
+            return createDevLogger();
+        },
+    };
+}
+
+/**
+ * Create tool middleware that logs every tool call/result in dev (best DX).
+ */
+export function createDevToolMiddleware(): import('../tools/types.js').ToolMiddleware {
+    return {
+        beforeExecute(tool, params) {
+            console.debug(`${P} 🔧 tool.call ${tool.name}`, params);
+        },
+        afterExecute(tool, result, _ctx) {
+            const preview = result.success ? JSON.stringify(result.data).slice(0, 80) : result.error?.message ?? 'error';
+            console.debug(`${P} 🔧 tool.done ${tool.name} (${result.executionTimeMs}ms)`, preview);
+        },
+        onError(tool, err, _ctx) {
+            console.debug(`${P} 🔧 tool.error ${tool.name}`, err.message);
+        },
+    };
+}

package/src/dx/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Best DX for creating agents in TypeScript.
+ *
+ * - agent(instructions) or agent({ instructions, model, dev }) — minimal, one call
+ * - defineAgent().instructions('...').model('...').dev().build() — fluent, discoverable
+ * - createDevLogger() / createDevToolMiddleware() — dev-mode visibility
+ */
+
+export { agent, type AgentMinimalOptions } from './agent.js';
+export { defineAgent, type DefineAgentOptions } from './define-agent.js';
+export { createDevLogger, createDevToolMiddleware } from './dev-logger.js';

package/src/errors.ts

@@ -0,0 +1,175 @@
+/**
+ * Production-grade structured errors for the agent framework.
+ * Industry-standard error codes and context for observability and handling.
+ */
+
+/** Error codes for programmatic handling and metrics */
+export const ErrorCode = {
+    /** Agent run failed (generic) */
+    AGENT_ERROR: 'AGENT_ERROR',
+    /** LLM provider call failed */
+    LLM_ERROR: 'LLM_ERROR',
+    /** Tool execution failed */
+    TOOL_ERROR: 'TOOL_ERROR',
+    /** Tool validation (parameters) failed */
+    TOOL_VALIDATION_ERROR: 'TOOL_VALIDATION_ERROR',
+    /** Guardrail check failed */
+    GUARDRAIL_VIOLATION: 'GUARDRAIL_VIOLATION',
+    /** Run or step timed out */
+    TIMEOUT: 'TIMEOUT',
+    /** Run was cancelled (e.g. AbortSignal) */
+    CANCELLED: 'CANCELLED',
+    /** Invalid configuration or parameters */
+    CONFIG_ERROR: 'CONFIG_ERROR',
+    /** Session or persistence error */
+    SESSION_ERROR: 'SESSION_ERROR',
+    /** Permission denied for tool or resource */
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    /** Max steps reached without final answer */
+    MAX_STEPS: 'MAX_STEPS',
+} as const;
+
+export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+/** Base agent error with code and context */
+export class AgentError extends Error {
+    readonly code: ErrorCodeType;
+    readonly cause?: Error;
+    readonly context?: Record<string, unknown>;
+
+    constructor(
+        message: string,
+        options: {
+            code?: ErrorCodeType;
+            cause?: Error;
+            context?: Record<string, unknown>;
+        } = {}
+    ) {
+        super(message);
+        this.name = 'AgentError';
+        this.code = options.code ?? ErrorCode.AGENT_ERROR;
+        this.cause = options.cause;
+        this.context = options.context;
+        Object.setPrototypeOf(this, AgentError.prototype);
+    }
+
+    toJSON(): Record<string, unknown> {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            cause: this.cause?.message,
+        };
+    }
+}
+
+/** LLM provider or API failure */
+export class LLMError extends AgentError {
+    constructor(
+        message: string,
+        options: { cause?: Error; context?: Record<string, unknown> } = {}
+    ) {
+        super(message, { ...options, code: ErrorCode.LLM_ERROR });
+        this.name = 'LLMError';
+        Object.setPrototypeOf(this, LLMError.prototype);
+    }
+}
+
+/** Tool execution or validation failure (exception; for result errors see tools/types ToolError) */
+export class ToolExecutionError extends AgentError {
+    readonly toolName?: string;
+
+    constructor(
+        message: string,
+        options: {
+            cause?: Error;
+            toolName?: string;
+            context?: Record<string, unknown>;
+            code?: ErrorCodeType;
+        } = {}
+    ) {
+        super(message, {
+            ...options,
+            code: options.code ?? ErrorCode.TOOL_ERROR,
+        });
+        this.name = 'ToolExecutionError';
+        this.toolName = options.toolName;
+        Object.setPrototypeOf(this, ToolExecutionError.prototype);
+    }
+}
+
+/** Guardrail check failed */
+export class GuardrailError extends AgentError {
+    readonly rule?: string;
+
+    constructor(
+        message: string,
+        options: { rule?: string; context?: Record<string, unknown> } = {}
+    ) {
+        super(message, { ...options, code: ErrorCode.GUARDRAIL_VIOLATION });
+        this.name = 'GuardrailError';
+        this.rule = options.rule;
+        Object.setPrototypeOf(this, GuardrailError.prototype);
+    }
+}
+
+/** Run or step timeout */
+export class TimeoutError extends AgentError {
+    readonly timeoutMs?: number;
+
+    constructor(
+        message: string,
+        options: { timeoutMs?: number; context?: Record<string, unknown> } = {}
+    ) {
+        super(message, { ...options, code: ErrorCode.TIMEOUT });
+        this.name = 'TimeoutError';
+        this.timeoutMs = options.timeoutMs;
+        Object.setPrototypeOf(this, TimeoutError.prototype);
+    }
+}
+
+/** Run cancelled (e.g. AbortController) */
+export class CancellationError extends AgentError {
+    constructor(message = 'Run was cancelled', options: { context?: Record<string, unknown> } = {}) {
+        super(message, { ...options, code: ErrorCode.CANCELLED });
+        this.name = 'CancellationError';
+        Object.setPrototypeOf(this, CancellationError.prototype);
+    }
+}
+
+/** Configuration or setup error */
+export class ConfigError extends AgentError {
+    constructor(
+        message: string,
+        options: { cause?: Error; context?: Record<string, unknown> } = {}
+    ) {
+        super(message, { ...options, code: ErrorCode.CONFIG_ERROR });
+        this.name = 'ConfigError';
+        Object.setPrototypeOf(this, ConfigError.prototype);
+    }
+}
+
+/** Session store or persistence error */
+export class SessionError extends AgentError {
+    constructor(
+        message: string,
+        options: { cause?: Error; context?: Record<string, unknown> } = {}
+    ) {
+        super(message, { ...options, code: ErrorCode.SESSION_ERROR });
+        this.name = 'SessionError';
+        Object.setPrototypeOf(this, SessionError.prototype);
+    }
+}
+
+/** Permission denied for tool or resource */
+export class PermissionError extends AgentError {
+    constructor(
+        message: string,
+        options: { context?: Record<string, unknown> } = {}
+    ) {
+        super(message, { ...options, code: ErrorCode.PERMISSION_DENIED });
+        this.name = 'PermissionError';
+        Object.setPrototypeOf(this, PermissionError.prototype);
+    }
+}