@sigrun/ext-gateway 0.0.0-stage → 0.1.1

package/dist/supervisor.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The per-channel supervisor (spec §8.12): a backoff state machine over
+ * ONE channel adapter. `start` resolves once the first attempt settled
+ * (running or backoff — a failing adapter never wedges boot); retries
+ * ride the injected timer.
+ *
+ * Pinned values (the plan's Global Constraints): the backoff delay
+ * starts at 1000 ms and doubles per consecutive failure, capped at
+ * 300000 ms, plus jitter from the injected `random()` — jitter only
+ * ever ADDS time (the delay stays within [base, min(2·base, cap)]), so
+ * a retry never fires early against the pinned floor. 600000 ms of
+ * running RESETS the delay (a healthy stretch earns a fresh 1000 ms).
+ *
+ * State machine: a `not_configured` adapter is never started (terminal
+ * state, the contract's rule). A rejected `start` and a later `ctx.fail`
+ * both enter `backoff` and schedule ONE retry — the failure path is
+ * event-driven, not a polling loop, so a healthy channel owns zero
+ * timers. `stop()` cancels the pending retry, waits for an in-flight
+ * attempt to settle, and awaits the adapter's optional `stop`.
+ */
+import type { ChannelContext, ChannelContribution } from "@sigrun/sigrun/extension";
+import type { EngineLog } from "./log.js";
+/** The supervision state machine's states (spec §8.12 status values).
+ *  `failed` is the engine-side CONFIG-ERROR state — a supervisor never
+ *  enters it (see engine.ts's static rows). */
+export type ChannelState = "stopped" | "not_configured" | "connecting" | "running" | "backoff" | "failed";
+/** The status-report callback a started adapter drives (the contract's
+ *  `ChannelContext.status` parameter — only the states a LIVE adapter
+ *  can report; `backoff`/`failed`/`stopped` are supervisor-owned). */
+export type StatusSink = (state: {
+    readonly state: "connecting" | "running";
+    readonly detail?: string;
+}) => void;
+/** One channel's status row (the admin status route's shape). */
+export interface ChannelStatus {
+    readonly state: ChannelState;
+    readonly detail?: string;
+    /** Clock ms when the row entered its current state. */
+    readonly since: number;
+    readonly lastError?: string;
+    readonly counts: {
+        readonly admitted: number;
+        readonly dropped: number;
+        readonly delivered: number;
+        readonly failed: number;
+    };
+}
+/** The supervisor's injectable dependencies. */
+export interface SupervisorDeps {
+    /**
+     * Build the ChannelContext the adapter's `start` receives, wiring the
+     * engine-owned members (`receive`/`action`/`log`) and `status` to
+     * `report`. The supervisor wraps the result's `fail` (failures route
+     * here); every other member passes through verbatim.
+     */
+    makeContext(signal: AbortSignal, report: StatusSink): ChannelContext;
+    /** Clock ms. */
+    now(): number;
+    /** [0, 1) — the backoff jitter source. */
+    random(): number;
+    /** Schedule `fn` at `ms`; the return value cancels it. */
+    setTimer(fn: () => void, ms: number): () => void;
+    readonly log: EngineLog;
+}
+/**
+ * One channel adapter's supervisor: constructed per channel at engine
+ * `start`, `start()` awaited by the engine, `stop()` awaited at engine
+ * stop. Not restartable after `stop()` (the engine stops once per boot).
+ */
+export declare class Supervisor {
+    private readonly entry;
+    private readonly deps;
+    private state;
+    private stateSince;
+    private detail;
+    private lastError;
+    private readonly counts;
+    /** The delay head for the NEXT retry (doubling bookkeeping). */
+    private delayMs;
+    /** When the channel entered running (0 = not running now). */
+    private runningSince;
+    /**
+     * When the channel became unhealthy (the FIRST failure after a
+     * healthy stretch). Persists across retry cycles — a perpetually
+     * failing channel's health dwell must not reset per attempt — and
+     * clears only when a retry reaches running.
+     */
+    private unhealthySince;
+    private cancelTimer;
+    private stopped;
+    private signal;
+    /** The in-flight start attempt (stop awaits it before settling). */
+    private attempt;
+    constructor(entry: {
+        extension: string;
+        channel: ChannelContribution;
+    }, deps: SupervisorDeps);
+    /** The channel id (the status route's key). */
+    get id(): string;
+    /** The extension slug that contributed the channel (logging). */
+    get extension(): string;
+    /** The current status row (a copy — callers never mutate internals). */
+    status(): ChannelStatus;
+    /**
+     * Begin supervision: resolves once the first attempt settled (running
+     * or backoff). A `not_configured` adapter resolves immediately and is
+     * never started.
+     */
+    start(signal: AbortSignal): Promise<void>;
+    /** Stop supervision: cancel the retry, await the in-flight attempt and
+     *  the adapter's optional `stop`. Idempotent. */
+    stop(): Promise<void>;
+    /** Count one admitted outcome (the engine's receive path reports). */
+    countAdmitted(): void;
+    /** Count one dropped outcome. */
+    countDropped(): void;
+    /** Count one delivered message (the outbound path, Task 5). */
+    countDelivered(): void;
+    /** Count one failed ledger entry (Task 5's worker reports). */
+    countFailed(): void;
+    /**
+     * Unhealthy dwell at `now`: time since the channel first became
+     * unhealthy WHILE it sits in `backoff` (the engine's §8.12 health
+     * input). 0 when healthy — a config-error channel never reaches here
+     * (it is an engine-side static row, never a supervisor).
+     */
+    unhealthyMs(now: number): number;
+    /** Mark the channel running (the engine's own transitions, tests). */
+    markRunning(detail?: string): void;
+    /**
+     * One start attempt: connecting → `channel.start(ctx)` → running, or
+     * backoff through {@link onFailure}. Never throws.
+     */
+    private runAttempt;
+    /**
+     * Build the adapter's context: the engine's `makeContext` result with
+     * `fail` intercepted (a post-connect failure routes into supervision,
+     * never into the engine's log-only base).
+     */
+    private buildContext;
+    /** The adapter's own connecting/running report. */
+    private onReport;
+    /**
+     * A start rejection or `ctx.fail`: enter backoff and schedule exactly
+     * ONE retry. Duplicates (a second `ctx.fail` while a retry is already
+     * pending, or an in-flight start's rejection after its `ctx.fail`)
+     * are ignored — the pending retry owns the recovery.
+     */
+    private onFailure;
+    /** Schedule the retry at the doubling delay plus jitter. */
+    private scheduleRetry;
+    private setState;
+}

package/dist/supervisor.js

@@ -0,0 +1,273 @@
+/**
+ * The per-channel supervisor (spec §8.12): a backoff state machine over
+ * ONE channel adapter. `start` resolves once the first attempt settled
+ * (running or backoff — a failing adapter never wedges boot); retries
+ * ride the injected timer.
+ *
+ * Pinned values (the plan's Global Constraints): the backoff delay
+ * starts at 1000 ms and doubles per consecutive failure, capped at
+ * 300000 ms, plus jitter from the injected `random()` — jitter only
+ * ever ADDS time (the delay stays within [base, min(2·base, cap)]), so
+ * a retry never fires early against the pinned floor. 600000 ms of
+ * running RESETS the delay (a healthy stretch earns a fresh 1000 ms).
+ *
+ * State machine: a `not_configured` adapter is never started (terminal
+ * state, the contract's rule). A rejected `start` and a later `ctx.fail`
+ * both enter `backoff` and schedule ONE retry — the failure path is
+ * event-driven, not a polling loop, so a healthy channel owns zero
+ * timers. `stop()` cancels the pending retry, waits for an in-flight
+ * attempt to settle, and awaits the adapter's optional `stop`.
+ */
+/** Initial backoff delay (ms) — the spec's "1 s doubling". */
+const INITIAL_BACKOFF_MS = 1_000;
+/** Backoff cap (ms) — the spec's "5 min". */
+const MAX_BACKOFF_MS = 300_000;
+/** Running time (ms) after which the backoff delay resets — the spec's
+ *  "reset after 10 min running". */
+const RUNNING_RESET_MS = 600_000;
+/**
+ * One channel adapter's supervisor: constructed per channel at engine
+ * `start`, `start()` awaited by the engine, `stop()` awaited at engine
+ * stop. Not restartable after `stop()` (the engine stops once per boot).
+ */
+export class Supervisor {
+    entry;
+    deps;
+    state = "stopped";
+    stateSince;
+    detail;
+    lastError;
+    counts = {
+        admitted: 0,
+        dropped: 0,
+        delivered: 0,
+        failed: 0,
+    };
+    /** The delay head for the NEXT retry (doubling bookkeeping). */
+    delayMs = INITIAL_BACKOFF_MS;
+    /** When the channel entered running (0 = not running now). */
+    runningSince = 0;
+    /**
+     * When the channel became unhealthy (the FIRST failure after a
+     * healthy stretch). Persists across retry cycles — a perpetually
+     * failing channel's health dwell must not reset per attempt — and
+     * clears only when a retry reaches running.
+     */
+    unhealthySince;
+    cancelTimer;
+    stopped = false;
+    signal;
+    /** The in-flight start attempt (stop awaits it before settling). */
+    attempt;
+    constructor(entry, deps) {
+        this.entry = entry;
+        this.deps = deps;
+        this.stateSince = deps.now();
+    }
+    /** The channel id (the status route's key). */
+    get id() {
+        return this.entry.channel.id;
+    }
+    /** The extension slug that contributed the channel (logging). */
+    get extension() {
+        return this.entry.extension;
+    }
+    /** The current status row (a copy — callers never mutate internals). */
+    status() {
+        return {
+            state: this.state,
+            ...(this.detail === undefined ? {} : { detail: this.detail }),
+            since: this.stateSince,
+            ...(this.lastError === undefined ? {} : { lastError: this.lastError }),
+            counts: { ...this.counts },
+        };
+    }
+    /**
+     * Begin supervision: resolves once the first attempt settled (running
+     * or backoff). A `not_configured` adapter resolves immediately and is
+     * never started.
+     */
+    async start(signal) {
+        this.signal = signal;
+        const readiness = await this.entry.channel.configured();
+        if (readiness.status !== "ready") {
+            // not_configured (the readiness union's only other member): the
+            // adapter is never started (the contract's rule) and the detail
+            // rides the status row.
+            this.setState("not_configured", readiness.detail);
+            return;
+        }
+        await this.runAttempt();
+    }
+    /** Stop supervision: cancel the retry, await the in-flight attempt and
+     *  the adapter's optional `stop`. Idempotent. */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.cancelTimer?.();
+        this.cancelTimer = undefined;
+        const attempt = this.attempt;
+        if (attempt !== undefined)
+            await attempt.catch(() => { });
+        this.runningSince = 0;
+        if (this.entry.channel.stop !== undefined) {
+            try {
+                await this.entry.channel.stop();
+            }
+            catch (error) {
+                this.deps.log.error(`channel "${this.id}" stop failed`, error);
+            }
+        }
+        this.setState("stopped");
+    }
+    /** Count one admitted outcome (the engine's receive path reports). */
+    countAdmitted() {
+        this.counts.admitted++;
+    }
+    /** Count one dropped outcome. */
+    countDropped() {
+        this.counts.dropped++;
+    }
+    /** Count one delivered message (the outbound path, Task 5). */
+    countDelivered() {
+        this.counts.delivered++;
+    }
+    /** Count one failed ledger entry (Task 5's worker reports). */
+    countFailed() {
+        this.counts.failed++;
+    }
+    /**
+     * Unhealthy dwell at `now`: time since the channel first became
+     * unhealthy WHILE it sits in `backoff` (the engine's §8.12 health
+     * input). 0 when healthy — a config-error channel never reaches here
+     * (it is an engine-side static row, never a supervisor).
+     */
+    unhealthyMs(now) {
+        if (this.state !== "backoff")
+            return 0;
+        return now - (this.unhealthySince ?? this.stateSince);
+    }
+    /** Mark the channel running (the engine's own transitions, tests). */
+    markRunning(detail) {
+        if (this.runningSince === 0)
+            this.runningSince = this.deps.now();
+        this.unhealthySince = undefined;
+        this.setState("running", detail);
+    }
+    /**
+     * One start attempt: connecting → `channel.start(ctx)` → running, or
+     * backoff through {@link onFailure}. Never throws.
+     */
+    async runAttempt() {
+        const signal = this.signal;
+        if (signal === undefined || this.stopped)
+            return;
+        this.setState("connecting");
+        const ctx = this.buildContext(signal);
+        const settled = (async () => {
+            try {
+                await this.entry.channel.start(ctx);
+            }
+            catch (error) {
+                this.onFailure(error);
+                return;
+            }
+            if (this.stopped)
+                return;
+            // A `ctx.fail` that fired while a hanging start later resolved:
+            // the scheduled retry stands — never overwrite backoff with
+            // running out from under it.
+            if (this.state === "connecting")
+                this.markRunning();
+        })();
+        this.attempt = settled;
+        try {
+            await settled;
+        }
+        catch (error) {
+            // The inner function catches adapter failures; a throw past it
+            // is a supervision bug — logged, never propagated (the loop
+            // must keep serving the other channels).
+            this.deps.log.error(`channel "${this.id}" supervision error`, error);
+        }
+        finally {
+            this.attempt = undefined;
+        }
+    }
+    /**
+     * Build the adapter's context: the engine's `makeContext` result with
+     * `fail` intercepted (a post-connect failure routes into supervision,
+     * never into the engine's log-only base).
+     */
+    buildContext(signal) {
+        const report = (state) => this.onReport(state);
+        const base = this.deps.makeContext(signal, report);
+        return {
+            ...base,
+            fail: (error) => this.onFailure(error),
+        };
+    }
+    /** The adapter's own connecting/running report. */
+    onReport(state) {
+        if (this.stopped)
+            return;
+        if (state.state === "running")
+            this.markRunning(state.detail);
+        else
+            this.setState("connecting", state.detail);
+    }
+    /**
+     * A start rejection or `ctx.fail`: enter backoff and schedule exactly
+     * ONE retry. Duplicates (a second `ctx.fail` while a retry is already
+     * pending, or an in-flight start's rejection after its `ctx.fail`)
+     * are ignored — the pending retry owns the recovery.
+     */
+    onFailure(error) {
+        if (this.stopped)
+            return;
+        if (this.state === "backoff")
+            return;
+        const message = error instanceof Error ? error.message : String(error);
+        this.lastError = message;
+        this.deps.log.error(`channel "${this.id}" failed`, error);
+        // The running reset: a channel that held running for 600000 ms
+        // earns a fresh 1000 ms; anything shorter keeps the doubled delay.
+        if (this.runningSince !== 0) {
+            if (this.deps.now() - this.runningSince >= RUNNING_RESET_MS) {
+                this.delayMs = INITIAL_BACKOFF_MS;
+            }
+            this.runningSince = 0;
+        }
+        if (this.unhealthySince === undefined) {
+            this.unhealthySince = this.deps.now();
+        }
+        this.setState("backoff");
+        this.scheduleRetry();
+        // The doubling arms the NEXT failure (the retry this failure just
+        // scheduled rides the current, undoubled delay).
+        this.delayMs = Math.min(this.delayMs * 2, MAX_BACKOFF_MS);
+    }
+    /** Schedule the retry at the doubling delay plus jitter. */
+    scheduleRetry() {
+        const signal = this.signal;
+        if (signal === undefined)
+            return;
+        const base = Math.min(this.delayMs, MAX_BACKOFF_MS);
+        // Jitter ADDS up to the next doubling step: the delay stays in
+        // [base, min(2·base, cap)] — never below the pinned floor, never
+        // past the cap.
+        const ceiling = Math.min(2 * base, MAX_BACKOFF_MS);
+        const delay = base + this.deps.random() * (ceiling - base);
+        this.cancelTimer?.();
+        this.cancelTimer = this.deps.setTimer(() => {
+            this.cancelTimer = undefined;
+            void this.runAttempt();
+        }, delay);
+    }
+    setState(state, detail) {
+        this.state = state;
+        this.stateSince = this.deps.now();
+        this.detail = detail;
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The chat-facing agent tools (spec §8.9). Policy failures are ordinary
+ * error results, never exceptions. Sends persist to the delivery ledger
+ * before waiting for a receipt, so a timeout leaves honest queued work.
+ */
+import { type ToolRegistration } from "@earendil-works/pi-durable";
+import type { ChannelContribution, SigrunHost } from "@sigrun/sigrun/extension";
+import type { BindingStore } from "./state/bindings.js";
+import type { IdentityStore } from "./state/identities.js";
+import type { Ledger } from "./state/ledger.js";
+import type { GatewayConfig } from "./config.js";
+import type { EngineLog } from "./log.js";
+export declare const RECEIPT_WAIT_MS = 30000;
+export interface ToolDeps {
+    readonly host: SigrunHost;
+    readonly bindings: BindingStore;
+    readonly identities: IdentityStore;
+    readonly ledger: Ledger;
+    channelOf(channel: string): ChannelContribution | undefined;
+    readConfig(): Promise<GatewayConfig>;
+    readonly log: EngineLog;
+    /** Poke the channel's worker after enqueueing. */
+    readonly kick?: () => void;
+    readonly receiptWaitMs?: number;
+}
+/** Build both tools over the engine's shared state. */
+export declare function createGatewayTools(deps: ToolDeps): readonly ToolRegistration[];

package/dist/tools.js

@@ -0,0 +1,207 @@
+/**
+ * The chat-facing agent tools (spec §8.9). Policy failures are ordinary
+ * error results, never exceptions. Sends persist to the delivery ledger
+ * before waiting for a receipt, so a timeout leaves honest queued work.
+ */
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, } from "@earendil-works/pi-durable";
+import { resolveTargets } from "./jobs.js";
+export const RECEIPT_WAIT_MS = 30_000;
+const RECEIPT_POLL_MS = 25;
+/** Build both tools over the engine's shared state. */
+export function createGatewayTools(deps) {
+    const sendMessage = defineTool({
+        name: "send_message",
+        description: "Send a message to one of the acting user's linked chats. `to` is a channel or channel:chatId; files are workspace paths.",
+        parameters: Type.Object({
+            to: Type.String({ description: "Target channel or channel:chatId" }),
+            text: Type.String({ description: "Message text" }),
+            files: Type.Optional(Type.Array(Type.String(), {
+                description: "Workspace paths of files to attach",
+            })),
+        }),
+        async execute(args, api, context) {
+            try {
+                const owner = await deps.host.identity.actingUser(api.conversationId);
+                if (owner === undefined)
+                    return toolError("The acting user could not be resolved.");
+                if (deps.identities.homesOf(owner).length === 0) {
+                    return toolError(`The acting user ${owner} has no linked chats.`);
+                }
+                const targets = await resolveTargets(deps, owner, [args.to]);
+                const target = targets.resolved[0];
+                if (target === undefined) {
+                    return toolError(targets.rejected[0]?.reason ?? "The target chat is not available.");
+                }
+                const channel = deps.channelOf(target.channel);
+                if (channel === undefined) {
+                    return toolError(`Channel "${target.channel}" is not running.`);
+                }
+                const config = await deps.readConfig();
+                const files = [];
+                for (const path of args.files ?? []) {
+                    const read = await deps.host.conversations.readFile(api.conversationId, path);
+                    if (read.bytes.byteLength > config.media.maxBytes) {
+                        return toolError(`File "${path}" is too large (limit ${config.media.maxBytes} bytes).`);
+                    }
+                    const kind = mediaKind(read.mime, path);
+                    const supported = channel.capabilities.media ?? [];
+                    if (!supported.includes(kind) && !supported.includes("document")) {
+                        return toolError(`Channel "${channel.label}" does not support ${kind} files or document fallback.`);
+                    }
+                    files.push({
+                        conversationId: api.conversationId,
+                        path,
+                        name: fileName(path),
+                        ...(read.mime === undefined ? {} : { mime: read.mime }),
+                        bytes: read.bytes,
+                    });
+                }
+                const entry = await deps.ledger.enqueue({
+                    channel: target.channel,
+                    chat: target.chat,
+                    kind: "notice",
+                    tag: `tool:${api.callId}`,
+                    message: {
+                        chat: target.chat,
+                        text: args.text,
+                        ...(files.length === 0
+                            ? {}
+                            : {
+                                files: files.map((file) => ({
+                                    name: file.name,
+                                    ...(file.mime === undefined ? {} : { mime: file.mime }),
+                                    bytes: file.bytes,
+                                })),
+                            }),
+                    },
+                    ...(files.length === 0 ? {} : { files }),
+                });
+                if (entry === undefined)
+                    return toolError("The message could not be queued.");
+                deps.kick?.();
+                const receipt = await waitForReceipt(deps.ledger, entry, deps.receiptWaitMs ?? RECEIPT_WAIT_MS, context.abortSignal ?? new AbortController().signal);
+                if (receipt === "failed") {
+                    return toolError("Delivery failed; the message was not sent.");
+                }
+                if (receipt === undefined) {
+                    return toolSuccess({ delivered: false, queued: true });
+                }
+                return toolSuccess({ delivered: true, messageIds: receipt });
+            }
+            catch (error) {
+                // Transport and host errors are also model-recoverable tool
+                // outcomes; logging retains the diagnostic policy errors lack.
+                deps.log.error("send_message failed", error);
+                return toolError(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+    const listChats = defineTool({
+        name: "list_chats",
+        description: "List chats the acting user may target with send_message.",
+        parameters: Type.Object({}),
+        async execute(_args, api) {
+            try {
+                const owner = await deps.host.identity.actingUser(api.conversationId);
+                if (owner === undefined)
+                    return toolError("The acting user could not be resolved.");
+                const chats = [];
+                const seen = new Set();
+                for (const home of deps.identities.homesOf(owner)) {
+                    const channel = deps.channelOf(home.channel);
+                    if (channel === undefined)
+                        continue;
+                    seen.add(`${home.channel}:${home.chat.chatId}`);
+                    chats.push({
+                        to: home.channel,
+                        label: `${channel.label} direct message ${home.chat.chatId}`,
+                    });
+                }
+                for (const [key, binding] of Object.entries(deps.bindings.entries())) {
+                    if (binding.dead === true)
+                        continue;
+                    const channelId = key.split(":", 1)[0];
+                    if (channelId === undefined)
+                        continue;
+                    const channel = deps.channelOf(channelId);
+                    if (channel === undefined)
+                        continue;
+                    const access = await deps.host.access.accessOf({ user: owner }, await deps.host.conversations.meta(binding.conversationId));
+                    if (access !== "write")
+                        continue;
+                    const target = `${channelId}:${binding.chat.chatId}`;
+                    if (seen.has(target))
+                        continue;
+                    seen.add(target);
+                    chats.push({
+                        to: target,
+                        label: `${channel.label} ${binding.chat.chatType === "dm" ? "direct message" : "group"} ${binding.chat.chatId}`,
+                    });
+                }
+                if (chats.length === 0) {
+                    return toolError(`The acting user ${owner} has no linked chats.`);
+                }
+                return toolSuccess({ chats });
+            }
+            catch (error) {
+                deps.log.error("list_chats failed", error);
+                return toolError(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+    return [sendMessage, listChats];
+}
+function toolError(message) {
+    return { output: [{ type: "text", text: message }], isError: true };
+}
+function toolSuccess(value) {
+    return { output: [{ type: "text", text: JSON.stringify(value) }] };
+}
+/** Poll the durable row so a same-process worker receipt resolves quickly. */
+async function waitForReceipt(ledger, entry, waitMs, signal) {
+    const deadline = Date.now() + waitMs;
+    while (!signal.aborted) {
+        const current = ledger.list().find((candidate) => candidate.id === entry.id);
+        if (current?.state === "delivered")
+            return current.receipt ?? [];
+        if (current?.state === "failed")
+            return "failed";
+        if (Date.now() >= deadline)
+            return undefined;
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                signal.removeEventListener("abort", abort);
+                resolve();
+            }, Math.min(RECEIPT_POLL_MS, Math.max(0, deadline - Date.now())));
+            const abort = () => {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", abort);
+                resolve();
+            };
+            signal.addEventListener("abort", abort, { once: true });
+        });
+    }
+    return undefined;
+}
+function fileName(path) {
+    return path.split(/[\\/]/).pop() ?? "attachment";
+}
+function mediaKind(mime, path) {
+    if (mime?.startsWith("image/") === true)
+        return "image";
+    if (mime?.startsWith("audio/") === true)
+        return "audio";
+    if (mime?.startsWith("video/") === true)
+        return "video";
+    if (mime !== undefined)
+        return "document";
+    const extension = path.split(".").pop()?.toLowerCase();
+    if (extension !== undefined && ["png", "jpg", "jpeg", "gif", "webp", "bmp"].includes(extension))
+        return "image";
+    if (extension !== undefined && ["ogg", "mp3", "wav", "m4a"].includes(extension))
+        return "audio";
+    if (extension !== undefined && ["mp4", "webm", "mov"].includes(extension))
+        return "video";
+    return "document";
+}