ashlr-plugin 1.36.4

package/bench/fixtures/tasklist-closed.json

@@ -0,0 +1,62 @@
+[
+  {
+    "id": "TASK-001",
+    "status": "closed",
+    "subject": "v1.21 release: Windows cross-platform hardening",
+    "owner": "alice",
+    "description": "Fixed ~30 Windows-specific test flakes. Key fixes: path separator normalization in cwd-clamp, tmpdir handling in stats-sqlite, skip markers for file-based SQLite tests on Windows. All CI checks green.",
+    "createdAt": "2026-04-20T09:00:00Z",
+    "updatedAt": "2026-04-25T08:00:00Z",
+    "closedAt": "2026-04-25T08:00:00Z",
+    "priority": "high",
+    "labels": ["v1.21", "windows", "ci"]
+  },
+  {
+    "id": "TASK-002",
+    "status": "closed",
+    "subject": "Add per-session token accounting to all MCP tools",
+    "owner": "bob",
+    "description": "Migrated from global stats to session-keyed accounting using CLAUDE_SESSION_ID. Fixes concurrent terminal clobbering. See _stats.ts refactor.",
+    "createdAt": "2026-04-18T10:00:00Z",
+    "updatedAt": "2026-04-22T16:00:00Z",
+    "closedAt": "2026-04-22T16:00:00Z",
+    "priority": "high",
+    "labels": ["v1.18", "accounting"]
+  },
+  {
+    "id": "TASK-003",
+    "status": "closed",
+    "subject": "Implement redirect-by-default for Read/Grep/Edit hooks",
+    "owner": "alice",
+    "description": "Changed default ASHLR_HOOK_MODE from 'nudge' to 'redirect'. Added isInsideCwd safety net so out-of-scope paths fall back to nudge. Added ASHLR_HOOK_MODE env override.",
+    "createdAt": "2026-04-17T09:00:00Z",
+    "updatedAt": "2026-04-23T12:00:00Z",
+    "closedAt": "2026-04-23T12:00:00Z",
+    "priority": "medium",
+    "labels": ["v1.18", "hooks"]
+  },
+  {
+    "id": "TASK-004",
+    "status": "closed",
+    "subject": "Deploy genome auto-consolidate + LLM synthesis",
+    "owner": "charlie",
+    "description": "Genome now auto-consolidates proposals into knowledge/ on session end. LLM synthesis uses local Ollama or cloud override. Cache TTL 1h. Falls back to snipCompact on LLM failure.",
+    "createdAt": "2026-04-15T11:00:00Z",
+    "updatedAt": "2026-04-22T18:00:00Z",
+    "closedAt": "2026-04-22T18:00:00Z",
+    "priority": "high",
+    "labels": ["v1.14", "genome"]
+  },
+  {
+    "id": "TASK-005",
+    "status": "closed",
+    "subject": "Fix status-line animation: session delta not lifetime",
+    "owner": "bob",
+    "description": "Status line was showing lifetime savings instead of session delta. Root cause: savings-status-line.ts was reading from the wrong stats key. Fixed by switching to session-scoped read.",
+    "createdAt": "2026-04-21T14:00:00Z",
+    "updatedAt": "2026-04-25T07:00:00Z",
+    "closedAt": "2026-04-25T07:00:00Z",
+    "priority": "medium",
+    "labels": ["v1.20.2", "status-line", "bugfix"]
+  }
+]

package/bench/fixtures/tasklist-large-mixed.json

