@providerprotocol/agents 0.0.1 → 0.0.3

package/src/agent/index.ts

@@ -1,384 +0,0 @@
-import {
-  llm,
-  UserMessage,
-} from '@providerprotocol/ai';
-import type {
-  LLMInstance,
-  Message,
-  Turn,
-} from '@providerprotocol/ai';
-import { generateUUID } from '../utils/uuid.ts';
-import { AgentState } from '../state/index.ts';
-import { loop } from '../execution/loop.ts';
-import type {
-  ExecutionContext,
-  GenerateResult,
-  AgentStreamResult,
-  AgentStrategy,
-} from '../execution/types.ts';
-import type { Middleware, MiddlewareContext } from '../middleware/types.ts';
-import type { Agent, AgentOptions } from './types.ts';
-
-/**
- * Create an agent instance.
- *
- * @param options - Agent configuration
- * @returns Agent instance
- *
- * @example
- * ```typescript
- * import { agent, AgentState } from '@providerprotocol/agents';
- * import { anthropic } from '@providerprotocol/ai/anthropic';
- *
- * const coder = agent({
- *   model: anthropic('claude-sonnet-4-20250514'),
- *   tools: [Bash, Read, Write],
- *   system: 'You are a coding assistant.',
- * });
- *
- * const state = AgentState.initial();
- * const { turn, state: newState } = await coder.generate('Hello', state);
- * ```
- */
-export function agent(options: AgentOptions): Agent {
-  const {
-    // UAP-specific options
-    execution = loop(),
-    middleware = [],
-    strategy = {},
-    checkpoints,
-    sessionId: providedSessionId,
-    _llmInstance,
-    // LLM options (passthrough to UPP)
-    model,
-    params = {},
-    config,
-    tools = [],
-    system,
-    structure,
-    toolStrategy,
-  } = options;
-
-  const agentId = generateUUID();
-  // Generate sessionId (UUIDv4) if checkpoints provided but no sessionId
-  // Per UAP spec Section 3.4: Session IDs MUST be UUIDv4
-  const sessionId = checkpoints ? (providedSessionId ?? generateUUID()) : providedSessionId;
-
-  // Create the LLM instance with full UPP passthrough (or use injected instance for testing)
-  const llmInstance: LLMInstance = _llmInstance ?? llm({
-    model,
-    params,
-    config,
-    system,
-    structure,
-    tools,
-    toolStrategy,
-  });
-
-  /**
-   * Normalize input to a Message.
-   */
-  function normalizeInput(input: string | Message): Message {
-    if (typeof input === 'string') {
-      return new UserMessage(input);
-    }
-    return input;
-  }
-
-  /**
-   * Run middleware before hooks.
-   */
-  async function runBeforeMiddleware(
-    middlewares: Middleware[],
-    context: MiddlewareContext,
-  ): Promise<MiddlewareContext> {
-    let currentContext = context;
-
-    for (const mw of middlewares) {
-      if (mw.before) {
-        const result = await mw.before(currentContext);
-        if (result) {
-          currentContext = result;
-        }
-      }
-    }
-
-    return currentContext;
-  }
-
-  /**
-   * Run middleware after hooks (in reverse order).
-   */
-  async function runAfterMiddleware(
-    middlewares: Middleware[],
-    context: MiddlewareContext,
-    result: GenerateResult,
-  ): Promise<GenerateResult> {
-    let currentResult = result;
-
-    // Run in reverse order
-    for (let i = middlewares.length - 1; i >= 0; i--) {
-      const mw = middlewares[i];
-      if (mw?.after) {
-        currentResult = await mw.after(context, currentResult);
-      }
-    }
-
-    return currentResult;
-  }
-
-  /**
-   * Run middleware error hooks (in reverse order).
-   */
-  async function runErrorMiddleware(
-    middlewares: Middleware[],
-    context: MiddlewareContext,
-    error: Error,
-  ): Promise<GenerateResult | undefined> {
-    // Run in reverse order
-    for (let i = middlewares.length - 1; i >= 0; i--) {
-      const mw = middlewares[i];
-      if (mw?.onError) {
-        const result = await mw.onError(context, error);
-        if (result) {
-          return result;
-        }
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Build execution context.
-   */
-  function buildExecutionContext(
-    input: Message,
-    state: AgentState,
-    resolvedStrategy: AgentStrategy,
-    signal?: AbortSignal,
-  ): ExecutionContext {
-    return {
-      agent: { id: agentId, system },
-      llm: llmInstance,
-      input,
-      state,
-      tools,
-      strategy: resolvedStrategy,
-      signal,
-      checkpoints,
-      sessionId,
-    };
-  }
-
-  const agentInstance: Agent = {
-    id: agentId,
-    model,
-    tools,
-    system,
-
-    async generate(
-      input: string | Message,
-      state: AgentState,
-    ): Promise<GenerateResult> {
-      const normalizedInput = normalizeInput(input);
-
-      // Create middleware context
-      const middlewareContext: MiddlewareContext = {
-        agent: { id: agentId, system },
-        input: normalizedInput,
-        state,
-        metadata: new Map(),
-      };
-
-      try {
-        // Run before middleware
-        const processedContext = await runBeforeMiddleware(middleware, middlewareContext);
-
-        // Build execution context
-        const executionContext = buildExecutionContext(
-          processedContext.input,
-          processedContext.state,
-          strategy,
-        );
-
-        // Execute strategy
-        const result = await execution.execute(executionContext);
-
-        // Run after middleware
-        const finalResult = await runAfterMiddleware(
-          middleware,
-          processedContext,
-          result,
-        );
-
-        return finalResult;
-      } catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
-
-        // Try to recover with error middleware
-        const recovered = await runErrorMiddleware(middleware, middlewareContext, err);
-        if (recovered) {
-          return recovered;
-        }
-
-        throw err;
-      }
-    },
-
-    stream(
-      input: string | Message,
-      state: AgentState,
-    ): AgentStreamResult {
-      const normalizedInput = normalizeInput(input);
-
-      // Create middleware context
-      const middlewareContext: MiddlewareContext = {
-        agent: { id: agentId, system },
-        input: normalizedInput,
-        state,
-        metadata: new Map(),
-      };
-
-      // We need to run before middleware synchronously enough to get the context
-      // but streaming is inherently async. We'll handle this by wrapping the stream.
-      let aborted = false;
-      const abortController = new AbortController();
-
-      let resolveResult: (result: GenerateResult) => void;
-      let rejectResult: (error: Error) => void;
-
-      const resultPromise = new Promise<GenerateResult>((resolve, reject) => {
-        resolveResult = resolve;
-        rejectResult = reject;
-      });
-
-      const createStream = async function* () {
-        try {
-          // Run before middleware
-          const processedContext = await runBeforeMiddleware(middleware, middlewareContext);
-
-          // Build execution context
-          const executionContext = buildExecutionContext(
-            processedContext.input,
-            processedContext.state,
-            strategy,
-            abortController.signal,
-          );
-
-          // Get the stream from the execution strategy
-          const streamResult = execution.stream(executionContext);
-
-          // Yield events from the stream
-          for await (const event of streamResult) {
-            if (aborted) {
-              break;
-            }
-            yield event;
-          }
-
-          // Get the final result
-          const result = await streamResult.result;
-
-          // Run after middleware
-          const finalResult = await runAfterMiddleware(
-            middleware,
-            processedContext,
-            result,
-          );
-
-          resolveResult(finalResult);
-        } catch (error) {
-          const err = error instanceof Error ? error : new Error(String(error));
-
-          // Try to recover with error middleware
-          const recovered = await runErrorMiddleware(middleware, middlewareContext, err);
-          if (recovered) {
-            resolveResult(recovered);
-            return;
-          }
-
-          rejectResult(err);
-          throw err;
-        }
-      };
-
-      const iterator = createStream();
-
-      return {
-        [Symbol.asyncIterator]() {
-          return iterator;
-        },
-        result: resultPromise,
-        abort() {
-          aborted = true;
-          abortController.abort();
-        },
-      };
-    },
-
-    async ask(
-      input: string | Message,
-      state: AgentState,
-    ): Promise<GenerateResult> {
-      const normalizedInput = normalizeInput(input);
-
-      // Generate with original state - execution strategy adds input to LLM call
-      const result = await agentInstance.generate(normalizedInput, state);
-
-      // Build final state with correct message order:
-      // original messages + input + response messages from this turn
-      const responseMessages = result.state.messages.slice(state.messages.length);
-      const finalState = state
-        .withMessage(normalizedInput)
-        .withMessages(responseMessages)
-        .withStep(result.state.step);
-
-      // Preserve metadata from execution
-      let stateWithMetadata = finalState;
-      for (const [key, value] of Object.entries(result.state.metadata)) {
-        stateWithMetadata = stateWithMetadata.withMetadata(key, value);
-      }
-
-      // Preserve reasoning traces
-      for (const reasoning of result.state.reasoning) {
-        stateWithMetadata = stateWithMetadata.withReasoning(reasoning);
-      }
-
-      // Preserve plan if present
-      if (result.state.plan) {
-        stateWithMetadata = stateWithMetadata.withPlan([...result.state.plan]);
-      }
-
-      return {
-        turn: result.turn,
-        state: stateWithMetadata,
-      };
-    },
-
-    async query(input: string | Message): Promise<Turn> {
-      const initialState = AgentState.initial();
-      const result = await agentInstance.generate(input, initialState);
-      return result.turn;
-    },
-  };
-
-  return agentInstance;
-}
-
-export type { Agent, AgentOptions } from './types.ts';
-export type {
-  GenerateResult,
-  AgentStreamResult,
-  AgentStreamEvent,
-  UAPEventType,
-  AgentStrategy,
-  // Sub-agent event types (Section 8.7)
-  SubagentEventType,
-  SubagentEventBase,
-  SubagentStartEvent,
-  SubagentInnerEvent,
-  SubagentEndEvent,
-  SubagentEvent,
-  OnSubagentEvent,
-} from '../execution/types.ts';

package/src/agent/types.ts

@@ -1,91 +0,0 @@
-import type {
-  ModelReference,
-  Tool,
-  Turn,
-  Message,
-  LLMInstance,
-  LLMOptions,
-} from '@providerprotocol/ai';
-import type { AgentState } from '../state/index.ts';
-import type {
-  ExecutionStrategy,
-  AgentStrategy,
-  GenerateResult,
-  AgentStreamResult,
-} from '../execution/types.ts';
-import type { Middleware } from '../middleware/types.ts';
-import type { CheckpointStore } from '../checkpoint/types.ts';
-
-/**
- * Options for creating an agent.
- * Extends LLMOptions for full UPP passthrough.
- */
-export interface AgentOptions extends Partial<Omit<LLMOptions, 'model'>> {
-  /** Model reference from a UPP provider factory */
-  model: ModelReference;
-  /** Execution strategy. Default: loop() */
-  execution?: ExecutionStrategy;
-  /** Ordered middleware pipeline */
-  middleware?: Middleware[];
-  /** Agent lifecycle hooks */
-  strategy?: AgentStrategy;
-  /** Checkpoint store for step-level persistence */
-  checkpoints?: CheckpointStore;
-  /** Session identifier for checkpointing (auto-generated if not provided) */
-  sessionId?: string;
-  /** @internal Pre-created LLM instance for testing */
-  _llmInstance?: LLMInstance;
-}
-
-/**
- * Agent interface.
- */
-export interface Agent {
-  /** Unique agent identifier (UUIDv4) */
-  readonly id: string;
-  /** The bound model */
-  readonly model: ModelReference;
-  /** Available tools */
-  readonly tools: Tool[];
-  /** System prompt */
-  readonly system?: string;
-
-  /**
-   * Execute agent and return Turn with new state.
-   *
-   * @param input - User input (string or Message)
-   * @param state - Current immutable state
-   * @returns Promise resolving to { turn, state }
-   */
-  generate(input: string | Message, state: AgentState): Promise<GenerateResult>;
-
-  /**
-   * Execute agent with streaming.
-   *
-   * @param input - User input (string or Message)
-   * @param state - Current immutable state
-   * @returns AgentStreamResult with async iterator and result promise
-   */
-  stream(input: string | Message, state: AgentState): AgentStreamResult;
-
-  /**
-   * Multi-turn execution with automatic history management.
-   * Appends input to state, calls generate(), appends response to returned state.
-   *
-   * @param input - User input (string or Message)
-   * @param state - Current immutable state
-   * @returns Promise resolving to { turn, state }
-   */
-  ask(input: string | Message, state: AgentState): Promise<GenerateResult>;
-
-  /**
-   * Stateless single-turn execution.
-   * Creates ephemeral state, executes, and discards state.
-   *
-   * @param input - User input (string or Message)
-   * @returns Promise resolving to Turn
-   */
-  query(input: string | Message): Promise<Turn>;
-}
-
-export type { GenerateResult, AgentStreamResult, AgentStrategy } from '../execution/types.ts';

package/src/checkpoint/file.ts

@@ -1,126 +0,0 @@
-/**
- * File-based Checkpoint Store
- *
- * Reference implementation of CheckpointStore using the filesystem.
- *
- * @see UAP-1.0 Spec Section 12.4.3
- */
-
-import { mkdir, readdir, rm } from 'node:fs/promises';
-import { join } from 'node:path';
-import type { AgentStateJSON } from '../state/types.ts';
-import type { CheckpointStore, FileCheckpointOptions, CheckpointMetadata } from './types.ts';
-import { generateUUID } from '../utils/uuid.ts';
-
-const DEFAULT_DIR = '.checkpoints';
-
-/**
- * Create a file-based checkpoint store.
- *
- * Stores checkpoints as JSON files in a directory structure:
- * ```
- * {dir}/
- *   {sessionId}/
- *     checkpoint.json   # Latest state
- *     metadata.json     # Session metadata
- * ```
- *
- * @param options - Configuration options
- * @returns CheckpointStore implementation
- *
- * @example
- * ```typescript
- * import { fileCheckpoints } from '@providerprotocol/agents/checkpoint';
- *
- * const store = fileCheckpoints({ dir: './my-checkpoints' });
- *
- * // Save a checkpoint
- * await store.save('session-123', state.toJSON());
- *
- * // Load a checkpoint
- * const saved = await store.load('session-123');
- * ```
- */
-export function fileCheckpoints(options: FileCheckpointOptions = {}): CheckpointStore {
-  const dir = options.dir ?? DEFAULT_DIR;
-
-  /**
-   * Ensure session directory exists.
-   */
-  async function ensureSessionDir(sessionId: string): Promise<string> {
-    const sessionDir = join(dir, sessionId);
-    await mkdir(sessionDir, { recursive: true });
-    return sessionDir;
-  }
-
-  /**
-   * Get paths for checkpoint files.
-   */
-  function getPaths(sessionId: string): { checkpointPath: string; metadataPath: string } {
-    const sessionDir = join(dir, sessionId);
-    return {
-      checkpointPath: join(sessionDir, 'checkpoint.json'),
-      metadataPath: join(sessionDir, 'metadata.json'),
-    };
-  }
-
-  return {
-    async save(sessionId: string, state: AgentStateJSON): Promise<void> {
-      await ensureSessionDir(sessionId);
-      const { checkpointPath, metadataPath } = getPaths(sessionId);
-
-      // Build metadata
-      const metadata: CheckpointMetadata = {
-        sessionId,
-        checkpointId: generateUUID(),
-        timestamp: new Date().toISOString(),
-        step: state.step,
-        agentId: state.metadata.agentId as string ?? 'unknown',
-      };
-
-      // Write checkpoint first, then metadata (sequential to avoid race conditions)
-      await Bun.write(checkpointPath, JSON.stringify(state, null, 2));
-      await Bun.write(metadataPath, JSON.stringify(metadata, null, 2));
-    },
-
-    async load(sessionId: string): Promise<AgentStateJSON | null> {
-      const { checkpointPath } = getPaths(sessionId);
-
-      try {
-        const file = Bun.file(checkpointPath);
-        const exists = await file.exists();
-        if (!exists) {
-          return null;
-        }
-        const content = await file.text();
-        return JSON.parse(content) as AgentStateJSON;
-      } catch {
-        // File doesn't exist or is invalid
-        return null;
-      }
-    },
-
-    async delete(sessionId: string): Promise<void> {
-      const sessionDir = join(dir, sessionId);
-      try {
-        await rm(sessionDir, { recursive: true, force: true });
-      } catch {
-        // Directory might not exist, ignore
-      }
-    },
-
-    async list(): Promise<string[]> {
-      try {
-        // Ensure base directory exists
-        await mkdir(dir, { recursive: true });
-
-        const entries = await readdir(dir, { withFileTypes: true });
-        return entries
-          .filter((entry) => entry.isDirectory())
-          .map((entry) => entry.name);
-      } catch {
-        return [];
-      }
-    },
-  };
-}

package/src/checkpoint/index.ts

@@ -1,40 +0,0 @@
-/**
- * Checkpoint Module
- *
- * Step-level persistence for crash recovery and session resume.
- *
- * @example
- * ```typescript
- * import { fileCheckpoints } from '@providerprotocol/agents/checkpoint';
- * import { agent, AgentState } from '@providerprotocol/agents';
- *
- * const store = fileCheckpoints({ dir: './checkpoints' });
- *
- * // Resume or start fresh
- * const saved = await store.load('my-session');
- * const initialState = saved
- *   ? AgentState.fromJSON(saved)
- *   : AgentState.initial();
- *
- * // Execute with checkpointing
- * const coder = agent({
- *   model: anthropic('claude-sonnet-4-20250514'),
- *   tools: [Bash, Read],
- *   checkpoints: store,
- *   sessionId: 'my-session',
- * });
- *
- * const { turn, state } = await coder.generate('Fix the bug', initialState);
- * ```
- *
- * @packageDocumentation
- */
-
-export { fileCheckpoints } from './file.ts';
-
-export type {
-  CheckpointStore,
-  FileCheckpointOptions,
-  CheckpointMetadata,
-  CheckpointData,
-} from './types.ts';