okengine 0.22.0 → 0.23.1

package/src/elements/ai/decisions/openrouter.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenRouter Decisions driver. `POST https://openrouter.ai/api/alpha/decisions`.
+ */
+
+import { decisionHttp } from "./http.ts";
+import type { DecisionProvider, DecisionRequest, DecisionResponse } from "./provider.ts";
+
+/** Default OpenRouter decisions URL. */
+export const OPENROUTER_DECISION_URL = "https://openrouter.ai/api/alpha/decisions";
+
+/** Default Jev model id on OpenRouter. */
+export const OPENROUTER_JEV_MODEL = "typesafe/jev-1.13";
+
+/**
+ * OpenRouter decision provider. This is the default when a decision omits `model`.
+ *
+ * @param apiKey - `OPENROUTER_API_KEY`
+ * @param timeoutMs - Provider deadline
+ */
+export function createOpenRouterDecisionProvider(
+  apiKey: string,
+  timeoutMs = 30_000,
+): DecisionProvider {
+  return {
+    id: "openrouter",
+    evaluate(request: DecisionRequest): Promise<DecisionResponse> {
+      return decisionHttp({
+        url: OPENROUTER_DECISION_URL,
+        apiKey,
+        request: { ...request, model: request.model || OPENROUTER_JEV_MODEL },
+        timeoutMs,
+        breakerKey: "openrouter",
+      });
+    },
+  };
+}

package/src/elements/ai/decisions/provider.ts

@@ -0,0 +1,102 @@
+/**
+ * Decision provider contract. Chat drivers stay on {@link AiDriverId}.
+ * Boolean questions are `noul` on the wire.
+ */
+
+/** Wire question sent in one batched request. */
+export type WireQuestion =
+  | {
+      readonly type: "choice";
+      readonly instructions: string;
+      readonly criteria: Readonly<Record<string, string | null>>;
+    }
+  | {
+      readonly type: "score";
+      readonly instructions: string;
+      readonly criteria: readonly string[];
+    }
+  | {
+      readonly type: "noul";
+      readonly instructions: string;
+      readonly criteria?: { readonly true?: string; readonly false?: string };
+    };
+
+/** One provider call. */
+export interface DecisionRequest {
+  readonly model: string;
+  readonly state: unknown;
+  readonly questions: Readonly<Record<string, WireQuestion>>;
+  readonly signal?: AbortSignal;
+}
+
+/** Token usage reported by the provider. */
+export interface DecisionUsage {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly cost?: number;
+}
+
+/** Parsed provider body. `model` is the resolved version. */
+export interface DecisionResponse {
+  readonly model: string;
+  readonly provider?: string;
+  readonly answers: Readonly<Record<string, unknown>>;
+  readonly usage: DecisionUsage;
+}
+
+/** Driver id for a decision provider. */
+export type DecisionDriverId = "typesafe" | "openrouter";
+
+/**
+ * One System One decision call.
+ */
+export interface DecisionProvider {
+  readonly id: DecisionDriverId;
+  /**
+   * Evaluate every question against `state` in one request.
+   *
+   * @param request - Model, state, and questions
+   */
+  evaluate(request: DecisionRequest): Promise<DecisionResponse>;
+}
+
+/** Statuses that are the caller's problem. They do not open the breaker. */
+export type DecisionRequestStatus = 400 | 401 | 402 | 403 | 404 | 422;
+
+/** Auth, billing, or a body the provider rejected. Does not open the breaker. */
+export class DecisionRequestError extends Error {
+  readonly status: DecisionRequestStatus;
+  /**
+   * @param status - HTTP status
+   * @param message - Provider body, truncated by the caller
+   */
+  constructor(status: DecisionRequestStatus, message: string) {
+    super(message);
+    this.name = "DecisionRequestError";
+    this.status = status;
+  }
+}
+
+/** The decision is missing a configured secret. Not an outage. */
+export class DecisionConfigError extends Error {
+  readonly secret: string;
+  /**
+   * @param secret - Secret contract name
+   */
+  constructor(secret: string) {
+    super(`fx.decide: secret "${secret}" is not configured`);
+    this.name = "DecisionConfigError";
+    this.secret = secret;
+  }
+}
+
+/** The breaker is open. Callers take the non-auto path. */
+export class DecisionOutageError extends Error {
+  /**
+   * @param message - Why the call was not sent
+   */
+  constructor(message: string) {
+    super(message);
+    this.name = "DecisionOutageError";
+  }
+}

