@songsid/agend 2.2.1 → 2.2.5

package/dist/web-ambient.js

@@ -0,0 +1,161 @@
+/**
+ * #2117 (from #2115's proposal): an **ambient** effect is declarative, like a widget. The agent supplies a small closed
+ * spec (a preset, its glyphs and a few numbers); the page draws it with its own code (src/ui/chat-ambient.js): plain
+ * nodes animated by the Web Animations API, under the chat's content and never taking a click. No agent code runs, so
+ * an ambient needs no Worker, preview origin, HTML-preview consent or FPS baseline (Canvas Worker effects do).
+ *
+ * A chat holds at most one looping ambient (`fall`, `rise`, `twinkle`) and one click ambient (`burst-on-click`): falling
+ * petals and click stars together. One module validates and canonicalises the spec; the store keeps only what this
+ * returns, and the page checks the bounds again.
+ */
+import { canonicalColor, canonicalText } from "./web-theme.js";
+export const AMBIENT_PRESETS = ["fall", "rise", "twinkle", "burst-on-click"];
+/** Where a preset is kept: a chat has one of each. */
+export const AMBIENT_KINDS = ["loop", "click"];
+export const ambientKind = (preset) => preset === "burst-on-click" ? "click" : "loop";
+export const AMBIENT_GLYPHS_MAX = 4;
+export const AMBIENT_GLYPH_GRAPHEMES = 2;
+export const AMBIENT_COLORS_MAX = 5;
+export const AMBIENT_SPEC_MAX_BYTES = 1024;
+/** The page's caps (chat-ambient.js keeps the same numbers): 24 looping particles, 3 bursts of 16 at once. */
+export const AMBIENT_LOOP_MAX = 24;
+export const AMBIENT_BURST_MAX = 16;
+export const AMBIENT_BURSTS_LIVE = 3;
+/** Each preset's bounds and defaults. A count is particles (loops) or particles per click (burst). */
+export const AMBIENT_RULES = {
+    fall: { count: [1, AMBIENT_LOOP_MAX], countDefault: 12, duration: [4, 30], durationDefault: [9, 19] },
+    rise: { count: [1, AMBIENT_LOOP_MAX], countDefault: 12, duration: [4, 30], durationDefault: [9, 19] },
+    twinkle: { count: [1, AMBIENT_LOOP_MAX], countDefault: 12, duration: [1, 10], durationDefault: [2, 5] },
+    "burst-on-click": { count: [4, AMBIENT_BURST_MAX], countDefault: 10, duration: [0.3, 2], durationDefault: [0.5, 0.9] },
+};
+export const AMBIENT_SIZE = [10, 40];
+export const AMBIENT_SIZE_DEFAULT = [14, 22];
+export const AMBIENT_SWAY_MAX = 80;
+export const AMBIENT_SWAY_DEFAULT = 40;
+export const AMBIENT_SPREAD = [20, 120];
+export const AMBIENT_SPREAD_DEFAULT = [34, 90];
+export const AMBIENT_ROTATE_MAX = 720;
+export const AMBIENT_ROTATE_DEFAULT = 300;
+export const AMBIENT_OPACITY_DEFAULT = [0, 0.85, 0.15];
+const KEYS = ["preset", "glyphs", "colors", "count", "duration", "size", "sway", "spread", "rotate", "opacity", "layer"];
+const ASSET_ID = /^[0-9a-f]{32}$/;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+/**
+ * #2155: a client that read an older declaration of the ranges (a tuple, which codex turned into `Array<string>`) sends
+ * `["3", "6"]`. A plain decimal string in one of these arrays is taken as its number; anything else is left as it is,
+ * for the check to refuse.
+ */
+const DECIMAL = /^\s*-?(?:\d+(?:\.\d*)?|\.\d+)\s*$/;
+const numbers = (v) => Array.isArray(v) ? v.map(x => typeof x === "string" && DECIMAL.test(x) ? Number(x) : x) : v;
+/** Two decimals are plenty for seconds, pixels and opacity, and keep the stored spec short. */
+const round = (n) => Math.round(n * 100) / 100;
+/**
+ * A spec, closed and canonical: unknown keys, a value out of its preset's bounds or a glyph that is not 1..2 visible
+ * graphemes (or one of this instance's `glyph` pictures, when `glyphAsset` is given) are refused.
+ */
+export function checkAmbient(raw, opts = {}) {
+    const errors = [];
+    const bad = (path, problem) => { errors.push({ path, problem }); };
+    if (!isObj(raw))
+        return { ok: false, errors: [{ path: "ambient", problem: "an object { preset, glyphs, … }" }] };
+    for (const k of Object.keys(raw))
+        if (!KEYS.includes(k))
+            bad(k.slice(0, 40), "unknown key");
+    const preset = raw.preset;
+    if (!AMBIENT_PRESETS.includes(preset))
+        return { ok: false, errors: [...errors, { path: "preset", problem: AMBIENT_PRESETS.join(" | ") }] };
+    const rules = AMBIENT_RULES[preset];
+    const glyphs = [];
+    if (!Array.isArray(raw.glyphs) || raw.glyphs.length < 1 || raw.glyphs.length > AMBIENT_GLYPHS_MAX)
+        bad("glyphs", `1..${AMBIENT_GLYPHS_MAX} glyphs`);
+    else
+        raw.glyphs.forEach((g, i) => {
+            if (typeof g === "string") {
+                const t = canonicalText(g, 1, AMBIENT_GLYPH_GRAPHEMES);
+                if (t === null)
+                    bad(`glyphs.${i}`, `1..${AMBIENT_GLYPH_GRAPHEMES} visible characters (an emoji, ✦, ❀)`);
+                else
+                    glyphs.push(t);
+            }
+            else if (isObj(g) && Object.keys(g).length === 1 && typeof g.asset === "string" && ASSET_ID.test(g.asset)) {
+                if (opts.glyphAsset && !opts.glyphAsset(g.asset))
+                    bad(`glyphs.${i}.asset`, "not one of this instance's glyph pictures (set_web_theme_asset slot glyph)");
+                else
+                    glyphs.push({ asset: g.asset });
+            }
+            else
+                bad(`glyphs.${i}`, "a short string, or { asset: <id> }");
+        });
+    const colors = [];
+    if (raw.colors !== undefined) {
+        if (!Array.isArray(raw.colors) || raw.colors.length > AMBIENT_COLORS_MAX)
+            bad("colors", `0..${AMBIENT_COLORS_MAX} colours`);
+        else
+            raw.colors.forEach((c, i) => { const v = canonicalColor(c); if (v === null)
+                bad(`colors.${i}`, "#rgb or #rrggbb");
+            else
+                colors.push(v); });
+    }
+    const int = (key, [lo, hi], dflt) => {
+        const v = raw[key];
+        if (v === undefined)
+            return dflt;
+        if (!Number.isSafeInteger(v) || v < lo || v > hi) {
+            bad(key, `a whole number ${lo}..${hi}${key === "count" ? ` for ${preset}` : ""}`);
+            return dflt;
+        }
+        return v;
+    };
+    const num = (key, [lo, hi], dflt) => {
+        const v = raw[key];
+        if (v === undefined)
+            return dflt;
+        if (!isNum(v) || v < lo || v > hi) {
+            bad(key, `a number ${lo}..${hi}`);
+            return dflt;
+        }
+        return round(v);
+    };
+    const range = (key, [lo, hi], dflt) => {
+        const v = numbers(raw[key]);
+        if (v === undefined)
+            return [dflt[0], dflt[1]];
+        if (!Array.isArray(v) || v.length !== 2 || !v.every(isNum) || v[0] < lo || v[1] > hi || v[0] > v[1]) {
+            bad(key, `[min, max] within ${lo}..${hi}${key === "duration" ? ` seconds for ${preset}` : ""}`);
+            return [dflt[0], dflt[1]];
+        }
+        return [round(v[0]), round(v[1])];
+    };
+    const count = int("count", rules.count, rules.countDefault);
+    const duration = range("duration", rules.duration, rules.durationDefault);
+    const size = range("size", AMBIENT_SIZE, AMBIENT_SIZE_DEFAULT);
+    const sway = num("sway", [0, AMBIENT_SWAY_MAX], AMBIENT_SWAY_DEFAULT);
+    const spread = range("spread", AMBIENT_SPREAD, AMBIENT_SPREAD_DEFAULT);
+    const rotate = num("rotate", [0, AMBIENT_ROTATE_MAX], AMBIENT_ROTATE_DEFAULT);
+    let opacity = [...AMBIENT_OPACITY_DEFAULT];
+    if (raw.opacity !== undefined) {
+        const o = numbers(raw.opacity);
+        if (!Array.isArray(o) || o.length !== 3 || !o.every(x => isNum(x) && x >= 0 && x <= 1))
+            bad("opacity", "[start, peak, end], each 0..1");
+        else
+            opacity = [round(o[0]), round(o[1]), round(o[2])];
+    }
+    if (raw.layer !== undefined && raw.layer !== "behind")
+        bad("layer", "\"behind\" (an ambient never covers the chat)");
+    if (errors.length)
+        return { ok: false, errors };
+    const spec = { preset, glyphs, colors, count, duration, size, sway, spread, rotate, opacity, layer: "behind" };
+    if (Buffer.byteLength(JSON.stringify(spec), "utf8") > AMBIENT_SPEC_MAX_BYTES)
+        return { ok: false, errors: [{ path: "ambient", problem: `at most ${AMBIENT_SPEC_MAX_BYTES} bytes` }] };
+    return { ok: true, value: spec };
+}
+/** The glyph pictures a spec names. */
+export function ambientAssets(spec) {
+    return spec.glyphs.flatMap(g => typeof g === "string" ? [] : [g.asset]);
+}
+/** One line per problem, for a tool's refusal. */
+export function ambientProblems(errors) {
+    return errors.map(e => `${e.path}: ${e.problem}`).join("; ");
+}
+//# sourceMappingURL=web-ambient.js.map

