okengine 0.5.0 → 0.6.0

package/src/drivers/ai-types.ts

@@ -14,14 +14,33 @@ export type AiDriverId =
   | "vertex"
   | "ollama";
 
+/** Tool definition offered to a model (Flow-backed at the fx layer). */
+export interface AiToolDef {
+  readonly name: string;
+  readonly description?: string;
+  /** JSON-schema-like parameters object. */
+  readonly parameters?: unknown;
+}
+
+/** One model-initiated tool invocation. */
+export interface AiToolCall {
+  readonly id: string;
+  readonly name: string;
+  readonly arguments: unknown;
+}
+
 /** One chat / completion turn. */
 export interface AiMessage {
   readonly role: "system" | "user" | "assistant" | "tool";
   readonly content: string;
   readonly name?: string;
+  /** When role is `tool`, the id of the tool call this message answers. */
+  readonly toolCallId?: string;
+  /** When role is `assistant`, optional tool calls the model requested. */
+  readonly toolCalls?: readonly AiToolCall[];
 }
 
-/** Options for a model completion. */
+/** Options for a model completion (or stream start). */
 export interface AiCompleteOptions {
   readonly messages: readonly AiMessage[];
   readonly model?: string;
@@ -29,6 +48,10 @@ export interface AiCompleteOptions {
   readonly maxTokens?: number;
   /** Structured output hint (JSON schema or name). */
   readonly responseFormat?: unknown;
+  /** Tools the model may call (OpenAI-shaped; drivers map). */
+  readonly tools?: readonly AiToolDef[];
+  /** Ambient / local abort — cooperative cancellation for complete + stream. */
+  readonly signal?: AbortSignal;
 }
 
 /** Result of a model completion. */
@@ -37,6 +60,7 @@ export interface AiCompleteResult {
   readonly raw?: unknown;
   readonly model: string;
   readonly driverId: AiDriverId;
+  readonly toolCalls?: readonly AiToolCall[];
   readonly usage?: {
     readonly inputTokens?: number;
     readonly outputTokens?: number;
@@ -44,6 +68,12 @@ export interface AiCompleteResult {
   };
 }
 
+/** One streamed token / delta from a model. */
+export interface AiStreamChunk {
+  readonly text: string;
+  readonly done?: boolean;
+}
+
 /** Embedding request. */
 export interface AiEmbedOptions {
   readonly input: string | readonly string[];
@@ -62,6 +92,12 @@ export interface AiModelClient {
   readonly driverId: AiDriverId;
   readonly model: string;
   complete(options: AiCompleteOptions): Promise<AiCompleteResult>;
+  /**
+   * Stream tokens. Optional — callers fail loud when missing (no stub echo).
+   *
+   * @param options - Same as complete, plus optional signal
+   */
+  stream?(options: AiCompleteOptions): AsyncIterable<AiStreamChunk>;
   embed?(options: AiEmbedOptions): Promise<AiEmbedResult>;
   close?(): Promise<void>;
 }
@@ -71,6 +107,11 @@ export interface AiOpenOptions {
   readonly model?: string;
   readonly apiKey?: string;
   readonly baseUrl?: string;
+  /**
+   * Extra HTTP headers (e.g. OpenRouter `HTTP-Referer` / `X-Title`).
+   * Merged into chat and embed requests; does not invent a new driver.
+   */
+  readonly headers?: Readonly<Record<string, string>>;
   /** Mock canned responses keyed by prompt name or substring. */
   readonly mockResponses?: Readonly<Record<string, unknown>>;
   readonly fetch?: typeof globalThis.fetch;

package/src/drivers/channel-smtp.ts

@@ -1,7 +1,8 @@
 /**
- * `smtp` channel driver — wraps sently's SMTP transport unchanged.
+ * `smtp` channel driver — wraps sently's SMTP transport with the Bun socket adapter.
  */
 
+import { BunAdapter } from "sently/adapters/bun";
 import { SMTPTransport } from "sently/transports/smtp";
 import type { ChannelDriver, ChannelOpenOptions } from "./channel-types.ts";
 
@@ -14,9 +15,14 @@ export function openSmtpChannel(options: ChannelOpenOptions = {}): ChannelDriver
   if (!options.host) {
     throw new Error("smtp channel: host is required");
   }
+  const port = options.port ?? 587;
+  // Implicit TLS only on the classic SMTPS port; Mailpit / local relays are plain.
+  const secure = port === 465;
   const transport = new SMTPTransport({
     host: options.host,
-    port: options.port ?? 587,
+    port,
+    secure,
+    adapter: new BunAdapter({ secure }),
     ...(options.user && options.pass ? { auth: { user: options.user, pass: options.pass } } : {}),
   });
   return { id: "smtp", transport };

package/src/drivers/index.ts

@@ -147,8 +147,11 @@ export { webpushChannelDriver, openWebPushChannel } from "./channel-webpush.ts";
 export type {
   AiDriverId,
   AiMessage,
+  AiToolDef,
+  AiToolCall,
   AiCompleteOptions,
   AiCompleteResult,
+  AiStreamChunk,
   AiEmbedOptions,
   AiEmbedResult,
   AiModelClient,
@@ -158,4 +161,21 @@ export type {
 
 export { mockAiDriver, createMockAiDriver } from "./ai-mock.ts";
 export { anthropicAiDriver, openAnthropic } from "./ai-anthropic.ts";
-export { openaiCompatibleAiDriver, openOpenaiCompatible } from "./ai-openai-compatible.ts";
+export {
+  openaiCompatibleAiDriver,
+  openOpenaiCompatible,
+  OPENAI_COMPAT_DEFAULT_BASE,
+  normalizeOpenaiCompatibleBaseUrl,
+  isOpenaiCloudBase,
+  openaiCompatibleHeaders,
+} from "./ai-openai-compatible.ts";
+export {
+  ollamaAiDriver,
+  openOllama,
+  OllamaUnavailableError,
+  OLLAMA_DEFAULT_MODEL,
+  OLLAMA_DEFAULT_BASE_URL,
+  normalizeOllamaBaseUrl,
+  resolveOllamaBaseUrl,
+  resolveOllamaModel,
+} from "./ai-ollama.ts";

package/src/drivers/ollama.ts

@@ -0,0 +1,14 @@
+/**
+ * Protocol-named re-export — prefer `okengine/drivers/ai-ollama` or
+ * `okengine/drivers` (`ollamaAiDriver`). Same surface as {@link ./ai-ollama.ts}.
+ */
+export {
+  ollamaAiDriver,
+  openOllama,
+  OllamaUnavailableError,
+  OLLAMA_DEFAULT_MODEL,
+  OLLAMA_DEFAULT_BASE_URL,
+  normalizeOllamaBaseUrl,
+  resolveOllamaBaseUrl,
+  resolveOllamaModel,
+} from "./ai-ollama.ts";

package/src/elements/ai/rate.test.ts

@@ -0,0 +1,53 @@
+/**
+ * AI rate presets — gate.rate only, no parallel budgeting system.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { memoryKvDriver } from "../../drivers/index.ts";
+import { createGateRuntime } from "../gate.ts";
+import { AI_RATE_PRESETS, aiRateGate, createAiRateGates } from "./rate.ts";
+
+describe("AI_RATE_PRESETS", () => {
+  test("ask is stricter than embed; agent is strictest", () => {
+    expect(AI_RATE_PRESETS.ask).toEqual({ max: 20, per: "1m", keyBy: "user" });
+    expect(AI_RATE_PRESETS.agent).toEqual({ max: 10, per: "1m", keyBy: "user" });
+    expect(AI_RATE_PRESETS.embed).toEqual({ max: 60, per: "1m", keyBy: "user" });
+    expect(AI_RATE_PRESETS.agent.max).toBeLessThan(AI_RATE_PRESETS.ask.max);
+    expect(AI_RATE_PRESETS.ask.max).toBeLessThan(AI_RATE_PRESETS.embed.max);
+  });
+
+  test("aiRateGate builds a real gate.rate decl", () => {
+    const g = aiRateGate("ask");
+    expect(g.kind).toBe("rate");
+    expect(g.max).toBe(20);
+    expect(g.per).toBe("1m");
+    expect(g.keyBy).toBe("user");
+    expect(g.name).toContain("20/1m");
+  });
+
+  test("createAiRateGates materializes three decls; deny after max", async () => {
+    const kv = await memoryKvDriver.open({ name: "ai-rate" });
+    const gates = createAiRateGates();
+    expect(gates).toHaveLength(3);
+    const runtime = createGateRuntime({ gates: [...gates], kv, now: () => 1_000 });
+    const ask = gates[0]!;
+    const ctx = {
+      auth: { userId: "u1", scopes: new Set<string>() },
+      operator: { id: null },
+      meta: {},
+    };
+    for (let i = 0; i < ask.max; i++) {
+      const ev = await runtime.check([ask.name], ctx);
+      expect(ev.every((e) => e.allowed)).toBe(true);
+    }
+    const denied = await runtime.check([ask.name], ctx);
+    expect(denied.some((e) => !e.allowed)).toBe(true);
+    await kv.close();
+  });
+
+  test("public AI edge can override keyBy to ip", () => {
+    const g = aiRateGate("ask", { keyBy: "ip", max: 5 });
+    expect(g.keyBy).toBe("ip");
+    expect(g.max).toBe(5);
+  });
+});

package/src/elements/ai/rate.ts

@@ -0,0 +1,66 @@
+/**
+ * AI rate-limit presets — reuse {@link gate.rate}, no parallel budgeting.
+ *
+ * Cost caps stay on prompt/agent `budget` decls. These presets throttle
+ * request volume on HTTP triggers that wrap `fx.ask` / agents / embeds.
+ */
+
+import { gate, type RateGateDecl } from "../gate/declare.ts";
+
+/** Preset keys for AI-facing HTTP edges. */
+export type AiRatePreset = "ask" | "agent" | "embed";
+
+/** One AI rate preset row. */
+export type AiRatePresetSpec = {
+  readonly max: number;
+  readonly per: string;
+  readonly keyBy: string;
+};
+
+/**
+ * Sensible defaults: AI calls are far more expensive per request than
+ * ordinary HTTP, so limits are tighter than typical API rate limits.
+ * Prefer `keyBy: "user"` when the edge is authenticated; use `ip` on
+ * public unauthenticated AI surfaces.
+ */
+export const AI_RATE_PRESETS: Readonly<Record<AiRatePreset, AiRatePresetSpec>> = {
+  ask: { max: 20, per: "1m", keyBy: "user" },
+  agent: { max: 10, per: "1m", keyBy: "user" },
+  embed: { max: 60, per: "1m", keyBy: "user" },
+};
+
+/**
+ * Build a `gate.rate` declaration from an AI preset.
+ *
+ * @param kind - ask · agent · embed
+ * @param overrides - Optional max / per / keyBy overrides
+ */
+export function aiRateGate(
+  kind: AiRatePreset,
+  overrides?: {
+    readonly max?: number;
+    readonly per?: string;
+    readonly keyBy?: string;
+    readonly description?: string;
+  },
+): RateGateDecl {
+  const preset = AI_RATE_PRESETS[kind];
+  return gate.rate({
+    max: overrides?.max ?? preset.max,
+    per: overrides?.per ?? preset.per,
+    keyBy: overrides?.keyBy ?? preset.keyBy,
+    description:
+      overrides?.description ??
+      `AI ${kind} rate limit (${overrides?.max ?? preset.max}/${overrides?.per ?? preset.per})`,
+  });
+}
+
+/**
+ * Materialize all AI rate gate decls (ask + agent + embed).
+ *
+ * @param enabled - When false, returns []
+ */
+export function createAiRateGates(enabled = true): readonly RateGateDecl[] {
+  if (!enabled) return [];
+  return [aiRateGate("ask"), aiRateGate("agent"), aiRateGate("embed")];
+}

package/src/elements/ai/redacted-prompt.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Redacted values must never leak into provider-facing prompt content.
+ * Same class of protection as fx.log — AI prompts are an egress vector.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { AiCompleteOptions, AiModelClient } from "../../drivers/ai-types.ts";
+import { REDACTED_PLACEHOLDER, Redacted } from "../../kernel/redacted.ts";
+import { ai, createAiRuntime, promptContentFromInput } from "../ai.ts";
+
+describe("Redacted never leaks into AI prompts", () => {
+  test("promptContentFromInput masks nested Redacted to placeholder", () => {
+    const secret = new Redacted("sk-live-super-secret");
+    const content = promptContentFromInput({
+      key: secret,
+      nested: { token: secret },
+      note: `billing with ${secret}`,
+    });
+    expect(content).toContain(REDACTED_PLACEHOLDER);
+    expect(content).not.toContain("sk-live-super-secret");
+  });
+
+  test("ask sends placeholder to the model — never cleartext", async () => {
+    const secret = new Redacted("vault-stripe-key-REAL");
+    const captured: AiCompleteOptions[] = [];
+    const client: AiModelClient = {
+      driverId: "mock",
+      model: "smart",
+      async complete(opts) {
+        captured.push(opts);
+        return {
+          text: JSON.stringify({ ok: true }),
+          raw: { ok: true },
+          model: "smart",
+          driverId: "mock",
+        };
+      },
+    };
+
+    const smart = ai.model("smart");
+    const prompt = smart.prompt("secure-ask", { out: { ok: "boolean" } });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [prompt],
+      clients: { smart: client },
+      forceJournal: false,
+    });
+
+    await runtime.ask("secure-ask", {
+      apiKey: secret,
+      nested: [secret],
+      label: `charge ${secret}`,
+    });
+
+    expect(captured).toHaveLength(1);
+    const content = captured[0]!.messages[0]!.content;
+    expect(content).toContain(REDACTED_PLACEHOLDER);
+    expect(content).not.toContain("vault-stripe-key-REAL");
+    expect(JSON.stringify(captured[0]!.messages)).not.toContain("vault-stripe-key-REAL");
+  });
+
+  test("template-string ask input already stringified stays placeholder-only", async () => {
+    const secret = new Redacted("TOP-SECRET-VALUE");
+    const captured: string[] = [];
+    const client: AiModelClient = {
+      driverId: "mock",
+      model: "smart",
+      async complete(opts) {
+        captured.push(opts.messages[0]!.content);
+        return {
+          text: "{}",
+          raw: {},
+          model: "smart",
+          driverId: "mock",
+        };
+      },
+    };
+    const smart = ai.model("smart");
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [smart.prompt("t")],
+      clients: { smart: client },
+      forceJournal: false,
+    });
+
+    await runtime.ask("t", `user said ${secret}`);
+    expect(captured[0]).toBe(`user said ${REDACTED_PLACEHOLDER}`);
+    expect(captured[0]).not.toContain("TOP-SECRET-VALUE");
+  });
+});