package/src/elements/ai/decisions/typesafe.ts

@@ -0,0 +1,36 @@
+/**
+ * TypeSafe System One driver. `POST https://api.typesafe.ai/v1/systemone`.
+ */
+
+import { decisionHttp } from "./http.ts";
+import type { DecisionProvider, DecisionRequest, DecisionResponse } from "./provider.ts";
+
+/** Default TypeSafe evaluation URL. */
+export const TYPESAFE_DECISION_URL = "https://api.typesafe.ai/v1/systemone";
+
+/** Pinned Jev version when the author selects the TypeSafe driver. */
+export const TYPESAFE_JEV_MODEL = "jev-1.13.0";
+
+/**
+ * TypeSafe decision provider.
+ *
+ * @param apiKey - `TYPESAFE_API_KEY`
+ * @param timeoutMs - Provider deadline
+ */
+export function createTypesafeDecisionProvider(
+  apiKey: string,
+  timeoutMs = 30_000,
+): DecisionProvider {
+  return {
+    id: "typesafe",
+    evaluate(request: DecisionRequest): Promise<DecisionResponse> {
+      return decisionHttp({
+        url: TYPESAFE_DECISION_URL,
+        apiKey,
+        request: { ...request, model: request.model || TYPESAFE_JEV_MODEL },
+        timeoutMs,
+        breakerKey: "typesafe",
+      });
+    },
+  };
+}

package/src/elements/ai/declare.ts

