@songsid/agend 2.3.2-beta.9 → 2.3.3-beta.1

package/dist/web-office-pack-tools.d.ts

@@ -0,0 +1,241 @@
+import { type CheckedPack } from "./ui/fleet-office-pack.js";
+import { type OfficeSkinStore } from "./web-office-skins.js";
+import type { Office, OfficeStore } from "./web-office-store.js";
+export declare const OFFICE_PACK_TOOL_LIMITS: {
+    readonly batchesPerHour: 20;
+    readonly bytesPerHour: number;
+    /** Pending changes waiting for an admin's yes: at most 8 in the fleet, 200 MiB of pictures, each for 24 hours. */
+    readonly pending: 8;
+    readonly pendingBytes: number;
+    readonly pendingMs: number;
+    /** #2695: office_pack_check's own hourly budget, in wire bytes (one full batch fits several times). */
+    readonly checkBatchesPerHour: 60;
+    readonly checkBytesPerHour: number;
+    /** The log keeps its newest entries: at most this many lines once it passes 512 KiB. */
+    readonly logLines: 500;
+    readonly logBytes: number;
+};
+export declare const OFFICE_PACK_APPROVALS: readonly ["apply", "approve"];
+export type OfficePackApproval = typeof OFFICE_PACK_APPROVALS[number];
+/** Until an admin chooses: every change waits for a yes. */
+export declare const OFFICE_PACK_APPROVAL_DEFAULT: OfficePackApproval;
+/** The built-in styles an office may be drawn in besides a kept pack (fleet-office-skin.js BUILT_IN_SKINS). */
+export declare const BUILT_IN_STYLES: readonly ["pixel", "studio", "cozy"];
+export declare const OFFICE_PACK_TOOLS: readonly ["office_pack_check", "office_pack_upload", "office_pack_delete", "office_pack_restore", "office_pack_list", "office_set_style"];
+export type OfficePackAnswer = Record<string, unknown>;
+export declare const mib: (bytes: number) => string;
+/**
+ * One office's override entry that does not fit a pack: `entry` is what is dropped — "seats.desks", "furniture.rack",
+ * "furnitureNight.rack", one seat's reservation "seatFor.desks.0" (#2691), or "seatFor.desks" for an area's empty
+ * reservation map. "overrides" (UNDROPPABLE) when the layout fails as a whole but no single entry does: never dropped.
+ */
+export interface OverrideConflict {
+    office: string;
+    name: string;
+    entry: string;
+    rule: string;
+}
+/** A conflict no exact drop clears: the change is refused even with drop_invalid_overrides (never a whole layout lost). */
+export declare const UNDROPPABLE = "overrides";
+export declare const undroppable: (conflicts: readonly OverrideConflict[]) => boolean;
+/**
+ * Each stored office whose overrides were made on `pack` (overrides.pack: the ones PUT /ui/offices checks against it),
+ * put on it whole (applyOverrides, as that save does — every entry, the reservations too), and where that fails entry
+ * by entry: what does not fit. When the entries found are dropped the rest must fit whole; if not (a rule between
+ * entries), the office's conflict is UNDROPPABLE instead, and the change is refused.
+ */
+export declare function overrideConflicts(offices: readonly Office[], pack: CheckedPack): OverrideConflict[];
+/** The offices with exactly those entries dropped (an office left with nothing but `pack` loses its overrides). An UNDROPPABLE conflict is never passed here. */
+export declare function dropConflicts(offices: readonly Office[], conflicts: readonly OverrideConflict[]): Office[];
+/** How many dropped entries a notice names; the rest are counted. */
+export declare const DROPS_SHOWN = 6;
+/**
+ * What a change drops, for its notice (an admin approving from General sees it): the count, then each office with its
+ * entries — "Ops: seats.desks, furniture.rack; Den: …" — the first DROPS_SHOWN entries, "…and N more" after them.
+ */
+export declare function dropsText(conflicts: readonly OverrideConflict[]): string;
+/** How much one agent may change: batches and bytes an hour (accepted calls only; a monotonic clock; memory only). */
+export declare class OfficePackBatchLimiter {
+    private readonly now;
+    private readonly limits;
+    private readonly batches;
+    constructor(now?: () => number, limits?: {
+        batchesPerHour: number;
+        bytesPerHour: number;
+    });
+    private recent;
+    /** Whether a batch of `bytes` may go now; else the ms until it may (never: larger than the hour's budget). */
+    check(instance: string, bytes: number): {
+        ok: true;
+    } | {
+        ok: false;
+        retry_after_ms: number | null;
+        why: string;
+    };
+    record(instance: string, bytes: number): void;
+    /** What is left of the hour's budget. */
+    left(instance: string): {
+        batches: number;
+        bytes: number;
+    };
+    forget(instance: string): void;
+}
+/**
+ * The receiving side of web-office-pack-read.ts's parts: one unfinished batch per instance and tool, dropped after a
+ * minute without a part; at most 8 at once and twice a batch's wire size in memory. The caller is the connection's
+ * instance, never a field of a part; no path is ever accepted.
+ */
+export declare class OfficePackUploads {
+    private readonly clock;
+    private readonly pending;
+    constructor(clock?: () => number);
+    forget(instance: string): void;
+    /** `admit`: asked once a batch's first part is valid, with the batch's wire bytes; an answer refuses the batch. */
+    accept(instance: string, tool: string, args: Record<string, unknown>, admit?: (bytes: number) => OfficePackAnswer | null): {
+        done: false;
+        answer: OfficePackAnswer;
+    } | {
+        done: true;
+        doc: unknown;
+        options: Record<string, unknown>;
+    };
+}
+/** A pending change's view (no picture bytes): the page, the notice and office_pack_list show it. */
+export interface PackChangeView {
+    id: string;
+    instance: string;
+    at: number;
+    expires_at: number;
+    action: "upload" | "delete" | "restore" | "style";
+    packs: Array<{
+        id: string;
+        name: string;
+        files?: number;
+        bytes?: number;
+        replaces?: string | null;
+    }>;
+    office?: string;
+    style?: string;
+    keep_previous?: boolean;
+    drop_invalid_overrides?: boolean;
+    drops?: OverrideConflict[];
+}
+export interface PackLogEntry {
+    at: string;
+    by: string;
+    action: string;
+    pack?: string;
+    name?: string;
+    version?: string;
+    files?: number;
+    bytes?: number;
+    manifest_sha256?: string;
+    pictures?: Record<string, string>;
+    previous_kept?: boolean;
+    replaced_version?: string | null;
+    office?: string;
+    style?: string;
+    dropped_overrides?: OverrideConflict[];
+    change?: string;
+    approved_by?: string;
+    approval?: string;
+    outcome?: string;
+}
+export interface OfficePackToolsDeps {
+    skins: OfficeSkinStore;
+    offices: OfficeStore;
+    /** The agents whose `office_packs` feature is on (the Office page shows them). */
+    allowedAgents(): string[];
+    /** Tell the fleet's admins (General): one short message; with `pending`, the change waits for their yes (buttons). */
+    notice(text: string, pending?: PackChangeView): void;
+    /** A pending change was decided or expired (its notice's buttons are retired with `text`). */
+    settled(id: string, text: string): void;
+    /** What changed, for every page: the packs' rev, the offices' rev, the agent changes (pending, approval, log). */
+    changed(what: {
+        skins?: string;
+        offices?: number;
+        changes?: boolean;
+    }): void;
+    logger?: {
+        info(obj: object, msg: string): void;
+        warn(obj: object, msg: string): void;
+    };
+}
+export declare class OfficePackTools {
+    private readonly deps;
+    readonly limiter: OfficePackBatchLimiter;
+    /** #2695: office_pack_check's budget (wire bytes), apart from the changes'. */
+    readonly checkLimiter: OfficePackBatchLimiter;
+    readonly uploads: OfficePackUploads;
+    private readonly pending;
+    private readonly now;
+    private approvalCache;
+    constructor(deps: OfficePackToolsDeps, opts?: {
+        limiter?: OfficePackBatchLimiter;
+        checkLimiter?: OfficePackBatchLimiter;
+        uploads?: OfficePackUploads;
+        now?: () => number;
+    });
+    private get settingsPath();
+    private get logPath();
+    /** The admins' choice: "apply" (at once) or "approve" (a pending change until an admin's yes). Kept beside the packs. */
+    approval(): OfficePackApproval;
+    setApproval(mode: unknown, by: string): {
+        ok: true;
+        approval: OfficePackApproval;
+    } | {
+        ok: false;
+        error: string;
+    };
+    /** Append one entry to the log (and the fleet log); the newest are kept once it grows past its cap. */
+    private log;
+    /** The newest log entries first. */
+    logEntries(limit?: number): PackLogEntry[];
+    /** A version's digests: the manifest's sha256 and each picture's (its kept bytes), from the upload or from disk. */
+    private digest;
+    private recordOf;
+    private sweep;
+    /** The pending changes (all, or one agent's). */
+    pendingViews(instance?: string): PackChangeView[];
+    /** GET /ui/office-pack-changes: what the Office page shows an admin. */
+    changes(): {
+        approval: OfficePackApproval;
+        agents: string[];
+        pending: PackChangeView[];
+        log: PackLogEntry[];
+    };
+    /** The tool call, from the instance its connection (or agent token) belongs to. */
+    handle(instance: string, tool: string, args: Record<string, unknown>): OfficePackAnswer;
+    /** #2695: a check's batch counts against its own budget as it starts (refused before any more of it arrives). */
+    private admitCheck;
+    private list;
+    /** The batch document, each pack checked as the web upload checks it. */
+    private decode;
+    /** Whether the checked packs may go in now: the pack count, the disk budget, the offices' overrides. */
+    private fit;
+    private check;
+    /** A change from an agent: judged, counted, then applied at once or held for an admin's yes. */
+    private submit;
+    private logFields;
+    /** What a change would do, or why it cannot: the packs it names (for the view), the override entries it drops. */
+    private judge;
+    /** Make the change (judged again first). Its answer for the agent, and a one-line summary for the notice. */
+    private apply;
+    /**
+     * An admin's yes or no on a pending change (the Office page, or the notice's buttons). A yes judges it again and
+     * applies it; what happened is the answer (and the notice's new text).
+     */
+    decide(id: string, decision: "approve" | "reject", by: string): {
+        ok: true;
+        text: string;
+        applied?: OfficePackAnswer;
+    } | {
+        ok: false;
+        status: 404 | 409;
+        error: string;
+        text: string;
+    };
+    forget(instance: string): void;
+}
+/** One line for a notice: what a pending change would do. */
+export declare function summaryOf(v: PackChangeView): string;