@@ -0,0 +1,27 @@
+[
+  { "id": "TASK-201", "status": "open",        "subject": "Migrate genome crypto to v2 key format",             "owner": "alice",   "createdAt": "2026-04-01T09:00:00Z", "priority": "high" },
+  { "id": "TASK-202", "status": "open",        "subject": "Add ashlr__glob streaming for large dirs",          "owner": "alice",   "createdAt": "2026-04-02T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-203", "status": "in-progress", "subject": "Implement cloud genome pull on session start",       "owner": "bob",     "createdAt": "2026-04-03T09:00:00Z", "priority": "high" },
+  { "id": "TASK-204", "status": "open",        "subject": "Add ashlr__sql query plan explain support",         "owner": "bob",     "createdAt": "2026-04-04T09:00:00Z", "priority": "low" },
+  { "id": "TASK-205", "status": "closed",      "subject": "Fix embed-populator crash on empty genome",         "owner": "charlie", "createdAt": "2026-04-05T09:00:00Z", "priority": "high" },
+  { "id": "TASK-206", "status": "open",        "subject": "Track A: decompose efficiency-server into 5 tools", "owner": "charlie", "createdAt": "2026-04-06T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-207", "status": "in-progress", "subject": "Track B: WebSearch + Task hook coverage",           "owner": "diana",   "createdAt": "2026-04-07T09:00:00Z", "priority": "high" },
+  { "id": "TASK-208", "status": "open",        "subject": "Track C: edit-structural AST rename server",        "owner": "diana",   "createdAt": "2026-04-08T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-209", "status": "open",        "subject": "Track D: LLM provider abstraction in _summarize",  "owner": "alice",   "createdAt": "2026-04-09T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-210", "status": "open",        "subject": "Track E: namespace + WHEN copy for redirects",      "owner": "bob",     "createdAt": "2026-04-10T09:00:00Z", "priority": "low" },
+  { "id": "TASK-211", "status": "open",        "subject": "Track F: GitHub OAuth refresh token flow",          "owner": "charlie", "createdAt": "2026-04-11T09:00:00Z", "priority": "high" },
+  { "id": "TASK-212", "status": "open",        "subject": "Track G: dashboard per-tool bar chart",             "owner": "diana",   "createdAt": "2026-04-12T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-213", "status": "in-progress", "subject": "Track H: v1.22 benchmark suite",                   "owner": "alice",   "createdAt": "2026-04-13T09:00:00Z", "priority": "high" },
+  { "id": "TASK-214", "status": "open",        "subject": "Add Ollama auto-detection for local LLM",           "owner": "bob",     "createdAt": "2026-04-14T09:00:00Z", "priority": "low" },
+  { "id": "TASK-215", "status": "closed",      "subject": "Retire tool-redirect.ts (absorbed into pretooluse hooks)", "owner": "charlie", "createdAt": "2026-04-15T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-216", "status": "open",        "subject": "Add ashlr__orient graph export format",             "owner": "diana",   "createdAt": "2026-04-16T09:00:00Z", "priority": "low" },
+  { "id": "TASK-217", "status": "open",        "subject": "Improve savings-math accuracy for cache hits",      "owner": "alice",   "createdAt": "2026-04-17T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-218", "status": "open",        "subject": "Add ashlr__bash --timeout flag",                    "owner": "bob",     "createdAt": "2026-04-18T09:00:00Z", "priority": "low" },
+  { "id": "TASK-219", "status": "closed",      "subject": "Fix hook-timings p95 calculation off-by-one",       "owner": "charlie", "createdAt": "2026-04-19T09:00:00Z", "priority": "low" },
+  { "id": "TASK-220", "status": "open",        "subject": "Add ashlr__tree depth filter",                      "owner": "diana",   "createdAt": "2026-04-20T09:00:00Z", "priority": "low" },
+  { "id": "TASK-221", "status": "open",        "subject": "Improve genome proposal deduplication",             "owner": "alice",   "createdAt": "2026-04-21T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-222", "status": "open",        "subject": "Add session-end cost breakdown report",             "owner": "bob",     "createdAt": "2026-04-22T09:00:00Z", "priority": "low" },
+  { "id": "TASK-223", "status": "in-progress", "subject": "ashlr Pro trial flow — upgrade wizard",            "owner": "charlie", "createdAt": "2026-04-23T09:00:00Z", "priority": "high" },
+  { "id": "TASK-224", "status": "open",        "subject": "Add ashlr__http response caching",                  "owner": "diana",   "createdAt": "2026-04-24T09:00:00Z", "priority": "medium" },
+  { "id": "TASK-225", "status": "open",        "subject": "Publish ashlr-plugin v1.22 to npm",                 "owner": "alice",   "createdAt": "2026-04-25T09:00:00Z", "priority": "high" }
+]

package/bench/fixtures/tasklist-sprint-open.json

