{"id":44691404,"url":"https://github.com/giulio-leone/onegenui-deep-agents","last_synced_at":"2026-02-18T22:02:39.237Z","repository":{"id":337730894,"uuid":"1154965306","full_name":"giulio-leone/onegenui-deep-agents","owner":"giulio-leone","description":"Deep Agent Framework built on Vercel AI SDK v6 — planning, context management, subagents, persistent memory, MCP integration","archived":false,"fork":false,"pushed_at":"2026-02-15T08:55:11.000Z","size":541,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-15T12:27:46.123Z","etag":null,"topics":["ai","generative-ui","onegenui","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giulio-leone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T01:07:08.000Z","updated_at":"2026-02-15T08:55:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/giulio-leone/onegenui-deep-agents","commit_stats":null,"previous_names":["g97iulio1609/onegenui-deep-agents","giulio-leone/onegenui-deep-agents"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/giulio-leone/onegenui-deep-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulio-leone%2Fonegenui-deep-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulio-leone%2Fonegenui-deep-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulio-leone%2Fonegenui-deep-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulio-leone%2Fonegenui-deep-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giulio-leone","download_url":"https://codeload.github.com/giulio-leone/onegenui-deep-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulio-leone%2Fonegenui-deep-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29596332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T20:59:56.587Z","status":"ssl_error","status_checked_at":"2026-02-18T20:58:41.434Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","generative-ui","onegenui","typescript"],"created_at":"2026-02-15T07:11:55.564Z","updated_at":"2026-02-18T22:02:39.230Z","avatar_url":"https://github.com/giulio-leone.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GaussFlow (@giulio-leone/gaussflow-agent)\n\n\u003e **GaussFlow** — AI Agent Framework built on Vercel AI SDK v6\n\nA hexagonal-architecture agent framework with built-in planning, context management, subagent orchestration, persistent memory, and MCP integration. Agents operate through a tool-loop powered by AI SDK's `ToolLoopAgent`, with filesystem, planning, and subagent tools composed via a fluent builder API.\n\n## Features\n\n- **Builder pattern** — fluent API with `DeepAgent.create()`, `.minimal()`, `.full()`, and `.auto()` factory methods\n- **Hexagonal architecture** — ports and adapters for filesystem, memory, MCP, validation, tracing, metrics, logging, and model access\n- **Plugin system** — deterministic middleware lifecycle with hook-based extensions and tool injection\n- **WorkflowPlugin** — multi-step workflow execution with retry, rollback, and conditional steps\n- **ObservabilityPlugin** — three-pillar observability: distributed tracing, metrics collection, and structured logging\n- **Guardrails** — input/output validation with Zod schemas, content filtering, and PII detection\n- **Web scraping tools** — crawl, search, and batch scrape via OneCrawl plugin\n- **RAG/knowledge tools** — entity extraction, knowledge queries via Vectorless plugin\n- **Evaluation metrics** — latency, token usage, tool frequency, and custom scoring\n- **ValidationPort** — engine-agnostic validation with `ZodValidationAdapter`\n- **BasePlugin** — abstract base class for building custom plugins\n- **AbstractBuilder** — template method pattern for validated, type-safe builders\n- **Multi-agent collaboration** — DAG-based `AgentGraph` with parallel forking and consensus strategies\n- **Built-in planning** — structured todo management with dependency tracking and priority\n- **Subagent orchestration** — spawn child agents with configurable depth limits and timeouts\n- **Context management** — automatic rolling summarization, tool-result offloading, and message truncation\n- **Human-in-the-loop approval** — configurable per-tool approval gates with allow/deny lists\n- **Checkpointing** — periodic state snapshots for session resume\n- **Event system** — typed lifecycle events with wildcard subscriptions\n- **MCP integration** — discover and execute tools from any MCP server\n- **Cross-session learning** — user profiles, memories, and shared knowledge persisting across sessions\n- **Multi-runtime** — runs on Node.js, Deno, Bun, Edge (Cloudflare Workers, Vercel Edge), and Browser\n- **CLI** — interactive REPL and single-shot mode with `gaussflow chat/run/demo` commands\n- **REST API** — zero-dependency HTTP server for multi-language access (Python, Go, Ruby, etc.)\n\n## Installation\n\n```bash\npnpm add @giulio-leone/gaussflow-agent\n```\n\n### Peer Dependencies\n\nThe package requires `ai` (v6+) and `zod` (v4+) as direct dependencies. The following peer dependencies are optional:\n\n| Package | Purpose |\n|---------|---------|\n| `@giulio-leone/gaussflow-mcp` | GaussFlow MCP registry adapter |\n| `@giulio-leone/gaussflow-providers` | AI model provider utilities |\n| `@supabase/supabase-js` | Supabase-backed persistent memory |\n| `tiktoken` | Accurate BPE token counting |\n| `@ai-sdk/mcp` | AI SDK MCP client adapter |\n| `onecrawl` | Web scraping and search tools (OneCrawlPlugin) |\n| `@giulio-leone/gaussflow-vectorless` | RAG/knowledge extraction (VectorlessPlugin) |\n\nInstall only the peers you need:\n\n```bash\npnpm add @supabase/supabase-js tiktoken\n```\n\n## Quick Start\n\n```typescript\nimport { DeepAgent } from \"@giulio-leone/gaussflow-agent\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst agent = DeepAgent.minimal({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a helpful coding assistant.\",\n});\n\nconst result = await agent.run(\"Create a utility function that debounces input.\");\n\nconsole.log(result.text);\nconsole.log(`Steps: ${result.steps.length}`);\nconsole.log(`Session: ${result.sessionId}`);\n```\n\n`DeepAgent.minimal()` creates an agent with a virtual filesystem and planning tools enabled, using in-memory storage and approximate token counting.\n\n## Architecture\n\nGaussFlow follows **hexagonal architecture** (ports \u0026 adapters). The core domain (DeepAgent) depends only on port interfaces; adapters implement those interfaces for specific platforms and services. Plugins extend behavior via lifecycle hooks.\n\n```\n┌──────────────────────────────────────────────────────────────────────┐\n│                     DeepAgent (Orchestrator)                         │\n│                                                                      │\n│  EventBus ─ ApprovalMgr ─ TokenTracker ─ ContextMgr ─ PluginMgr    │\n└──────┬──────────────┬──────────────┬──────────────┬─────────────────┘\n       │              │              │              │\n  ┌────▼────┐   ┌─────▼─────┐  ┌────▼────┐  ┌─────▼─────┐\n  │  Ports  │   │   Ports   │  │  Ports  │  │   Ports   │\n  │(inbound)│   │ (outbound)│  │(observe)│  │ (infra)   │\n  ├─────────┤   ├───────────┤  ├─────────┤  ├───────────┤\n  │PluginPort│  │Filesystem │  │Tracing  │  │RuntimePort│\n  │ModelPort │  │MemoryPort │  │Metrics  │  │Validation │\n  │Consensus │  │McpPort    │  │Logging  │  │TokenCount │\n  │          │  │LearningPt │  │         │  │           │\n  └────┬────┘  └─────┬─────┘  └────┬────┘  └─────┬─────┘\n       │              │              │              │\n  ┌────▼────┐   ┌─────▼─────┐  ┌────▼────┐  ┌─────▼─────┐\n  │Adapters │   │ Adapters  │  │Adapters │  │ Adapters  │\n  ├─────────┤   ├───────────┤  ├─────────┤  ├───────────┤\n  │BasePlugin│  │VirtualFS  │  │InMemory │  │NodeRuntime│\n  │Guardrails│  │LocalFS    │  │ Tracing │  │DenoRuntime│\n  │Workflow  │  │InMemoryMem│  │InMemory │  │BunRuntime │\n  │Observ.   │  │Supabase   │  │ Metrics │  │EdgeRuntime│\n  │OneCrawl  │  │AiSdkMcp   │  │Console  │  │ZodValid. │\n  │Vectorless│  │OnegenUiMcp│  │ Logging │  │Approximate│\n  │Evals     │  │InMemLearn │  │         │  │Tiktoken   │\n  │A2A       │  │           │  │         │  │           │\n  └────┬────┘  └───────────┘  └─────────┘  └───────────┘\n       │\n  ┌────▼────────────────────────┐\n  │          Tools              │\n  │ ls, read, write, edit,     │\n  │ glob, grep, todos, task,   │\n  │ scrape, search, generate,  │\n  │ query, mcp:*               │\n  └────────────────────────────┘\n       │\n  ┌────▼────────────────────────┐\n  │     AgentGraph (DAG)        │\n  │ node() → edge() → fork()   │\n  │ consensus strategies        │\n  │ streaming events            │\n  └────────────────────────────┘\n```\n\n### Key Concepts\n\n| Concept | Description |\n|---------|-------------|\n| **Port** | Interface contract (e.g. `FilesystemPort`, `TracingPort`) — no implementation details |\n| **Adapter** | Concrete implementation of a port (e.g. `VirtualFilesystem`, `InMemoryTracingAdapter`) |\n| **Plugin** | Extends agent behavior via lifecycle hooks and/or tool injection |\n| **AbstractBuilder** | Template method pattern ensuring `validate()` before `construct()` |\n| **BasePlugin** | Abstract class providing `name`, `version`, and `buildHooks()` skeleton |\n\n### Package Structure\n\n```\nsrc/\n  index.ts                    Public API surface\n  types.ts                    Shared type definitions\n  ports/\n    filesystem.port.ts        FilesystemPort interface\n    memory.port.ts            MemoryPort interface\n    mcp.port.ts               McpPort interface\n    model.port.ts             ModelPort interface\n    plugin.port.ts            Plugin contracts and lifecycle hooks\n    token-counter.port.ts     TokenCounterPort interface\n    learning.port.ts          LearningPort interface\n    runtime.port.ts           RuntimePort interface\n    validation.port.ts        ValidationPort interface\n    tracing.port.ts           TracingPort / Span interfaces\n    metrics.port.ts           MetricsPort interface\n    logging.port.ts           LoggingPort / LogLevel / LogEntry\n    consensus.port.ts         ConsensusPort for fork evaluation\n  adapters/\n    filesystem/\n      virtual-fs.adapter.ts   In-memory VFS with optional disk sync\n      local-fs.adapter.ts     Sandboxed Node.js fs wrapper\n    memory/\n      in-memory.adapter.ts    Map-based in-process storage\n      supabase.adapter.ts     Supabase-backed persistent storage\n    mcp/\n      ai-sdk-mcp.adapter.ts   @ai-sdk/mcp client bridge\n      onegenui-mcp.adapter.ts @giulio-leone/gaussflow-mcp registry bridge\n    token-counter/\n      approximate.adapter.ts  Character-ratio estimation (~4 chars/token)\n      tiktoken.adapter.ts     BPE-accurate counting via tiktoken\n    learning/\n      in-memory-learning.adapter.ts  Map-based learning storage\n    runtime/\n      base-runtime.adapter.ts Base runtime adapter\n      node-runtime.adapter.ts Node.js runtime (process.env)\n      deno-runtime.adapter.ts Deno runtime (Deno.env.get)\n      bun-runtime.adapter.ts  Bun runtime (process.env)\n      edge-runtime.adapter.ts Edge/CF Workers runtime\n      detect-runtime.ts       Auto-detection + factory\n    validation/\n      zod-validation.adapter.ts  Zod-based ValidationPort implementation\n    tracing/\n      in-memory-tracing.adapter.ts  In-memory span storage\n    metrics/\n      in-memory-metrics.adapter.ts  In-memory counters/histograms/gauges\n    logging/\n      console-logging.adapter.ts    Console-based structured logging\n    consensus/\n      llm-judge.adapter.ts    LLM-based consensus evaluation\n      majority-vote.adapter.ts Simple majority vote consensus\n      debate.adapter.ts       Multi-round debate consensus\n  agent/\n    deep-agent.ts             DeepAgent class and DeepAgentBuilder\n    agent-config.ts           Default configs and resolvers\n    approval-manager.ts       Tool-call approval logic\n    event-bus.ts              Typed event emitter\n    stop-conditions.ts        Reusable stop predicates\n  plugins/\n    base.plugin.ts            Abstract base class for plugins\n    plugin-manager.ts         Plugin lifecycle + deterministic hook execution\n    agent-card.plugin.ts      AgentCard generation and serving\n    a2a.plugin.ts             A2A integration plugin\n    a2a-handler.ts            JSON-RPC A2A request handler\n    guardrails.plugin.ts      Input/output validation and content filtering\n    onecrawl.plugin.ts        OneCrawl web scraping integration\n    vectorless.plugin.ts      Vectorless RAG/knowledge integration\n    evals.plugin.ts           Evaluation metrics collection\n    workflow.plugin.ts        Multi-step workflow with retry/rollback\n    observability.plugin.ts   Tracing + metrics + logging plugin\n  tools/\n    filesystem/               ls, read_file, write_file, edit_file, glob, grep\n    planning/                 write_todos, review_todos\n    subagent/                 task (spawn child agent)\n  context/\n    context-manager.ts        Offloading and truncation\n    rolling-summarizer.ts     LLM-based conversation compression\n    token-tracker.ts          Cumulative usage tracking\n  graph/\n    agent-graph.ts            AgentGraph class and AgentGraphBuilder\n    agent-node.ts             Graph node wrapper\n    graph-executor.ts         DAG execution engine\n    shared-context.ts         Shared filesystem context for graph nodes\n  streaming/\n    event-stream.ts           Event stream utilities\n    sse-handler.ts            Server-Sent Events handler\n    ws-handler.ts             WebSocket handler\n    delta-encoder.ts          Delta encoding for efficient streaming\n    graph-stream.ts           Graph event streaming\n  domain/\n    todo.schema.ts            Todo Zod schemas\n    checkpoint.schema.ts      Checkpoint Zod schemas\n    conversation.schema.ts    Message and conversation schemas\n    events.schema.ts          Event type schemas\n    learning.schema.ts        Learning Zod schemas\n    eval.schema.ts            Evaluation Zod schemas\n    workflow.schema.ts        Workflow step, context, result schemas\n    graph.schema.ts           Graph configuration and result schemas\n  utils/\n    abstract-builder.ts       Template method builder base class\n```\n\n## API Reference\n\n### DeepAgent\n\nThe main orchestrator class. Use the static factory methods to create instances.\n\n#### Static Factories\n\n##### `DeepAgent.create(config): DeepAgentBuilder`\n\nReturns a builder for full control over agent composition.\n\n```typescript\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a project manager.\",\n})\n  .withPlanning()\n  .withSubagents()\n  .withMaxSteps(50)\n  .build();\n```\n\n##### `DeepAgent.minimal(config): DeepAgent`\n\nCreates an agent with planning enabled, using default adapters (VirtualFilesystem, InMemoryAdapter, ApproximateTokenCounter). Equivalent to `DeepAgent.create(config).withPlanning().build()`.\n\n```typescript\nconst agent = DeepAgent.minimal({\n  model: openai(\"gpt-4o\"),\n  instructions: \"Complete the task.\",\n});\n```\n\n##### `DeepAgent.full(config): DeepAgent`\n\nCreates a fully-featured agent with planning, subagents, and optional memory/MCP/token counter overrides.\n\n```typescript\nimport { SupabaseMemoryAdapter } from \"@giulio-leone/gaussflow-agent\";\nimport { createClient } from \"@supabase/supabase-js\";\n\nconst supabase = createClient(url, key);\n\nconst agent = DeepAgent.full({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a senior engineer.\",\n  memory: new SupabaseMemoryAdapter(supabase),\n  mcp: mcpAdapter,\n  tokenCounter: tiktokenCounter,\n});\n```\n\n#### Instance Methods\n\n##### `.run(prompt): Promise\u003cDeepAgentResult\u003e`\n\nExecutes the agent loop with the given prompt. Returns when the agent completes or reaches `maxSteps`.\n\n```typescript\ninterface DeepAgentResult {\n  text: string;       // Final assistant response\n  steps: unknown[];   // All intermediate steps\n  sessionId: string;  // Unique session identifier\n}\n```\n\n##### `.dispose(): Promise\u003cvoid\u003e`\n\nCloses MCP connections and removes all event listeners. Call when the agent is no longer needed.\n\n### DeepAgentBuilder\n\nFluent builder returned by `DeepAgent.create()`.\n\n| Method | Description |\n|--------|-------------|\n| `.withFilesystem(fs)` | Provide a custom `FilesystemPort` implementation |\n| `.withMemory(memory)` | Provide a custom `MemoryPort` implementation |\n| `.withLearning(learning, userId?)` | Provide a `LearningPort` for cross-session learning |\n| `.withRuntime(runtime)` | Provide a custom `RuntimePort` (auto-detected by default) |\n| `.withTokenCounter(counter)` | Provide a custom `TokenCounterPort` implementation |\n| `.withMcp(mcp)` | Provide a `McpPort` for MCP tool integration |\n| `.withPlanning()` | Enable planning tools (`write_todos`, `review_todos`) |\n| `.withSubagents(config?)` | Enable the `task` tool for spawning subagents |\n| `.withApproval(config?)` | Enable human-in-the-loop approval for tool calls |\n| `.withMaxSteps(n)` | Override the maximum number of agent loop steps |\n| `.use(plugin)` | Register a plugin (hooks + optional tool injection) |\n| `.on(event, handler)` | Register an event handler before building |\n| `.build()` | Construct the `DeepAgent` instance |\n\nAll methods return `this` for chaining. Defaults are applied for any adapter not explicitly provided:\n\n| Adapter | Default |\n|---------|---------|\n| Filesystem | `VirtualFilesystem` |\n| Memory | `InMemoryAdapter` |\n| Token Counter | `ApproximateTokenCounter` |\n| Max Steps | `30` |\n\n### Plugin System\n\nPlugins are executed in **registration order** and can participate in a deterministic lifecycle:\n\n- `beforeRun` / `afterRun`\n- `beforeTool` / `afterTool`\n- `beforeStep` / `afterStep`\n- `onError`\n\nPlugins can also inject tools by exposing a `tools` map.\n\n```typescript\nimport type { DeepAgentPlugin } from \"@giulio-leone/gaussflow-agent\";\n\nconst observabilityPlugin: DeepAgentPlugin = {\n  name: \"observability\",\n  hooks: {\n    beforeRun: async (_ctx, params) =\u003e ({\n      prompt: `[trace] ${params.prompt}`,\n    }),\n    afterRun: async (_ctx, params) =\u003e {\n      console.log(\"Final output length:\", params.result.text.length);\n    },\n  },\n};\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a release engineer.\",\n})\n  .use(observabilityPlugin)\n  .build();\n```\n\n#### Built-in Plugins\n\n| Plugin | Description |\n|--------|-------------|\n| `AgentCardPlugin` | Resolves `agents.md` / `skills.md` with priority `manual file \u003e override \u003e auto-generated` |\n| `A2APlugin` | Exposes an A2A JSON-RPC handler and adds the `a2a:call` tool for remote A2A agents |\n| `GuardrailsPlugin` | Input/output validation with Zod schemas, content filtering, and PII detection |\n| `WorkflowPlugin` | Multi-step workflow execution with retry, rollback, and conditional steps |\n| `ObservabilityPlugin` | Three-pillar observability: distributed tracing, metrics, and structured logging |\n| `OneCrawlPlugin` | Web scraping and search tools via `onecrawl` (tools: `scrape`, `search`, `batch`) |\n| `VectorlessPlugin` | RAG/knowledge tools via `@giulio-leone/gaussflow-vectorless` (tools: `generate`, `query`, `search-entities`, `list`) |\n| `EvalsPlugin` | Evaluation metrics: latency, tokens, tool usage, custom scorers |\n\n`A2APlugin` can consume `AgentCardPlugin` as a discovery provider:\n\n```typescript\nimport {\n  DeepAgent,\n  AgentCardPlugin,\n  A2APlugin,\n} from \"@giulio-leone/gaussflow-agent\";\n\nconst agentCard = new AgentCardPlugin();\nconst a2a = new A2APlugin({ agentCardProvider: agentCard });\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"Coordinate infra operations across distributed agents.\",\n})\n  .use(agentCard)\n  .use(a2a)\n  .build();\n\nconst a2aHttpHandler = a2a.createHttpHandler(agent);\n```\n\n#### GuardrailsPlugin\n\nInput/output validation and content filtering:\n\n```typescript\nimport { DeepAgent, createGuardrailsPlugin, createPiiFilter } from \"@giulio-leone/gaussflow-agent\";\nimport { z } from \"zod\";\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a helpful assistant.\",\n})\n  .use(createGuardrailsPlugin({\n    inputSchema: z.string().min(1).max(10000),\n    outputSchema: z.string().max(50000),\n    contentFilters: [createPiiFilter()],\n    toolSchemas: {\n      write_file: z.object({ path: z.string(), content: z.string().max(100000) }),\n    },\n    onFailure: \"throw\", // or \"warn\"\n  }))\n  .build();\n```\n\n#### OneCrawlPlugin\n\nWeb scraping and search tools:\n\n```typescript\nimport { DeepAgent, createOneCrawlPlugin } from \"@giulio-leone/gaussflow-agent\";\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You can search and scrape the web.\",\n})\n  .use(createOneCrawlPlugin({\n    maxContentLength: 10000,\n    timeout: 30000,\n  }))\n  .build();\n// Adds tools: scrape, search, batch\n```\n\n#### VectorlessPlugin\n\nRAG/knowledge extraction tools (no vector database needed):\n\n```typescript\nimport { DeepAgent, createVectorlessPlugin } from \"@giulio-leone/gaussflow-agent\";\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You can extract and query knowledge from text.\",\n})\n  .use(createVectorlessPlugin())\n  .build();\n// Adds tools: generate, query, search-entities, list\n```\n\n#### EvalsPlugin\n\nEvaluation metrics collection:\n\n```typescript\nimport { DeepAgent, createEvalsPlugin } from \"@giulio-leone/gaussflow-agent\";\n\nconst evals = createEvalsPlugin({\n  persist: true,\n  scorers: [\n    { name: \"length\", score: (_prompt, output) =\u003e Math.min(output.length / 1000, 1) },\n  ],\n  onEval: (result) =\u003e console.log(`Latency: ${result.metrics.latencyMs}ms`),\n});\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a helpful assistant.\",\n})\n  .use(evals)\n  .build();\n\nawait agent.run(\"Hello\");\nconsole.log(evals.getLastResult()); // { metrics: { latencyMs, stepCount, toolCalls, ... } }\n```\n\n#### WorkflowPlugin\n\nMulti-step workflow execution with automatic retry, rollback on failure, and conditional step skipping:\n\n```typescript\nimport { DeepAgent, createWorkflowPlugin } from \"@giulio-leone/gaussflow-agent\";\nimport type { WorkflowStep } from \"@giulio-leone/gaussflow-agent\";\n\nconst steps: WorkflowStep[] = [\n  {\n    id: \"fetch-data\",\n    name: \"Fetch Data\",\n    execute: async (ctx) =\u003e {\n      const res = await fetch(\"https://api.example.com/data\");\n      return { ...ctx, data: await res.json() };\n    },\n    rollback: async (ctx) =\u003e {\n      console.log(\"Rolling back fetch-data\");\n    },\n    retry: { maxAttempts: 3, backoffMs: 1000, backoffMultiplier: 2 },\n  },\n  {\n    id: \"transform\",\n    name: \"Transform\",\n    condition: (ctx) =\u003e ctx.data != null, // Skip if no data\n    execute: async (ctx) =\u003e ({ ...ctx, transformed: true }),\n  },\n];\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"Process the workflow results.\",\n})\n  .use(createWorkflowPlugin({ steps, initialContext: { env: \"prod\" } }))\n  .build();\n```\n\n**Key API:**\n\n| Type | Description |\n|------|-------------|\n| `WorkflowStep` | `{ id, name, execute, rollback?, condition?, retry? }` |\n| `WorkflowContext` | `Record\u003cstring, unknown\u003e` — shared mutable context between steps |\n| `WorkflowResult` | `{ status, context, completedSteps, skippedSteps, failedStep?, error?, totalDurationMs }` |\n| `RetryConfig` | `{ maxAttempts: 3, backoffMs: 1000, backoffMultiplier: 2 }` |\n\n#### ObservabilityPlugin\n\nThree-pillar observability integrating `TracingPort`, `MetricsPort`, and `LoggingPort`:\n\n```typescript\nimport {\n  DeepAgent,\n  createObservabilityPlugin,\n  InMemoryTracingAdapter,\n  InMemoryMetricsAdapter,\n  ConsoleLoggingAdapter,\n} from \"@giulio-leone/gaussflow-agent\";\n\nconst tracer = new InMemoryTracingAdapter();\nconst metrics = new InMemoryMetricsAdapter();\nconst logger = new ConsoleLoggingAdapter();\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a helpful assistant.\",\n})\n  .use(createObservabilityPlugin({ tracer, metrics, logger }))\n  .build();\n\nawait agent.run(\"Hello\");\n// Tracer: spans for agent.run and each tool.* call\n// Metrics: agent.runs.total, agent.runs.success, agent.tools.total, agent.tool.duration.ms\n// Logger: structured logs with sessionId context at debug/info/error levels\n```\n\n**Observability Ports:**\n\n| Port | Methods |\n|------|---------|\n| `TracingPort` | `startSpan(name, parentSpan?): Span` |\n| `MetricsPort` | `incrementCounter(name, value?, labels?)`, `recordHistogram(name, value, labels?)`, `recordGauge(name, value, labels?)` |\n| `LoggingPort` | `log(level, message, context?)`, `debug()`, `info()`, `warn()`, `error()` |\n\n**Span interface:** `traceId`, `spanId`, `name`, `setAttribute()`, `setStatus()`, `end()`\n\n### BasePlugin\n\nAbstract base class for building plugins. Subclasses provide `name` and implement `buildHooks()`:\n\n```typescript\nimport { BasePlugin } from \"@giulio-leone/gaussflow-agent\";\nimport type { PluginHooks, PluginContext, BeforeRunParams, BeforeRunResult } from \"@giulio-leone/gaussflow-agent\";\n\nclass TimingPlugin extends BasePlugin {\n  readonly name = \"timing\";\n  private startTime = 0;\n\n  protected buildHooks(): PluginHooks {\n    return {\n      beforeRun: async (_ctx: PluginContext, _params: BeforeRunParams) =\u003e {\n        this.startTime = Date.now();\n      },\n      afterRun: async () =\u003e {\n        console.log(`Run took ${Date.now() - this.startTime}ms`);\n      },\n    };\n  }\n}\n\nconst agent = DeepAgent.create({ model, instructions: \"...\" })\n  .use(new TimingPlugin())\n  .build();\n```\n\n### AbstractBuilder\n\nTemplate method pattern for validated builders. Subclasses implement `validate()` and `construct()`:\n\n```typescript\nimport { AbstractBuilder } from \"@giulio-leone/gaussflow-agent\";\n\ninterface AppConfig {\n  name: string;\n  port: number;\n}\n\nclass AppConfigBuilder extends AbstractBuilder\u003cAppConfig\u003e {\n  private name = \"\";\n  private port = 3000;\n\n  withName(name: string): this { this.name = name; return this; }\n  withPort(port: number): this { this.port = port; return this; }\n\n  protected validate(): void {\n    if (!this.name) throw new Error(\"name is required\");\n    if (this.port \u003c 1 || this.port \u003e 65535) throw new Error(\"invalid port\");\n  }\n\n  protected construct(): AppConfig {\n    return { name: this.name, port: this.port };\n  }\n}\n\nconst config = new AppConfigBuilder()\n  .withName(\"my-app\")\n  .withPort(8080)\n  .build(); // Calls validate() then construct()\n```\n\nUsed internally by `DeepAgentBuilder` and `AgentGraphBuilder`.\n\n### ValidationPort\n\nEngine-agnostic validation contract. The framework ships with `ZodValidationAdapter` (default):\n\n```typescript\nimport { ZodValidationAdapter } from \"@giulio-leone/gaussflow-agent\";\nimport type { ValidationPort, ValidationResult } from \"@giulio-leone/gaussflow-agent\";\nimport { z } from \"zod\";\n\nconst validator: ValidationPort = new ZodValidationAdapter();\n\n// Safe validation\nconst result: ValidationResult\u003cstring\u003e = validator.validate(z.string().email(), \"user@example.com\");\nif (result.success) {\n  console.log(result.data); // \"user@example.com\"\n}\n\n// Throwing validation\nconst email = validator.validateOrThrow(z.string().email(), \"user@example.com\");\n```\n\n**Interface:**\n\n```typescript\ninterface ValidationPort {\n  validate\u003cT\u003e(schema: unknown, data: unknown): ValidationResult\u003cT\u003e;\n  validateOrThrow\u003cT\u003e(schema: unknown, data: unknown): T;\n}\n\ninterface ValidationResult\u003cT = unknown\u003e {\n  readonly success: boolean;\n  readonly data?: T;\n  readonly error?: string;\n}\n```\n\nTo use a different validation engine (Yup, Joi, etc.), implement `ValidationPort` and pass it to plugins via their options.\n\n### Tools\n\nTools are automatically registered based on builder configuration.\n\n#### Filesystem Tools\n\nAlways included. Created via `createFilesystemTools(fs)`.\n\n| Tool | Description |\n|------|-------------|\n| `ls` | List directory contents |\n| `read_file` | Read file content as string |\n| `write_file` | Write content to a file, creating directories as needed |\n| `edit_file` | Apply targeted string replacements to a file |\n| `glob` | Find files matching a glob pattern |\n| `grep` | Search file contents by regex pattern |\n\nIndividual tool factories are also exported: `createLsTool`, `createReadFileTool`, `createWriteFileTool`, `createEditFileTool`, `createGlobTool`, `createGrepTool`.\n\n#### Planning Tools\n\nEnabled via `.withPlanning()`. Created via `createPlanningTools(fs)`.\n\n| Tool | Description |\n|------|-------------|\n| `write_todos` | Create or update a structured list of todos |\n| `review_todos` | Review current todo status and dependencies |\n\nTodos are stored as JSON in the persistent filesystem zone. Each todo has an `id`, `title`, `description`, `status` (pending/in_progress/done/blocked), `dependencies`, and `priority` (low/medium/high/critical).\n\n#### Subagent Tool\n\nEnabled via `.withSubagents(config?)`. Created via `createSubagentTools(config)`.\n\n| Tool | Description |\n|------|-------------|\n| `task` | Spawn a child `ToolLoopAgent` with its own filesystem tools to handle a subtask |\n\nThe subagent receives a prompt and optional instructions, runs with its own step limit, and returns its findings to the parent agent.\n\n```typescript\ninterface TaskToolConfig {\n  parentModel: LanguageModel;\n  parentFilesystem: FilesystemPort;\n  maxDepth?: number;      // Default: 3\n  timeoutMs?: number;     // Default: 300000 (5 min)\n  currentDepth?: number;\n}\n```\n\n### Ports\n\nPort interfaces define the contracts for hexagonal architecture. Implement these to provide custom adapters.\n\n#### ModelPort\n\nLLM invocation abstraction.\n\n```typescript\ninterface ModelPort {\n  getModel(): LanguageModel;\n  getContextWindowSize(): number;\n  getModelId(): string;\n  generate(options: ModelGenerateOptions): Promise\u003cModelGenerateResult\u003e;\n  generateStream?(options: ModelGenerateOptions): Promise\u003cModelStreamResult\u003e;\n}\n```\n\n#### FilesystemPort\n\nFile operations with zone-based isolation (`transient` or `persistent`).\n\n```typescript\ninterface FilesystemPort {\n  read(path: string, zone?: FilesystemZone): Promise\u003cstring\u003e;\n  write(path: string, content: string, zone?: FilesystemZone): Promise\u003cvoid\u003e;\n  exists(path: string, zone?: FilesystemZone): Promise\u003cboolean\u003e;\n  delete(path: string, zone?: FilesystemZone): Promise\u003cvoid\u003e;\n  list(path: string, options?: ListOptions, zone?: FilesystemZone): Promise\u003cFileEntry[]\u003e;\n  search(pattern: string, options?: SearchOptions, zone?: FilesystemZone): Promise\u003cSearchResult[]\u003e;\n  glob(pattern: string, zone?: FilesystemZone): Promise\u003cstring[]\u003e;\n  stat(path: string, zone?: FilesystemZone): Promise\u003cFileStat\u003e;\n  syncToPersistent?(): Promise\u003cvoid\u003e;\n  clearTransient?(): Promise\u003cvoid\u003e;\n}\n```\n\n#### MemoryPort\n\nPersistent state storage for todos, checkpoints, conversations, and arbitrary metadata.\n\n```typescript\ninterface MemoryPort {\n  saveTodos(sessionId: string, todos: Todo[]): Promise\u003cvoid\u003e;\n  loadTodos(sessionId: string): Promise\u003cTodo[]\u003e;\n  saveCheckpoint(sessionId: string, checkpoint: Checkpoint): Promise\u003cvoid\u003e;\n  loadLatestCheckpoint(sessionId: string): Promise\u003cCheckpoint | null\u003e;\n  listCheckpoints(sessionId: string): Promise\u003cCheckpoint[]\u003e;\n  deleteOldCheckpoints(sessionId: string, keepCount: number): Promise\u003cvoid\u003e;\n  saveConversation(sessionId: string, messages: Message[]): Promise\u003cvoid\u003e;\n  loadConversation(sessionId: string): Promise\u003cMessage[]\u003e;\n  saveMetadata(sessionId: string, key: string, value: unknown): Promise\u003cvoid\u003e;\n  loadMetadata\u003cT\u003e(sessionId: string, key: string): Promise\u003cT | null\u003e;\n  deleteMetadata(sessionId: string, key: string): Promise\u003cvoid\u003e;\n}\n```\n\n#### RuntimePort\n\nPlatform-agnostic runtime abstraction. Auto-detected or explicitly set with `.withRuntime()`.\n\n```typescript\ninterface RuntimePort {\n  randomUUID(): string;\n  fetch(input: string | URL | Request, init?: RequestInit): Promise\u003cResponse\u003e;\n  getEnv(key: string): string | undefined;\n  setTimeout(callback: () =\u003e void, ms: number): { clear(): void };\n}\n```\n\n#### LearningPort\n\nCross-session learning with user profiles, memories, and shared knowledge.\n\n```typescript\ninterface LearningPort {\n  getProfile(userId: string): Promise\u003cUserProfile | null\u003e;\n  updateProfile(userId: string, updates: Partial\u003cOmit\u003cUserProfile, \"userId\" | \"createdAt\"\u003e\u003e): Promise\u003cUserProfile\u003e;\n  deleteProfile(userId: string): Promise\u003cvoid\u003e;\n  \n  addMemory(userId: string, memory: Omit\u003cUserMemoryInput, \"id\" | \"createdAt\"\u003e): Promise\u003cUserMemory\u003e;\n  getMemories(userId: string, options?: { tags?: string[]; limit?: number; since?: number }): Promise\u003cUserMemory[]\u003e;\n  deleteMemory(userId: string, memoryId: string): Promise\u003cvoid\u003e;\n  clearMemories(userId: string): Promise\u003cvoid\u003e;\n  \n  addKnowledge(knowledge: Omit\u003cSharedKnowledgeInput, \"id\" | \"createdAt\" | \"usageCount\"\u003e): Promise\u003cSharedKnowledge\u003e;\n  queryKnowledge(query: string, options?: { category?: string; limit?: number }): Promise\u003cSharedKnowledge[]\u003e;\n  incrementKnowledgeUsage(knowledgeId: string): Promise\u003cvoid\u003e;\n  deleteKnowledge(knowledgeId: string): Promise\u003cvoid\u003e;\n}\n```\n\n```typescript\nimport { DeepAgent, InMemoryLearningAdapter } from \"@giulio-leone/gaussflow-agent\";\n\nconst learning = new InMemoryLearningAdapter();\nawait learning.updateProfile(\"user-1\", { style: \"concise\", language: \"en\" });\nawait learning.addMemory(\"user-1\", { content: \"Prefers TypeScript\", tags: [\"preference\"] });\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a helpful assistant.\",\n})\n  .withLearning(learning, \"user-1\")\n  .build();\n// Learning context is automatically injected into run() and stream()\n```\n\n#### McpPort\n\nMCP server discovery and tool execution.\n\n```typescript\ninterface McpPort {\n  discoverTools(): Promise\u003cRecord\u003cstring, McpToolDefinition\u003e\u003e;\n  executeTool(name: string, args: unknown): Promise\u003cMcpToolResult\u003e;\n  listServers(): Promise\u003cMcpServerInfo[]\u003e;\n  connect(config: McpServerConfig): Promise\u003cvoid\u003e;\n  disconnect(serverId: string): Promise\u003cvoid\u003e;\n  closeAll(): Promise\u003cvoid\u003e;\n}\n```\n\nMCP tools are registered with a `mcp:` namespace prefix (e.g., `mcp:web_search`).\n\n#### TokenCounterPort\n\nToken counting, budgeting, and cost estimation.\n\n```typescript\ninterface TokenCounterPort {\n  count(text: string, model?: string): number;\n  countMessages(messages: Message[], model?: string): number;\n  getContextWindowSize(model: string): number;\n  estimateCost(inputTokens: number, outputTokens: number, model: string): number;\n  truncate(text: string, maxTokens: number, model?: string): string;\n}\n```\n\n#### ValidationPort\n\nEngine-agnostic validation contract. Used by `GuardrailsPlugin`, `OneCrawlPlugin`, and `VectorlessPlugin`.\n\n```typescript\ninterface ValidationPort {\n  validate\u003cT\u003e(schema: unknown, data: unknown): ValidationResult\u003cT\u003e;\n  validateOrThrow\u003cT\u003e(schema: unknown, data: unknown): T;\n}\n```\n\n#### TracingPort\n\nDistributed tracing contract for span-based instrumentation.\n\n```typescript\ninterface Span {\n  readonly traceId: string;\n  readonly spanId: string;\n  readonly name: string;\n  setAttribute(key: string, value: string | number | boolean): void;\n  setStatus(status: \"ok\" | \"error\", message?: string): void;\n  end(): void;\n}\n\ninterface TracingPort {\n  startSpan(name: string, parentSpan?: Span): Span;\n}\n```\n\n#### MetricsPort\n\nMetrics collection contract for counters, histograms, and gauges.\n\n```typescript\ninterface MetricsPort {\n  incrementCounter(name: string, value?: number, labels?: Record\u003cstring, string\u003e): void;\n  recordHistogram(name: string, value: number, labels?: Record\u003cstring, string\u003e): void;\n  recordGauge(name: string, value: number, labels?: Record\u003cstring, string\u003e): void;\n}\n```\n\n#### LoggingPort\n\nStructured logging contract with log levels.\n\n```typescript\ntype LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\ninterface LoggingPort {\n  log(level: LogLevel, message: string, context?: Record\u003cstring, unknown\u003e): void;\n  debug(message: string, context?: Record\u003cstring, unknown\u003e): void;\n  info(message: string, context?: Record\u003cstring, unknown\u003e): void;\n  warn(message: string, context?: Record\u003cstring, unknown\u003e): void;\n  error(message: string, context?: Record\u003cstring, unknown\u003e): void;\n}\n```\n\n#### ConsensusPort\n\nStrategy for evaluating fork results in `AgentGraph`.\n\n```typescript\ninterface ConsensusPort {\n  evaluate(results: Array\u003c{ id: string; output: string }\u003e): Promise\u003cConsensusResult\u003e;\n}\n\ninterface ConsensusResult {\n  winnerId: string;\n  winnerOutput: string;\n  scores?: Record\u003cstring, number\u003e;\n  merged?: string;\n  reasoning?: string;\n}\n```\n\n### Adapters\n\n#### Filesystem\n\n| Adapter | Description |\n|---------|-------------|\n| `VirtualFilesystem` | In-memory filesystem with optional disk persistence via `syncToPersistent()`. Supports transient and persistent zones. Default adapter. |\n| `LocalFilesystem` | Sandboxed wrapper over Node.js `fs`. Restricts operations to a configured base path. |\n\n#### Memory\n\n| Adapter | Description |\n|---------|-------------|\n| `InMemoryAdapter` | `Map`-based in-process storage. Suitable for testing and ephemeral sessions. Default adapter. |\n| `SupabaseMemoryAdapter` | Supabase-backed storage using `deep_agent_todos`, `deep_agent_checkpoints`, `deep_agent_conversations`, and `deep_agent_metadata` tables. |\n\n#### Learning\n\n| Adapter | Description |\n|---------|-------------|\n| `InMemoryLearningAdapter` | `Map`-based in-process learning storage. Suitable for testing and ephemeral sessions. |\n\n#### Runtime\n\n| Adapter | Description |\n|---------|-------------|\n| `NodeRuntimeAdapter` | Node.js runtime. Uses `process.env` for environment variables. |\n| `DenoRuntimeAdapter` | Deno runtime. Uses `Deno.env.get()` for environment variables. |\n| `BunRuntimeAdapter` | Bun runtime. Uses `process.env` (Node-compatible). |\n| `EdgeRuntimeAdapter` | Edge/Cloudflare Workers. Env vars bound via request context. |\n\n#### Token Counter\n\n| Adapter | Description |\n|---------|-------------|\n| `ApproximateTokenCounter` | Fast estimation using ~4 characters per token. Includes context window sizes for common models. Default adapter. |\n| `TiktokenTokenCounter` | BPE-accurate counting via the `tiktoken` library. Falls back to `ApproximateTokenCounter` when tiktoken is unavailable. |\n\n#### MCP\n\n| Adapter | Description |\n|---------|-------------|\n| `AiSdkMcpAdapter` | Bridges `@ai-sdk/mcp` clients to the `McpPort` interface. Supports stdio, HTTP, and SSE transports. |\n| `OnegenUiMcpAdapter` | Bridges `@giulio-leone/gaussflow-mcp` `McpRegistry` to the `McpPort` interface. |\n\n#### Validation\n\n| Adapter | Description |\n|---------|-------------|\n| `ZodValidationAdapter` | Zod-based implementation of `ValidationPort`. Default validation engine. |\n\n#### Tracing\n\n| Adapter | Description |\n|---------|-------------|\n| `InMemoryTracingAdapter` | In-memory span storage. Useful for testing and development. |\n\n#### Metrics\n\n| Adapter | Description |\n|---------|-------------|\n| `InMemoryMetricsAdapter` | In-memory counters, histograms, and gauges. Useful for testing. |\n\n#### Logging\n\n| Adapter | Description |\n|---------|-------------|\n| `ConsoleLoggingAdapter` | Structured logging via `console.log/warn/error`. |\n\n#### Consensus\n\n| Adapter | Description |\n|---------|-------------|\n| `LlmJudgeConsensus` | LLM-based evaluation of fork results. Uses a model to pick the best output. |\n| `MajorityVoteConsensus` | Simple majority vote across fork outputs. |\n| `DebateConsensus` | Multi-round debate between fork outputs for consensus. |\n\n### Events\n\nSubscribe to lifecycle events via the builder's `.on()` method or directly on `agent.eventBus`.\n\n```typescript\nconst agent = DeepAgent.create(config)\n  .withPlanning()\n  .on(\"tool:call\", (event) =\u003e {\n    console.log(`Tool called: ${event.data.toolName}`);\n  })\n  .on(\"*\", (event) =\u003e {\n    // Wildcard: receives all events\n  })\n  .build();\n```\n\nEvery event has the shape:\n\n```typescript\ninterface AgentEvent\u003cT = unknown\u003e {\n  type: AgentEventType;\n  timestamp: number;\n  sessionId: string;\n  data: T;\n}\n```\n\n#### Event Types\n\n| Event | Description |\n|-------|-------------|\n| `agent:start` | Agent run begins |\n| `agent:stop` | Agent run completes |\n| `step:start` | A step in the tool loop begins |\n| `step:end` | A step in the tool loop ends |\n| `tool:call` | A tool is invoked |\n| `tool:result` | A tool returns a result |\n| `tool:approval-required` | A tool call requires human approval |\n| `tool:approved` | A tool call was approved |\n| `tool:denied` | A tool call was denied |\n| `checkpoint:save` | A checkpoint was persisted |\n| `checkpoint:load` | A checkpoint was restored |\n| `context:summarize` | Conversation was summarized to reduce tokens |\n| `context:offload` | A large tool result was offloaded to the VFS |\n| `context:truncate` | Messages were truncated to fit the context window |\n| `subagent:spawn` | A subagent was spawned via the `task` tool |\n| `subagent:complete` | A subagent finished execution |\n| `planning:update` | The todo list was updated |\n| `error` | An error occurred during execution |\n\n### Context Management\n\nThe framework automatically manages the LLM context window through three mechanisms:\n\n#### Tool-Result Offloading\n\nWhen a tool result exceeds `offloadTokenThreshold` (default: 20,000 tokens), the `ContextManager` writes it to the transient VFS zone and replaces the inline result with a file reference. The agent can read the full content via `read_file` when needed.\n\n#### Rolling Summarization\n\nWhen conversation messages exceed `summarizationThreshold` (default: 70% of context window), the `RollingSummarizer` compresses older messages into a summary using a dedicated LLM call. Recent messages (configurable via `preserveRecentMessages`, default: 10) are always preserved.\n\n#### Message Truncation\n\nWhen messages exceed `truncationThreshold` (default: 85% of context window), the `ContextManager` drops the oldest non-system messages to fit within budget. System messages are always preserved.\n\n#### Token Tracking\n\nThe `TokenTracker` accumulates input and output token usage across the session, providing budget awareness and cost estimation.\n\n## Examples\n\n- `examples/01-basic-agent.ts` — minimal planning agent\n- `examples/02-planning-agent.ts` — structured todo workflow\n- `examples/03-subagent-orchestration.ts` — parent/child delegation\n- `examples/04-mcp-integration.ts` — MCP tool federation\n- `examples/05-persistent-memory.ts` — persistent session state\n- `examples/06-full-featured.ts` — full stack composition\n- `examples/07-plugin-system.ts` — custom plugin + AgentCardPlugin\n- `examples/08-a2a-server.ts` — expose DeepAgent as A2A JSON-RPC server\n- `examples/09-cli-and-rest.ts` — REST API server\n\n### Basic Planning Agent\n\n```typescript\nimport { DeepAgent } from \"@giulio-leone/gaussflow-agent\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst agent = DeepAgent.minimal({\n  model: openai(\"gpt-4o\"),\n  instructions: `You are a project planner. Break tasks into todos,\n    then work through them systematically.`,\n  maxSteps: 50,\n});\n\nconst result = await agent.run(\n  \"Set up a REST API with user authentication endpoints.\"\n);\n```\n\n### Agent with MCP Tools\n\n```typescript\nimport { DeepAgent, AiSdkMcpAdapter } from \"@giulio-leone/gaussflow-agent\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst mcp = new AiSdkMcpAdapter({\n  servers: [\n    {\n      id: \"web-search\",\n      name: \"Web Search\",\n      transport: \"stdio\",\n      command: \"npx\",\n      args: [\"-y\", \"@anthropic/web-search-mcp\"],\n    },\n  ],\n});\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You can search the web to answer questions.\",\n})\n  .withMcp(mcp)\n  .withPlanning()\n  .build();\n\nconst result = await agent.run(\"Research the latest Node.js release.\");\nawait agent.dispose();\n```\n\n### Full-Featured Agent with Persistence\n\n```typescript\nimport {\n  DeepAgent,\n  SupabaseMemoryAdapter,\n  LocalFilesystem,\n  TiktokenTokenCounter,\n} from \"@giulio-leone/gaussflow-agent\";\nimport { openai } from \"@ai-sdk/openai\";\nimport { createClient } from \"@supabase/supabase-js\";\n\nconst supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_KEY!);\n\nconst agent = DeepAgent.create({\n  model: openai(\"gpt-4o\"),\n  instructions: \"You are a senior engineer working on a codebase.\",\n  maxSteps: 100,\n  context: {\n    summarizationThreshold: 0.65,\n    offloadTokenThreshold: 15_000,\n  },\n  checkpoint: {\n    enabled: true,\n    baseStepInterval: 10,\n    maxCheckpoints: 5,\n  },\n})\n  .withFilesystem(new LocalFilesystem(\"/path/to/project\"))\n  .withMemory(new SupabaseMemoryAdapter(supabase))\n  .withTokenCounter(new TiktokenTokenCounter())\n  .withPlanning()\n  .withSubagents({ maxDepth: 2, timeoutMs: 120_000 })\n  .withApproval({\n    defaultMode: \"approve-all\",\n    requireApproval: [\"write_file\", \"edit_file\"],\n    onApprovalRequired: async (request) =\u003e {\n      console.log(`Approve ${request.toolName}?`, request.args);\n      return true; // Replace with actual UI prompt\n    },\n  })\n  .on(\"agent:start\", (e) =\u003e console.log(\"Agent started\"))\n  .on(\"error\", (e) =\u003e console.error(\"Error:\", e.data))\n  .build();\n\nconst result = await agent.run(\"Refactor the auth module to use JWT.\");\nawait agent.dispose();\n```\n\n## Configuration\n\n### DeepAgentConfig\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `id` | `string` | `crypto.randomUUID()` | Agent/session identifier |\n| `name` | `string` | -- | Display name |\n| `instructions` | `string` | **(required)** | System prompt |\n| `model` | `LanguageModel` | **(required)** | AI SDK model instance |\n| `maxSteps` | `number` | `30` | Maximum tool-loop iterations |\n| `context` | `ContextConfig` | See below | Context window management |\n| `approval` | `ApprovalConfig` | See below | Human-in-the-loop settings |\n| `subagent` | `SubagentConfig` | See below | Subagent orchestration settings |\n| `checkpoint` | `CheckpointConfig` | See below | Checkpoint/resume settings |\n\n### ContextConfig\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `summarizationThreshold` | `number` | `0.70` | Context ratio to trigger summarization |\n| `truncationThreshold` | `number` | `0.85` | Context ratio to trigger truncation |\n| `offloadTokenThreshold` | `number` | `20000` | Token count to trigger VFS offload |\n| `summarizationModel` | `LanguageModel \\| null` | `null` (uses agent model) | Model for summarization calls |\n| `preserveRecentMessages` | `number` | `10` | Messages to keep during summarization |\n\n### ApprovalConfig\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `defaultMode` | `\"approve-all\" \\| \"deny-all\"` | `\"approve-all\"` | Default approval policy |\n| `requireApproval` | `string[]` | `[]` | Tools requiring approval (deny-list) |\n| `autoApprove` | `string[]` | `[]` | Auto-approved tools (allow-list) |\n| `onApprovalRequired` | `(req) =\u003e Promise\u003cboolean\u003e` | `async () =\u003e true` | Approval callback |\n\n### SubagentConfig\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `maxDepth` | `number` | `3` | Maximum nesting depth |\n| `timeoutMs` | `number` | `300000` | Execution timeout (ms) |\n| `allowNesting` | `boolean` | `true` | Whether subagents can spawn subagents |\n\n### CheckpointConfig\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `enabled` | `boolean` | `true` | Enable checkpointing |\n| `baseStepInterval` | `number` | `5` | Steps between checkpoints |\n| `maxCheckpoints` | `number` | `10` | Maximum retained checkpoints |\n\n## Multi-Runtime Support\n\nThe framework runs on **Node.js**, **Deno**, **Bun**, **Edge** (Cloudflare Workers, Vercel Edge), and **Browser** runtimes. The core API (`DeepAgent`, `VirtualFilesystem`, `InMemoryAdapter`) is runtime-agnostic; platform-specific adapters live in dedicated sub-path exports.\n\n### RuntimePort\n\nPlatform-specific APIs are abstracted behind a `RuntimePort` interface. The framework auto-detects your runtime and selects the appropriate adapter:\n\n```ts\nimport { DeepAgent } from \"@giulio-leone/gaussflow-agent\";\n\n// Auto-detect runtime (Node, Deno, Bun, or Edge)\nconst agent = DeepAgent.create({ model, instructions: \"...\" }).build();\n\n// Or specify explicitly\nimport { DenoRuntimeAdapter } from \"@giulio-leone/gaussflow-agent\";\nconst agent = DeepAgent.create({ model, instructions: \"...\" })\n  .withRuntime(new DenoRuntimeAdapter())\n  .build();\n```\n\n| Adapter | Runtime | `getEnv()` |\n|---------|---------|------------|\n| `NodeRuntimeAdapter` | Node.js | `process.env` |\n| `DenoRuntimeAdapter` | Deno | `Deno.env.get()` |\n| `BunRuntimeAdapter` | Bun | `process.env` |\n| `EdgeRuntimeAdapter` | Edge/CF Workers | Returns `undefined` (env bound via request context) |\n\n### Installation per Runtime\n\n```ts\n// Node.js / Bun — core + Node-specific adapters\nimport { DeepAgent } from '@giulio-leone/gaussflow-agent';\nimport { LocalFilesystem, TiktokenTokenCounter } from '@giulio-leone/gaussflow-agent/node';\n\n// Deno — Deno.Kv memory, Deno filesystem\nimport { DenoFilesystem, DenoKvMemoryAdapter } from '@giulio-leone/gaussflow-agent/deno';\n\n// Edge / Cloudflare Workers — OPFS filesystem, IndexedDB memory\nimport { OpfsFilesystem, IndexedDbMemoryAdapter } from '@giulio-leone/gaussflow-agent/edge';\n\n// Browser — same adapters as Edge (OPFS + IndexedDB)\nimport { OpfsFilesystem, IndexedDbMemoryAdapter } from '@giulio-leone/gaussflow-agent/browser';\n```\n\n### Auto-Configuration\n\n`DeepAgent.auto()` creates an agent using universal adapters (`VirtualFilesystem`, `InMemoryAdapter`, `ApproximateTokenCounter`) that work in any runtime — no platform-specific imports required.\n\n```ts\nimport { DeepAgent } from '@giulio-leone/gaussflow-agent';\nimport { openai } from '@ai-sdk/openai';\n\nconst agent = DeepAgent.auto({\n  model: openai('gpt-4o'),\n  instructions: 'You are a helpful assistant.',\n});\n\nconst result = await agent.run('Summarize the project.');\n```\n\nFor runtime-specific adapters (e.g. `LocalFilesystem`, `DenoKvMemoryAdapter`), use `DeepAgent.create()` and compose manually.\n\n### MCP Server Mode\n\nExpose agent tools as an MCP-compatible HTTP server for cross-language consumption:\n\n```ts\nimport { DeepAgent } from '@giulio-leone/gaussflow-agent';\nimport { McpServer, createStreamableHttpHandler } from '@giulio-leone/gaussflow-agent/server';\nimport { openai } from '@ai-sdk/openai';\n\nconst agent = DeepAgent.minimal({\n  model: openai('gpt-4o'),\n  instructions: 'You are a coding assistant.',\n});\n\nconst server = new McpServer({\n  name: 'my-agent',\n  version: '1.0.0',\n  tools: agent.tools,\n});\n\nconst handler = createStreamableHttpHandler({ server });\n\n// Node.js / Bun — serve with any HTTP framework\nconst httpServer = Bun.serve({ port: 3000, fetch: handler });\n// Or with Node.js:\n// import { createServer } from 'node:http';\n// createServer(async (req, res) =\u003e { ... }).listen(3000);\n```\n\n### Cross-Language Consumption\n\nAny language that speaks HTTP + JSON-RPC can consume agent tools via the MCP Streamable HTTP transport. Initialize a session, list available tools, call them, and close the session — all with standard HTTP requests.\n\nSee [`examples/python-mcp-client/`](./examples/python-mcp-client/) for a working Python client.\n\n## Multi-Agent Collaboration\n\nOrchestrate multiple agents using a declarative graph API with DAG execution, parallel forking, and consensus:\n\n```ts\nimport { AgentGraph, LlmJudgeConsensus } from '@giulio-leone/gaussflow-agent';\nimport { openai } from '@ai-sdk/openai';\n\nconst model = openai('gpt-4o');\n\nconst graph = AgentGraph.create({ maxConcurrency: 3 })\n  .node('research', { model, instructions: 'Research the topic thoroughly.' })\n  .node('code', { model, instructions: 'Write clean, tested code.' })\n  .node('test', { model, instructions: 'Write comprehensive tests.' })\n  .edge('research', 'code')\n  .edge('code', 'test')\n  .fork('review', [\n    { model, instructions: 'Review for correctness and bugs.' },\n    { model, instructions: 'Review for performance and style.' },\n    { model, instructions: 'Review for security vulnerabilities.' },\n  ])\n  .consensus('review', new LlmJudgeConsensus({ model }))\n  .edge('test', 'review')\n  .build();\n\nconst result = await graph.run('Build a REST API with JWT auth.');\nconsole.log(result.output);\nconsole.log(result.nodeResults); // Per-node results\n```\n\n## Real-Time Event Streaming\n\nStream agent events via SSE for real-time monitoring:\n\n```ts\nimport { DeepAgent, createSseHandler } from '@giulio-leone/gaussflow-agent';\nimport { openai } from '@ai-sdk/openai';\n\nconst agent = DeepAgent.minimal({ model: openai('gpt-4o'), instructions: '...' });\nconst handler = createSseHandler({ eventBus: agent.eventBus });\n\n// Serve with any runtime (Node.js, Deno, Bun, Cloudflare Workers)\nBun.serve({ port: 3001, fetch: handler });\n```\n\nClient-side with native EventSource:\n\n```js\nconst source = new EventSource('http://localhost:3001?filter=tool:call,step:end');\nsource.addEventListener('tool:call', (e) =\u003e console.log(JSON.parse(e.data)));\n```\n\n## CLI\n\n```bash\n# Interactive REPL\ngaussflow chat --provider openai --api-key sk-...\n\n# Single-shot\ngaussflow run \"What is AI?\" --provider anthropic\n\n# Config management\ngaussflow config set openai sk-...\ngaussflow config list\n\n# Feature demos\ngaussflow demo guardrails --provider openai\ngaussflow demo workflow --provider openai\ngaussflow demo graph --provider openai\n```\n\n## REST API\n\n```typescript\nimport { OneAgentServer } from \"@giulio-leone/gaussflow-agent\";\n\nconst server = new OneAgentServer({ port: 3456, cors: true });\nawait server.listen();\n```\n\n```bash\n# Health check\ncurl http://localhost:3456/api/health\n\n# Run prompt\ncurl -X POST http://localhost:3456/api/run \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\":\"Hello!\",\"provider\":\"openai\",\"apiKey\":\"sk-...\"}'\n\n# Stream response (SSE)\ncurl -X POST http://localhost:3456/api/stream \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\":\"Tell me a story\",\"provider\":\"openai\",\"apiKey\":\"sk-...\"}'\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiulio-leone%2Fonegenui-deep-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiulio-leone%2Fonegenui-deep-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiulio-leone%2Fonegenui-deep-agents/lists"}