@agent-native/core 0.113.0 → 0.114.0

package/src/localization/index.ts

@@ -0,0 +1,2 @@
+export * from "./shared.js";
+export * from "./server.js";

package/src/localization/server.ts

@@ -0,0 +1,131 @@
+import {
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
+  localeDirection,
+  normalizeLocaleCode,
+  normalizeLocalizationPreference,
+  resolveLocaleFromPreference,
+  type LocaleCode,
+  type LocalePreference,
+  type LocalizationPreference,
+} from "./shared.js";
+
+interface RequestLike {
+  headers?: Headers | Record<string, string | string[] | undefined> | null;
+}
+
+type HeaderMap = Headers | Record<string, string | string[] | undefined>;
+
+export interface ResolvedRequestLocale {
+  locale: LocaleCode;
+  preference: LocalizationPreference;
+  dir: "ltr" | "rtl";
+}
+
+export interface ResolveLocaleFromRequestOptions {
+  request?: Request | RequestLike | null;
+  acceptLanguage?: string | null;
+  preference?: LocalizationPreference | LocalePreference | null;
+  fallback?: LocaleCode;
+}
+
+export interface LocaleInitScriptOptions {
+  locale?: LocaleCode;
+  preference?: LocalizationPreference | LocalePreference;
+  messages?: Record<string, unknown> | null;
+}
+
+function readHeader(
+  headers: HeaderMap | undefined | null,
+  key: string,
+): string | null {
+  if (!headers) return null;
+  if (typeof (headers as Headers).get === "function") {
+    return (headers as Headers).get(key);
+  }
+  const lowerKey = key.toLowerCase();
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== lowerKey) continue;
+    if (Array.isArray(value)) return value.join(",");
+    return value ?? null;
+  }
+  return null;
+}
+
+export function parseAcceptLanguage(header: string | null | undefined) {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((part) => {
+      const [tag, ...params] = part.trim().split(";");
+      const q = params
+        .map((param) => param.trim())
+        .find((param) => param.startsWith("q="));
+      const weight = q ? Number.parseFloat(q.slice(2)) : 1;
+      return {
+        tag,
+        weight: Number.isFinite(weight) ? weight : 0,
+      };
+    })
+    .filter((entry) => entry.tag && entry.weight > 0)
+    .sort((a, b) => b.weight - a.weight)
+    .map((entry) => entry.tag);
+}
+
+export function resolveLocaleFromRequest(
+  options: ResolveLocaleFromRequestOptions = {},
+): ResolvedRequestLocale {
+  const header =
+    options.acceptLanguage ??
+    readHeader(options.request?.headers, "accept-language");
+  const candidates = parseAcceptLanguage(header);
+  const preference = normalizeLocalizationPreference(
+    options.preference ?? { locale: "system" },
+  );
+  const locale =
+    preference.locale === "system"
+      ? resolveLocaleFromPreference(preference, [
+          ...candidates,
+          options.fallback ?? DEFAULT_LOCALE,
+        ])
+      : (normalizeLocaleCode(preference.locale) ??
+        options.fallback ??
+        DEFAULT_LOCALE);
+  return {
+    locale,
+    preference,
+    dir: localeDirection(locale),
+  };
+}
+
+export function getLocaleInitScript(options: LocaleInitScriptOptions = {}) {
+  const safeLocale = normalizeLocaleCode(options.locale) ?? DEFAULT_LOCALE;
+  const shouldStorePreference = options.preference !== undefined;
+  const safePreference = normalizeLocalizationPreference(
+    options.preference ?? { locale: "system" },
+  );
+  const payload = {
+    locale: safeLocale,
+    preference: safePreference,
+    dir: localeDirection(safeLocale),
+    messages: options.messages ?? undefined,
+  };
+
+  return `(function(){try{var supported=${JSON.stringify(
+    SUPPORTED_LOCALES,
+  )};var payload=${JSON.stringify(
+    payload,
+  )};var shouldStorePreference=${JSON.stringify(
+    shouldStorePreference,
+  )};function valid(x){return supported.indexOf(x)>=0}function canon(x){if(typeof x!=='string'||!x)return null;try{var c=Intl.getCanonicalLocales(x)[0];if(valid(c))return c;var lang=c&&c.split('-')[0].toLowerCase();for(var i=0;i<supported.length;i++){if(supported[i].split('-')[0].toLowerCase()===lang)return supported[i]}}catch(e){}return null}function storageGet(k){try{return window.localStorage.getItem(k)}catch(e){return null}}function storageSet(k,v){try{window.localStorage.setItem(k,v)}catch(e){}}var stored=storageGet(${JSON.stringify(
+    LOCALE_STORAGE_KEY,
+  )});var pref=payload.preference&&payload.preference.locale;var locale=payload.locale;if(!valid(locale)){locale=null}if(!locale&&stored&&stored!=='system'){locale=canon(stored)}if(!locale&&pref&&pref!=='system'){locale=canon(pref)}if(!locale){var langs=navigator.languages&&navigator.languages.length?navigator.languages:[navigator.language];for(var j=0;j<langs.length&&!locale;j++){locale=canon(langs[j])}}if(!locale)locale=${JSON.stringify(
+    DEFAULT_LOCALE,
+  )};var root=document.documentElement;root.setAttribute('lang',locale);root.setAttribute('dir',locale==='ar-SA'?'rtl':'ltr');root.setAttribute('data-locale',locale);payload.locale=locale;payload.dir=locale==='ar-SA'?'rtl':'ltr';window[${JSON.stringify(
+    LOCALE_HYDRATION_GLOBAL,
+  )}]=payload;if(shouldStorePreference&&pref){storageSet(${JSON.stringify(
+    LOCALE_STORAGE_KEY,
+  )},pref)}}catch(e){}})();`;
+}