@@ -0,0 +1,79 @@
+[
+  {
+    "id": "TASK-101",
+    "status": "open",
+    "subject": "Implement ashlr__websearch dedup pipeline",
+    "owner": "alice",
+    "description": "Build the domain deduplication and snippet truncation pipeline for ashlr__websearch. Should integrate with summarizeIfLarge for result sets > 3 entries. See Track B spec in ultrathink-deploy-agents plan.",
+    "createdAt": "2026-04-24T10:00:00Z",
+    "updatedAt": "2026-04-24T14:30:00Z",
+    "priority": "high",
+    "labels": ["track-b", "token-efficiency"]
+  },
+  {
+    "id": "TASK-102",
+    "status": "open",
+    "subject": "Add PreToolUse hook for WebSearch redirect",
+    "owner": "alice",
+    "description": "Create pretooluse-websearch.ts following the pretooluse-grep.ts pattern. Should block in redirect mode and nudge in nudge mode. Include hook-timings telemetry.",
+    "createdAt": "2026-04-24T10:05:00Z",
+    "updatedAt": "2026-04-24T15:00:00Z",
+    "priority": "high",
+    "labels": ["track-b", "hooks"]
+  },
+  {
+    "id": "TASK-103",
+    "status": "open",
+    "subject": "Write unit tests for websearch and task tools",
+    "owner": "bob",
+    "description": "Test files: __tests__/websearch.test.ts and __tests__/task-tools.test.ts. Mock recordSavingAccurate and summarizeIfLarge. Cover: dedup, truncation, summarize gate, savings call shape.",
+    "createdAt": "2026-04-24T10:10:00Z",
+    "updatedAt": "2026-04-25T09:00:00Z",
+    "priority": "medium",
+    "labels": ["track-b", "testing"]
+  },
+  {
+    "id": "TASK-104",
+    "status": "open",
+    "subject": "Register new tools in _router-handlers.ts and hooks.json",
+    "owner": "bob",
+    "description": "Add import statements for websearch-server-handlers and task-server-handlers to _router-handlers.ts. Add WebSearch, TaskList, TaskGet matchers to hooks/hooks.json. Verify no circular imports.",
+    "createdAt": "2026-04-24T10:15:00Z",
+    "updatedAt": "2026-04-24T16:00:00Z",
+    "priority": "medium",
+    "labels": ["track-b", "wiring"]
+  },
+  {
+    "id": "TASK-105",
+    "status": "open",
+    "subject": "Create bench fixtures for Track H",
+    "owner": "charlie",
+    "description": "Add bench/fixtures/websearch-*.json and bench/fixtures/tasklist-*.json with realistic shapes for benchmark runs. 3-5 files each. Synthetic data is fine.",
+    "createdAt": "2026-04-24T10:20:00Z",
+    "updatedAt": "2026-04-24T11:00:00Z",
+    "priority": "low",
+    "labels": ["track-b", "bench"]
+  },
+  {
+    "id": "TASK-106",
+    "status": "open",
+    "subject": "Update commands/ashlr-help.md with new tools",
+    "owner": "charlie",
+    "description": "Add ashlr__websearch and ashlr__task_list / ashlr__task_get to the help command listing.",
+    "createdAt": "2026-04-24T10:25:00Z",
+    "updatedAt": "2026-04-24T10:25:00Z",
+    "priority": "low",
+    "labels": ["track-b", "docs"]
+  },
+  {
+    "id": "TASK-107",
+    "status": "in-progress",
+    "subject": "Track H: benchmark all new v1.22 tools",
+    "owner": "diana",
+    "description": "Run bench suite against websearch + task fixtures. Report token savings vs baseline. Target: > 40% reduction for websearch, > 50% for task list with 50+ items.",
+    "createdAt": "2026-04-25T08:00:00Z",
+    "updatedAt": "2026-04-25T09:30:00Z",
+    "priority": "high",
+    "labels": ["track-h", "bench"]
+  }
+]

package/bench/fixtures/websearch-bun-runtime.json

