@providerprotocol/agents 0.0.2 → 0.0.4

package/src/state/index.ts

@@ -1,301 +0,0 @@
-import type {
-  Message,
-  UserContent,
-  AssistantContent,
-  ToolCall,
-  ToolResult,
-} from '@providerprotocol/ai';
-import { UserMessage, AssistantMessage, ToolResultMessage } from '@providerprotocol/ai';
-import { generateUUID } from '../utils/uuid.ts';
-import type {
-  AgentStateInterface,
-  AgentStateJSON,
-  PlanStep,
-  MessageJSON,
-  SubagentExecutionTrace,
-} from './types.ts';
-import { UAP_VERSION } from './types.ts';
-
-/**
- * Immutable agent state snapshot.
- * All operations return new instances - the original state is never mutated.
- */
-export class AgentState implements AgentStateInterface {
-  readonly id: string;
-
-  readonly messages: readonly Message[];
-
-  readonly step: number;
-
-  readonly metadata: Readonly<Record<string, unknown>>;
-
-  readonly reasoning: readonly string[];
-
-  readonly plan: readonly PlanStep[] | undefined;
-
-  readonly subagentTraces: readonly SubagentExecutionTrace[];
-
-  private constructor(
-    id: string,
-    messages: readonly Message[],
-    step: number,
-    metadata: Readonly<Record<string, unknown>>,
-    reasoning: readonly string[],
-    plan: readonly PlanStep[] | undefined,
-    subagentTraces: readonly SubagentExecutionTrace[],
-  ) {
-    this.id = id;
-    this.messages = messages;
-    this.step = step;
-    this.metadata = metadata;
-    this.reasoning = reasoning;
-    this.plan = plan;
-    this.subagentTraces = subagentTraces;
-  }
-
-  /**
-   * Create an initial empty state.
-   */
-  static initial(): AgentState {
-    return new AgentState(
-      generateUUID(),
-      [],
-      0,
-      {},
-      [],
-      undefined,
-      [],
-    );
-  }
-
-  /**
-   * Return new state with a message added.
-   */
-  withMessage(message: Message): AgentState {
-    return new AgentState(
-      generateUUID(),
-      [...this.messages, message],
-      this.step,
-      this.metadata,
-      this.reasoning,
-      this.plan,
-      this.subagentTraces,
-    );
-  }
-
-  /**
-   * Return new state with messages added.
-   */
-  withMessages(messages: Message[]): AgentState {
-    return new AgentState(
-      generateUUID(),
-      [...this.messages, ...messages],
-      this.step,
-      this.metadata,
-      this.reasoning,
-      this.plan,
-      this.subagentTraces,
-    );
-  }
-
-  /**
-   * Return new state with context replaced (all messages).
-   * Use for context window management (pruning, summarization).
-   */
-  withContext(messages: Message[]): AgentState {
-    return new AgentState(
-      generateUUID(),
-      [...messages],
-      this.step,
-      this.metadata,
-      this.reasoning,
-      this.plan,
-      this.subagentTraces,
-    );
-  }
-
-  /**
-   * Return new state with updated step number.
-   */
-  withStep(step: number): AgentState {
-    return new AgentState(
-      generateUUID(),
-      this.messages,
-      step,
-      this.metadata,
-      this.reasoning,
-      this.plan,
-      this.subagentTraces,
-    );
-  }
-
-  /**
-   * Return new state with metadata entry added/updated.
-   */
-  withMetadata(key: string, value: unknown): AgentState {
-    return new AgentState(
-      generateUUID(),
-      this.messages,
-      this.step,
-      { ...this.metadata, [key]: value },
-      this.reasoning,
-      this.plan,
-      this.subagentTraces,
-    );
-  }
-
-  /**
-   * Return new state with reasoning trace added.
-   */
-  withReasoning(reasoning: string): AgentState {
-    return new AgentState(
-      generateUUID(),
-      this.messages,
-      this.step,
-      this.metadata,
-      [...this.reasoning, reasoning],
-      this.plan,
-      this.subagentTraces,
-    );
-  }
-
-  /**
-   * Return new state with plan set.
-   */
-  withPlan(plan: PlanStep[]): AgentState {
-    return new AgentState(
-      generateUUID(),
-      this.messages,
-      this.step,
-      this.metadata,
-      this.reasoning,
-      [...plan],
-      this.subagentTraces,
-    );
-  }
-
-  /**
-   * Return new state with sub-agent trace added.
-   * Per UAP spec Section 8.8.
-   */
-  withSubagentTrace(trace: SubagentExecutionTrace): AgentState {
-    return new AgentState(
-      generateUUID(),
-      this.messages,
-      this.step,
-      this.metadata,
-      this.reasoning,
-      this.plan,
-      [...this.subagentTraces, trace],
-    );
-  }
-
-  /**
-   * Serialize state to JSON for persistence.
-   */
-  toJSON(): AgentStateJSON {
-    return {
-      version: UAP_VERSION,
-      id: this.id,
-      messages: this.messages.map((msg) => serializeMessage(msg)),
-      step: this.step,
-      metadata: { ...this.metadata },
-      reasoning: [...this.reasoning],
-      plan: this.plan ? this.plan.map((s) => ({ ...s })) : undefined,
-      subagentTraces: this.subagentTraces.length > 0
-        ? this.subagentTraces.map((t) => ({ ...t }))
-        : undefined,
-    };
-  }
-
-  /**
-   * Deserialize state from JSON.
-   */
-  static fromJSON(json: AgentStateJSON): AgentState {
-    if (json.version !== UAP_VERSION) {
-      throw new Error(`Unsupported UAP version: ${json.version}. Expected: ${UAP_VERSION}`);
-    }
-
-    return new AgentState(
-      json.id,
-      json.messages.map((msg) => deserializeMessage(msg)),
-      json.step,
-      json.metadata,
-      json.reasoning,
-      json.plan ? json.plan.map((s) => ({ ...s })) : undefined,
-      json.subagentTraces ? json.subagentTraces.map((t) => ({ ...t })) : [],
-    );
-  }
-}
-
-/**
- * Serialize a UPP Message to JSON.
- */
-function serializeMessage(message: Message): MessageJSON {
-  if (message instanceof UserMessage) {
-    return {
-      role: 'user',
-      content: message.content,
-      metadata: message.metadata,
-    };
-  }
-  if (message instanceof AssistantMessage) {
-    return {
-      role: 'assistant',
-      content: {
-        content: message.content,
-        toolCalls: message.toolCalls,
-      },
-      metadata: message.metadata,
-    };
-  }
-  if (message instanceof ToolResultMessage) {
-    return {
-      role: 'tool_result',
-      content: message.results,
-      metadata: message.metadata,
-    };
-  }
-  throw new Error(`Unknown message type: ${typeof message}`);
-}
-
-/**
- * Deserialize a JSON message to UPP Message.
- */
-function deserializeMessage(json: MessageJSON): Message {
-  switch (json.role) {
-    case 'user':
-      return new UserMessage(
-        json.content as string | UserContent[],
-        { metadata: json.metadata },
-      );
-    case 'assistant': {
-      const assistantContent = json.content as {
-        content: string | AssistantContent[];
-        toolCalls?: ToolCall[];
-      };
-      return new AssistantMessage(
-        assistantContent.content,
-        assistantContent.toolCalls,
-        { metadata: json.metadata },
-      );
-    }
-    case 'tool_result':
-      return new ToolResultMessage(
-        json.content as ToolResult[],
-        { metadata: json.metadata },
-      );
-    default:
-      throw new Error(`Unknown message role: ${json.role}`);
-  }
-}
-
-export type {
-  AgentStateInterface,
-  AgentStateJSON,
-  PlanStep,
-  PlanStepStatus,
-  SubagentExecutionTrace,
-  SubagentExecutionTraceJSON,
-  ToolExecutionTrace,
-} from './types.ts';

