@every-app/sdk 0.3.0-rc.1 → 0.3.0-rc.3

package/dist/internal/appSettings.d.ts

@@ -23,6 +23,7 @@
  * the app Worker's secret names.
  */
 import { type ApiKeyCapability, type CapabilityLookup } from "./capabilities.js";
+import { type AiDefaultChoice, type IsSet } from "./aiDefault.js";
 /** A provider as `providers` lists it: its id, or an entry with a need. */
 export interface ProviderEntry extends SettingNeedFields {
     id: string;
@@ -62,12 +63,16 @@ export interface SettingsManifestLike {
     readonly secrets?: ReadonlyArray<string | SecretEntry>;
     readonly ai?: {
         readonly routes?: readonly string[];
+        /** The app needs the Gateway's default chat model (`/api/ai/default`): `true`, or an entry with its need. */
+        readonly chat?: boolean | SettingNeedFields;
     };
     /** A remote MCP app's registration (./remoteMcp.ts): its credential is a required Gateway setting. */
     readonly remote?: unknown;
     readonly name?: string;
 }
 export type SettingKind = "provider" | "capability" | "secret" | "ai-routes"
+/** The Gateway's default model provider (`ai.chat`): one key of any provider in the order, or the operator's choice. */
+ | "ai-default"
 /** A remote MCP app's credential (./remoteMcp.ts): one Gateway setting named by the row. */
  | "remote-mcp";
 /** Which Worker holds a setting: the Gateway's, or the app's own. */
@@ -80,6 +85,13 @@ export type SettingNeed = {
     kind: "anyOf";
     group: string;
 };
+/** What `appSettings` may be told about the Gateway, for the default model provider. */
+export interface AppSettingsOptions {
+    /** The operator's stored default (`everyapp ai default`), or none. */
+    aiDefault?: AiDefaultChoice | null;
+    /** What is set, to put the configured provider first; absent, the order decides. */
+    isSet?: IsSet;
+}
 /** One thing the app needs set, as the manifest declares it. */
 export interface AppSetting {
     kind: SettingKind;
@@ -88,8 +100,14 @@ export interface AppSetting {
     /** "OpenRouter", "DataForSEO", "MAIN_SECRET", "AI proxy routes". */
     label: string;
     holder: SettingHolder;
-    /** Every one of these must be set for the setting to count as set. */
+    /** Every one of these must be set for the setting to count as set (or any one group of `alternatives`). */
     names: string[];
+    /**
+     * For the default model provider: the settings of each provider that
+     * could serve it, any one group of which, all set, makes the setting
+     * set; `names` is the first group, what to ask for.
+     */
+    alternatives?: string[][];
     /** Read when set, never required (a capability's optional settings). */
     alsoReads: string[];
     need: SettingNeed;
@@ -157,7 +175,7 @@ export declare function secretNames(manifest: Pick<SettingsManifestLike, "secret
  * which is always set. `lookup` is where ids are found: the catalog alone
  * by default, or a gateway's registry with its registered rows.
  */
-export declare function appSettings(manifest: SettingsManifestLike, lookup?: CapabilityLookup): AppSetting[];
+export declare function appSettings(manifest: SettingsManifestLike, lookup?: CapabilityLookup, options?: AppSettingsOptions): AppSetting[];
 export interface EvaluateOptions {
     /**
      * A capability's own readiness rule, where names alone don't say (the

package/dist/internal/appSettings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appSettings.d.ts","sourceRoot":"","sources":["../../src/internal/appSettings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAKL,KAAK,gBAAgB,EAErB,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAW3B,2EAA2E;AAC3E,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wFAAwF;AACxF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC;IACvD,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IACtD,sGAAsG;IACtG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,WAAW,GACnB,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,WAAW;AACb,4FAA4F;GAC1F,YAAY,CAAC;AAEjB,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,KAAK,CAAC;AAE9C,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,kGAAkG;IAClG,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,sEAAsE;IACtE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wEAAwE;IACxE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD;;;OAGG;IACH,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACpB,gIAAgI;IAChI,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,GAAG,EAAE,OAAO,CAAC;CACd;AAED,0FAA0F;AAC1F,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAC;IACf,yFAAyF;IACzF,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,gEAAgE;IAChE,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,qEAAqE;AACrE,wBAAgB,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,SAAS,GAAG,WAAW,CAOxE;AAgBD,gFAAgF;AAChF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,WAAW,CAAC,GAChD,aAAa,EAAE,CAQjB;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CACzB,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,WAAW,CAAC,GAChD,MAAM,EAAE,CAEV;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,GAC9C,WAAW,EAAE,CAQf;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CACzB,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,GAC9C,MAAM,EAAE,CAEV;AA4GD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,GAAE,gBAA0B,GACjC,UAAU,EAAE,CAmGd;AAgBD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;CACjE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,KAAK,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,EAC9D,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,CAkCnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,QAAQ,CAAC,EACnD,EACE,GAAG,EACH,KAAK,EACL,QAAgB,GACjB,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GACpD,YAAY,GAAG,IAAI,CAgBrB;AAED,4FAA4F;AAC5F,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAClE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE;IACP,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GACA,QAAQ,CAeV;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,EACV,MAAM,GAAE,gBAA0B,GACjC,MAAM,CAER;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,MAAM,GAAE,gBAA0B,GACjC,gBAAgB,GAAG,SAAS,CAG9B"}
+{"version":3,"file":"appSettings.d.ts","sourceRoot":"","sources":["../../src/internal/appSettings.ts"],"names":[],"mappings":"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"}

package/dist/internal/appSettings.js

@@ -23,6 +23,7 @@
  * the app Worker's secret names.
  */
 import { CATALOG, capabilitySettings, } from "./capabilities.js";
+import { aiDefaultSetupHint, aiRequiredSettings, resolveAiDefault, } from "./aiDefault.js";
 import { isInstallOwnedGatewaySetting, isSettableGatewaySetting, } from "./gatewaySettings.js";
 import { remoteMcpAuthLabel, remoteMcpOf, remoteMcpSecretOf, } from "./remoteMcp.js";
 /** The need an entry declares; required unless it says otherwise. */
@@ -86,7 +87,8 @@ export function secretNames(manifest) {
  * registered row's are its own, so they count too.
  */
 function providerNames(capability) {
-    return capabilitySettings(capability).filter((name) => !isInstallOwnedGatewaySetting(name));
+    // An optional key (AI Gateway's own token) is never a need.
+    return aiRequiredSettings(capability).filter((name) => !isInstallOwnedGatewaySetting(name));
 }
 /** A capability's Gateway settings: what it needs, and what it also reads. */
 function capabilityNames(capability) {
@@ -173,8 +175,37 @@ function withNeed(setting, entry, defaults = {}) {
  * which is always set. `lookup` is where ids are found: the catalog alone
  * by default, or a gateway's registry with its registered rows.
  */
-export function appSettings(manifest, lookup = CATALOG) {
+export function appSettings(manifest, lookup = CATALOG, options = {}) {
     const settings = [];
+    const chat = manifest.ai?.chat;
+    if (chat === true || (chat && typeof chat === "object")) {
+        // The default resolves on what is set: with nothing set, the first of
+        // the order (or the operator's choice) and its settings are what to
+        // ask for; with one configured, that provider's. `isSet` here only
+        // orders the candidates; evaluateAppSettings decides what is set.
+        const resolution = resolveAiDefault({
+            choice: options.aiDefault ?? null,
+            isSet: options.isSet ?? (() => false),
+            lookup,
+        });
+        const settable = (names) => names.filter((name) => !isInstallOwnedGatewaySetting(name));
+        const provider = lookup.get(resolution.provider);
+        settings.push(withNeed({
+            kind: "ai-default",
+            id: "ai-default",
+            label: `A chat model (${resolution.label})`,
+            holder: "gateway",
+            names: settable(resolution.settings),
+            alsoReads: [],
+            alternatives: resolution.candidates
+                .map((candidate) => settable(candidate.settings))
+                .filter((names) => names.length > 0),
+        }, chat === true ? undefined : chat, {
+            ...(provider?.mode === "ai" ? { docs: provider.docs } : {}),
+            setup: "setup/ai.md",
+            hint: aiDefaultSetupHint(resolution),
+        }));
+    }
     for (const entry of providerEntries(manifest)) {
         const capability = lookup.get(entry.id);
         if (capability?.mode !== "ai")
@@ -259,15 +290,30 @@ export function appSettings(manifest, lookup = CATALOG) {
 }
 /** Whether each name of `setting` is set: all → true, one unset → false, else unknown. */
 function settingIsSet(setting, isSet) {
+    const groupIsSet = (names) => {
+        let unknown = false;
+        for (const name of names) {
+            const state = isSet(setting.holder, name);
+            if (state === false)
+                return false;
+            if (state === null)
+                unknown = true;
+        }
+        return unknown ? null : true;
+    };
+    if (!setting.alternatives?.length)
+        return groupIsSet(setting.names);
+    // Any one provider configured makes the default serve; unknown only
+    // when no group is set and one couldn't be read.
     let unknown = false;
-    for (const name of setting.names) {
-        const state = isSet(setting.holder, name);
-        if (state === false)
-            return false;
+    for (const names of setting.alternatives) {
+        const state = groupIsSet(names);
+        if (state === true)
+            return true;
         if (state === null)
             unknown = true;
     }
-    return unknown ? null : true;
+    return unknown ? null : false;
 }
 /**
  * Every setting against what is set. `isSet` answers per holder and name:

package/dist/internal/audit.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The audit log's shared reading of an event row: who did it, what it was
+ * about, and what the type means in plain words. Admin → Activity → Audit,
+ * `everyapp workspace audit` and `everyapp_workspace_audit` all show the
+ * same columns, so the three derive them here, from the stored `actor`
+ * and `data` (the catalogue's builders decide what those hold; the
+ * gateway's `summarize` writes the one-line summary from the same data).
+ * Nothing here reads a secret, a tool's arguments or result, or a mail
+ * body: the rows never hold one.
+ */
+import { type EventGroup, type EventTypeInfo } from "./events.js";
+/** Who caused an audit event, as every surface shows it. */
+export interface AuditActor {
+    /** `user`, `agent`, `app`, `operator`, `gateway`, or what the row says. */
+    kind: string;
+    /** The user id, the credential id (an agent), the app id, the operator's id; null for the gateway. */
+    id: string | null;
+    email: string | null;
+    /** A member's name, or the AI app's name for an agent. */
+    name: string | null;
+}
+/** What an audit event is about, picked from its `data` by the keys the catalogue uses. */
+export interface AuditSubject {
+    app?: {
+        id: string;
+        name: string | null;
+    };
+    user?: {
+        id: string;
+        email: string | null;
+        name: string | null;
+    };
+    group?: {
+        id: string;
+        name: string | null;
+    };
+    provider?: {
+        id: string;
+        name: string | null;
+    };
+    mcpApp?: {
+        id: string;
+        name: string | null;
+    };
+    subscription?: {
+        id: string;
+        name: string | null;
+    };
+    /** `member.invited`: whom. */
+    invitation?: {
+        email: string;
+        role: string | null;
+    };
+    /** Setting names an event lists (never a value): unmet, changed, added, removed. */
+    settings?: string[];
+    tool?: string;
+    /** The AI app of a connection or a blocked call. */
+    client?: string;
+    /** A personal access token's name. */
+    token?: string;
+}
+/** The stored `actor` (a JSON string or the parsed object) as the surfaces show it. */
+export declare function auditActorOf(actor: unknown): AuditActor;
+/**
+ * The Who cell: a person by name or email, "agent · Claude" for an AI
+ * client, "CLI · <operator>" for the operator's command line, "app · crm"
+ * for an app's own event, "Gateway" for what the gateway did by itself.
+ */
+export declare function auditActorLabel(actor: AuditActor): string;
+/** The plain-words label for a type: the catalogue's description, or "App event" for an app's own. */
+export declare function auditTypeLabel(type: string): string;
+/** What the event is about, from its stored `data`. */
+export declare function auditSubjectOf(type: string, data: unknown): AuditSubject;
+/** The Subject cell: the first thing the event is about, by name, then what else it names. */
+export declare function auditSubjectLabel(subject: AuditSubject): string;
+/**
+ * What the audit log leaves out unless asked for by type: `ping` (a test)
+ * and `tool.*` (the tool-calls view lists every call, blocked or not).
+ */
+export declare const AUDIT_DEFAULT_EXCLUDED: readonly string[];
+/**
+ * Whether an event of `type` is in the audit log's default view, or
+ * matches the type filter given (an exact type, or a prefix like
+ * `member.*`; `*` is everything, the excluded included).
+ */
+export declare function auditTypeMatches(type: string, filter: string | undefined): boolean;
+/** The SQL the filter translates to: `type = ?` or `type LIKE 'prefix.%'`; null for `*`. */
+export declare function auditTypeCondition(filter: string): {
+    op: "eq";
+    value: string;
+} | {
+    op: "prefix";
+    value: string;
+} | null;
+/** A type-filter value someone typed, cleaned, or null for none. */
+export declare function auditTypeFilterOf(value: unknown): string | undefined;
+export interface AuditTypeGroup {
+    group: EventGroup;
+    label: string;
+    /** `member.*` */
+    pattern: string;
+    types: EventTypeInfo[];
+}
+/** The groups' plain-words headings, as the Add-subscription dialog names them. */
+export declare const AUDIT_GROUP_LABELS: Partial<Record<EventGroup, string>>;
+/** The catalogue grouped for a type filter, in catalogue order, `ping` left out. */
+export declare function auditTypeGroups(types?: readonly EventTypeInfo[]): AuditTypeGroup[];
+//# sourceMappingURL=audit.d.ts.map

package/dist/internal/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/internal/audit.ts"],"names":[],"mappings":"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"}

package/dist/internal/audit.js

@@ -0,0 +1,235 @@
+/**
+ * The audit log's shared reading of an event row: who did it, what it was
+ * about, and what the type means in plain words. Admin → Activity → Audit,
+ * `everyapp workspace audit` and `everyapp_workspace_audit` all show the
+ * same columns, so the three derive them here, from the stored `actor`
+ * and `data` (the catalogue's builders decide what those hold; the
+ * gateway's `summarize` writes the one-line summary from the same data).
+ * Nothing here reads a secret, a tool's arguments or result, or a mail
+ * body: the rows never hold one.
+ */
+import { APP_EVENT_PREFIX, EVENT_TYPES, eventPatternMatches, eventTypeInfo, isAppOwnEventType, } from "./events.js";
+function obj(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function strings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+/** The stored `actor` (a JSON string or the parsed object) as the surfaces show it. */
+export function auditActorOf(actor) {
+    let parsed = actor;
+    if (typeof actor === "string") {
+        try {
+            parsed = JSON.parse(actor);
+        }
+        catch {
+            parsed = {};
+        }
+    }
+    const who = obj(parsed);
+    return {
+        kind: str(who.kind) ?? "gateway",
+        id: str(who.id),
+        email: str(who.email),
+        name: str(who.name),
+    };
+}
+/**
+ * The Who cell: a person by name or email, "agent · Claude" for an AI
+ * client, "CLI · <operator>" for the operator's command line, "app · crm"
+ * for an app's own event, "Gateway" for what the gateway did by itself.
+ */
+export function auditActorLabel(actor) {
+    switch (actor.kind) {
+        case "user":
+            return actor.name ?? actor.email ?? actor.id ?? "a member";
+        case "agent":
+            return `agent · ${actor.name ?? actor.id ?? "AI app"}`;
+        case "operator":
+            return `CLI · ${actor.email ?? actor.id ?? "operator"}`;
+        case "app":
+            return `app · ${actor.id ?? "app"}`;
+        case "gateway":
+            return "Gateway";
+        default:
+            return actor.name ?? actor.email ?? actor.id ?? actor.kind;
+    }
+}
+/** The plain-words label for a type: the catalogue's description, or "App event" for an app's own. */
+export function auditTypeLabel(type) {
+    const info = eventTypeInfo(type);
+    if (info)
+        return info.description;
+    if (isAppOwnEventType(type)) {
+        const rest = type.slice(APP_EVENT_PREFIX.length);
+        return `App event: ${rest.slice(rest.indexOf(".") + 1)}`;
+    }
+    return type;
+}
+function named(value) {
+    const subject = obj(value);
+    const id = str(subject.id) ?? str(subject.rowId);
+    return id ? { id, name: str(subject.name) } : undefined;
+}
+/** What the event is about, from its stored `data`. */
+export function auditSubjectOf(type, data) {
+    const d = obj(data);
+    const subject = {};
+    const app = named(d.app);
+    if (app) {
+        if (type.startsWith("mcp_app."))
+            subject.mcpApp = app;
+        else
+            subject.app = app;
+    }
+    else if (isAppOwnEventType(type)) {
+        const rest = type.slice(APP_EVENT_PREFIX.length);
+        subject.app = { id: rest.slice(0, rest.indexOf(".")), name: null };
+    }
+    const user = obj(d.user);
+    if (str(user.id)) {
+        subject.user = {
+            id: str(user.id),
+            email: str(user.email),
+            name: str(user.name),
+        };
+    }
+    const group = named(d.group);
+    if (group)
+        subject.group = group;
+    const provider = named(d.provider);
+    if (provider)
+        subject.provider = provider;
+    const subscription = named(d.subscription);
+    if (subscription)
+        subject.subscription = subscription;
+    const invitation = obj(d.invitation);
+    if (str(invitation.email)) {
+        subject.invitation = {
+            email: str(invitation.email),
+            role: str(invitation.role),
+        };
+    }
+    const settings = [
+        ...strings(d.settings),
+        ...strings(d.unmet),
+        ...strings(d.changed),
+        ...strings(d.names),
+    ];
+    if (settings.length > 0)
+        subject.settings = [...new Set(settings)];
+    const tool = str(d.tool);
+    if (tool)
+        subject.tool = tool;
+    const client = str(obj(d.client).name) ?? str(obj(d.connection).clientName);
+    if (client)
+        subject.client = client;
+    if (type.startsWith("token.") && str(d.name))
+        subject.token = str(d.name);
+    return subject;
+}
+/** The Subject cell: the first thing the event is about, by name, then what else it names. */
+export function auditSubjectLabel(subject) {
+    const parts = [];
+    const app = subject.app ?? subject.mcpApp;
+    if (app)
+        parts.push(app.name ?? app.id);
+    if (subject.user) {
+        parts.push(subject.user.name ?? subject.user.email ?? subject.user.id);
+    }
+    if (subject.invitation)
+        parts.push(subject.invitation.email);
+    if (subject.group)
+        parts.push(subject.group.name ?? subject.group.id);
+    if (subject.provider) {
+        parts.push(subject.provider.name ?? subject.provider.id);
+    }
+    if (subject.subscription) {
+        parts.push(subject.subscription.name ?? subject.subscription.id);
+    }
+    if (subject.token)
+        parts.push(subject.token);
+    if (subject.tool)
+        parts.push(subject.tool);
+    if (subject.client)
+        parts.push(subject.client);
+    if (subject.settings)
+        parts.push(subject.settings.join(", "));
+    return parts.join(" · ");
+}
+/**
+ * What the audit log leaves out unless asked for by type: `ping` (a test)
+ * and `tool.*` (the tool-calls view lists every call, blocked or not).
+ */
+export const AUDIT_DEFAULT_EXCLUDED = ["ping", "tool.*"];
+/**
+ * Whether an event of `type` is in the audit log's default view, or
+ * matches the type filter given (an exact type, or a prefix like
+ * `member.*`; `*` is everything, the excluded included).
+ */
+export function auditTypeMatches(type, filter) {
+    if (filter === undefined) {
+        return !AUDIT_DEFAULT_EXCLUDED.some((pattern) => eventPatternMatches(pattern, type));
+    }
+    if (filter === "*")
+        return true;
+    return eventPatternMatches(filter, type);
+}
+/** The SQL the filter translates to: `type = ?` or `type LIKE 'prefix.%'`; null for `*`. */
+export function auditTypeCondition(filter) {
+    if (filter === "*")
+        return null;
+    if (filter.endsWith(".*"))
+        return { op: "prefix", value: filter.slice(0, -1) };
+    return { op: "eq", value: filter };
+}
+/** A type-filter value someone typed, cleaned, or null for none. */
+export function auditTypeFilterOf(value) {
+    const text = typeof value === "string" ? value.trim() : "";
+    return text.length > 0 ? text : undefined;
+}
+/** A group with no heading here reads as its name ("organization" → "Organization"). */
+function groupHeading(group) {
+    const words = group.replace(/_/g, " ");
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** The groups' plain-words headings, as the Add-subscription dialog names them. */
+export const AUDIT_GROUP_LABELS = {
+    member: "Members",
+    app: "Apps",
+    cap: "Monthly caps",
+    tool: "Agent tool calls",
+    connection: "AI connections",
+    token: "Tokens",
+    access: "Cloudflare Access",
+    mcp_app: "MCP apps",
+    provider: "API providers",
+    ping: "Test",
+};
+/** The catalogue grouped for a type filter, in catalogue order, `ping` left out. */
+export function auditTypeGroups(types = EVENT_TYPES) {
+    const groups = new Map();
+    for (const info of types) {
+        if (info.group === "ping")
+            continue;
+        const existing = groups.get(info.group);
+        if (existing)
+            existing.types.push(info);
+        else {
+            groups.set(info.group, {
+                group: info.group,
+                label: AUDIT_GROUP_LABELS[info.group] ?? groupHeading(info.group),
+                pattern: `${info.group}.*`,
+                types: [info],
+            });
+        }
+    }
+    return [...groups.values()];
+}