@songsid/agend 2.1.12 → 2.2.0-alpha.2

package/dist/web-shell-routes.js

@@ -0,0 +1,96 @@
+/**
+ * #1408 §3: the one classifier for the web app's navigations. Every place that has to know "is this a page of the
+ * app?" asks it, and none keeps a list of its own:
+ * - web-api.ts serves the app shell for exactly these paths, never as a prefix fallback;
+ * - the gate's sign-in fallback answers a signed-out browser navigation with the sign-in page;
+ * - the public link's manifest (public-web-gateway.ts) admits these GETs.
+ *
+ * Client routes take only first segments the server's data routes never use (chat, fleet), so a page and a data
+ * read can never be confused (a test checks both directions). /view and /view/<name> are the View panel (step 2;
+ * view-api.ts serves them, open to anyone when `web.view_access` is open). /settings and /settings/<section> are the
+ * Settings panel (step 3; settings-api.ts serves them, signed in only).
+ */
+export const FLEET_TABS = ["tasks", "schedules", "teams", "org", "cache", "config"];
+export const SETTINGS_SECTIONS = ["agents", "bots", "classic", "general", "advanced"];
+const PATH_SEPARATOR_OR_CONTROL = /[/\\\u0000-\u001f\u007f]/;
+/** Longest instance name a path may carry; real names are far shorter. */
+export const MAX_INSTANCE_NAME = 128;
+/**
+ * The same rule instance paths are held to (access-path.ts): not empty, no separator, no control character, no
+ * traversal. A name that passes may still be unknown; that is the panel's "not found" state, never an error page.
+ */
+export function isSafeInstanceName(name) {
+    return name.length > 0 && name.length <= MAX_INSTANCE_NAME && !PATH_SEPARATOR_OR_CONTROL.test(name)
+        && name !== "." && !name.includes("..");
+}
+/** Decode one path segment; null when it is not valid percent-encoding. */
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return null;
+    }
+}
+/** The app shell's routes (#1408 §3). Only GET and HEAD are navigations. */
+export function shellRoute(method, path) {
+    if (method !== "GET" && method !== "HEAD")
+        return null;
+    if (path === "/ui")
+        return { kind: "shell", route: { panel: "chat", instance: null } };
+    if (path === "/ui/fleet")
+        return { kind: "shell", route: { panel: "fleet", tab: "tasks" } };
+    // #1386 part (b): the Needs you list. A page, not a read of the list — that arrives only over SSE `needs` and
+    // /ui/poll (#1374: no new read for it).
+    if (path === "/ui/needs")
+        return { kind: "shell", route: { panel: "needs" } };
+    const fleet = /^\/ui\/fleet\/([^/]+)$/.exec(path);
+    if (fleet)
+        return FLEET_TABS.includes(fleet[1]) ? { kind: "shell", route: { panel: "fleet", tab: fleet[1] } } : null;
+    const chat = /^\/ui\/chat\/([^/]+)$/.exec(path);
+    if (chat) {
+        const name = decodeSegment(chat[1]);
+        return name !== null && isSafeInstanceName(name) ? { kind: "shell", route: { panel: "chat", instance: name } } : { kind: "malformed" };
+    }
+    if (path === "/view")
+        return { kind: "shell", route: { panel: "view", instance: null } };
+    const view = /^\/view\/([^/]+)$/.exec(path);
+    if (view) {
+        const name = decodeSegment(view[1]);
+        return name !== null && isSafeInstanceName(name) ? { kind: "shell", route: { panel: "view", instance: name } } : { kind: "malformed" };
+    }
+    if (path === "/settings")
+        return { kind: "shell", route: { panel: "settings", section: "agents" } };
+    const settings = /^\/settings\/([^/]+)$/.exec(path);
+    if (settings) {
+        return SETTINGS_SECTIONS.includes(settings[1])
+            ? { kind: "shell", route: { panel: "settings", section: settings[1] } } : null;
+    }
+    // `/ui/chat` with nothing after it, or more than one segment: not a page (404 like any unknown path).
+    return null;
+}
+/** The Settings panel's pages: what settings-api.ts serves (behind the session gate). */
+export function isSettingsPage(path) {
+    const m = shellRoute("GET", path);
+    return m !== null && m.kind === "shell" && m.route.panel === "settings";
+}
+/** The View panel's pages: what view-api.ts serves, and what `web.view_access: open` lets anyone read. */
+export function isViewPage(path) {
+    const m = shellRoute("GET", path);
+    return m !== null && (m.kind === "malformed" ? path.startsWith("/view/") : m.route.panel === "view");
+}
+/**
+ * A browser navigation to a page of the web app: the shell's routes. The gate answers these, signed out, with the
+ * sign-in page instead of a JSON 401.
+ */
+export function isWebPageNavigation(path) {
+    return shellRoute("GET", path) !== null;
+}
+/** The app's client-side paths, for links the server builds (#1386 links, the tour). */
+export function chatPath(instance) {
+    return `/ui/chat/${encodeURIComponent(instance)}`;
+}
+export function viewPath(instance) {
+    return `/view/${encodeURIComponent(instance)}`;
+}
+//# sourceMappingURL=web-shell-routes.js.map