@@ -0,0 +1,32 @@
+[
+  {
+    "title": "Bun — A fast all-in-one JavaScript runtime",
+    "url": "https://bun.sh/",
+    "snippet": "Bun is a fast JavaScript all-in-one toolkit. It is a runtime, bundler, test runner, and package manager. Bun is designed to be a drop-in Node.js replacement with native TypeScript support, built-in SQLite, a fast HTTP server, and the Bun Shell for cross-platform scripting. Benchmarks show Bun is 3-4x faster than Node.js for HTTP throughput and 30x faster for cold starts.",
+    "score": 0.99
+  },
+  {
+    "title": "Bun Documentation — Installation",
+    "url": "https://bun.sh/docs/installation",
+    "snippet": "Install Bun via curl: curl -fsSL https://bun.sh/install | bash. Or via npm: npm install -g bun. Or via Homebrew: brew install oven-sh/bun/bun. Bun requires macOS 12+, Linux (kernel 5.6+), or Windows 10+. After installation, verify with: bun --version. Bun auto-detects package.json and tsconfig.json.",
+    "score": 0.95
+  },
+  {
+    "title": "Bun Blog — Bun v1.2 Release Notes",
+    "url": "https://bun.sh/blog/bun-v1.2",
+    "snippet": "Bun v1.2 adds: S3 object storage built-in, PostgreSQL client built-in, improved Node.js compatibility for crypto, streams, and child_process. The bun test runner now supports --coverage with LCOV output. The bundler supports CSS, SVG, and HTML entry points. Memory usage reduced 40% for long-running server workloads.",
+    "score": 0.91
+  },
+  {
+    "title": "GitHub — oven-sh/bun",
+    "url": "https://github.com/oven-sh/bun",
+    "snippet": "Bun is implemented in Zig and uses JavaScriptCore (WebKit's JS engine) instead of V8. The repository contains the runtime, bundler, package manager, and standard library. Currently at 74k GitHub stars. Contributions welcome — see CONTRIBUTING.md for build instructions. Issues labeled 'good first issue' are ideal for new contributors.",
+    "score": 0.88
+  },
+  {
+    "title": "Bun vs Node.js vs Deno — 2025 Comparison",
+    "url": "https://blog.logrocket.com/bun-vs-node-vs-deno-2025/",
+    "snippet": "Comprehensive comparison of JavaScript runtimes in 2025. Bun wins on: raw HTTP throughput (Bun: 400k req/s, Node: 95k, Deno: 130k), cold-start time (Bun: 5ms, Node: 150ms), and built-in SQLite. Node.js wins on: ecosystem maturity, third-party module compatibility, and enterprise adoption. Deno wins on: TypeScript-first DX and security sandbox.",
+    "score": 0.82
+  }
+]

package/bench/fixtures/websearch-react-hooks-patterns.json

@@ -0,0 +1,32 @@
+[
+  {
+    "title": "React Docs — Hooks Reference",
+    "url": "https://react.dev/reference/react/hooks",
+    "snippet": "Hooks let you use different React features from your components. Built-in hooks include: useState for local state, useEffect for side effects, useContext for consuming context, useReducer for complex state logic, useCallback and useMemo for performance optimization, useRef for DOM refs and mutable values, and useId for unique IDs. Custom hooks let you extract stateful logic into reusable functions.",
+    "score": 0.98
+  },
+  {
+    "title": "Patterns.dev — React Hooks Patterns",
+    "url": "https://www.patterns.dev/react/hooks-pattern/",
+    "snippet": "The Hooks pattern allows you to add state and lifecycle methods to functional components without using class components. This guide covers: the Container/Presentational pattern replaced by hooks, custom hooks for data fetching, the useLocalStorage hook, and composing hooks for complex features. Hooks make it easy to extract and share stateful logic between components.",
+    "score": 0.93
+  },
+  {
+    "title": "kentcdodds.com — The State Reducer Pattern with React Hooks",
+    "url": "https://kentcdodds.com/blog/the-state-reducer-pattern-with-react-hooks",
+    "snippet": "The state reducer pattern is an advanced React hooks pattern for inversion of control. It allows users of your component to customize how state changes happen. Implementation uses useReducer with an overrideable reducer function. The pattern is useful for component libraries where consumers need fine-grained control over state transitions.",
+    "score": 0.87
+  },
+  {
+    "title": "Smashing Magazine — Advanced React Hooks",
+    "url": "https://www.smashingmagazine.com/2021/11/advanced-react-hooks-redux/",
+    "snippet": "Advanced hooks patterns covered: useImperativeHandle for exposing imperative APIs, useLayoutEffect vs useEffect timing differences, useDeferredValue for concurrent mode, useTransition for non-urgent updates, and useSyncExternalStore for third-party state integration. Each pattern includes real-world use cases and performance benchmarks.",
+    "score": 0.81
+  },
+  {
+    "title": "GitHub — awesome-react-hooks",
+    "url": "https://github.com/rehooks/awesome-react-hooks",
+    "snippet": "A curated list of React Hooks resources and libraries. Includes: data fetching hooks (SWR, React Query), form hooks (React Hook Form, Formik), animation hooks (Framer Motion), routing hooks (React Router v6), and state management hooks (Zustand, Jotai). Over 6,000 stars.",
+    "score": 0.76
+  }
+]

