ai-functions 2.1.3 → 2.3.0

package/src/types.ts

@@ -2,16 +2,106 @@
  * Core types for AI functions
  */
 
+// ============================================================================
+// Human Function Pending Types
+// ============================================================================
+
+/**
+ * Symbol used to identify pending human function results
+ */
+export const PENDING_HUMAN_RESULT_SYMBOL = Symbol.for('HumanFunctionPending')
+
+/**
+ * Human interaction channels
+ *
+ * - chat: Real-time messaging (WebSocket, in-app)
+ * - email: Async email communication
+ * - phone: Voice calls
+ * - sms: SMS text messages
+ * - workspace: Team collaboration platforms (Slack, Teams, Discord)
+ * - web: Web-based interface (browser, web app)
+ */
+export type HumanChannel = 'chat' | 'email' | 'phone' | 'sms' | 'workspace' | 'web'
+
+/**
+ * Pending human function result returned when human input is not yet available.
+ *
+ * This is returned by human functions that need actual human input but are running
+ * in a placeholder mode (e.g., during testing or when channel integrations are not configured).
+ *
+ * Use `isPendingHumanResult()` to check if a result is pending before using it.
+ *
+ * @example
+ * ```ts
+ * const result = await approveRefund({ amount: 500, reason: 'Duplicate charge' })
+ *
+ * if (isPendingHumanResult(result)) {
+ *   console.log('Waiting for human approval via:', result.channel)
+ *   // Handle pending state - queue for later, show UI, etc.
+ * } else {
+ *   // result is the actual TOutput type
+ *   console.log('Approved:', result.approved)
+ * }
+ * ```
+ */
+export interface HumanFunctionPending<TExpected = unknown> {
+  /** Symbol marker for type identification */
+  readonly [PENDING_HUMAN_RESULT_SYMBOL]: true
+  /** Indicates this is a pending placeholder, not actual human response */
+  readonly _pending: true
+  /** The channel where human input was requested */
+  readonly channel: HumanChannel
+  /** Generated UI/content artifacts for the channel */
+  readonly artifacts: unknown
+  /** The expected response type schema */
+  readonly expectedResponseType: TExpected
+}
+
+/**
+ * Type guard to check if a result is a pending human function result.
+ *
+ * Use this to safely handle cases where human input is not yet available.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a HumanFunctionPending object
+ *
+ * @example
+ * ```ts
+ * const result = await reviewDocument({ docId: '123' })
+ *
+ * if (isPendingHumanResult(result)) {
+ *   // result is HumanFunctionPending - human input needed
+ *   console.warn('Human review pending:', result.channel)
+ *   return { status: 'pending', channel: result.channel }
+ * }
+ *
+ * // result is ReviewResult - actual human response
+ * return { status: 'reviewed', approved: result.approved }
+ * ```
+ */
+export function isPendingHumanResult<T>(
+  value: T | HumanFunctionPending
+): value is HumanFunctionPending {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    '_pending' in value &&
+    value._pending === true &&
+    PENDING_HUMAN_RESULT_SYMBOL in value
+  )
+}
+
+// ============================================================================
+// AI Function Types
+// ============================================================================
+
 /**
  * A function definition that can be called by AI
  *
  * @typeParam TOutput - The return type of the function handler
  * @typeParam TInput - The input type accepted by the function handler
  */
