@opencxh/domain 1.191.0 → 1.193.0

package/dist/platform/ai-tools.d.ts

@@ -38,6 +38,15 @@ export interface ToolCatalogEntry {
     /** internal | outward as the tool declares it; absent = outward. */
     effect?: "internal" | "outward";
 }
+/**
+ * Can this tool reach outside the building? A read never does; an `effect: "internal"` write says
+ * so itself. Everything else — including a tool that declares neither — counts as outward, so a
+ * forgotten declaration costs a tool for the turn rather than quietly sending a mail.
+ */
+export declare function isOutwardTool(tool: {
+    access?: "read" | "write";
+    effect?: "internal" | "outward";
+}): boolean;
 /** A model's request to call a tool. */
 export interface AiToolCall {
     id: string;

package/dist/platform/assist-source.d.ts

@@ -1,99 +1,104 @@
-import { LocaleBundle } from '../entities/analytics/dashboard';
-import { NotificationText } from './notification';
+import { LocaleBundle, LocalizedText } from './localization';
 /**
- * Role group of an app that reports what currently needs someone's attention.
- *
- * A constant and not a literal at both ends: `Bridge.providers.list` answers an unknown group
- * with an empty list, so a typo would read as "nothing needs attention".
+ * Role group of an app that reports what currently needs someone's attention. A constant, not a
+ * literal: `Bridge.providers.list` answers an unknown group with an empty list.
  */
 export declare const ASSIST_SOURCE_PROVIDER_GROUP = "assist-source";
 /**
- * One thing that needs attention now, as the app that owns it sees it.
- *
- * Declared by the owner rather than derived centrally: only comms knows that an unanswered
- * first reply is worse than an unread newsletter, and only `apps/work` knows that `closedAt`
- * and not a status name decides whether an item is done. A hub that scored this itself would
- * need every app's types.
+ * How urgent a nudge is, across sources. `blocking` = nothing moves until you answer (an approval),
+ * `due` = a deadline is here or past (SLA, overdue), `open` = everything else. The hub orders by
+ * band first, then `priority` within the band, so no source has to calibrate against another.
  */
-export interface AssistNudge {
+export declare const ASSIST_BANDS: readonly ["blocking", "due", "open"];
+export type AssistBand = (typeof ASSIST_BANDS)[number];
+/** What a source gets to say about one thing: the same texts, whether nudge or starter. */
+interface AssistRanked {
     /** `<app>.<thing>` — the prefix is the owner, as with memory kinds and dossier keys. */
     id: string;
-    /** Short label: "SLA", "Over tijd", "Straks". Bare i18n key; the hub stamps the namespace. */
-    tag: string;
+    /** Absent counts as `"open"`. */
+    band?: AssistBand;
+    /** Rank within the band; higher sorts earlier. */
+    priority?: number;
     /** Lucide icon name. */
     icon?: string;
-    /** One line, in the owner's words. */
-    text: NotificationText;
     /** The assignment that handles this — fills the launcher, or the agent's procedure. */
-    ask: NotificationText;
-    /** What it is about, as `<kind>:<ref>`. Also the scope the walkthrough's composer writes to. */
+    ask: LocalizedText;
+}
+/**
+ * One thing that needs attention now, declared by the app that owns it. Only comms knows that an
+ * unanswered first reply outranks an unread newsletter; a hub scoring this itself would need every
+ * app's types. All texts are bare i18n keys; the hub stamps the source's namespace.
+ */
+export interface AssistNudge extends AssistRanked {
+    /** Short label: "SLA", "Over tijd". */
+    tag: LocalizedText;
+    /** One line, in the owner's words. */
+    text: LocalizedText;
+    /** What it is about, as `<kind>:<ref>`. Also the scope the queue's composer writes to. */
     subjectKey?: string;
-    /** Higher sorts earlier. The source ranks its own; the hub only merges. */
-    priority?: number;
-    /**
-     * Where "open it" goes. `/…` follows the kernel router, `https://…` opens a tab — the same
-     * convention `AiToolResult.sources` uses.
-     */
+    /** Where "open it" goes: `/…` follows the kernel router, `https://…` opens a tab. */
     url?: string;
     /**
-     * Where "later" posts `{ remindAt }`, as an invoke action
-     * (`communication.interaction.<id>.remind`).
-     *
-     * The owner names the route rather than the board deriving one, because parking checks the
-     * resource's own ACL and only the owning app has it. A source without such a route omits this
-     * and simply gets no "later" button — better than a button that always fails.
+     * Where "later" posts `{ remindAt }`, as an invoke action. The owner names the route because
+     * parking checks the resource's own ACL. Absent = no "later" button, which beats one that fails.
      */
     snoozeAction?: string;
+    /** Where "done" posts, as an invoke action. Same rule as `snoozeAction`. */
+    resolveAction?: string;
     /**
      * Federated resource that draws this nudge's body in the queue, as `"<app>:<Component>"`.
-     *
-     * Absent = the queue falls back to `text` plus a button to `url`, so a source that never
-     * adopts this keeps working. The component is handed `{ nudge, onHandled }`.
+     * Handed {@link AssistCardProps}. Absent = the queue falls back to `text` plus a button to `url`.
      */
     resource?: string;
-    /**
-     * Where "done" posts, as an invoke action. Same reasoning as `snoozeAction`: only the owning
-     * app knows what done means (comms closes, work leaves the status ladder) and only it holds
-     * the ACL. A source without such a route omits this and gets no "done" button.
-     */
-    resolveAction?: string;
+}
+/** What a nudge's federated body receives. */
+export interface AssistCardProps {
+    nudge: AssistNudge;
+    /** The body handled the card itself (a reply went out); the queue moves on. */
+    onHandled: () => void;
 }
 /** A fixed starting point, offered even when nothing needs attention. */
-export interface AssistStarter {
-    id: string;
-    label: NotificationText;
-    sub?: NotificationText;
-    icon?: string;
-    ask: NotificationText;
+export interface AssistStarter extends AssistRanked {
+    label: LocalizedText;
+    sub?: LocalizedText;
     /**
-     * Whether this sets an agent to work or just asks something. The source knows — "handle the
-     * SLA conversations" is work, "summarise my open threads" is a question — and guessing it
-     * from the wording is the classify step the launcher deliberately does not have. Absent
-     * counts as `"task"`: a nudge is always something to be done.
+     * Whether this sets an agent to work or just asks something. The source knows; guessing it from
+     * the wording is the classify step the launcher deliberately does not have. Absent = `"task"`.
      */
     mode?: "chat" | "task";
 }
 /**
- * Bare payload of `GET /provider/assist/describe` — not wrapped in `ResponseFactory`, the way
- * every fan-out in this repo reads a describe.
- *
- * User-scoped: the hub calls it with an acting identity, because a nudge is per person.
+ * Bare payload of `GET /provider/assist/describe` — not wrapped in `ResponseFactory`, like every
+ * fan-out describe in this repo. User-scoped: the hub calls it with an acting identity.
  */
 export interface AssistSourceDescribe {
-    /** The declaring app (== manifest name == `req.source.app`). */
+    /** The declaring app. A label: the hub namespaces on which provider actually answered. */
     source: string;
     nudges: AssistNudge[];
     starters: AssistStarter[];
     /** Texts for every key above, in every language this app ships. `flattenLocales()` helps. */
     locales?: LocaleBundle;
+    /**
+     * This app's own SSE event names that can change the rows above, so the board refreshes on a
+     * push. Bare names, matched against `SSEMessage.payload.event` exactly as pushed.
+     */
+    refreshOn?: string[];
 }
 /** Every source's answer, merged. */
 export interface AssistBoard {
     nudges: AssistNudge[];
     starters: AssistStarter[];
-    /** Which apps answered. */
-    sources: string[];
     locales: LocaleBundle;
     /** Apps that answered nothing. Silence is not an answer, so it is named. */
     degradedApps: string[];
+    /**
+     * Which app's realtime events invalidate this board, as app name -> event names. Assembled by
+     * the hub because the client cannot know its sources at build time.
+     */
+    refreshOn: Record<string, string[]>;
 }
+/** The `<ref>` of a nudge's `subjectKey` when it is of `kind`, else `undefined`. */
+export declare function subjectRef(nudge: Pick<AssistNudge, "subjectKey">, kind: string): string | undefined;
+/** Band, then priority, then id — so two equal rows never reshuffle between reads. */
+export declare function compareAssistRank(a: AssistRanked, b: AssistRanked): number;
+export {};

package/dist/platform/attention.d.ts

@@ -1,23 +1,32 @@
+import { ResourceReminder } from '../entities/resource-reminder/types';
 /**
  * The primitives both attention scorers share.
  *
  * Here rather than in one of them, so `apps/work` can score its items without importing
  * interaction types and vice versa: each app owns one half and neither owns the other.
  */
-/** Score of something that must not surface at all. Filter with a single `> INELIGIBLE`. */
+export declare const HOUR_MS = 3600000;
+export declare const DAY_MS = 86400000;
+/** Score of something that must not surface at all. Filter with {@link isEligible}. */
 export declare const INELIGIBLE: number;
+export declare const isEligible: (scored: {
+    score: number;
+}) => boolean;
+export type Priority = "urgent" | "high" | "normal" | "low";
 /** Priority weight, shared by interactions and work items. */
-export declare const W_PRIORITY: Record<"urgent" | "high" | "normal" | "low", number>;
+export declare const W_PRIORITY: Record<Priority, number>;
+/**
+ * Every contributor a scorer may name. A closed union, because the assist sources map these to
+ * nudge tags: a reason renamed here fails to compile there instead of silently falling through.
+ */
+export type AttentionReason = `priority:${Priority}` | "unseen" | "assigned-to-you" | `waiting:${number}h` | "awaiting-approval" | "no-reply" | "awaiting-reply" | "bulk" | "overdue" | "due-today" | `auto:${string}`;
 export interface Scored {
     score: number;
-    /** Human-readable contributors, insertion order. Drives the tag on an assist nudge. */
-    reasons: string[];
+    /** Contributors in insertion order. Drives the tag on an assist nudge. */
+    reasons: AttentionReason[];
 }
 /** One user's own "later" mark on a resource, as both scorers read it. */
-export interface ParkMark {
-    remindAt: number;
-    parkedAt: number;
-}
+export type ParkMark = Pick<ResourceReminder, "remindAt" | "parkedAt">;
 export interface AttentionCtx {
     /** Whose attention. Drives the unseen + assigned-to-me boosts. */
     userId: string;
@@ -26,3 +35,5 @@ export interface AttentionCtx {
     /** Personally parked: resourceId -> own mark. */
     remindersById?: Record<string, ParkMark>;
 }
+/** Index one user's reminders the way `AttentionCtx.remindersById` wants them. */
+export declare function parkMarksById(reminders: readonly ResourceReminder[]): Record<string, ParkMark>;

package/dist/platform/localization.d.ts

@@ -4,4 +4,24 @@ type Prev = [never, 0, 1, 2, 3, 4, 5, ...0[]];
 export type Paths<T, D extends number = 5> = [D] extends [never] ? never : T extends object ? {
     [K in keyof T]-?: K extends string | number ? T[K] extends object ? `${K}` | `${K}.${Paths<T[K], Prev[D]>}` : `${K}` : never;
 }[keyof T] : "";
+/**
+ * An i18n reference as federated describes ship it: a bare key plus its variables. The hub that
+ * receives it stamps the source's namespace (`qualifyText` in platform-api).
+ */
+export interface LocalizedText {
+    key: string;
+    vars?: Record<string, string | number>;
+}
+export interface LocaleString {
+    lang: string;
+    key: string;
+    value: string;
+}
+/**
+ * Flat list, not a nested map: every consumer already iterates it. Kept flat since the http key
+ * transform that once forced it was removed (2026-08-17).
+ */
+export type LocaleBundle = LocaleString[];
+/** Authoring convenience: turn a nested { lang: { key: value } } map into a LocaleBundle. */
+export declare function flattenLocales(nested: Record<string, Record<string, string>>): LocaleBundle;
 export {};

package/dist/platform/notification.d.ts

@@ -1,4 +1,4 @@
-import { LocaleBundle } from '../entities/analytics/dashboard';
+import { LocaleBundle, LocalizedText } from './localization';
 /**
  * Role group of an app that declares its own notification kinds.
  *
@@ -7,20 +7,8 @@ import { LocaleBundle } from '../entities/analytics/dashboard';
  * `ONBOARDING_SOURCE_PROVIDER_GROUP` is a constant.
  */
 export declare const NOTIFICATION_SOURCE_PROVIDER_GROUP = "notification-source";
-/**
- * Text a reader renders without the sender knowing what it says: an i18n key from the declaring
- * app's own bundle, plus values for `{name}` placeholders.
- *
- * Not a rendered string, because one notification is read on a laptop in Dutch and pushed to a
- * phone in English. Not a bare key either: half of these lines carry data ("Vincent mentioned you")
- * and a key per person does not exist.
- *
- * Sources write **bare** keys; the hub stamps the namespace (see `qualifyText` in platform-api).
- */
-export interface NotificationText {
-    key: string;
-    vars?: Record<string, string | number>;
-}
+/** Alias of {@link LocalizedText}: sources write bare keys, the hub stamps the namespace. */
+export type NotificationText = LocalizedText;
 /**
  * One switchable kind of notification, declared by the app that sends it.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.191.0",
+  "version": "1.193.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",