@venturekit-pro/ai 0.0.48 → 0.0.50

package/dist/generate/types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * `generate` — the provider-neutral model call behind the LLM gateway and
+ * the agent loop.
+ *
+ * Wider than `chat/` (which stays the single-shot text API): function
+ * tools + tool choice, model-native web search with citations, native
+ * structured output, file / image inputs, prompt-cache hints and
+ * cached / cache-write usage, search counts for pricing, provider-state
+ * replay between turns, streaming, and cancellation through an
+ * `AbortSignal`.
+ *
+ * Adapters are `fetch()`-based like the chat adapters, and throw
+ * `Error("[ai/generate/<provider>] <status> <statusText>: <body>")` on an
+ * HTTP failure so `fallback/isRetryableError` (and callers that classify
+ * vendor errors) read the status the same way.
+ */
+import type { ChatFinishReason, ChatProvider } from '../chat/types.js';
+/** A JSON Schema object (tool inputs, structured output). */
+export type JsonSchema = Record<string, unknown>;
+export interface TextPart {
+    type: 'text';
+    text: string;
+}
+/** A document the model reads natively (PDF, plain text). `data` is base64. */
+export interface FilePart {
+    type: 'file';
+    mediaType: string;
+    data: string;
+    filename?: string;
+}
+/** An image input. `data` is base64. */
+export interface ImagePart {
+    type: 'image';
+    mediaType: string;
+    data: string;
+}
+export type ContentPart = TextPart | FilePart | ImagePart;
+/** A function-tool call the model asked for. */
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * Opaque, provider-specific assistant content replayed verbatim on the
+ * next turn (Anthropic server-tool blocks, Gemini thought signatures).
+ * Ignored by other providers.
+ */
+export interface ProviderState {
+    provider: ChatProvider;
+    data: unknown;
+}
+/**
+ * Prompt-cache breakpoint: `cache: true` asks the provider to cache the
+ * prompt up to and including this message (tools and system first). Put
+ * it on the end of the stable prefix — kernel, brand profile, playbook.
+ * Anthropic gets a `cache_control` block (at most 4 per call: the system
+ * one plus the latest three); OpenAI and Gemini cache prefixes on their
+ * own, so the marker is a no-op there.
+ */
+interface Cacheable {
+    cache?: boolean;
+}
+export interface SystemMessage extends Cacheable {
+    role: 'system';
+    content: string;
+}
+export interface UserMessage extends Cacheable {
+    role: 'user';
+    content: string | ContentPart[];
+}
+export interface AssistantMessage extends Cacheable {
+    role: 'assistant';
+    content: string;
+    toolCalls?: ToolCall[];
+    providerState?: ProviderState;
+}
+/** The result of one function-tool call, answered back to the model. */
+export interface ToolMessage extends Cacheable {
+    role: 'tool';
+    toolCallId: string;
+    name: string;
+    content: string;
+    isError?: boolean;
+}
+export type GenerateMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+}
+/** `required` = the model must call some tool; `{ name }` = that tool. */
+export type ToolChoice = 'auto' | 'none' | 'required' | {
+    name: string;
+};
+/**
+ * Model-native web search (Anthropic web search tool, OpenAI `web_search`,
+ * Gemini Google Search grounding). Results and citations come back on the
+ * result; every search is counted for pricing.
+ */
+export interface WebSearchOptions {
+    /** Searches allowed in one call (Anthropic `max_uses`, OpenAI `max_tool_calls`). */
+    maxUses?: number;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    /** Localizes results. `country` is ISO 3166-1 alpha-2. */
+    userLocation?: {
+        country?: string;
+        city?: string;
+        region?: string;
+        timezone?: string;
+    };
+}
+export type ResponseFormat = {
+    type: 'json_schema';
+    name: string;
+    schema: JsonSchema;
+    strict?: boolean;
+} | {
+    type: 'json';
+};
+/**
+ * Prompt-cache options for the call. Setting it with no message marked
+ * `cache: true` lets Anthropic place the breakpoint itself (automatic
+ * caching).
+ */
+export interface CacheOptions {
+    /**
+     * Groups calls that share a prefix: OpenAI `prompt_cache_key` (routing
+     * and per-group cache accounting). Use a stable, PII-free value such as
+     * `<tenant>:<graph>:<node>`.
+     */
+    key?: string;
+    /** Anthropic entry lifetime. `1h` writes cost 2× input instead of 1.25×. Default `5m`. */
+    ttl?: '5m' | '1h';
+}
+/**
+ * How much the model may think before it answers, provider-neutral:
+ * OpenAI reasoning models get `reasoning.effort` (`max` → `high`), Claude
+ * extended thinking with a token budget (1k / 4k / 12k / 24k; not when the
+ * call forces a tool, which Anthropic refuses with thinking on), Gemini a
+ * thinking budget (2.5) or level (3+). More effort spends more output
+ * tokens. Left out, each vendor's default applies.
+ */
+export type ReasoningEffort = 'low' | 'medium' | 'high' | 'max';
+/** Thinking-token budget per effort, for vendors that take a budget (Claude, Gemini 2.5). */
+export declare const THINKING_BUDGET: Record<ReasoningEffort, number>;
+export interface GenerateRequest {
+    /** Wire model id at the adapter level (the gateway takes a catalog key). */
+    model: string;
+    messages: GenerateMessage[];
+    /** Hard cap on output tokens. Default 4096. With a thinking budget, raised to fit it. */
+    maxTokens?: number;
+    /** See {@link ReasoningEffort}. */
+    effort?: ReasoningEffort;
+    temperature?: number;
+    topP?: number;
+    stop?: string[];
+    tools?: ToolDefinition[];
+    toolChoice?: ToolChoice;
+    webSearch?: WebSearchOptions;
+    /** Native structured output; the parsed value comes back as `result.json`. */
+    responseFormat?: ResponseFormat;
+    /** Prompt caching for the call (see also `cache: true` on messages). */
+    cache?: CacheOptions;
+    /** Request timeout, covering the body read (the whole stream when streaming). Default 120 s. */
+    timeoutMs?: number;
+    /** Forwarded as `Idempotency-Key` to vendors that support it. */
+    idempotencyKey?: string;
+    /** Cooperative cancellation: aborts the HTTP call. */
+    signal?: AbortSignal;
+}
+/** A source the answer cites. */
+export interface Citation {
+    url: string;
+    title?: string;
+    citedText?: string;
+}
+/** A page a web search returned. */
+export interface SearchResult {
+    url: string;
+    title?: string;
+    pageAge?: string;
+}
+export interface GenerateUsage {
+    /** Every input token: uncached, read from the cache and written to it. */
+    tokensIn: number | null;
+    /** Input tokens served from the provider's prompt cache. */
+    cachedTokensIn: number | null;
+    /** Input tokens written to the provider's prompt cache (priced above the input rate). */
+    cacheWriteTokensIn?: number | null;
+    /** The part of `cacheWriteTokensIn` written with a 1-hour lifetime (Anthropic). */
+    cacheWrite1hTokensIn?: number | null;
+    /** Output tokens, reasoning included. */
+    tokensOut: number | null;
+    /** Web searches the vendor ran (priced per search). */
+    webSearches: number;
+}
+export interface GenerateResult {
+    provider: ChatProvider;
+    /** Wire model that served the call. */
+    model: string;
+    /** Final assistant text (may be empty when the model only called tools). */
+    text: string;
+    /** Parsed structured output when `responseFormat` was set and the reply parsed. */
+    json?: unknown;
+    toolCalls: ToolCall[];
+    citations: Citation[];
+    searchResults: SearchResult[];
+    searchQueries: string[];
+    finishReason: ChatFinishReason | null;
+    usage: GenerateUsage;
+    latencyMs: number;
+    /** Replay this on the assistant message of the next turn. */
+    providerState?: ProviderState;
+}
+/**
+ * What a stream yields: text as it is written, each function-tool call
+ * once its arguments are complete, each native web search as it starts,
+ * then exactly one `done` with the same result `generate()` returns.
+ */
+export type GenerateStreamEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'tool_call';
+    call: ToolCall;
+} | {
+    type: 'search';
+    query: string;
+} | {
+    type: 'done';
+    result: GenerateResult;
+};
+export interface GenerateClient {
+    readonly provider: ChatProvider;
+    generate(request: GenerateRequest): Promise<GenerateResult>;
+    /** Streams the call (server-sent events). Clients without it are called through `generate`. */
+    stream?(request: GenerateRequest): AsyncIterable<GenerateStreamEvent>;
+}
+export interface GenerateAdapterConfig {
+    apiKey: string;
+    baseUrl?: string;
+    /** Default request timeout. Default 120 s. */
+    timeoutMs?: number;
+    /** Test seam. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+export type GenerateClientConfig = {
+    provider: ChatProvider;
+} & GenerateAdapterConfig;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/generate/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/generate/types.ts"],"names":[],"mappings":"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"}

package/dist/generate/types.js

@@ -0,0 +1,19 @@
+/**
+ * `generate` — the provider-neutral model call behind the LLM gateway and
+ * the agent loop.
+ *
+ * Wider than `chat/` (which stays the single-shot text API): function
+ * tools + tool choice, model-native web search with citations, native
+ * structured output, file / image inputs, prompt-cache hints and
+ * cached / cache-write usage, search counts for pricing, provider-state
+ * replay between turns, streaming, and cancellation through an
+ * `AbortSignal`.
+ *
+ * Adapters are `fetch()`-based like the chat adapters, and throw
+ * `Error("[ai/generate/<provider>] <status> <statusText>: <body>")` on an
+ * HTTP failure so `fallback/isRetryableError` (and callers that classify
+ * vendor errors) read the status the same way.
+ */
+/** Thinking-token budget per effort, for vendors that take a budget (Claude, Gemini 2.5). */
+export const THINKING_BUDGET = { low: 1024, medium: 4096, high: 12_288, max: 24_576 };
+//# sourceMappingURL=types.js.map

package/dist/generate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/generate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA0IH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,eAAe,GAAoC,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC"}

package/dist/harness/define.d.ts

@@ -0,0 +1,15 @@
+import type { GraphDefinition, NodeDefinition } from './types.js';
+/** A node failure that must not be retried (bad input, a claim already taken, no budget). */
+export declare class NodeFatalError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/** Declare a node. Identity at runtime; keeps the node's literal types. */
+export declare function defineNode<N extends NodeDefinition>(node: N): N;
+/**
+ * Declare a graph: code, versioned (`key@version`), pinned per run.
+ * Register a new version alongside the old one so in-flight runs finish
+ * on the version they started with.
+ */
+export declare function defineGraph(graph: GraphDefinition): GraphDefinition;
+//# sourceMappingURL=define.d.ts.map

package/dist/harness/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/harness/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAElE,6FAA6F;AAC7F,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,IAAI,SAAe;CAKjD;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,CAAC,SAAS,cAAc,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAwBnE"}

package/dist/harness/define.js

@@ -0,0 +1,38 @@
+/** A node failure that must not be retried (bad input, a claim already taken, no budget). */
+export class NodeFatalError extends Error {
+    code;
+    constructor(message, code = 'node_fatal') {
+        super(message);
+        this.name = 'NodeFatalError';
+        this.code = code;
+    }
+}
+/** Declare a node. Identity at runtime; keeps the node's literal types. */
+export function defineNode(node) {
+    return node;
+}
+/**
+ * Declare a graph: code, versioned (`key@version`), pinned per run.
+ * Register a new version alongside the old one so in-flight runs finish
+ * on the version they started with.
+ */
+export function defineGraph(graph) {
+    const ids = new Set();
+    for (const node of graph.nodes) {
+        if (ids.has(node.id))
+            throw new Error(`[ai/harness] ${graph.key}@${graph.version}: duplicate node '${node.id}'`);
+        ids.add(node.id);
+    }
+    if (!ids.has(graph.start))
+        throw new Error(`[ai/harness] ${graph.key}@${graph.version}: start node '${graph.start}' does not exist`);
+    for (const node of graph.nodes) {
+        if (typeof node.next === 'string' && !ids.has(node.next)) {
+            throw new Error(`[ai/harness] ${graph.key}@${graph.version}: node '${node.id}' goes to unknown node '${node.next}'`);
+        }
+        if (node.kind === 'gate' && node.decisions.length === 0) {
+            throw new Error(`[ai/harness] ${graph.key}@${graph.version}: gate '${node.id}' accepts no decision`);
+        }
+    }
+    return graph;
+}
+//# sourceMappingURL=define.js.map

package/dist/harness/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/harness/define.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAS;IAEtB,YAAY,OAAe,EAAE,IAAI,GAAG,YAAY;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,UAAU,UAAU,CAA2B,IAAO;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAsB;IAChD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,gBAAgB,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,qBAAqB,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QAC7F,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,gBAAgB,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,iBAAiB,KAAK,CAAC,KAAK,kBAAkB,CACzF,CAAC;IACJ,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,KAAK,CACb,gBAAgB,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,WAAW,IAAI,CAAC,EAAE,2BAA2B,IAAI,CAAC,IAAI,GAAG,CACpG,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CACb,gBAAgB,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,WAAW,IAAI,CAAC,EAAE,uBAAuB,CACpF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/harness/harness.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `createHarness` — the durable runtime for graphs.
+ *
+ * One task per node attempt (`{ runId, step, attempt }`):
+ *
+ *   lease (CAS queued → running, `node.started`)
+ *   → run the node (heartbeat renews the lease; a cancel poll and the
+ *     node timeout abort `ctx.signal`)
+ *   → ONE compare-and-set commit: output, next node, events, node-run row
+ *   → schedule the next task
+ *
+ * A gate is reached in the same commit (status `waiting`, nothing in
+ * flight) and left by `resume()`. A failed attempt is retried with
+ * backoff unless it is fatal (`NodeFatalError`, a gateway policy denial,
+ * a 4xx caller error) or the node's attempts are used up. Duplicate or
+ * late deliveries are no-ops (`stale` / `busy`). `sweep()` re-sends tasks
+ * that were lost or held back, and fails the attempt of a worker whose
+ * lease expired.
+ */
+import type { Harness, HarnessOptions, RetryCategory } from './types.js';
+/** Misuse of the harness API (unknown run, wrong status, bad decision, lost race). */
+export declare class HarnessError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** What kind of failure `err` is, for `retry.on` (an `AgentRunError` is judged by its cause). */
+export declare function retryCategory(err: unknown): RetryCategory;
+export declare function createHarness(options: HarnessOptions): Harness;
+//# sourceMappingURL=harness.d.ts.map

package/dist/harness/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/harness/harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH,OAAO,KAAK,EAIV,OAAO,EACP,cAAc,EAKd,aAAa,EAId,MAAM,YAAY,CAAC;AAUpB,sFAAsF;AACtF,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AA2CD,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA0BzD;AAiBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAk0C9D"}