package/src/state/types.ts

@@ -1,173 +0,0 @@
-import type { Message, MessageMetadata, TokenUsage } from '@providerprotocol/ai';
-
-/**
- * Status of a plan step during execution.
- */
-export type PlanStepStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
-
-/**
- * A single tool execution trace from a sub-agent.
- * Per UAP spec Section 8.8.
- */
-export interface ToolExecutionTrace {
-  /** Name of the tool */
-  toolName: string;
-  /** Tool call ID */
-  toolCallId?: string;
-  /** Arguments passed to the tool */
-  arguments: Record<string, unknown>;
-  /** Tool result */
-  result: string;
-  /** Whether the tool errored */
-  isError?: boolean;
-  /** Execution time in milliseconds */
-  duration?: number;
-}
-
-/**
- * Sub-agent execution trace for checkpoint persistence.
- * Per UAP spec Section 8.8.
- */
-export interface SubagentExecutionTrace {
-  /** Unique ID of the sub-agent instance */
-  subagentId: string;
-  /** Type/name of the sub-agent */
-  subagentType: string;
-  /** Tool call ID that spawned this sub-agent */
-  parentToolCallId: string;
-  /** The task given to the sub-agent */
-  prompt: string;
-  /** Start timestamp (ms since epoch) */
-  startTime: number;
-  /** End timestamp (ms since epoch) */
-  endTime: number;
-  /** Whether execution succeeded */
-  success: boolean;
-  /** Sub-agent's response (if successful) */
-  result?: string;
-  /** Error message (if failed) */
-  error?: string;
-  /** Tools used by sub-agent */
-  toolExecutions?: ToolExecutionTrace[];
-  /** Token usage for sub-agent */
-  usage?: TokenUsage;
-}
-
-/**
- * Serialized form of SubagentExecutionTrace.
- */
-export interface SubagentExecutionTraceJSON {
-  subagentId: string;
-  subagentType: string;
-  parentToolCallId: string;
-  prompt: string;
-  startTime: number;
-  endTime: number;
-  success: boolean;
-  result?: string;
-  error?: string;
-  toolExecutions?: ToolExecutionTrace[];
-  usage?: TokenUsage;
-}
-
-/**
- * A single step in an execution plan.
- */
-export interface PlanStep {
-  /** Unique step identifier */
-  id: string;
-  /** Description of what this step does */
-  description: string;
-  /** Tool to use (if applicable) */
-  tool?: string;
-  /** IDs of steps this depends on */
-  dependsOn: string[];
-  /** Current status */
-  status: PlanStepStatus;
-}
-
-/**
- * Serialized form of a PlanStep.
- */
-export interface PlanStepJSON {
-  id: string;
-  description: string;
-  tool?: string;
-  dependsOn: string[];
-  status: PlanStepStatus;
-}
-
-/**
- * Serialized form of AgentState for persistence.
- */
-export interface AgentStateJSON {
-  /** UAP version */
-  version: string;
-  /** State snapshot ID */
-  id: string;
-  /** Serialized messages */
-  messages: MessageJSON[];
-  /** Current step number */
-  step: number;
-  /** User-defined metadata */
-  metadata: Record<string, unknown>;
-  /** Reasoning traces (for ReAct) */
-  reasoning: string[];
-  /** Execution plan (for Plan strategy) */
-  plan?: PlanStepJSON[];
-  /** Sub-agent execution traces (per UAP spec Section 8.8) */
-  subagentTraces?: SubagentExecutionTraceJSON[];
-}
-
-/**
- * Serialized form of a Message.
- * This preserves the UPP Message structure for serialization.
- */
-export interface MessageJSON {
-  role: 'user' | 'assistant' | 'tool_result';
-  content: unknown;
-  metadata?: MessageMetadata;
-}
-
-/**
- * Interface for AgentState operations.
- * All operations return new instances (immutable).
- */
-export interface AgentStateInterface {
-  /** State snapshot ID (UUIDv4) */
-  readonly id: string;
-  /** Conversation history (UPP Messages) */
-  readonly messages: readonly Message[];
-  /** Current step number */
-  readonly step: number;
-  /** User-defined metadata */
-  readonly metadata: Readonly<Record<string, unknown>>;
-  /** Reasoning traces (for ReAct) */
-  readonly reasoning: readonly string[];
-  /** Execution plan (for Plan strategy) */
-  readonly plan: readonly PlanStep[] | undefined;
-  /** Sub-agent execution traces (per UAP spec Section 8.8) */
-  readonly subagentTraces: readonly SubagentExecutionTrace[];
-
-  /** Return new state with message added */
-  withMessage(message: Message): AgentStateInterface;
-  /** Return new state with messages added */
-  withMessages(messages: Message[]): AgentStateInterface;
-  /** Return new state with context replaced (all messages) */
-  withContext(messages: Message[]): AgentStateInterface;
-  /** Return new state with updated step */
-  withStep(step: number): AgentStateInterface;
-  /** Return new state with metadata entry */
-  withMetadata(key: string, value: unknown): AgentStateInterface;
-  /** Return new state with reasoning added */
-  withReasoning(reasoning: string): AgentStateInterface;
-  /** Return new state with plan set */
-  withPlan(plan: PlanStep[]): AgentStateInterface;
-  /** Return new state with sub-agent trace added */
-  withSubagentTrace(trace: SubagentExecutionTrace): AgentStateInterface;
-  /** Serialize to JSON */
-  toJSON(): AgentStateJSON;
-}
-
-/** UAP version for serialization */
-export const UAP_VERSION = '1.0.0';

