@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/libraries/ai/structured/completeStructured.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import type { LLMProvider } from "../adapters/LLMProvider.js";
+import type { CompleteOptions, CompleteResult, ToolDefinition, ToolUsePart } from "../types.js";
+
+/**
+ * `completeStructured<TSchema>({ llm, schema, ... })` — single-shot
+ * call that returns a typed object matching the supplied Zod schema.
+ *
+ * Pattern: defines a synthetic "respond" tool whose `input_schema` is
+ * the JSON-schema view of the user's Zod schema, forces
+ * `tool_choice: { type: "tool", name }` so the model MUST invoke it,
+ * then parses the tool_use input back through the Zod schema (catches
+ * any drift the JSON-schema view didn't constrain — e.g. Zod
+ * refinements that don't translate).
+ *
+ * Provider-portable by design — works against any `LLMProvider` whose
+ * `complete()` honors `tools` + `toolChoice`. Provider-specific
+ * structured-output APIs (OpenAI `response_format: json_schema`,
+ * Anthropic `parse()` helper) can be wired in adapter-specific
+ * overrides in a later commit; this primitive ships the load-bearing
+ * cross-provider path first.
+ *
+ * Why a synthetic tool instead of "ask the model for JSON in a code
+ * block":
+ *   - Tool-use is the model's native structured-output channel —
+ *     providers train it explicitly. JSON-in-text is best-effort and
+ *     drifts (markdown fences, trailing commentary, hallucinated keys).
+ *   - The tool's `input_schema` is forced upstream in the request, so
+ *     the provider can constrain decoding (Anthropic does shape-aware
+ *     decoding for tool inputs).
+ *   - Tool inputs come back already-parsed JSON — no re-parsing /
+ *     stripping markdown.
+ *
+ * Errors: `StructuredOutputError` thrown when (a) the model returns
+ * text instead of invoking the tool (rare with `toolChoice: tool` but
+ * possible on `max_tokens` cutoff), (b) the tool input fails Zod
+ * validation. Both carry the raw `CompleteResult` for debugging.
+ */
+
+export interface CompleteStructuredOptions<TSchema extends z.ZodTypeAny>
+  extends Omit<CompleteOptions, "tools" | "toolChoice"> {
+  /** Provider that runs the request. */
+  llm: LLMProvider;
+  /** Zod schema describing the desired output shape. */
+  schema: TSchema;
+  /**
+   * Override the synthetic tool's name. Default `"respond"`. Useful
+   * when the tool name appears in the model's reasoning trace and you
+   * want it to read more naturally.
+   */
+  responseToolName?: string;
+  /** Override the synthetic tool's description shown to the model. */
+  responseToolDescription?: string;
+}
+
+export interface CompleteStructuredResult<T> {
+  /** The parsed, schema-validated output. */
+  data: T;
+  /** The raw provider response (usage / id / model / etc.). */
+  raw: CompleteResult;
+}
+
+export class StructuredOutputError extends Error {
+  constructor(
+    message: string,
+    public readonly raw: CompleteResult,
+  ) {
+    super(message);
+    this.name = "StructuredOutputError";
+  }
+}
+
+const DEFAULT_TOOL_NAME = "respond";
+const DEFAULT_TOOL_DESCRIPTION =
+  "Respond with the structured output. Call this tool exactly once with the final answer matching the input schema.";
+
+export async function completeStructured<TSchema extends z.ZodTypeAny>(
+  opts: CompleteStructuredOptions<TSchema>,
+): Promise<CompleteStructuredResult<z.infer<TSchema>>> {
+  const inputSchema = z.toJSONSchema(opts.schema, {
+    target: "draft-2020-12",
+  }) as Record<string, unknown>;
+  delete inputSchema["$schema"];
+
+  const responseTool: ToolDefinition = {
+    name: opts.responseToolName ?? DEFAULT_TOOL_NAME,
+    description: opts.responseToolDescription ?? DEFAULT_TOOL_DESCRIPTION,
+    inputSchema,
+  };
+
+  // Drop the keys we own from the forwarded options.
+  const {
+    llm,
+    schema: _schema,
+    responseToolName: _name,
+    responseToolDescription: _desc,
+    ...providerOpts
+  } = opts;
+  void _schema;
+  void _name;
+  void _desc;
+
+  const raw = await llm.complete({
+    ...providerOpts,
+    tools: [responseTool],
+    toolChoice: { type: "tool", name: responseTool.name },
+  });
+
+  const toolUse = raw.content.find(
+    (p): p is ToolUsePart => p.type === "tool_use" && p.name === responseTool.name,
+  );
+  if (!toolUse) {
+    throw new StructuredOutputError(
+      `Model did not invoke the "${responseTool.name}" tool — got stop_reason="${raw.stopReason}"`,
+      raw,
+    );
+  }
+
+  const parsed = opts.schema.safeParse(toolUse.input);
+  if (!parsed.success) {
+    throw new StructuredOutputError(
+      `Response did not match schema: ${formatZodIssues(parsed.error.issues)}`,
+      raw,
+    );
+  }
+
+  return { data: parsed.data as z.infer<TSchema>, raw };
+}
+
+interface ZodLikeIssue {
+  path?: Array<string | number>;
+  message: string;
+}
+
+function formatZodIssues(issues: readonly ZodLikeIssue[]): string {
+  if (!issues.length) return "validation failed";
+  return issues
+    .map((issue) => {
+      const path = (issue.path ?? []).join(".") || "(root)";
+      return `${path}: ${issue.message}`;
+    })
+    .join("; ");
+}