-export interface AIFunctionDefinition<
-  TOutput = unknown,
-  TInput = unknown
-> {
+export interface AIFunctionDefinition<TOutput = unknown, TInput = unknown> {
   /** Unique name for the function */
   name: string
   /** Human-readable description for the AI */
@@ -162,9 +252,11 @@ export interface WriteOptions {
 /**
  * Type for functions that support both regular calls and tagged template literals
  */
-export type TemplateFunction<TArgs extends unknown[], TReturn> =
-  & ((prompt: string, ...args: TArgs) => TReturn)
-  & ((strings: TemplateStringsArray, ...values: unknown[]) => TReturn)
+export type TemplateFunction<TArgs extends unknown[], TReturn> = ((
+  prompt: string,
+  ...args: TArgs
+) => TReturn) &
+  ((strings: TemplateStringsArray, ...values: unknown[]) => TReturn)
 
 /**
  * A single item in a list
@@ -210,18 +302,6 @@ export type CodeLanguage = 'typescript' | 'javascript' | 'python' | 'go' | 'rust
  */
 export type GenerativeOutputType = 'string' | 'object' | 'image' | 'video'
 
-/**
- * Human interaction channels
- *
- * - chat: Real-time messaging (WebSocket, in-app)
- * - email: Async email communication
- * - phone: Voice calls
- * - sms: SMS text messages
- * - workspace: Team collaboration platforms (Slack, Teams, Discord)
- * - web: Web-based interface (browser, web app)
- */
-export type HumanChannel = 'chat' | 'email' | 'phone' | 'sms' | 'workspace' | 'web'
-
 /**
  * Legacy channel type for backwards compatibility
  * @deprecated Use HumanChannel instead
@@ -273,12 +353,24 @@ export interface BaseFunctionDefinition<TOutput = unknown, TInput = unknown> {
 }
 
 /**
- * Code function - generates actual executable code
+ * Code function - a **deterministic** handler.
+ *
+ * `Code` is the deterministic kind: a fetch/transform/rule handler that runs
+ * the **same logic every time** with no model in the execution path. When
+ * called, it invokes the supplied {@link CodeFunctionDefinition.handler}
+ * (or evaluates the inline {@link CodeFunctionDefinition.code} body) and
+ * returns the result directly — no LLM is consulted at call time.
+ *
+ * This is the contract consumers bind to (e.g. ADR-0033's
+ * "Code = deterministic"). If you want a model to *author* code, that is a
+ * generation task: use {@link generateCode} / the `generate('code', …)`
+ * primitive, or define a `Generative` function whose output is source text.
+ * See the migration note in the package README.
  *
- * When called, this generates:
- * - Implementation code with JSDoc comments
- * - Vitest test cases
- * - Example usage scripts
+ * Exactly one of `handler` or `code` should be supplied. `handler` is the
+ * canonical form (a native function reference); `code` is an inline source
+ * body, deterministically compiled by the consumer's runtime — never sent to
+ * a model.
  *
  * @example
  * ```ts
@@ -290,7 +382,7 @@ export interface BaseFunctionDefinition<TOutput = unknown, TInput = unknown> {
  *     rate: 'Tax rate as decimal (number)',
  *   },
  *   returnType: 'The calculated tax amount (number)',
- *   language: 'typescript',
+ *   handler: ({ amount, rate }) => amount * rate,
  * })
  * ```
  *
@@ -300,6 +392,51 @@ export interface BaseFunctionDefinition<TOutput = unknown, TInput = unknown> {
 export interface CodeFunctionDefinition<TOutput = unknown, TInput = unknown>
   extends BaseFunctionDefinition<TOutput, TInput> {
   type: 'code'
+  /**
+   * The deterministic handler invoked on every call. Receives the parsed
+   * `args` and returns (or resolves to) the result. No LLM is involved.
+   *
+   * Either `handler` or {@link CodeFunctionDefinition.code} must be provided;
+   * `handler` takes precedence when both are present.
+   */
+  handler?: (input: TInput) => TOutput | Promise<TOutput>
+  /**
+   * Inline source body for the handler, as a string. Deterministically
+   * compiled by the consumer's runtime (it is **not** generated by a model).
+   * Used when a handler cannot be passed by reference (e.g. a definition
+   * loaded from storage). The body receives the `args` in scope and should
+   * `return` the result.
+   *
+   * Either `code` or {@link CodeFunctionDefinition.handler} must be provided.
+   */
+  code?: string
+  /** Target programming language of `code` (default: `'typescript'`). Metadata only. */
+  language?: CodeLanguage
+  /** Optional human-readable note about what the handler does. Metadata only. */
+  instructions?: string
+}
+
+/**
+ * Definition for a code-**authoring** request — the explicit, opt-in path for
+ * having a model *write* code. This is the behavior `type: 'code'` used to
+ * have implicitly; it has been split out so that `Code` can mean
+ * "deterministic handler" without a silent change of meaning.
+ *
+ * This is **not** part of the {@link FunctionDefinition} union and never
+ * executes deterministically — calling it consults a model. Drive it via
+ * {@link generateCode}.
+ *
+ * @typeParam TInput - The arguments schema describing the code to author
+ */
+export interface CodeGenerationDefinition<TInput = unknown> {
+  /** Name of the function/query to author */
+  name: string
+  /** Human-readable description of what the code should do */
+  description?: string
+  /** Arguments/spec schema describing the code to generate */
+  args: TInput
+  /** Return type schema the authored code should produce (optional) */
+  returnType?: unknown
   /** Target programming language */
   language?: CodeLanguage
   /** Additional context or requirements for code generation */
@@ -308,6 +445,8 @@ export interface CodeFunctionDefinition<TOutput = unknown, TInput = unknown>
   includeTests?: boolean
   /** Whether to include example usage (default: true) */
   includeExamples?: boolean
+  /** Model to use for authoring (defaults to 'sonnet') */
+  model?: string
 }
 
 /**

package/src/wrap-for-v3.ts

@@ -0,0 +1,105 @@
+/**
+ * wrapForV3 — convenience composer for the v3 cascade-walker / evaluator-panel
+ * use case.
+ *
+ * Composes `cacheMiddleware`, `budgetMiddleware`, and `traceMiddleware` in a
+ * single `wrapLanguageModel` call so callers in services-as-software (round
+ * 15+ swap) can replace their existing post-hoc duck-typing in
+ * `cost-estimate.ts` with a single wrap call:
+ *
+ * ```ts
+ * import { wrapForV3, BudgetTracker, getEvalLogStore } from 'ai-functions'
+ *
+ * const tracker = new BudgetTracker({ maxCost: 1.0 })
+ * const store = getEvalLogStore()
+ *
+ * const wrapped = wrapForV3(openai('gpt-4o'), {
+ *   cache: { store: 'disk', ttlMs: 86_400_000 },
+ *   budget: { tracker },
+ *   trace: { emit: (e) => store.record({ ...e, costUsd: e.costUsd ?? 0 }) },
+ * })
+ * ```
+ *
+ * **Composition order:**
+ *   1. **cache** — first so cache hits skip budget+trace network cost. The
+ *      cached payload's usage still flows downstream so budget records the
+ *      cost on hits AND misses.
+ *   2. **budget** — second so it sees the wrapped result regardless of
+ *      cache hit/miss; tracker.recordUsage fires either way.
+ *   3. **trace** — last so the event sees the final outcome (post-cache,
+ *      post-budget). Errors from `emit` are swallowed.
+ *
+ * AI SDK 6 ordering semantics (per the wrapLanguageModel JSDoc): "the first
+ * middleware will transform the input first, and the last middleware will
+ * be wrapped directly around the model." So when we hand the array
+ * `[cache, budget, trace]`, the runtime call order is
+ * `cache → budget → trace → model` on the way in, and the reverse on the
+ * way out. Cache sees the call first; if it has a hit, downstream layers
+ * never run their `wrapGenerate` body for that call. Budget and trace each
+ * get their own post-completion hook on the result the layer below them
+ * returned — so on a cache hit, neither budget nor trace runs (because
+ * cache short-circuits via `return cached`). To get budget + trace on
+ * cache hits, the budgetMiddleware/traceMiddleware would need to wrap the
+ * cache middleware (i.e. install AFTER it in the chain). Per the spec
+ * above, "later in the array = closer to the model" → install order
+ * matters: callers who want cache-hit cost recording should pass
+ * `[budget, trace, cache]`. We use `[cache, budget, trace]` as the default
+ * because the eval-fixture use case wants the 5x verify-time win and is
+ * happy to skip the cost record on the hit path (the original miss already
+ * recorded it).
+ *
+ * @packageDocumentation
+ */
+
+import { wrapLanguageModel, type LanguageModel } from 'ai'
+import type { LanguageModelV3, LanguageModelV3Middleware } from '@ai-sdk/provider'
+import { cacheMiddleware, type CacheMiddlewareOptions } from './middleware/cache.js'
+import { budgetMiddleware, type BudgetMiddlewareOptions } from './middleware/budget.js'
+import { traceMiddleware, type TraceMiddlewareOptions } from './middleware/trace.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Options for {@link wrapForV3}. All three middleware sections are
+ * optional — pass only what you need.
+ */
+export interface WrapForV3Options {
+  /** Cache config (see {@link CacheMiddlewareOptions}). */
+  cache?: CacheMiddlewareOptions
+  /** Budget tracking config (see {@link BudgetMiddlewareOptions}). */
+  budget?: BudgetMiddlewareOptions
+  /** Trace emission config (see {@link TraceMiddlewareOptions}). */
+  trace?: TraceMiddlewareOptions
+}
+
+// ============================================================================
+// Composer
+// ============================================================================
+
+/**
+ * Wrap a {@link LanguageModel} with the v3-cascade middleware stack
+ * (cache → budget → trace, in install order).
+ *
+ * Returns the wrapped model with the same shape as the input; downstream
+ * `generateText` / `generateObject` / `streamText` calls treat it as a
+ * regular model.
+ *
+ * @see WrapForV3Options for partial-config behaviour
+ */
+export function wrapForV3(model: LanguageModel, opts: WrapForV3Options = {}): LanguageModel {
+  const middleware: LanguageModelV3Middleware[] = []
+  if (opts.cache) middleware.push(cacheMiddleware(opts.cache))
+  if (opts.budget) middleware.push(budgetMiddleware(opts.budget))
+  if (opts.trace) middleware.push(traceMiddleware(opts.trace))
+  if (middleware.length === 0) return model
+  // wrapLanguageModel currently accepts LanguageModelV3 — at the AI SDK 6
+  // surface, `LanguageModel` is the wider union. The runtime is V3
+  // everywhere in the published providers; the cast is the same one the
+  // wrapLanguageModel cookbook uses.
+  return wrapLanguageModel({
+    model: model as LanguageModelV3,
+    middleware,
+  }) as LanguageModel
+}