package/src/localization/shared.ts

@@ -0,0 +1,208 @@
+export const SUPPORTED_LOCALES = [
+  "en-US",
+  "es-ES",
+  "fr-FR",
+  "de-DE",
+  "pt-BR",
+  "zh-CN",
+  "zh-TW",
+  "ja-JP",
+  "ko-KR",
+  "hi-IN",
+  "ar-SA",
+] as const;
+
+export type LocaleCode = (typeof SUPPORTED_LOCALES)[number];
+export type LocalePreference = "system" | LocaleCode;
+
+export interface LocaleMetadata {
+  code: LocaleCode;
+  englishName: string;
+  nativeName: string;
+  dir: "ltr" | "rtl";
+}
+
+export interface LocalizationPreference {
+  locale: LocalePreference;
+}
+
+export const DEFAULT_LOCALE: LocaleCode = "en-US";
+export const LOCALIZATION_SETTING_KEY = "localization";
+export const LOCALE_STORAGE_KEY = "agent-native:locale-preference";
+export const LOCALE_HYDRATION_GLOBAL = "__AGENT_NATIVE_LOCALE__";
+
+export const LOCALE_METADATA: Record<LocaleCode, LocaleMetadata> = {
+  "en-US": {
+    code: "en-US",
+    englishName: "English",
+    nativeName: "English",
+    dir: "ltr",
+  },
+  "zh-CN": {
+    code: "zh-CN",
+    englishName: "Chinese (Simplified)",
+    nativeName: "简体中文",
+    dir: "ltr",
+  },
+  "zh-TW": {
+    code: "zh-TW",
+    englishName: "Chinese (Traditional, Taiwan)",
+    nativeName: "繁體中文",
+    dir: "ltr",
+  },
+  "es-ES": {
+    code: "es-ES",
+    englishName: "Spanish",
+    nativeName: "Español",
+    dir: "ltr",
+  },
+  "fr-FR": {
+    code: "fr-FR",
+    englishName: "French",
+    nativeName: "Français",
+    dir: "ltr",
+  },
+  "de-DE": {
+    code: "de-DE",
+    englishName: "German",
+    nativeName: "Deutsch",
+    dir: "ltr",
+  },
+  "ja-JP": {
+    code: "ja-JP",
+    englishName: "Japanese",
+    nativeName: "日本語",
+    dir: "ltr",
+  },
+  "ko-KR": {
+    code: "ko-KR",
+    englishName: "Korean",
+    nativeName: "한국어",
+    dir: "ltr",
+  },
+  "pt-BR": {
+    code: "pt-BR",
+    englishName: "Portuguese (Brazil)",
+    nativeName: "Português (Brasil)",
+    dir: "ltr",
+  },
+  "hi-IN": {
+    code: "hi-IN",
+    englishName: "Hindi",
+    nativeName: "हिन्दी",
+    dir: "ltr",
+  },
+  "ar-SA": {
+    code: "ar-SA",
+    englishName: "Arabic",
+    nativeName: "العربية",
+    dir: "rtl",
+  },
+};
+
+const SUPPORTED_LOCALE_SET = new Set<string>(SUPPORTED_LOCALES);
+
+const CHINESE_LOCALE_ALIASES: Record<string, LocaleCode> = {
+  "zh-cn": "zh-CN",
+  "zh-hans": "zh-CN",
+  "zh-hans-cn": "zh-CN",
+  "zh-hans-sg": "zh-CN",
+  "zh-hant": "zh-TW",
+  "zh-hant-hk": "zh-TW",
+  "zh-hant-mo": "zh-TW",
+  "zh-hant-tw": "zh-TW",
+  "zh-hk": "zh-TW",
+  "zh-mo": "zh-TW",
+  "zh-sg": "zh-CN",
+  "zh-tw": "zh-TW",
+};
+
+function normalizeChineseLocaleAlias(canonical: string): LocaleCode | null {
+  const normalized = canonical.toLowerCase();
+  const alias = CHINESE_LOCALE_ALIASES[normalized];
+  if (alias) return alias;
+
+  const parts = normalized.split("-");
+  if (parts[0] !== "zh") return null;
+  if (
+    parts.includes("hant") ||
+    parts.includes("tw") ||
+    parts.includes("hk") ||
+    parts.includes("mo")
+  ) {
+    return "zh-TW";
+  }
+  if (parts.includes("hans") || parts.includes("cn") || parts.includes("sg")) {
+    return "zh-CN";
+  }
+  return null;
+}
+
+export function isLocaleCode(value: unknown): value is LocaleCode {
+  return typeof value === "string" && SUPPORTED_LOCALE_SET.has(value);
+}
+
+export function normalizeLocaleCode(value: unknown): LocaleCode | null {
+  if (typeof value !== "string" || value.trim().length === 0) return null;
+  try {
+    for (const canonical of Intl.getCanonicalLocales(value.trim())) {
+      if (isLocaleCode(canonical)) return canonical;
+      const alias = normalizeChineseLocaleAlias(canonical);
+      if (alias) return alias;
+      const language = canonical.split("-")[0]?.toLowerCase();
+      const match = SUPPORTED_LOCALES.find(
+        (locale) => locale.split("-")[0]?.toLowerCase() === language,
+      );
+      if (match) return match;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export function normalizeLocalePreference(
+  value: unknown,
+): LocalePreference | null {
+  if (value === "system") return "system";
+  return normalizeLocaleCode(value);
+}
+
+export function normalizeLocalizationPreference(
+  value: unknown,
+): LocalizationPreference {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const locale = normalizeLocalePreference(
+      (value as { locale?: unknown }).locale,
+    );
+    if (locale) return { locale };
+  }
+  const locale = normalizeLocalePreference(value);
+  return { locale: locale ?? "system" };
+}
+
+export function localeDirection(locale: LocaleCode): "ltr" | "rtl" {
+  return LOCALE_METADATA[locale]?.dir ?? "ltr";
+}
+
+export function resolveLocaleFromCandidates(
+  candidates: Iterable<unknown>,
+): LocaleCode {
+  for (const candidate of candidates) {
+    const normalized = normalizeLocaleCode(candidate);
+    if (normalized) return normalized;
+  }
+  return DEFAULT_LOCALE;
+}
+
+export function resolveLocaleFromPreference(
+  preference: LocalizationPreference | LocalePreference | unknown,
+  systemCandidates: Iterable<unknown> = [],
+): LocaleCode {
+  const normalized =
+    typeof preference === "string"
+      ? normalizeLocalePreference(preference)
+      : normalizeLocalizationPreference(preference).locale;
+  if (normalized && normalized !== "system") return normalized;
+  return resolveLocaleFromCandidates(systemCandidates);
+}

package/src/mcp/actions/call-mcp-tool.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { callMcpTool } from "../../mcp-client/app-api.js";
+
+export default defineAction({
+  description:
+    "Call an MCP tool visible to the authenticated app request by server id and original tool name. Server credentials and tokens are never exposed.",
+  agentTool: false,
+  toolCallable: false,
+  requiresAuth: true,
+  schema: z.object({
+    serverId: z.string().trim().min(1),
+    toolName: z.string().trim().min(1),
+    arguments: z.record(z.string(), z.unknown()).default({}),
+  }),
+  run: ({ serverId, toolName, arguments: args }) =>
+    callMcpTool(serverId, toolName, args),
+});

package/src/mcp/actions/create-org-service-token.ts

@@ -0,0 +1,87 @@
+/**
+ * Mint an org-scoped SERVICE token for CI and other non-human callers (e.g.
+ * the `PLAN_RECAP_TOKEN` GitHub secret used by PR Visual Recap). Unlike a
+ * personal connect token, the credential belongs to the ORG: it keeps working
+ * when the human who minted it leaves or revokes their own tokens, and rows
+ * created with it are org-scoped so every org member can see them.
+ *
+ * SECURITY:
+ *   - Gated to org owners/admins (see service-token-access.ts).
+ *   - The token value appears ONLY in this action's response — it is never
+ *     stored (only its `jti`) and never logged.
+ *   - Not callable by the sandboxed agent tool loop (`toolCallable: false`):
+ *     minting a long-lived credential must be an explicit human/HTTP/CLI act,
+ *     never a prompt-injection target.
+ *   - Revocable via `revoke-org-service-token` — same `revoked_at` gate the
+ *     personal-token revocation path uses.
+ */
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { getAppProductionUrl } from "../../server/app-url.js";
+import { getRequestContext } from "../../server/request-context.js";
+import { mintOrgServiceToken } from "../connect-route.js";
+import {
+  requireServiceTokenCaller,
+  ServiceTokenError,
+} from "./service-token-access.js";
+
+export default defineAction({
+  description:
+    "Create a named, org-scoped service token (for CI like PR Visual Recap's PLAN_RECAP_TOKEN). The token acts as a service principal owned by the organization, not a person. Org owner/admin only. The token value is returned ONCE and never stored — copy it immediately.",
+  schema: z.object({
+    name: z
+      .string()
+      .min(1)
+      .max(64)
+      .describe("Short service name, e.g. 'ci' or 'pr-recap'"),
+    ttlDays: z
+      .number()
+      .int()
+      .min(1)
+      .max(365)
+      .optional()
+      .describe("Token lifetime in days (1-365, default 365)"),
+  }),
+  toolCallable: false,
+  run: async (args, ctx) => {
+    const caller = await requireServiceTokenCaller({
+      userEmail: ctx?.userEmail,
+      orgId: ctx?.orgId,
+      level: "manage",
+    });
+
+    // App origin for OAuth-signed tokens (resource/issuer binding). The MCP
+    // path provides requestOrigin via runWithRequestContext; the HTTP action
+    // route falls back to the configured production URL. Deployments with
+    // A2A_SECRET don't depend on it (the A2A signer ignores appUrl).
+    const appUrl = (
+      getRequestContext()?.requestOrigin || getAppProductionUrl()
+    ).replace(/\/+$/, "");
+    if (!appUrl && !process.env.A2A_SECRET?.trim()) {
+      throw new ServiceTokenError(
+        "Could not determine the app URL needed to mint a token. Set APP_URL on the deployment.",
+        500,
+      );
+    }
+
+    const minted = await mintOrgServiceToken({
+      serviceName: args.name,
+      orgId: caller.orgId,
+      createdBy: caller.email,
+      ttlDays: args.ttlDays,
+      appUrl,
+    });
+
+    return {
+      // The ONLY place the secret ever appears. Never stored, never logged.
+      token: minted.token,
+      id: minted.id,
+      serviceName: minted.serviceName,
+      serviceEmail: minted.serviceEmail,
+      orgId: caller.orgId,
+      ttlDays: minted.ttlDays,
+      note: "Store this token now (e.g. as the PLAN_RECAP_TOKEN GitHub Actions secret). It will not be shown again. Revoke it any time with revoke-org-service-token.",
+    };
+  },
+});

package/src/mcp/actions/list-mcp-tools.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { listVisibleMcpTools } from "../../mcp-client/app-api.js";
+
+export default defineAction({
+  description:
+    "List MCP tools visible to the authenticated app request. Returns tool contracts only; server credentials and tokens are never exposed.",
+  agentTool: false,
+  requiresAuth: true,
+  schema: z.object({
+    serverId: z.string().trim().min(1).optional(),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: ({ serverId }) => listVisibleMcpTools({ serverId }),
+});

package/src/mcp/actions/list-org-service-tokens.ts

@@ -0,0 +1,44 @@
+/**
+ * List the active org service tokens — metadata only (name, who minted it,
+ * created/last-used/revoked timestamps). Token values are never stored, so
+ * they can never appear here. Any org member may list; minting and revoking
+ * are owner/admin-gated.
+ */
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { listOrgServiceTokens } from "../connect-store.js";
+import { requireServiceTokenCaller } from "./service-token-access.js";
+
+export default defineAction({
+  description:
+    "List your organization's service tokens (CI credentials such as PLAN_RECAP_TOKEN): name, who created them, created/last-used times, and revocation state. Token values are never stored and never shown. Any org member can list.",
+  schema: z.object({
+    includeRevoked: z
+      .boolean()
+      .optional()
+      .describe("Also include revoked tokens (default false)"),
+  }),
+  http: { method: "GET" },
+  run: async (args, ctx) => {
+    const caller = await requireServiceTokenCaller({
+      userEmail: ctx?.userEmail,
+      orgId: ctx?.orgId,
+      level: "read",
+    });
+    const rows = await listOrgServiceTokens(caller.orgId);
+    const tokens = rows
+      .filter((row) => args.includeRevoked || row.revokedAt == null)
+      .map((row) => ({
+        id: row.id,
+        serviceName: row.serviceName,
+        serviceEmail: row.ownerEmail,
+        label: row.label,
+        createdBy: row.createdBy,
+        createdAt: row.createdAt,
+        lastUsedAt: row.lastUsedAt,
+        revokedAt: row.revokedAt,
+      }));
+    return { orgId: caller.orgId, tokens };
+  },
+});

package/src/mcp/actions/revoke-org-service-token.ts

@@ -0,0 +1,30 @@
+/**
+ * Revoke an org service token by id. Owner/admin only. Uses the same
+ * `revoked_at` gate as personal-token revocation, so the token stops
+ * authenticating on its next request. The revoke is scoped by org id AND
+ * kind='service' in SQL — a caller can never revoke another org's token or a
+ * personal token through this action.
+ */
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { revokeOrgServiceToken } from "../connect-store.js";
+import { requireServiceTokenCaller } from "./service-token-access.js";
+
+export default defineAction({
+  description:
+    "Revoke one of your organization's service tokens by id (get ids from list-org-service-tokens). The token stops working immediately. Org owner/admin only. Idempotent.",
+  schema: z.object({
+    id: z.string().min(1).describe("Service token id to revoke"),
+  }),
+  toolCallable: false,
+  run: async (args, ctx) => {
+    const caller = await requireServiceTokenCaller({
+      userEmail: ctx?.userEmail,
+      orgId: ctx?.orgId,
+      level: "manage",
+    });
+    const revoked = await revokeOrgServiceToken(caller.orgId, args.id);
+    return { ok: revoked };
+  },
+});

package/src/mcp/actions/service-token-access.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared gating for the org service-token actions.
+ *
+ * GATING DECISION: the org model HAS roles (`org_members.role` is
+ * 'owner' | 'admin' | 'member' — see `org/types.ts`), so minting and revoking
+ * service tokens require the caller to be an org **owner or admin**. Listing
+ * is allowed for any org member (token values are never stored, so the list
+ * only exposes metadata).
+ *
+ * Synthetic service identities (`svc-*@service.<orgId>`) are never inserted
+ * into `org_members`, so a leaked service token can NOT mint further service
+ * tokens or revoke others — the role lookup simply finds no membership.
+ */
+import { getDbExec } from "../../db/client.js";
+import type { OrgRole } from "../../org/types.js";
+
+export class ServiceTokenError extends Error {
+  statusCode: number;
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = "ServiceTokenError";
+    this.statusCode = statusCode;
+  }
+}
+
+/** Look up the caller's role in `orgId`, or null when not a member. */
+export async function getOrgRoleForEmail(
+  orgId: string,
+  email: string,
+): Promise<OrgRole | null> {
+  try {
+    const { rows } = await getDbExec().execute({
+      sql: `SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
+      args: [orgId, email.toLowerCase()],
+    });
+    const role = rows[0]?.role;
+    return role === "owner" || role === "admin" || role === "member"
+      ? role
+      : null;
+  } catch {
+    // org tables not provisioned (template without orgs) → no membership.
+    return null;
+  }
+}
+
+/**
+ * Return all org IDs the email belongs to, or [] when the org tables are
+ * absent (template without orgs).
+ */
+async function getOrgIdsForEmail(email: string): Promise<string[]> {
+  try {
+    const { rows } = await getDbExec().execute({
+      sql: `SELECT org_id FROM org_members WHERE LOWER(email) = ?`,
+      args: [email.toLowerCase()],
+    });
+    return rows.map((r) => String(r.org_id)).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export interface ServiceTokenCallerContext {
+  email: string;
+  orgId: string;
+  role: OrgRole;
+}
+
+/**
+ * Resolve and gate the caller for a service-token action. Throws
+ * `ServiceTokenError` (401/400/403) on failure so the action route maps it to
+ * the right HTTP status.
+ */
+export async function requireServiceTokenCaller(params: {
+  userEmail: string | undefined;
+  orgId: string | null | undefined;
+  /** 'manage' = mint/revoke (owner/admin only); 'read' = list (any member). */
+  level: "manage" | "read";
+}): Promise<ServiceTokenCallerContext> {
+  const email = params.userEmail?.trim();
+  if (!email) {
+    throw new ServiceTokenError("Sign in to manage org service tokens.", 401);
+  }
+
+  // Prefer the org ID from the token's claims; fall back to looking up the
+  // user's org membership when the token was minted without org context (e.g.
+  // a personal connect token created before the user joined an org, or one
+  // created from a session that had no active org at the time).
+  let orgId = params.orgId?.trim() || "";
+  if (!orgId) {
+    const memberOrgs = await getOrgIdsForEmail(email);
+    if (memberOrgs.length === 0) {
+      throw new ServiceTokenError(
+        "No active organization. Service tokens are org-scoped — join or create an organization first.",
+        400,
+      );
+    }
+    if (memberOrgs.length > 1) {
+      throw new ServiceTokenError(
+        "Your session is not scoped to a specific organization and you belong to multiple orgs. " +
+          "Re-authenticate with an org-scoped session to disambiguate.",
+        400,
+      );
+    }
+    orgId = memberOrgs[0];
+  }
+
+  const role = await getOrgRoleForEmail(orgId, email);
+  if (!role) {
+    throw new ServiceTokenError(
+      "You are not a member of this organization.",
+      403,
+    );
+  }
+  if (params.level === "manage" && role === "member") {
+    throw new ServiceTokenError(
+      "Only org owners or admins can create or revoke service tokens.",
+      403,
+    );
+  }
+  return { email, orgId, role };
+}