package/src/thread-tree/index.ts

@@ -1,249 +0,0 @@
-import { generateUUID } from '../utils/uuid.ts';
-import { AgentState } from '../state/index.ts';
-import type { ThreadNodeJSON, ThreadTreeJSON } from './types.ts';
-
-/**
- * A node in the thread tree representing a conversation state snapshot.
- */
-export class ThreadNode {
-  /** Node ID (UUIDv4) */
-  readonly id: string;
-
-  /** Parent node ID (null for root) */
-  readonly parentId: string | null;
-
-  /** State snapshot at this node */
-  state: AgentState;
-
-  /** Optional branch name */
-  name?: string;
-
-  /** Child node IDs */
-  readonly children: string[];
-
-  constructor(
-    id: string,
-    parentId: string | null,
-    state: AgentState,
-    name?: string,
-    children: string[] = [],
-  ) {
-    this.id = id;
-    this.parentId = parentId;
-    this.state = state;
-    this.name = name;
-    this.children = children;
-  }
-
-  /**
-   * Serialize to JSON.
-   */
-  toJSON(): ThreadNodeJSON {
-    return {
-      id: this.id,
-      parentId: this.parentId,
-      state: this.state.toJSON(),
-      name: this.name,
-      children: [...this.children],
-    };
-  }
-
-  /**
-   * Deserialize from JSON.
-   */
-  static fromJSON(json: ThreadNodeJSON): ThreadNode {
-    return new ThreadNode(
-      json.id,
-      json.parentId,
-      AgentState.fromJSON(json.state),
-      json.name,
-      [...json.children],
-    );
-  }
-}
-
-/**
- * A tree-structured collection of conversation threads with parent-child relationships.
- * Enables branching conversations and easy switching between alternative paths.
- */
-export class ThreadTree {
-  /** Root node */
-  readonly root: ThreadNode;
-
-  /** Currently active node */
-  private currentNode: ThreadNode;
-
-  /** All nodes by ID */
-  readonly nodes: Map<string, ThreadNode>;
-
-  constructor(root?: ThreadNode) {
-    if (root) {
-      this.root = root;
-      this.currentNode = root;
-      this.nodes = new Map([[root.id, root]]);
-    } else {
-      const rootNode = new ThreadNode(
-        generateUUID(),
-        null,
-        AgentState.initial(),
-        'root',
-      );
-      this.root = rootNode;
-      this.currentNode = rootNode;
-      this.nodes = new Map([[rootNode.id, rootNode]]);
-    }
-  }
-
-  /**
-   * Get the currently active node.
-   */
-  get current(): ThreadNode {
-    return this.currentNode;
-  }
-
-  /**
-   * Create a branch from a node.
-   *
-   * @param fromId - ID of the node to branch from
-   * @param name - Optional name for the branch
-   * @returns ID of the new node
-   */
-  branch(fromId: string, name?: string): string {
-    const parent = this.nodes.get(fromId);
-    if (!parent) {
-      throw new Error(`Node not found: ${fromId}`);
-    }
-
-    const newNode = new ThreadNode(
-      generateUUID(),
-      fromId,
-      parent.state, // Copy parent's state
-      name,
-    );
-
-    // Add to parent's children
-    parent.children.push(newNode.id);
-
-    // Add to nodes map
-    this.nodes.set(newNode.id, newNode);
-
-    return newNode.id;
-  }
-
-  /**
-   * Switch to a different node.
-   *
-   * @param nodeId - ID of the node to switch to
-   */
-  checkout(nodeId: string): void {
-    const node = this.nodes.get(nodeId);
-    if (!node) {
-      throw new Error(`Node not found: ${nodeId}`);
-    }
-
-    this.currentNode = node;
-  }
-
-  /**
-   * Get the AgentState representing the full history from root to current node.
-   * Since nodes store full state snapshots, this returns the current node's state.
-   *
-   * @returns AgentState with combined history
-   */
-  history(): AgentState {
-    return this.currentNode.state
-      .withMetadata('_threadTreeNodeId', this.currentNode.id);
-  }
-
-  /**
-   * Get all leaf nodes (nodes with no children).
-   *
-   * @returns Array of leaf node IDs
-   */
-  getLeaves(): string[] {
-    const leaves: string[] = [];
-
-    for (const [id, node] of this.nodes) {
-      if (node.children.length === 0) {
-        leaves.push(id);
-      }
-    }
-
-    return leaves;
-  }
-
-  /**
-   * Get all branch names.
-   *
-   * @returns Map of node IDs to branch names
-   */
-  getBranches(): Map<string, string | undefined> {
-    const branches = new Map<string, string | undefined>();
-
-    for (const [id, node] of this.nodes) {
-      if (node.name) {
-        branches.set(id, node.name);
-      }
-    }
-
-    return branches;
-  }
-
-  /**
-   * Serialize to JSON.
-   */
-  toJSON(): ThreadTreeJSON {
-    const nodes: ThreadNodeJSON[] = [];
-
-    for (const node of this.nodes.values()) {
-      nodes.push(node.toJSON());
-    }
-
-    return {
-      rootId: this.root.id,
-      currentId: this.currentNode.id,
-      nodes,
-    };
-  }
-
-  /**
-   * Deserialize from JSON.
-   */
-  static fromJSON(json: ThreadTreeJSON): ThreadTree {
-    // First, create all nodes
-    const nodesMap = new Map<string, ThreadNode>();
-
-    for (const nodeJson of json.nodes) {
-      const node = ThreadNode.fromJSON(nodeJson);
-      nodesMap.set(node.id, node);
-    }
-
-    // Find root and current nodes
-    const root = nodesMap.get(json.rootId);
-    const current = nodesMap.get(json.currentId);
-
-    if (!root) {
-      throw new Error(`Root node not found: ${json.rootId}`);
-    }
-
-    if (!current) {
-      throw new Error(`Current node not found: ${json.currentId}`);
-    }
-
-    // Create tree with root
-    const tree = new ThreadTree(root);
-
-    // Replace the nodes map
-    tree.nodes.clear();
-    for (const [id, node] of nodesMap) {
-      tree.nodes.set(id, node);
-    }
-
-    // Set current node
-    tree.checkout(current.id);
-
-    return tree;
-  }
-}
-
-export type { ThreadNodeJSON, ThreadTreeJSON } from './types.ts';