@@ -6,6 +6,7 @@
 
 import {
   aiAgentRegistry,
+  aiDecisionRegistry,
   aiEmbedRegistry,
   aiMcpServerRegistry,
   aiModelRegistry,
@@ -53,6 +54,8 @@ export interface AiPromptOptions {
   readonly version?: number;
   readonly evals?: string;
   readonly budget?: AiBudgetDecl;
+  /** One schema-mismatch retry. Default `0` throws on the first mismatch. */
+  readonly repair?: 0 | 1;
   /**
    * Ordered recovery chain of logical model names for this command.
    * Resolved as `ask.via ?? prompt.via ?? [prompt.model]`.
@@ -70,11 +73,103 @@ export interface AiEmbedOptions {
   readonly into?: { readonly name: string; readonly facet?: string } | string;
 }
 
+/** Who may have to approve one agent tool before it runs. */
+export type AiToolApproval =
+  | boolean
+  | ((input: unknown, ctx: { readonly auth?: unknown; readonly tenant?: unknown }) => boolean);
+
+/** One agent tool, optionally held for approval. */
+export interface AiAgentToolOptions {
+  readonly name: string;
+  /** `true` always waits. A function waits only when it returns true. */
+  readonly approval?: AiToolApproval;
+  /** Gate that may approve or deny. Required when {@link approval} is set. */
+  readonly gate?: { readonly name: string } | string;
+  /** How long to wait before a deny. Default `24h`. */
+  readonly timeout?: string;
+}
+
+/**
+ * Choice answer a Flow can receive. Author keys, plus `none_of_these`.
+ *
+ * @typeParam Options - Author option map
+ */
+export type DecisionChoiceValue<Options extends Readonly<Record<string, string | null>>> =
+  | keyof Options
+  | "none_of_these";
+
+/** One choice question. `none_of_these` is injected on the wire. */
+export interface AiChoiceQuestion {
+  readonly kind: "choice";
+  readonly instructions: string;
+  readonly options: Readonly<Record<string, string | null>>;
+}
+
+/** One ordered score question. */
+export interface AiScoreQuestion {
+  readonly kind: "score";
+  readonly instructions: string;
+  readonly levels: readonly string[];
+}
+
+/** One yes/no question. The wire type is `noul`. */
+export interface AiBooleanQuestion {
+  readonly kind: "boolean";
+  readonly instructions: string;
+  readonly criteria?: { readonly true?: string; readonly false?: string };
+}
+
+/** A question inside `ai.decision({ ask })`. */
+export type AiDecisionQuestion = AiChoiceQuestion | AiScoreQuestion | AiBooleanQuestion;
+
+/** Autonomy grant. Present only in the lockfile's certificate. */
+export interface AiDecisionAutonomy {
+  readonly maxError: number;
+  /** Audit sample rate in `[0, 1]`. Required whenever autonomy is set. */
+  readonly audit: number;
+  /** Learn-then-Test family-wise level. Default `0.1`. */
+  readonly risk?: number;
+}
+
+/** Options for {@link ai.decision}. Exactly one of `review` and `onUncertain` is required. */
+export interface AiDecisionOptions {
+  readonly model?: AiModelDecl | string;
+  readonly in?: unknown;
+  readonly ask: Readonly<Record<string, AiDecisionQuestion>>;
+  readonly autonomy?: AiDecisionAutonomy;
+  readonly review?: { readonly name: string } | string;
+  readonly onUncertain?: "abstain";
+  readonly locale?: (input: unknown) => string | undefined;
+  readonly evals?: string;
+  /** `openrouter` (default) or `typesafe`. */
+  readonly driverId?: "openrouter" | "typesafe";
+  readonly timeout?: AiTimeout;
+}
+
+/** Declared decision handle. */
+export interface AiDecisionDecl {
+  readonly kind: "decision";
+  readonly name: string;
+  readonly ask: Readonly<Record<string, AiDecisionQuestion>>;
+  readonly mode: "review" | "abstain";
+  readonly review?: string;
+  readonly model?: string;
+  readonly driverId: "openrouter" | "typesafe";
+  readonly autonomy?: AiDecisionAutonomy;
+  readonly evals?: string;
+  readonly timeout?: AiTimeout;
+  readonly locale?: (input: unknown) => string | undefined;
+  /** Declared `in` schema. Label export keeps only these fields. */
+  readonly inputSchema?: unknown;
+}
+
 /** Options for {@link ai.agent}. */
 export interface AiAgentOptions {
   readonly model?: AiModelDecl | string;
-  readonly tools?: readonly ({ readonly name: string } | string)[];
+  readonly tools?: readonly (AiAgentToolOptions | { readonly name: string } | string)[];
   readonly maxSteps?: number;
+  /** Nested agent depth. Default 3. */
+  readonly maxDepth?: number;
   readonly budget?: AiBudgetDecl;
 }
 
@@ -104,6 +199,8 @@ export interface AiPromptDecl {
   readonly version?: number;
   readonly evals?: string;
   readonly budget?: AiBudgetDecl;
+  /** One schema-mismatch retry. Default `0`. */
+  readonly repair?: 0 | 1;
   readonly via?: readonly string[];
   readonly timeout?: AiTimeout;
   readonly model?: string;
@@ -119,12 +216,24 @@ export interface AiEmbedDecl {
   readonly into?: string;
 }
 
+/** Approval held on one tool. The predicate stays in code. */
+export interface AiAgentApprovalDecl {
+  readonly gate: string;
+  readonly timeout: string;
+  readonly when?: (
+    input: unknown,
+    ctx: { readonly auth?: unknown; readonly tenant?: unknown },
+  ) => boolean;
+}
+
 /** Declared agent whose tools are flows. */
 export interface AiAgentDecl {
   readonly kind: "agent";
   readonly name: string;
   readonly tools: readonly string[];
+  readonly approvals?: Readonly<Record<string, AiAgentApprovalDecl>>;
   readonly maxSteps?: number;
+  readonly maxDepth?: number;
   readonly model?: string;
   readonly budget?: AiBudgetDecl;
 }
@@ -186,6 +295,10 @@ function toolName(tool: { readonly name: string } | string): string {
   return typeof tool === "string" ? tool : tool.name;
 }
 
+function gateName(gate: { readonly name: string } | string): string {
+  return typeof gate === "string" ? gate : gate.name;
+}
+
 /**
  * Shape of the {@link ai} element namespace.
  */
@@ -211,6 +324,37 @@ export interface AiNamespace {
    * @param options - Tools / maxSteps / model / budget
    */
   agent(name: string, options?: AiAgentOptions): AiAgentDecl;
+  /**
+   * Declare a decision. Exactly one of `review` and `onUncertain: "abstain"`.
+   *
+   * @param name - Decision id
+   * @param options - Questions, mode, and optional autonomy
+   */
+  decision(name: string, options: AiDecisionOptions): AiDecisionDecl;
+  /**
+   * A choice question. The answer union is {@link DecisionChoiceValue}: author keys or `none_of_these`.
+   *
+   * @param instructions - What to decide
+   * @param options - At most 254 author options
+   */
+  choice(instructions: string, options: Readonly<Record<string, string | null>>): AiChoiceQuestion;
+  /**
+   * An ordered score question.
+   *
+   * @param instructions - What to rate
+   * @param levels - 2–10 level descriptions, low to high
+   */
+  score(instructions: string, levels: readonly string[]): AiScoreQuestion;
+  /**
+   * A yes/no question. Sent as `noul`.
+   *
+   * @param instructions - The yes/no question
+   * @param criteria - Optional true/false descriptions
+   */
+  boolean(
+    instructions: string,
+    criteria?: { readonly true?: string; readonly false?: string },
+  ): AiBooleanQuestion;
   /**
    * Declare an external MCP server whose allowlisted tools join `fx.call`.
    *
@@ -228,6 +372,7 @@ export function listAiDecls(): {
   readonly prompts: readonly AiPromptDecl[];
   readonly embeds: readonly AiEmbedDecl[];
   readonly agents: readonly AiAgentDecl[];
+  readonly decisions: readonly AiDecisionDecl[];
   readonly mcpServers: readonly AiMcpServerDecl[];
 } {
   return {
@@ -235,6 +380,7 @@ export function listAiDecls(): {
     prompts: aiPromptRegistry.slice(),
     embeds: aiEmbedRegistry.slice(),
     agents: aiAgentRegistry.slice(),
+    decisions: aiDecisionRegistry.slice(),
     mcpServers: aiMcpServerRegistry.slice(),
   };
 }
@@ -247,6 +393,7 @@ export function resetAiDecls(): void {
   aiPromptRegistry.length = 0;
   aiEmbedRegistry.length = 0;
   aiAgentRegistry.length = 0;
+  aiDecisionRegistry.length = 0;
   aiMcpServerRegistry.length = 0;
 }
 
@@ -290,6 +437,7 @@ export const ai: AiNamespace = {
           ...(promptOpts.version !== undefined ? { version: promptOpts.version } : {}),
           ...(promptOpts.evals !== undefined ? { evals: promptOpts.evals } : {}),
           ...(promptOpts.budget !== undefined ? { budget: promptOpts.budget } : {}),
+          ...(promptOpts.repair !== undefined ? { repair: promptOpts.repair } : {}),
           ...(promptOpts.via !== undefined ? { via: promptOpts.via } : {}),
           ...(promptOpts.timeout !== undefined ? { timeout: promptOpts.timeout } : {}),
           ...(promptOpts.in !== undefined ? { in: promptOpts.in } : {}),
@@ -329,11 +477,28 @@ export const ai: AiNamespace = {
    * @param options - Tools / maxSteps / model / budget
    */
   agent(name: string, options: AiAgentOptions = {}): AiAgentDecl {
+    const approvals: Record<string, AiAgentApprovalDecl> = {};
+    for (const tool of options.tools ?? []) {
+      if (typeof tool === "string" || !("approval" in tool) || tool.approval === undefined) {
+        continue;
+      }
+      if (tool.approval === false) continue;
+      if (tool.gate === undefined) {
+        throw new TypeError(`ai.agent("${name}"): tool "${toolName(tool)}" approval requires gate`);
+      }
+      approvals[toolName(tool)] = {
+        gate: gateName(tool.gate),
+        timeout: tool.timeout ?? "24h",
+        ...(typeof tool.approval === "function" ? { when: tool.approval } : {}),
+      };
+    }
     const decl: AiAgentDecl = {
       kind: "agent",
       name,
       tools: (options.tools ?? []).map(toolName),
+      ...(Object.keys(approvals).length > 0 ? { approvals } : {}),
       ...(options.maxSteps !== undefined ? { maxSteps: options.maxSteps } : {}),
+      ...(options.maxDepth !== undefined ? { maxDepth: options.maxDepth } : {}),
       ...(options.budget !== undefined ? { budget: options.budget } : {}),
       ...(typeof options.model === "string"
         ? { model: options.model }
@@ -345,6 +510,27 @@ export const ai: AiNamespace = {
     return decl;
   },
 
+  decision(name: string, options: AiDecisionOptions): AiDecisionDecl {
+    const decl = buildDecisionDecl(name, options);
+    aiDecisionRegistry.push(decl);
+    return decl;
+  },
+
+  choice(instructions: string, options: Readonly<Record<string, string | null>>): AiChoiceQuestion {
+    return { kind: "choice", instructions, options };
+  },
+
+  score(instructions: string, levels: readonly string[]): AiScoreQuestion {
+    return { kind: "score", instructions, levels };
+  },
+
+  boolean(
+    instructions: string,
+    criteria?: { readonly true?: string; readonly false?: string },
+  ): AiBooleanQuestion {
+    return { kind: "boolean", instructions, ...(criteria !== undefined ? { criteria } : {}) };
+  },
+
   /**
    * Declare an external MCP server whose allowlisted tools join `fx.call`.
    *
@@ -386,3 +572,68 @@ export const ai: AiNamespace = {
     return decl;
   },
 };
+
+/**
+ * Validate a decision and return the registered shape.
+ *
+ * @param name - Decision id
+ * @param options - Author options
+ */
+export function buildDecisionDecl(name: string, options: AiDecisionOptions): AiDecisionDecl {
+  if (!name) throw new TypeError("ai.decision: name is required");
+  const keys = Object.keys(options.ask ?? {});
+  if (keys.length === 0) throw new TypeError(`ai.decision("${name}"): ask is empty`);
+  const hasReview = options.review !== undefined;
+  const abstain = options.onUncertain === "abstain";
+  if (hasReview === abstain) {
+    throw new TypeError(
+      `ai.decision("${name}"): declare exactly one of review or onUncertain: "abstain"`,
+    );
+  }
+  if (options.autonomy !== undefined && options.autonomy.audit === undefined) {
+    throw new TypeError(`ai.decision("${name}"): autonomy requires audit`);
+  }
+  for (const key of keys) {
+    if (key === "meta" || key === "$") {
+      throw new TypeError(`ai.decision("${name}"): question id "${key}" is reserved`);
+    }
+    const question = options.ask[key];
+    if (!question) continue;
+    if (question.kind === "choice") {
+      const count = Object.keys(question.options).length;
+      if (count > 254) {
+        throw new TypeError(
+          `ai.decision("${name}"): choice "${key}" has ${count} options; max 254`,
+        );
+      }
+      if (Object.prototype.hasOwnProperty.call(question.options, "none_of_these")) {
+        throw new TypeError(`ai.decision("${name}"): choice "${key}" must not set none_of_these`);
+      }
+    }
+    if (question.kind === "score") {
+      const count = question.levels.length;
+      if (count < 2 || count > 10) {
+        throw new TypeError(`ai.decision("${name}"): score "${key}" needs 2–10 levels`);
+      }
+    }
+  }
+  const review = typeof options.review === "string" ? options.review : options.review?.name;
+  const model =
+    typeof options.model === "string"
+      ? options.model
+      : (options.model?.model ?? options.model?.name);
+  return {
+    kind: "decision",
+    name,
+    ask: options.ask,
+    mode: abstain ? "abstain" : "review",
+    ...(review !== undefined ? { review } : {}),
+    ...(model !== undefined ? { model } : {}),
+    driverId: options.driverId ?? "openrouter",
+    ...(options.autonomy !== undefined ? { autonomy: options.autonomy } : {}),
+    ...(options.evals !== undefined ? { evals: options.evals } : {}),
+    ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+    ...(options.locale !== undefined ? { locale: options.locale } : {}),
+    ...(options.in !== undefined ? { inputSchema: options.in } : {}),
+  };
+}