package/bench/fixtures/websearch-typescript-generics.json

@@ -0,0 +1,38 @@
+[
+  {
+    "title": "TypeScript Handbook — Generics",
+    "url": "https://www.typescriptlang.org/docs/handbook/2/generics.html",
+    "snippet": "Generics allow you to create reusable components that can work with a variety of types rather than a single one. Using type variables, a special kind of variable that works on types rather than values, you can define functions, classes, and interfaces that are type-safe without committing to a specific type. For example: function identity<T>(arg: T): T { return arg; } This is the identity function. We've now added a type variable T that captures the type the user provides so we can use that information later.",
+    "score": 0.97
+  },
+  {
+    "title": "TypeScript Handbook — Generics (mirror)",
+    "url": "https://www.typescriptlang.org/docs/handbook/generics.html",
+    "snippet": "Duplicate domain entry — should be deduped. Generic classes have a similar shape to generic interfaces. Generic classes have a generic type parameter list in angle brackets following the name of the class.",
+    "score": 0.65
+  },
+  {
+    "title": "Understanding TypeScript Generics — freeCodeCamp",
+    "url": "https://www.freecodecamp.org/news/typescript-generics-use-case/",
+    "snippet": "TypeScript generics are a powerful feature that allow you to create flexible, reusable functions and classes. Generics enable you to define a component that can work with any data type. This tutorial walks through practical examples including generic constraints, default type parameters, and conditional types. You'll learn when to use generics vs. union types, and how to avoid common pitfalls.",
+    "score": 0.91
+  },
+  {
+    "title": "TypeScript Generics Tutorial — refactoring.guru",
+    "url": "https://refactoring.guru/typescript-generics",
+    "snippet": "In this tutorial we explore advanced generic patterns: generic utility types (Partial, Required, Readonly, Pick, Omit), mapped types, and template literal types. Code examples show before/after refactoring with generics to eliminate type duplication.",
+    "score": 0.84
+  },
+  {
+    "title": "Stack Overflow — TypeScript generics with constraints",
+    "url": "https://stackoverflow.com/questions/typed-generics-typescript",
+    "snippet": "Top answer (1.2k votes): Use a constraint to limit what T can be. Example: function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; } This pattern is extremely common in utility libraries like lodash-es and type-fest. The keyof constraint ensures type safety at compile time.",
+    "score": 0.88
+  },
+  {
+    "title": "TypeScript Deep Dive — Generics",
+    "url": "https://basarat.gitbook.io/typescript/type-system/generics",
+    "snippet": "Generics are just variables for types. The motivation for generics is to provide meaningful type constraints between members. This chapter covers: generic functions, generic classes, generic constraints, and the common patterns you'll see in real TypeScript codebases like Angular and NestJS.",
+    "score": 0.79
+  }
+]

package/bench/refs/node-sdk/.refrev

@@ -0,0 +1 @@
+049801243cc791e0ba28910b8a638f0e05446bcd

package/bench/refs/node-sdk/README.md