package/dist/web-shell-routes.js.map

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

package/dist/web-upload.d.ts

@@ -0,0 +1,183 @@
+export declare const UPLOAD_LIMITS: {
+    /** One file. */
+    readonly maxFileBytes: number;
+    /** Files on one message. */
+    readonly maxFiles: 5;
+    /** All files on one message together. */
+    readonly maxTotalBytes: number;
+};
+/** How long an uploaded file waits to be sent with a message before its id stops working. */
+export declare const UPLOAD_TTL_MS: number;
+/** An upload no message has taken yet is stored under this prefix; it drops the prefix when a message takes it. */
+export declare const PENDING_PREFIX = "web-pending-";
+/** The largest file the dashboard will serve back (a reply attachment can be anything the agent made). */
+export declare const MAX_SERVED_BYTES: number;
+export type UploadKind = "photo" | "document";
+export interface SniffedType {
+    kind: UploadKind;
+    mime: string;
+    ext: string;
+}
+/**
+ * The type of an upload, from its bytes. Images by signature (PNG, JPEG, GIF, WebP), PDF by `%PDF-`,
+ * text when it is valid UTF-8 with no NUL byte. Everything else is refused — no executable, archive or
+ * office format is guessed at.
+ */
+export declare function sniffUpload(bytes: Uint8Array, name: string): SniffedType | null;
+/** A file name as a label only: no directory, no control characters, no leading dots, bounded. */
+export declare function displayName(raw: string | undefined | null, fallback: string): string;
+/** Any lone surrogate replaced by U+FFFD, so the name always encodes. */
+export declare function wellFormed(s: string): string;
+export interface UploadEntry {
+    id: string;
+    instance: string;
+    path: string;
+    kind: UploadKind;
+    mime: string;
+    name: string;
+    size: number;
+    /** On the ledger's own elapsed clock (not the wall clock): when the upload window closes. */
+    expiresAt: number;
+    /**
+     * pending: uploaded, waiting for a message. reserved: a message has taken it and is being delivered (no other
+     * message can take it, and no sweep may remove it). sent: delivered — the agent has it.
+     */
+    state: "pending" | "reserved" | "sent";
+}
+export interface ServedFile {
+    id: string;
+    /** realpath at registration: a later swap for a symlink does not change what is served. */
+    realPath: string;
+    name: string;
+    mime: string;
+    size: number;
+    /** The file registered (device + inode): a file put in its place later is not served under this id (#1304 review). */
+    dev: number;
+    ino: number;
+    /** The instance whose chat shows it. */
+    instance: string;
+    kind: UploadKind;
+}
+export declare const isFileId: (id: string) => boolean;
+/** Images the browser may show inline; everything else is served as a download. */
+export declare const INLINE_MIME: Set<string>;
+/**
+ * Uploads waiting for their message, and every file the dashboard may fetch back. In memory: ids from
+ * before a restart stop working (the files stay in the inbox, where the agent got them).
+ */
+export declare class WebFileLedger {
+    private readonly uploads;
+    /** The file each upload was written as (device + inode): a rename moves only that file (#1304 review). */
+    private readonly written;
+    private readonly served;
+    private readonly now;
+    private readonly maxServed;
+    constructor(opts?: {
+        now?: () => number;
+        maxServed?: number;
+    });
+    /**
+     * Store an upload in `inboxDir` under a name chosen here and register it. The directory is made
+     * private (0700), the file 0600, written exclusively (never over an existing file).
+     */
+    storeUpload(input: {
+        instance: string;
+        inboxDir: string;
+        bytes: Uint8Array;
+        name: string;
+        type: SniffedType;
+    }): UploadEntry;
+    /**
+     * The uploads a message names, all or nothing: each must exist, belong to this instance, not be
+     * expired and be waiting for a message; together within the per-message limits. On success they are
+     * RESERVED for this message — no other message can take them, no sweep removes them — until the caller
+     * says how the delivery went: commit() when it was delivered, release() when it definitely was not.
+     */
+    takeForMessage(instance: string, ids: readonly string[]): {
+        ok: true;
+        entries: UploadEntry[];
+    } | {
+        ok: false;
+        error: string;
+    };
+    /** Move an upload's file (same directory) and keep what is served for its id on the new path. */
+    private rename;
+    /** Is the file at `p` the one this ledger wrote for `e` (regular, same size, same device + inode)? */
+    private isWritten;
+    /** The files this process still owns — waiting for a message or on their way: a sweep must not touch them. */
+    ownedPaths(): Set<string>;
+    /** The reserved uploads were delivered: they are the agent's now. */
+    commit(entries: readonly UploadEntry[]): void;
+    /**
+     * The delivery definitely did not happen: the uploads wait for a message again, and the user can retry with the
+     * same ids. One whose window closed meanwhile is removed now (file and id) — its sweep has already run.
+     */
+    release(entries: readonly UploadEntry[]): void;
+    /**
+     * Make a file fetchable by id (an upload, or a file an agent attached to its reply). The path is
+     * resolved now and must be a regular file within the size limit; null when it is not.
+     */
+    registerServed(input: {
+        id?: string;
+        path: string;
+        name?: string;
+        mime?: string;
+        instance: string;
+        kind?: UploadKind;
+    }): ServedFile | null;
+    /**
+     * The bytes of a served file, re-checked at read time: opened without following a symlink, still a
+     * regular file, still the file (device + inode) and size it was registered with. Null when any of that fails.
+     */
+    read(id: string): {
+        file: ServedFile;
+        bytes: Buffer;
+    } | null;
+    /** Forget an instance's files (it was deleted). The files themselves are its workspace's to remove. */
+    forget(instance: string): void;
+    /**
+     * Drop what is done with. A sent upload leaves the list (the agent has it; the file stays in the inbox, as one
+     * from Telegram does). One that expired before any message took it was never seen by anyone but this ledger:
+     * its file is deleted with its id, so abandoned uploads do not pile up in the workspace.
+     */
+    prune(): void;
+}
+/**
+ * The text and meta an agent gets for a message with files — the same tags and keys a Telegram
+ * message produces (attachment-handler.ts), so agents need nothing new.
+ */
+export declare function attachmentDelivery(message: string, entries: readonly UploadEntry[]): {
+    text: string;
+    meta: Record<string, string>;
+};
+/** What the chat shows for a file: never the path. */
+export declare function publicAttachment(f: {
+    id: string;
+    kind: UploadKind;
+    name: string;
+    size: number;
+    mime: string;
+}): {
+    id: string;
+    kind: UploadKind;
+    name: string;
+    size: number;
+    mime: string;
+};
+/**
+ * At fleet startup (#1273): the ledger of uploads waiting for a message lives in memory, so after a restart an
+ * upload no message took is nobody's — its id is gone. Remove each such file (named web-pending-…) in every
+ * workspace inbox once it is older than the upload window. Files a message took (web-…, no "pending") are the
+ * agent's and follow the inbox's ordinary 7-day rotation, exactly like a file from Telegram; nothing else in an
+ * inbox is ever touched here.
+ *
+ * Age is the file's mtime against the wall clock — the only clock a file has. A future mtime (the clock was set
+ * back) counts as just written, never as a negative age, so it is kept and looked at again later; a clock set
+ * forward can only remove an upload early, and after a restart none of them can be sent anyway. The uploads this
+ * process holds (`owned`, by inbox path) are skipped: their window is the ledger's elapsed time, not a file's mtime.
+ * Returns how many were removed and, when younger ones remain, in how long the next one comes due.
+ */
+export declare function sweepOrphanedUploads(workspacesDir: string, nowMs?: number, ttlMs?: number, owned?: ReadonlySet<string>): {
+    deleted: number;
+    nextDueInMs: number | null;
+};