package/lib/libraries/ai/tokens/Tokenizer.ts

@@ -0,0 +1,216 @@
+import type { Message, MessageContentPart } from "../types.js";
+
+/**
+ * Pluggable tokenizer contract — counts tokens for a given model
+ * without committing the library to a specific tokenizer
+ * implementation (tiktoken / claude-tokenizer / model-bundled
+ * /encoding-rs / online API). Consumers inject the right tokenizer
+ * for their provider; this library never imports a tokenizer SDK
+ * itself, so the dep graph stays narrow.
+ *
+ * Why an interface instead of "just use tiktoken":
+ *   - Tokenization is provider-specific. OpenAI uses tiktoken (cl100k /
+ *     o200k); Anthropic uses a Claude-specific BPE; Llama / Mistral
+ *     have their own. One library, three tokenizers.
+ *   - Tiktoken pulls a 5+ MB WASM blob — fine for server-side, hostile
+ *     for edge runtimes. An "estimate" tokenizer is preferable when
+ *     exactness doesn't matter (rate-limit budgeting, prompt-fit
+ *     gating).
+ *   - Tests need a predictable in-process tokenizer; consumers can
+ *     register `HeuristicTokenizer` for cheap deterministic counts.
+ *
+ * The library ships `HeuristicTokenizer` as a baseline (~4 chars per
+ * token, the well-known rule-of-thumb for English). Real tokenizers
+ * (tiktoken-backed for OpenAI, claude-tokenizer for Anthropic) are
+ * straightforward to implement against this interface and can land in
+ * v4.x adapter sub-packages so they're tree-shake-friendly.
+ */
+
+export interface Tokenizer {
+  /** Stable model identifier the tokenizer is calibrated for. */
+  readonly model: string;
+  /**
+   * Count tokens in a single string. Synchronous so callers can use it
+   * inside hot prompt-assembly loops without await ceremony.
+   */
+  count(text: string): number;
+  /**
+   * Optional encode (text → tokens). Provided when the tokenizer is
+   * exact (tiktoken / claude); omitted on heuristic backends.
+   */
+  encode?(text: string): number[];
+  /** Optional decode (tokens → text). Same caveat as `encode`. */
+  decode?(tokens: number[]): string;
+  /**
+   * Free any resources the tokenizer holds (tiktoken WASM handles,
+   * file mappings). Idempotent. Safe to call when nothing was
+   * allocated.
+   */
+  dispose?(): void;
+}
+
+/**
+ * Sum tokens across a `Message[]` history — text parts, tool_use
+ * input JSON, tool_result content, image part overhead. Provider-
+ * specific message-formatting overhead (per-turn separator tokens,
+ * role-name tokens) is approximated by `perMessageOverhead`; refine
+ * per provider when exactness matters.
+ */
+export interface CountMessagesOptions {
+  /** Tokens added per message (separators / role name). Default 4. */
+  perMessageOverhead?: number;
+  /**
+   * Tokens budgeted per image part. Anthropic / OpenAI both charge a
+   * fixed-ish range (~85–1500 depending on resolution). Default 1024
+   * — middle of the range; pass a tighter estimate when known.
+   */
+  perImageTokens?: number;
+}
+
+const DEFAULT_PER_MESSAGE_OVERHEAD = 4;
+const DEFAULT_PER_IMAGE_TOKENS = 1024;
+
+/**
+ * @deprecated AI-R3. Token *truth* comes back in the provider response — read
+ * `CompleteResult.usage` / `StreamStopEvent.usage` (real, billed counts). This
+ * heuristic-driven count is inaccurate (±15%) and a per-model maintenance
+ * burden. For pre-call budgeting only, use `estimateMessageTokens`.
+ */
+export function countMessageTokens(
+  tokenizer: Tokenizer,
+  messages: Message[],
+  opts: CountMessagesOptions = {},
+): number {
+  const perMessage = opts.perMessageOverhead ?? DEFAULT_PER_MESSAGE_OVERHEAD;
+  const perImage = opts.perImageTokens ?? DEFAULT_PER_IMAGE_TOKENS;
+
+  let total = 0;
+  for (const msg of messages) {
+    total += perMessage;
+    if (typeof msg.content === "string") {
+      total += tokenizer.count(msg.content);
+    } else {
+      total += countParts(tokenizer, msg.content, perImage);
+    }
+    if (msg.name) total += tokenizer.count(msg.name);
+  }
+  return total;
+}
+
+function countParts(tokenizer: Tokenizer, parts: MessageContentPart[], perImage: number): number {
+  let n = 0;
+  for (const p of parts) {
+    switch (p.type) {
+      case "text":
+        n += tokenizer.count(p.text);
+        break;
+      case "tool_use":
+        n += tokenizer.count(p.name);
+        // input JSON shows up to the model verbatim — count it.
+        try {
+          n += tokenizer.count(JSON.stringify(p.input ?? {}));
+        } catch {
+          // unrenderable input → conservative estimate
+          n += 16;
+        }
+        break;
+      case "tool_result":
+        n += tokenizer.count(p.content);
+        break;
+      case "image":
+        n += perImage;
+        break;
+    }
+  }
+  return n;
+}
+
+/**
+ * Heuristic tokenizer — `Math.ceil(text.length / 4)`, the canonical
+ * rule-of-thumb for English text. ±15% accuracy; good enough for
+ * rate-limit budgeting and prompt-fit gating, not for exact billing.
+ *
+ * Ships zero deps and works in every runtime (Node, Workers, Bun,
+ * browser). Real tokenizers swap in via the `Tokenizer` interface
+ * without changing call sites.
+ *
+ * @deprecated AI-R3. Token truth comes back in the provider response — read
+ * `CompleteResult.usage`. Use this only as a pre-call estimate; the standalone
+ * `estimateTokens` / `estimateMessageTokens` helpers are the lighter, honestly-
+ * labelled way to do that without a pluggable-tokenizer subsystem. The
+ * `Tokenizer` interface itself is NOT deprecated — a real tiktoken/claude
+ * tokenizer still implements it.
+ */
+export class HeuristicTokenizer implements Tokenizer {
+  readonly model: string;
+  private readonly charsPerToken: number;
+
+  constructor(opts: { model?: string; charsPerToken?: number } = {}) {
+    this.model = opts.model ?? "heuristic";
+    this.charsPerToken = opts.charsPerToken ?? 4;
+  }
+
+  count(text: string): number {
+    if (!text) return 0;
+    return Math.ceil(text.length / this.charsPerToken);
+  }
+}
+
+const ESTIMATE_CHARS_PER_TOKEN = 4;
+
+/**
+ * Rough pre-call token **estimate** for a single string (`~chars/4`). For
+ * prompt-fit / rate-limit gating *before* a request exists — NOT a billing
+ * figure (the real count is returned by the provider on the response,
+ * `CompleteResult.usage`). ±15%; zero-dep; works in every runtime.
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / ESTIMATE_CHARS_PER_TOKEN);
+}
+
+/**
+ * Rough pre-call token **estimate** for a `Message[]` history — sums text,
+ * tool-use input JSON, tool-result content, plus per-message and per-image
+ * overhead. ESTIMATE ONLY, for prompt-fit gating before the request exists;
+ * read the response `usage` for real counts. (This is the honest replacement
+ * for the deprecated `countMessageTokens`.)
+ */
+export function estimateMessageTokens(
+  messages: Message[],
+  opts: CountMessagesOptions = {},
+): number {
+  const perMessage = opts.perMessageOverhead ?? DEFAULT_PER_MESSAGE_OVERHEAD;
+  const perImage = opts.perImageTokens ?? DEFAULT_PER_IMAGE_TOKENS;
+  let total = 0;
+  for (const msg of messages) {
+    total += perMessage;
+    if (typeof msg.content === "string") {
+      total += estimateTokens(msg.content);
+    } else {
+      for (const p of msg.content) {
+        switch (p.type) {
+          case "text":
+            total += estimateTokens(p.text);
+            break;
+          case "tool_use":
+            total += estimateTokens(p.name);
+            try {
+              total += estimateTokens(JSON.stringify(p.input ?? {}));
+            } catch {
+              total += 16;
+            }
+            break;
+          case "tool_result":
+            total += estimateTokens(p.content);
+            break;
+          case "image":
+            total += perImage;
+            break;
+        }
+      }
+    }
+    if (msg.name) total += estimateTokens(msg.name);
+  }
+  return total;
+}