@@ -0,0 +1,17 @@
+# node-sdk reference subset
+
+Subset of [github.com/vercel/ai](https://github.com/vercel/ai) at commit
+`049801243cc791e0ba28910b8a638f0e05446bcd`, included for benchmark reproducibility.
+
+32 TypeScript source files sampled from `packages/ai/src/` covering:
+agent orchestration, embed, error types, generate-image, generate-object,
+generate-speech, generate-text, telemetry, and utility modules.
+
+No test files are included. Files ending in `.test.ts` or `.spec.ts` were excluded.
+
+## License notice
+
+The files in `src/` are copyright Vercel, Inc. and contributors, licensed under
+the Apache-2.0 License. See https://github.com/vercel/ai/blob/main/LICENSE for
+the full text. These files are included here solely for benchmark reproducibility
+under fair use / the Apache-2.0 license terms.

package/bench/refs/node-sdk/src/agent/agent.ts

@@ -0,0 +1,163 @@
+import type { Arrayable, Context, ToolSet } from '@ai-sdk/provider-utils';
+import { ModelMessage } from '@ai-sdk/provider-utils';
+import { GenerateTextResult } from '../generate-text/generate-text-result';
+import { Output } from '../generate-text/output';
+import { StreamTextTransform } from '../generate-text/stream-text';
+import { StreamTextResult } from '../generate-text/stream-text-result';
+import {
+  OnToolExecutionEndCallback,
+  OnToolExecutionStartCallback,
+} from '../generate-text/tool-execution-events';
+import { TimeoutConfiguration } from '../prompt/request-options';
+import type {
+  ToolLoopAgentOnFinishCallback,
+  ToolLoopAgentOnStartCallback,
+  ToolLoopAgentOnStepFinishCallback,
+  ToolLoopAgentOnStepStartCallback,
+} from './tool-loop-agent-settings';
+
+/**
+ * Parameters for calling an agent.
+ */
+export type AgentCallParameters<
+  CALL_OPTIONS,
+  TOOLS extends ToolSet = {},
+  RUNTIME_CONTEXT extends Context = Context,
+> = ([CALL_OPTIONS] extends [never]
+  ? { options?: never }
+  : { options: CALL_OPTIONS }) &
+  (
+    | {
+        /**
+         * A prompt. It can be either a text prompt or a list of messages.
+         *
+         * You can either use `prompt` or `messages` but not both.
+         */
+        prompt: string | Array<ModelMessage>;
+
+        /**
+         * A list of messages.
+         *
+         * You can either use `prompt` or `messages` but not both.
+         */
+        messages?: never;
+      }
+    | {
+        /**
+         * A list of messages.
+         *
+         * You can either use `prompt` or `messages` but not both.
+         */
+        messages: Array<ModelMessage>;
+
+        /**
+         * A prompt. It can be either a text prompt or a list of messages.
+         *
+         * You can either use `prompt` or `messages` but not both.
+         */
+        prompt?: never;
+      }
+  ) & {
+    /**
+     * Abort signal.
+     */
+    abortSignal?: AbortSignal;
+
+    /**
+     * Timeout in milliseconds. Can be specified as a number or as an object with `totalMs`.
+     */
+    timeout?: TimeoutConfiguration<TOOLS>;
+
+    /**
+     * Callback that is called when the agent operation begins, before any LLM calls.
+     */
+    experimental_onStart?: ToolLoopAgentOnStartCallback<TOOLS, RUNTIME_CONTEXT>;
+
+    /**
+     * Callback that is called when a step (LLM call) begins, before the provider is called.
+     */
+    experimental_onStepStart?: ToolLoopAgentOnStepStartCallback<
+      TOOLS,
+      RUNTIME_CONTEXT
+    >;
+
+    /**
+     * Callback that is called before each tool execution begins.
+     */
+    experimental_onToolExecutionStart?: OnToolExecutionStartCallback<TOOLS>;
+
+    /**
+     * Callback that is called after each tool execution completes.
+     */
+    experimental_onToolExecutionEnd?: OnToolExecutionEndCallback<TOOLS>;
+
+    /**
+     * Callback that is called when each step (LLM call) is finished, including intermediate steps.
+     */
+    onStepFinish?: ToolLoopAgentOnStepFinishCallback<TOOLS, RUNTIME_CONTEXT>;
+
+    /**
+     * Callback that is called when all steps are finished and the response is complete.
+     */
+    onFinish?: ToolLoopAgentOnFinishCallback<TOOLS, RUNTIME_CONTEXT>;
+  };
+
+/**
+ * Parameters for streaming an output from an agent.
+ */
+export type AgentStreamParameters<
+  CALL_OPTIONS,
+  TOOLS extends ToolSet,
+  RUNTIME_CONTEXT extends Context = Context,
+> = AgentCallParameters<CALL_OPTIONS, TOOLS, RUNTIME_CONTEXT> & {
+  /**
+   * Optional stream transformations.
+   * They are applied in the order they are provided.
+   * The stream transformations must maintain the stream structure for streamText to work correctly.
+   */
+  experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
+};
+
+/**
+ * An Agent receives a prompt (text or messages) and generates or streams an output
+ * that consists of steps, tool calls, data parts, etc.
+ *
+ * You can implement your own Agent by implementing the `Agent` interface,
+ * or use the `ToolLoopAgent` class.
+ */
+export interface Agent<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+  RUNTIME_CONTEXT extends Context = Context,
+  OUTPUT extends Output = never,
+> {
+  /**
+   * The specification version of the agent interface. This will enable
+   * us to evolve the agent interface and retain backwards compatibility.
+   */
+  readonly version: 'agent-v1';
+
+  /**
+   * The id of the agent.
+   */
+  readonly id: string | undefined;
+
+  /**
+   * The tools that the agent can use.
+   */
+  readonly tools: TOOLS;
+
+  /**
+   * Generates an output from the agent (non-streaming).
+   */
+  generate(
+    options: AgentCallParameters<CALL_OPTIONS, TOOLS, RUNTIME_CONTEXT>,
+  ): PromiseLike<GenerateTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>>;
+
+  /**
+   * Streams an output from the agent (streaming).
+   */
+  stream(
+    options: AgentStreamParameters<CALL_OPTIONS, TOOLS, RUNTIME_CONTEXT>,
+  ): PromiseLike<StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>>;
+}

package/bench/refs/node-sdk/src/agent/create-agent-ui-stream.ts

@@ -0,0 +1,83 @@
+import { StreamTextTransform, UIMessageStreamOptions } from '../generate-text';
+import { Output } from '../generate-text/output';
+import type { Arrayable, Context, ToolSet } from '@ai-sdk/provider-utils';
+import { TimeoutConfiguration } from '../prompt/request-options';
+import { InferUIMessageChunk } from '../ui-message-stream';
+import { convertToModelMessages } from '../ui/convert-to-model-messages';
+import { InferUITools, UIMessage } from '../ui/ui-messages';
+import { validateUIMessages } from '../ui/validate-ui-messages';
+import { AsyncIterableStream } from '../util/async-iterable-stream';
+import { Agent } from './agent';
+import type { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-settings';
+
+/**
+ * Runs the agent and stream the output as a UI message stream.
+ *
+ * @param agent - The agent to run.
+ * @param uiMessages - The input UI messages.
+ * @param abortSignal - The abort signal. Optional.
+ * @param timeout - Timeout in milliseconds. Optional.
+ * @param options - The options for the agent.
+ * @param experimental_transform - The stream transformations. Optional.
+ * @param onStepFinish - Callback that is called when each step is finished. Optional.
+ *
+ * @returns The UI message stream.
+ */
+export async function createAgentUIStream<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+  RUNTIME_CONTEXT extends Context = Context,
+  OUTPUT extends Output = never,
+  MESSAGE_METADATA = unknown,
+>({
+  agent,
+  uiMessages,
+  options,
+  abortSignal,
+  timeout,
+  experimental_transform,
+  onStepFinish,
+  ...uiMessageStreamOptions
+}: {
+  agent: Agent<CALL_OPTIONS, TOOLS, RUNTIME_CONTEXT, OUTPUT>;
+  uiMessages: unknown[];
+  abortSignal?: AbortSignal;
+  timeout?: TimeoutConfiguration<TOOLS>;
+  options?: CALL_OPTIONS;
+  experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
+  onStepFinish?: ToolLoopAgentOnStepFinishCallback<TOOLS>;
+  // TODO `originalMessages` is part of this for bc, omit in v7
+} & UIMessageStreamOptions<
+  UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>
+>): Promise<
+  AsyncIterableStream<
+    InferUIMessageChunk<UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>>
+  >
+> {
+  const validatedMessages = await validateUIMessages<
+    UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>
+  >({
+    messages: uiMessages,
+    tools: agent.tools,
+  });
+
+  const modelMessages = await convertToModelMessages(validatedMessages, {
+    tools: agent.tools,
+  });
+
+  const result = await agent.stream({
+    prompt: modelMessages,
+    options: options as CALL_OPTIONS,
+    abortSignal,
+    timeout,
+    experimental_transform,
+    onStepFinish,
+  });
+
+  return result.toUIMessageStream({
+    ...uiMessageStreamOptions,
+    // TODO reading `originalMessages` is here for bc, always use `validatedMessages` in v7
+    originalMessages:
+      uiMessageStreamOptions.originalMessages ?? validatedMessages,
+  });
+}