package/dist/web-ambient.js.map

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

package/dist/web-api.d.ts

@@ -1,24 +1,29 @@
 import { type HumanOrigin } from "./human-delivery-receipts.js";
+import { type HumanAuthority, type WebAuthorityResult, type WebPeer } from "./authority/web-authority.js";
 import type { CachedImage } from "./web-images.js";
 import type { SettingsExecution } from "./settings-transaction.js";
 import type { PaneContextSource } from "./pane-context-cache.js";
+import type { OwnerCssStore } from "./web-owner-css-store.js";
+import type { ModStore } from "./web-mod-store.js";
+import type { WebEffectService } from "./web-effect-service.js";
+import type { ThemeStore } from "./web-theme-store.js";
+import type { WebAppearance } from "./web-appearance.js";
 import type { SendOpts } from "./channel/types.js";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { LifecycleCreateArgs } from "./instance-lifecycle.js";
 import { type PreviewAvailability } from "./web-preview.js";
 import { type WebChatHistory } from "./web-chat-history.js";
 import { type WebFileLedger } from "./web-upload.js";
-import type { WebSessionStore } from "./web-session.js";
+import type { WebSessionStore, SessionRecord } from "./web-session.js";
 import { type WebPrefsStore } from "./web-prefs.js";
 import { type WebAccount } from "./web-profile.js";
 import { type MentionNames, type MentionQuery } from "./web-mentions.js";
 import type { ExplicitInstanceRemoval } from "./instance-removal.js";
 /**
- * Push a single SSE frame to every client. If a client throws (closed socket
- * after a network drop, etc.), evict it from the set and continue — without
- * the eviction the dead entry leaks forever, and without the try/catch a
- * single dead client breaks delivery to every client iterated after it.
+ * #1920 §5.2: one event for the guests' streams only, each as projected for it — a message that has just become what
+ * its channel saw (an admin's page already has it, unchanged).
  */