package/lib/libraries/ai/tools/defineTool.ts

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../types.js";
+
+/**
+ * `defineTool({ name, description, schema, handler })` — the load-bearing
+ * primitive the agent loop dispatches against. Pairs a Zod schema (the
+ * tool's input contract) with a typed handler that consumes the parsed
+ * input.
+ *
+ * Why a factory instead of a class:
+ *   - The handler's input type is inferred from the Zod schema via
+ *     `z.infer<typeof schema>`. A factory carries the inferred type
+ *     through naturally; class generics force the consumer to repeat
+ *     the inference.
+ *   - The factory produces a `Tool` value that satisfies both the
+ *     `ToolDefinition` shape (what providers see) and an `execute`
+ *     surface (what the agent loop calls), without any inheritance
+ *     ceremony.
+ *   - `definition` is computed once at registration time — the
+ *     `zodToJsonSchema` call doesn't run per-invocation.
+ *
+ * The handler receives the parsed input, plus a `ToolContext` carrying
+ * cancellation + caller metadata. Handlers MAY return any JSON-
+ * serializable value; the agent loop stringifies the result back into
+ * a `tool_result` content part. Throwing inside the handler short-
+ * circuits with `isError: true` (visible to the model) — the loop
+ * doesn't crash, it lets the model recover.
+ *
+ * Strictness: by default, schema parsing is strict (extra keys throw)
+ * to catch model output drift early. Pass `strict: false` to switch
+ * to lenient parsing if a provider tends to wrap or annotate fields.
+ */
+
+export interface ToolContext {
+  /** Caller-supplied abort signal. Honored by long-running handlers. */
+  signal?: AbortSignal;
+  /**
+   * Free-form caller metadata. The agent loop forwards what it was
+   * called with — typical contents: `{ requestId, userId }`.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+export type ToolHandler<TInput, TOutput = unknown> = (
+  input: TInput,
+  ctx: ToolContext,
+) => TOutput | Promise<TOutput>;
+
+export interface DefineToolOptions<TSchema extends z.ZodTypeAny, TOutput> {
+  /** Stable name. Models reference tools by name; keep it snake_case. */
+  name: string;
+  /**
+   * One-line description shown to the model. The model uses this to
+   * decide *when* to call the tool — make it precise. Bad: "Get data."
+   * Good: "Look up the current weather forecast for a single city."
+   */
+  description: string;
+  /**
+   * Zod schema for the tool's input. Object schemas are strongly
+   * recommended (providers expect JSON Schema with `type: "object"`).
+   */
+  schema: TSchema;
+  /**
+   * Receives the parsed input + a `ToolContext`. Return value is
+   * stringified back to the model as the tool result; throwing produces
+   * an `isError: true` tool_result the model can see and recover from.
+   */
+  handler: ToolHandler<z.infer<TSchema>, TOutput>;
+  /**
+   * Strict parsing (extra keys throw). Default true — catches model
+   * output drift early. Set false for permissive providers.
+   */
+  strict?: boolean;
+}
+
+export interface Tool<TSchema extends z.ZodTypeAny = z.ZodTypeAny, TOutput = unknown> {
+  name: string;
+  description: string;
+  schema: TSchema;
+  /** JSON Schema view used by `LLMProvider` adapters. Built once at registration. */
+  definition: ToolDefinition;
+  /**
+   * Run the tool with raw provider-supplied input. Validates against the
+   * Zod schema first; on validation failure returns `{ ok: false,
+   * isError: true, content }` with the Zod issue path so the model can
+   * see what was wrong.
+   *
+   * On handler success: `{ ok: true, output }` with the raw return
+   * value. The agent loop is responsible for serializing `output` for
+   * the `tool_result` content part.
+   *
+   * On handler throw: `{ ok: false, isError: true, content }` with the
+   * error message — *not* re-thrown, so the loop survives and the model
+   * can decide whether to retry.
+   */
+  execute(input: unknown, ctx: ToolContext): Promise<ToolExecuteResult<TOutput>>;
+}
+
+export type ToolExecuteResult<TOutput> =
+  | { ok: true; output: TOutput }
+  | { ok: false; isError: true; content: string };
+
+export function defineTool<TSchema extends z.ZodTypeAny, TOutput>(
+  opts: DefineToolOptions<TSchema, TOutput>,
+): Tool<TSchema, TOutput> {
+  const inputSchema = z.toJSONSchema(opts.schema, {
+    target: "draft-2020-12",
+  }) as Record<string, unknown>;
+  // Strip the $schema header so providers (which don't expect it) accept the schema.
+  delete inputSchema["$schema"];
+
+  const definition: ToolDefinition = {
+    name: opts.name,
+    description: opts.description,
+    inputSchema,
+  };
+
+  const strict = opts.strict ?? true;
+
+  return {
+    name: opts.name,
+    description: opts.description,
+    schema: opts.schema,
+    definition,
+    async execute(input: unknown, ctx: ToolContext): Promise<ToolExecuteResult<TOutput>> {
+      const parsed = strict ? opts.schema.safeParse(input) : opts.schema.safeParse(input ?? {});
+      if (!parsed.success) {
+        return {
+          ok: false,
+          isError: true,
+          content: formatZodIssues(parsed.error.issues),
+        };
+      }
+      try {
+        const output = await opts.handler(parsed.data as z.infer<TSchema>, ctx);
+        return { ok: true, output };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err ?? "unknown error");
+        return {
+          ok: false,
+          isError: true,
+          content: `tool "${opts.name}" failed: ${message}`,
+        };
+      }
+    },
+  };
+}
+
+interface ZodLikeIssue {
+  path?: Array<string | number>;
+  message: string;
+}
+
+function formatZodIssues(issues: readonly ZodLikeIssue[]): string {
+  if (!issues.length) return "validation failed";
+  return issues
+    .map((issue) => {
+      const path = (issue.path ?? []).join(".") || "(root)";
+      return `${path}: ${issue.message}`;
+    })
+    .join("; ");
+}
+
+/**
+ * `ToolRegistry` — ordered map keyed by tool name, with lookup helpers
+ * the agent loop needs (`getDefinitions()` for the provider request,
+ * `lookup(name)` for dispatch). Constructible standalone (tests) or via
+ * the convenience `toolRegistry(...tools)` factory.
+ */
+export class ToolRegistry {
+  private readonly tools = new Map<string, Tool<z.ZodTypeAny, unknown>>();
+
+  constructor(tools: ReadonlyArray<Tool<z.ZodTypeAny, unknown>> = []) {
+    for (const tool of tools) this.add(tool);
+  }
+
+  add(tool: Tool<z.ZodTypeAny, unknown>): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`ToolRegistry: duplicate tool name "${tool.name}"`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  lookup(name: string): Tool<z.ZodTypeAny, unknown> | undefined {
+    return this.tools.get(name);
+  }
+
+  /** Tool definitions the agent loop attaches to provider requests. */
+  getDefinitions(): ToolDefinition[] {
+    return Array.from(this.tools.values()).map((t) => t.definition);
+  }
+
+  size(): number {
+    return this.tools.size;
+  }
+
+  list(): ReadonlyArray<Tool<z.ZodTypeAny, unknown>> {
+    return Array.from(this.tools.values());
+  }
+}
+
+export function toolRegistry(...tools: Array<Tool<z.ZodTypeAny, unknown>>): ToolRegistry {
+  return new ToolRegistry(tools);
+}