okengine 0.5.0 → 0.6.0

package/src/elements/ai.test.ts

@@ -56,13 +56,22 @@ describe("agent gate denial is recorded", () => {
 
     const refund = ai.agent("support", {
       tools: ["bookings.refundBooking"],
-      maxSteps: 2,
+      maxSteps: 1,
+      model: "smart",
     });
 
     const called: string[] = [];
     const runtime = createAiRuntime({
+      models: [ai.model("smart")],
       agents: [refund],
       gates,
+      defaultDriver: createMockAiDriver({
+        "*": {
+          __toolCalls: [
+            { id: "c1", name: "bookings.refundBooking", arguments: { reason: "customer" } },
+          ],
+        },
+      }),
       gatesForFlow: (name) => (name === "bookings.refundBooking" ? ["member"] : []),
       callFlow: async (name) => {
         called.push(name);
@@ -87,8 +96,16 @@ describe("agent gate denial is recorded", () => {
     const member = gate.policy("member", ({ auth }) => !!auth.verified);
     const gates = createGateRuntime({ gates: [member] });
     const runtime = createAiRuntime({
-      agents: [ai.agent("support", { tools: ["bookings.getBooking"], maxSteps: 1 })],
+      models: [ai.model("smart")],
+      agents: [
+        ai.agent("support", { tools: ["bookings.getBooking"], maxSteps: 1, model: "smart" }),
+      ],
       gates,
+      defaultDriver: createMockAiDriver({
+        "*": {
+          __toolCalls: [{ id: "c1", name: "bookings.getBooking", arguments: {} }],
+        },
+      }),
       gatesForFlow: () => ["member"],
       callFlow: async () => ({ booking: "B1" }),
     });
@@ -367,13 +384,20 @@ describe("agent tool trail carries effects; denials are not errors", () => {
     const member = gate.policy("member", ({ auth }) => !!auth.verified);
     const gates = createGateRuntime({ gates: [member] });
     const runtime = createAiRuntime({
+      models: [ai.model("smart")],
       agents: [
         ai.agent("support", {
           tools: ["bookings.refundBooking"],
           maxSteps: 1,
+          model: "smart",
         }),
       ],
       gates,
+      defaultDriver: createMockAiDriver({
+        "*": {
+          __toolCalls: [{ id: "c1", name: "bookings.refundBooking", arguments: {} }],
+        },
+      }),
       gatesForFlow: () => ["member"],
       effectsForFlow: (name) =>
         name === "bookings.refundBooking"

package/src/elements/ai.ts

@@ -25,7 +25,12 @@ export type {
   AiPromptOptions,
 } from "./ai/declare.ts";
 
-export { createAiRuntime, AiSchemaValidationError } from "./ai/runtime.ts";
+export {
+  createAiRuntime,
+  AiSchemaValidationError,
+  promptContentFromInput,
+  AI_DEFAULT_MAX_STEPS,
+} from "./ai/runtime.ts";
 export type {
   AgentDenial,
   AgentRunRecord,
@@ -38,9 +43,13 @@ export type {
   AiJournalEntry,
   AiRuntime,
   AiSchemaMismatch,
+  AiStreamOptions,
   CreateAiRuntimeOptions,
 } from "./ai/runtime.ts";
 
+export { AI_RATE_PRESETS, aiRateGate, createAiRateGates } from "./ai/rate.ts";
+export type { AiRatePreset } from "./ai/rate.ts";
+
 export { assertAllowPiiForAsk, AiPiiBuildError, type PiiAskCheckInput } from "./ai/pii.ts";
 
 export {

package/src/i18n/catalogs/ar.ts

@@ -0,0 +1,67 @@
+/**
+ * Built-in Arabic messages — framework OKE codes + typed failure messages.
+ */
+
+export const builtinAr = {
+  oke: {
+    "1001": {
+      cause: 'التدفق "{flow}" يقرأ "{resource}" دون الإعلان عنه.',
+      fix: 'أضف "{resource}" إلى effects.reads لهذا التدفق.',
+    },
+    "1002": {
+      cause: 'التدفق "{flow}" يكتب "{resource}" دون الإعلان عنه.',
+      fix: 'أضف "{resource}" إلى effects.writes لهذا التدفق.',
+    },
+    "1003": {
+      cause: 'التدفق "{flow}" يُصدِر "{resource}" دون الإعلان عنه.',
+      fix: 'أضف "{resource}" إلى effects.emits لهذا التدفق.',
+    },
+    "1004": {
+      cause: 'التدفق "{flow}" يرسل "{resource}" دون الإعلان عنه.',
+      fix: 'أضف "{resource}" إلى effects.sends لهذا التدفق.',
+    },
+    "1005": {
+      cause: 'التدفق "{flow}" يستدعي النموذج "{resource}" دون الإعلان عنه.',
+      fix: 'أضف "{resource}" إلى effects.asks لهذا التدفق.',
+    },
+    "1006": {
+      cause: 'التدفق "{flow}" يقرأ السر "{resource}" دون الإعلان عنه.',
+      fix: 'أضف "{resource}" إلى effects.secrets لهذا التدفق.',
+    },
+    "1007": {
+      cause: 'التدفق "{flow}" يستدعي التدفق "{resource}" دون الإعلان عنه.',
+      fix: 'أضف "{resource}" إلى effects.calls لهذا التدفق.',
+    },
+    "1042": {
+      cause: 'التدفق "{flow}" يُصدِر الإشارة "{resource}" بلا مشترك.',
+      fix: "أضف on({resource}, …) أو عيّن الإشارة '{'optional: true'}'.",
+    },
+    "1101": {
+      cause: "جدول النطاق غير موجود — لم تُطبَّق الترحيلات.",
+      fix: "شغّل `oke db migrate` على هذه البيئة.",
+    },
+  },
+  errors: {
+    Unauthorized: "المصادقة مطلوبة.",
+    Forbidden: "غير مسموح لك بتنفيذ هذا الإجراء.",
+    RateLimited: "طلبات كثيرة جداً. حاول لاحقاً.",
+    ValidationError: "فشل التحقق من الطلب.",
+    NotFound: "المورد المطلوب غير موجود.",
+    AuthFailed: "فشلت المصادقة.",
+    AuthRateLimited: "محاولات مصادقة كثيرة جداً. حاول لاحقاً.",
+    "AuthFailed.invalid_credentials": "بيانات الاعتماد غير صحيحة.",
+    "AuthFailed.invalid_refresh": "رمز التحديث غير صالح أو منتهٍ.",
+    "AuthFailed.invalid_email": "أدخل بريداً إلكترونياً صالحاً.",
+    "AuthFailed.invalid_phone": "أدخل رقم هاتف صالحاً.",
+    "AuthFailed.unauthenticated": "سجّل الدخول للمتابعة.",
+    "AuthFailed.password_breached": "اختر كلمة مرور أخرى — هذه تظهر في قائمة اختراق.",
+    "AuthFailed.username_policy": "اسم المستخدم لا يستوفي متطلبات السياسة.",
+    "AuthFailed.password_policy": "كلمة المرور لا تستوفي متطلبات السياسة.",
+    "AuthFailed.invalid_origin": "تم رفض أصل مفتاح المرور.",
+    "Forbidden.csrf": "تم حظر الطلب عبر المواقع.",
+    "Forbidden.ip_denied": "عنوان IP الخاص بك محظور.",
+    "Forbidden.ip_not_allowed": "عنوان IP الخاص بك غير مسموح.",
+    "Forbidden.policy_denied": "رفضت السياسة هذا الطلب.",
+    "AuthRateLimited.rate_limited": "محاولات مصادقة كثيرة جداً. حاول لاحقاً.",
+  },
+} as const;

package/src/i18n/catalogs/en.ts

@@ -0,0 +1,68 @@
+/**
+ * Built-in English messages — framework OKE codes + typed failure messages.
+ */
+
+export const builtinEn = {
+  oke: {
+    "1001": {
+      cause: 'Flow "{flow}" reads "{resource}" without declaring it.',
+      fix: "Add \"{resource}\" to this flow''s effects.reads.",
+    },
+    "1002": {
+      cause: 'Flow "{flow}" writes "{resource}" without declaring it.',
+      fix: "Add \"{resource}\" to this flow''s effects.writes.",
+    },
+    "1003": {
+      cause: 'Flow "{flow}" emits "{resource}" without declaring it.',
+      fix: "Add \"{resource}\" to this flow''s effects.emits.",
+    },
+    "1004": {
+      cause: 'Flow "{flow}" sends "{resource}" without declaring it.',
+      fix: "Add \"{resource}\" to this flow''s effects.sends.",
+    },
+    "1005": {
+      cause: 'Flow "{flow}" asks "{resource}" without declaring it.',
+      fix: "Add \"{resource}\" to this flow''s effects.asks.",
+    },
+    "1006": {
+      cause: 'Flow "{flow}" reads secret "{resource}" without declaring it.',
+      fix: "Add \"{resource}\" to this flow''s effects.secrets.",
+    },
+    "1007": {
+      cause: 'Flow "{flow}" calls "{resource}" without declaring it.',
+      fix: "Add \"{resource}\" to this flow''s effects.calls.",
+    },
+    "1042": {
+      cause: 'Flow "{flow}" emits signal "{resource}" with no subscriber.',
+      fix: "Add on({resource}, …) or mark the signal '{'optional: true'}'.",
+    },
+    "1101": {
+      cause: "domain table not found — migrations have not been applied.",
+      fix: "run `oke db migrate` against this environment.",
+    },
+  },
+  errors: {
+    Unauthorized: "Authentication required.",
+    Forbidden: "You are not allowed to perform this action.",
+    RateLimited: "Too many requests. Try again later.",
+    ValidationError: "The request failed validation.",
+    NotFound: "The requested resource was not found.",
+    AuthFailed: "Authentication failed.",
+    AuthRateLimited: "Too many authentication attempts. Try again later.",
+    "AuthFailed.invalid_credentials": "Invalid credentials.",
+    "AuthFailed.invalid_refresh": "Refresh token is invalid or expired.",
+    "AuthFailed.invalid_email": "Enter a valid email address.",
+    "AuthFailed.invalid_phone": "Enter a valid phone number.",
+    "AuthFailed.unauthenticated": "Sign in to continue.",
+    "AuthFailed.password_breached":
+      "Choose a different password — this one appears in a breach list.",
+    "AuthFailed.username_policy": "That username does not meet the policy requirements.",
+    "AuthFailed.password_policy": "That password does not meet the policy requirements.",
+    "AuthFailed.invalid_origin": "Passkey origin was rejected.",
+    "Forbidden.csrf": "Cross-site request blocked.",
+    "Forbidden.ip_denied": "Your IP address is blocked.",
+    "Forbidden.ip_not_allowed": "Your IP address is not allowed.",
+    "Forbidden.policy_denied": "Policy denied this request.",
+    "AuthRateLimited.rate_limited": "Too many authentication attempts. Try again later.",
+  },
+} as const;

package/src/i18n/failure-message.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { fail } from "../kernel/errors.ts";
+import { OKE_ERRORS, OkeError } from "../kernel/errors.ts";
+import { catalogReasonKey, resolveFailureMessage } from "./failure-message.ts";
+import { runWithLocale } from "./locale-context.ts";
+
+describe("catalogReasonKey", () => {
+  test("keeps identifiers; slugifies free text", () => {
+    expect(catalogReasonKey("invalid_credentials")).toBe("invalid_credentials");
+    expect(catalogReasonKey("policy denied")).toBe("policy_denied");
+  });
+});
+
+describe("resolveFailureMessage", () => {
+  test("resolves reason-specific then code-level keys", () => {
+    expect(resolveFailureMessage("AuthFailed", { reason: "invalid_credentials" }, "en")).toBe(
+      "Invalid credentials.",
+    );
+    expect(resolveFailureMessage("AuthFailed", { reason: "invalid_credentials" }, "ar")).toBe(
+      "بيانات الاعتماد غير صحيحة.",
+    );
+    expect(resolveFailureMessage("Unauthorized", {}, "ar")).toBe("المصادقة مطلوبة.");
+    expect(resolveFailureMessage("FlightFull", { seats: 0 }, "en")).toBeUndefined();
+  });
+});
+
+describe("fail — auto message", () => {
+  test("attaches localized message from active locale", () => {
+    const en = runWithLocale({ locale: "en", defaultLocale: "en" }, () =>
+      fail("AuthFailed", { reason: "invalid_email" }),
+    );
+    expect(en.error.message).toBe("Enter a valid email address.");
+
+    const ar = runWithLocale({ locale: "ar", defaultLocale: "en" }, () => fail("NotFound", {}));
+    expect(ar.error.message).toBe("المورد المطلوب غير موجود.");
+  });
+
+  test("explicit message wins", () => {
+    const r = fail("AuthFailed", { reason: "invalid_email" }, { message: "custom" });
+    expect(r.error.message).toBe("custom");
+  });
+});
+
+describe("OkeError — localized cause/fix", () => {
+  test("uses Arabic catalog when locale is ar", () => {
+    const err = new OkeError(
+      OKE_ERRORS.UNDECLARED_READ,
+      { flow: "notes.create", resource: "sql:notes" },
+      "ar",
+    );
+    expect(err.causeText).toContain("notes.create");
+    expect(err.causeText).toContain("sql:notes");
+    expect(err.causeText).toContain("يقرأ");
+    expect(err.fix).toContain("effects.reads");
+  });
+});

package/src/i18n/failure-message.ts

@@ -0,0 +1,93 @@
+/**
+ * Resolve a localized `error.message` for typed flow failures.
+ */
+
+import { getActiveDefaultLocale, getActiveLocale } from "./locale-context.ts";
+import { getMessageCatalogs, translate } from "./messages.ts";
+import type { MessageValues } from "./types.ts";
+
+/**
+ * Whether a reason string is safe as a catalog key segment.
+ *
+ * @param reason - Failure `data.reason`
+ */
+export function isCatalogReason(reason: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(reason);
+}
+
+/**
+ * Normalize a free-text reason into a catalog key segment.
+ *
+ * @param reason - Raw reason
+ */
+export function catalogReasonKey(reason: string): string {
+  if (isCatalogReason(reason)) return reason;
+  return reason
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+}
+
+/**
+ * Build ICU values from failure data (string/number/boolean leaves only).
+ *
+ * @param data - Failure payload
+ */
+export function failureMessageValues(data: unknown): MessageValues | undefined {
+  if (data === null || data === undefined || typeof data !== "object") return undefined;
+  const out: Record<string, string | number | boolean> = {};
+  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Resolve a localized message for a typed failure, or `undefined` when no
+ * built-in / app catalog entry exists (custom app codes stay message-less).
+ *
+ * Lookup order: `errors.{code}.{reason}` → `errors.{code}`.
+ *
+ * @param code - Failure code (`AuthFailed`, `Unauthorized`, …)
+ * @param data - Failure data (may include `reason`)
+ * @param locale - Override locale (defaults to active request locale)
+ */
+export function resolveFailureMessage(
+  code: string,
+  data?: unknown,
+  locale?: string,
+): string | undefined {
+  const catalogs = getMessageCatalogs();
+  const activeLocale = locale ?? getActiveLocale("en");
+  const defaultLocale = getActiveDefaultLocale("en");
+  const values = failureMessageValues(data);
+  const reason =
+    data !== null &&
+    data !== undefined &&
+    typeof data === "object" &&
+    "reason" in data &&
+    typeof (data as { reason: unknown }).reason === "string"
+      ? catalogReasonKey((data as { reason: string }).reason)
+      : undefined;
+
+  const keys: string[] = [];
+  if (reason) keys.push(`errors.${code}.${reason}`);
+  keys.push(`errors.${code}`);
+
+  for (const key of keys) {
+    const primary = catalogs[activeLocale]?.[key];
+    const fallback = catalogs[defaultLocale]?.[key];
+    if (primary === undefined && fallback === undefined) continue;
+    return translate({
+      locale: activeLocale,
+      defaultLocale,
+      catalogs,
+      key,
+      values,
+    });
+  }
+  return undefined;
+}

package/src/i18n/format.ts

@@ -0,0 +1,67 @@
+/**
+ * ICU MessageFormat formatting via FormatJS (`intl-messageformat`).
+ *
+ * Supports interpolation, cardinal/ordinal plurals, `select` / `selectordinal`,
+ * and rich-text tags (`<tag>…</tag>` with function values).
+ */
+
+import IntlMessageFormat from "intl-messageformat";
+import type { MessageValues } from "./types.ts";
+
+const cache = new Map<string, IntlMessageFormat>();
+
+/**
+ * Clear the compiled-message cache (tests only).
+ */
+export function clearMessageFormatCache(): void {
+  cache.clear();
+}
+
+/**
+ * Format an ICU message for a locale.
+ *
+ * @param message - ICU MessageFormat source
+ * @param locale - BCP 47 locale tag
+ * @param values - Interpolation / plural / select / rich-text values
+ */
+export function formatMessage(message: string, locale: string, values?: MessageValues): string {
+  const cacheKey = `${locale}\0${message}`;
+  let formatter = cache.get(cacheKey);
+  if (!formatter) {
+    try {
+      formatter = new IntlMessageFormat(message, locale);
+    } catch {
+      // Malformed ICU — treat as a plain template.
+      return message;
+    }
+    cache.set(cacheKey, formatter);
+  }
+
+  try {
+    const result = formatter.format(values as Record<string, unknown> | undefined);
+    return partsToString(result);
+  } catch {
+    // Missing args — leave the source for callers that fall back.
+    return message;
+  }
+}
+
+/**
+ * Collapse FormatJS rich-text / string output to a single string.
+ *
+ * @param result - `format()` return value
+ */
+function partsToString(result: unknown): string {
+  if (typeof result === "string") return result;
+  if (typeof result === "number" || typeof result === "boolean") return String(result);
+  if (Array.isArray(result)) {
+    return result
+      .map((part) => {
+        if (typeof part === "string" || typeof part === "number") return String(part);
+        return "";
+      })
+      .join("");
+  }
+  if (result == null) return "";
+  return String(result);
+}

package/src/i18n/index.ts

@@ -0,0 +1,57 @@
+/**
+ * App i18n — ICU message catalogs for `fx.t`, typed keys, locale helpers.
+ *
+ * Channel locale resolution lives in `elements/channel/locale.ts`; this
+ * module owns Flow-facing string catalogs registered via {@link defineLocale}.
+ */
+
+export { clearMessageFormatCache, formatMessage } from "./format.ts";
+
+export {
+  catalogReasonKey,
+  failureMessageValues,
+  isCatalogReason,
+  resolveFailureMessage,
+} from "./failure-message.ts";
+
+export {
+  getActiveDefaultLocale,
+  getActiveLocale,
+  getLocaleContext,
+  runWithLocale,
+  type LocaleContext,
+} from "./locale-context.ts";
+
+export {
+  clearMessageCatalogs,
+  defineLocale,
+  defineMessages,
+  flattenMessages,
+  getMessageCatalogs,
+  interpolateMessage,
+  matchConfiguredLocale,
+  translate,
+  type MessageCatalog,
+  type MessageCatalogs,
+  type TranslateOptions,
+} from "./messages.ts";
+
+export type {
+  AppMessageKey,
+  FlattenKeys,
+  MessageTree,
+  MessageValue,
+  MessageValues,
+  MessagesFor,
+  Register,
+} from "./types.ts";
+
+export {
+  formatLocaleChain,
+  isRtlLocale,
+  parseAcceptLanguage,
+  resolveLocale,
+  type LocaleChainStep,
+  type LocaleResolution,
+  type ResolveLocaleOptions,
+} from "../elements/channel/locale.ts";

package/src/i18n/locale-context.ts

@@ -0,0 +1,48 @@
+/**
+ * Request-scoped locale for {@link fail} / {@link OkeError} localization.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** Active locale bag for the current async context. */
+export interface LocaleContext {
+  readonly locale: string;
+  readonly defaultLocale: string;
+}
+
+const storage = new AsyncLocalStorage<LocaleContext>();
+
+/**
+ * Run `fn` with an active locale context (request / invocation scope).
+ *
+ * @param ctx - Locale + default
+ * @param fn - Work to run
+ */
+export function runWithLocale<T>(ctx: LocaleContext, fn: () => T): T {
+  return storage.run(ctx, fn);
+}
+
+/**
+ * Active locale context, if any.
+ */
+export function getLocaleContext(): LocaleContext | undefined {
+  return storage.getStore();
+}
+
+/**
+ * Active locale, or `fallback` when none is set.
+ *
+ * @param fallback - Default when outside a request (default `"en"`)
+ */
+export function getActiveLocale(fallback = "en"): string {
+  return storage.getStore()?.locale ?? fallback;
+}
+
+/**
+ * Active default locale for catalog fallback.
+ *
+ * @param fallback - Default when outside a request (default `"en"`)
+ */
+export function getActiveDefaultLocale(fallback = "en"): string {
+  return storage.getStore()?.defaultLocale ?? fallback;
+}