+export declare function broadcastToGuests(clients: Set<ServerResponse>, event: string, data: unknown, onError?: (err: unknown) => void): void;
 export declare function broadcastSseEvent(clients: Set<ServerResponse>, event: string, data: unknown, onError?: (err: unknown) => void, id?: string): void;
 /** One SSE frame; `id` (a chat message's) lets a reconnecting EventSource say what it last saw. */
 export declare function sseFrame(event: string, data: unknown, id?: string): string;
@@ -27,6 +32,14 @@ export declare const SSE_HEARTBEAT_MS = 10000;
 /** Minimal interface — only what web-api needs from FleetManager. */
 export interface WebApiContext {
     readonly webToken: string | null;
+    /** #2072: what this host can run (the published snapshot); absent in a hand-built context. */
+    backendAvailabilityRows?(): import("./backend-availability.js").BackendAvailability[];
+    /** #2072: a backend's cached model catalog, for an instance's own account when one is named; never a probe. */
+    modelCatalogFor?(backend: string, instance: string | null): Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
     /** Absent in a hand-built context: cookies are then simply not a credential, the header token still is. */
     readonly webSessions?: WebSessionStore | null;
     readonly dataDir: string;
@@ -36,9 +49,11 @@ export interface WebApiContext {
             group_id?: number | string;
             mode?: string;
         };
+        health_port?: number;
         web?: {
             echo_to_channel?: boolean;
             usage_panel?: boolean;
+            usage_report_on_public_link?: boolean;
             upload_max_file_mb?: number;
             upload_max_total_mb?: number;
         };
@@ -108,13 +123,20 @@ export interface WebApiContext {
      * many channels were posted to. Never rejects the web send on failure.
      */
     sendClassicWebEcho?(instance: string, text: string, sender?: string): Promise<number>;
+    /** #1920 §5.2: a web message's channel copy was sent — guests of that channel may see it now. */
+    webMessageInChannel?(instance: string, messageId: string): void;
     /** false: definitely not delivered (the instance's IPC is gone, or it was restarted meanwhile). */
-    deliverToInstance(instanceName: string, payload: Record<string, unknown>): Promise<boolean | void>;
-    deliverHumanToInstance?(instanceName: string, payload: Record<string, unknown>, origin: HumanOrigin, originalBody: string): Promise<boolean | void>;
+    deliverToInstance(instanceName: string, payload: Record<string, unknown>, options?: {
+        stillCurrent?: () => boolean;
+    }): Promise<boolean | void>;
+    deliverHumanToInstance?(instanceName: string, payload: Record<string, unknown>, origin: HumanOrigin, originalBody: string, options?: {
+        stillCurrent?: () => boolean;
+    }): Promise<boolean | void>;
     getUiStatus(): unknown;
     /** Current owned pane reader shared with status; absent means context is unavailable. */
     getPaneContextSource?(name: string): PaneContextSource | null;
     /** #1306: which preview origin this /ui load may frame (Host and the TLS signal only); absent: previews off. */
+    readonly effectBoot?: string;
     previewForUi?(hostHeader: string | undefined, secure: boolean): PreviewAvailability & {
         boot: string | null;
     };
@@ -141,6 +163,27 @@ export interface WebApiContext {
     readonly sseHeartbeatMs?: number;
     /** #1665: the web preferences kept on the host (one bucket: the operator's); absent: /ui/prefs is not offered. */
     readonly webPrefs?: WebPrefsStore;
+    /** #1629 r4 §3: each person's own CSS (human sessions only; never the public link, never an agent). */
+    readonly ownerCss?: OwnerCssStore;
+    /** #1629: every instance's theme (web-themes.json), read by the page; a person's reset and lock. */
+    readonly themeStore?: ThemeStore;
+    readonly webAppearance?: WebAppearance;
+    /** #1629 r4-5: installed mods and a person's staged import. */
+    readonly mods?: ModStore;
+    /** #1629 B2: session-only effect library, runtime resources and reported host profiles. */
+    readonly effectService?: WebEffectService;
+    /** #1629 r4-5: an instance's card text as shown (a person's fields over the agent's), for a mod's export. */
+    modCardText?(name: string): {
+        tagline?: string;
+        bio?: string;
+    };
+    /** #1629 r4-5c: an effect this person may export (their own claim, or human-shared); null for anyone else's. */
+    modPlacedEffect?(person: string, id: string): {
+        name: string;
+        files: ReadonlyMap<string, Uint8Array>;
+    } | null;
+    /** A fleet.yaml instance (own key) or a ClassicBot room, now. */
+    isKnownInstance?(name: string): boolean;
     startInstance(name: string, config: unknown, topicMode: boolean): Promise<void>;
     stopInstance(name: string): Promise<{
         backgroundWorkEnded: boolean;
@@ -151,10 +194,21 @@ export interface WebApiContext {
     needsYouItems?(): unknown[];
     /** #1389: the org chart's structure (fleet.yaml's teams, General, descriptions, thread links); absent: an empty chart. */
     orgChart?(): unknown;
+    /** #1918: in-flight and recently finished cross-instance traffic, bounded (fleet-traffic.ts). */
+    trafficSnapshot?(): {
+        now: string;
+        items: unknown[];
+        delegations?: unknown[];
+    };
     /** #1218: an instance's Log steps, read on demand (null: no such instance; `{ enabled: false }`: the Log is off). */
     logSteps?(name: string, q: import("./log-service.js").LogQuery): Promise<unknown>;
     /** #1468: the prompt-cache expiry analysis for a window ("24h" | "7d" | "30d"); absent: not offered. */
     cacheReport?(window: string): Promise<unknown>;
+    /** #2122: the usage report (Fleet → Usage); absent: not offered. */
+    usageReport?(params: {
+        range: import("./usage-report.js").UsageRange;
+        group: import("./usage-report.js").UsageGroup;
+    }): Promise<unknown>;
     /** #1269: an instance's chat command from the web chat (web-commands.ts); absent: not offered. */
     webCommand?(input: {
         instance: string;
@@ -164,10 +218,41 @@ export interface WebApiContext {
     }, opts: {
         publicLink: boolean;
         person?: WebPerson;
+        authority?: HumanAuthority;
     }): Promise<{
         status: number;
         body: unknown;
     }>;
+    /** #1939 S2b: "Authorize this browser" — the Confirm card in the account's DM; and what the app shows for this browser. */
+    requestSessionAuthorization?(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+    }): Promise<{
+        ok: true;
+        expiresInMs: number;
+    } | {
+        ok: false;
+        refusal: string;
+        retryAfterMs?: number;
+    }>;
+    webSessionAuthorization?(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+    }): {
+        state: string;
+        until?: number;
+        expiresInMs?: number;
+        reason?: string;
+    };
+    /** #1939 S1: the design's §3 for one request (`instance` once the body names it); absent: web carries no authority. */
+    webAuthority?(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+        instance?: string;
+    }): WebAuthorityResult;
     /**
      * #1827: a web person — for the account a session is bound to (none: the operator) — as agents and chats see them.
      * Absent: everyone is "web-user", as before.
@@ -197,6 +282,8 @@ export interface WebApiContext {
         key: string;
         userId: string;
         name: string;
+        guest?: true;
+        authority?: HumanAuthority;
     }): Promise<{
         status: number;
         error?: string;
@@ -255,6 +342,18 @@ export interface WebApiContext {
         delete(id: string): void;
     } | null;
 }
+/** A person's export: an instance's look (theme, identity, its widgets), their sidebar widget and their own CSS. */
+export declare function exportMod(ctx: WebApiContext, person: string, body: Record<string, unknown>): {
+    ok: true;
+    text: string;
+    filename: string;
+    omitted: number;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+    detail?: string;
+};
 /** #1827: a web person as the web chat shows them to agents and chats. */
 export interface WebPerson {
     /** Their key in the web preferences (web-profile.ts webPersonKey): never shown. */
@@ -287,6 +386,8 @@ export type PublicPreviewForUi = PreviewAvailability & {
     detail?: string;
 };
 export interface AppShellContext {
+    /** #2118: independent trusted opaque effect document, never HTML-preview consent or listener state. */
+    readonly effectBoot?: string;
     previewForUi?(hostHeader: string | undefined, secure: boolean): (PreviewAvailability & {
         boot: string | null;
     }) | null;
@@ -302,6 +403,15 @@ export interface AppShellContext {
     } | null;
     /** #1665: the host's theme and language go into the page itself, so a device paints them before any script reads. */
     readonly webPrefs?: WebPrefsStore;
+    /** #1629 r4 §3: which owner CSS this load's person has in force (data-owner-css), for a signed-in human session only. */
+    readonly ownerCss?: OwnerCssStore;
+    readonly webToken?: string | null;
+    readonly webSessions?: WebApiContext["webSessions"];
+    /** #1920 phase 3: a guest's page says who it is signed in as (its web name and platform), for its "Guest" chip. */
+    guestBadge?(owner: WebAccount): {
+        name: string;
+        platform: string;
+    };
 }
 export type AppShellMode = "full" | "view-only";
 /** The app shell page for one entry, under the panels' CSP; it may frame exactly <preview origin>/frame, and only