Keep every hook call's response, searchable by the user and the bot

A hook call used to record only how it was taken; its run's answer went
to the chat alone and was lost to the call once the job was pruned. Now
`bot_hook_events` keeps `response`, `response_message_id` and
`responded_at`, written on every call a run took in when that run ends
(completed, failed, lost, stopped or cancelled) by
`recordHookCallResponse` in the job helpers, and calls turn done or
failed. The Calls view searches what calls sent and what runs answered,
filters by status and pages; Show all loads one call whole. Bots get
`search_hook_calls` and `read_hook_call` for their own hooks (never in a
hook call's own run), with payloads always marked as outside data.
Calls are kept for the app setting `hook_events_keep_days` (Settings >
General, default now 30 days). The caller still only gets 202 Queued.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

src/pages/admin/settings/(functions)/grab-settings-server-props.ts

@@ -7,6 +7,7 @@ import type { PagePropsType } from "@/src/types";
 import type { BunextPageServerFn } from "@moduletrace/bunext/types";
 import grabRunLimitsOverview from "@/src/functions/backend/db/app-settings/grab-run-limits";
 import grabSkillLimitsOverview from "@/src/functions/backend/db/app-settings/grab-skill-limits";
+import grabHookCallRetentionOverview from "@/src/functions/backend/db/app-settings/grab-hook-events-keep-days";
 import grabStorageQuotaOverview from "@/src/functions/backend/db/app-settings/grab-storage-quota-overview";
 import { grabSystemPromptAppendOverview } from "@/src/functions/backend/db/app-settings/grab-system-prompt-append";
 import runningVersion from "@/src/utils/running-version";
@@ -49,6 +50,7 @@ export default async function grabSettingsServerProps({ req }: Params) {
             system_prompt_append: await grabSystemPromptAppendOverview().catch(() => null),
             run_limits: await grabRunLimitsOverview().catch(() => null),
             skill_limits: await grabSkillLimitsOverview().catch(() => null),
+            hook_call_retention: await grabHookCallRetentionOverview().catch(() => null),
             running_version: runningVersion({ env: process.env }),
         },
     };

src/pages/admin/settings/general/(partials)/hook-call-retention-form.tsx

@@ -0,0 +1,110 @@
+import { useState } from "react";
+import fetchApi from "@moduletrace/twui/utils/fetch/fetchApi";
+import type { APIResponseObject } from "@moduletrace/bunext/types";
+import Form from "@moduletrace/twui/form/Form";
+import Input from "@moduletrace/twui/form/Input";
+import { AppData } from "@/src/data/app-data";
+import type { HookCallRetentionOverview } from "@/src/types";
+import SettingsSaveBar from "../../(partials)/settings-save-bar";
+
+type Props = {
+    retention?: HookCallRetentionOverview | null;
+};
+
+/**
+ * How many days hook calls are kept, saved on its own without a reload.
+ * Zero puts the code's default back.
+ */
+export default function HookCallRetentionForm({ retention }: Props) {
+    const [overview, setOverview] = useState(retention || undefined);
+    const [dirty, setDirty] = useState(false);
+    const [keep_days, setKeepDays] = useState(String(retention?.keep_days ?? ""));
+    /**
+     * The input only reads `defaultValue` when it mounts, so discarding or
+     * saving remounts it with the saved number.
+     */
+    const [form_key, setFormKey] = useState(0);
+    const [loading, setLoading] = useState(false);
+    const [status, setStatus] = useState<{
+        msg?: string;
+        error?: boolean;
+        success?: boolean;
+    }>();
+
+    const save = async () => {
+        if (!window.confirm("Save how long hook calls are kept? Calls older than that are deleted at the next daily prune.")) return;
+
+        setLoading(true);
+        setStatus(undefined);
+
+        const res = await fetchApi<{}, APIResponseObject<HookCallRetentionOverview>>(
+            "/api/admin/settings/hook-call-retention",
+            {
+                method: "POST",
+                body: { keep_days: Number(keep_days) || 0 },
+            },
+        ).catch(() => null);
+
+        setLoading(false);
+
+        if (!res?.success || !res.singleRes) {
+            setStatus({
+                error: true,
+                msg: res?.msg || `Couldn't save it.`,
+            });
+            return;
+        }
+
+        setOverview(res.singleRes);
+        setKeepDays(String(res.singleRes.keep_days));
+        setFormKey((key) => key + 1);
+        setDirty(false);
+        setStatus({
+            success: true,
+            msg: `Saved: hook calls are kept for ${res.singleRes.keep_days} days.`,
+        });
+    };
+
+    const discard = () => {
+        setKeepDays(String(overview?.keep_days ?? ""));
+        setFormKey((key) => key + 1);
+        setDirty(false);
+        setStatus(undefined);
+    };
+
+    return (
+        <Form
+            onSubmit={(event) => {
+                event.preventDefault();
+                save().catch(() => {});
+            }}
+            className="w-full gap-3! items-stretch"
+        >
+            <Input
+                key={`keep-${form_key}`}
+                label="Keep hook calls for"
+                type="number"
+                min={0}
+                max={overview?.max}
+                step={1}
+                numberText
+                rawNumber
+                defaultValue={keep_days}
+                onChange={(event) => {
+                    setKeepDays(event.target.value);
+                    setDirty(true);
+                    setStatus(undefined);
+                }}
+                suffix={`days`}
+                info={`Each call keeps its payload (up to ${AppData.BotHookMaxPayloadBytes / 1024} KB) and its run's response, so a long time on a busy hook grows the database. 0 uses the default (${overview?.default_days ?? ""}).`}
+            />
+            <SettingsSaveBar
+                dirty={dirty}
+                loading={loading}
+                status={status}
+                save_label="Save"
+                onDiscard={discard}
+            />
+        </Form>
+    );
+}

src/pages/admin/settings/general/(sections)/hook-call-retention-section.tsx

@@ -0,0 +1,25 @@
+import { useContext } from "react";
+import { AppContext } from "@/src/pages/__root";
+import isPassThroughUser from "@/src/utils/rbac/is-pass-through-user";
+import SettingsGroup from "../../(partials)/settings-group";
+import HookCallRetentionForm from "../(partials)/hook-call-retention-form";
+
+/**
+ * How long hook calls and their responses are kept. Only the super admin
+ * sees it, since it changes every user's hooks.
+ */
+export default function HookCallRetentionSection() {
+    const { pageProps } = useContext(AppContext);
+
+    if (!isPassThroughUser({ user_types: pageProps?.user_types })) return null;
+
+    return (
+        <SettingsGroup
+            title="Hook calls"
+            description="How long every call to a hook is kept, with what it sent and what its run answered, so you and the bots can search them. Older calls are deleted once a day; the chat messages their runs posted stay."
+            id="hook-calls"
+        >
+            <HookCallRetentionForm retention={pageProps?.hook_call_retention} />
+        </SettingsGroup>
+    );
+}

src/pages/admin/settings/general/index.tsx

@@ -1,4 +1,5 @@
 import AppearanceSection from "./(sections)/appearance-section";
+import HookCallRetentionSection from "./(sections)/hook-call-retention-section";
 import InstallIconSection from "./(sections)/install-icon-section";
 import InstallNameSection from "./(sections)/install-name-section";
 import NotificationsSection from "./(sections)/notifications-section";
@@ -23,6 +24,7 @@ export default function AdminSettingsGeneralPage() {
             <PromptSection />
             <RunLimitsSection />
             <SkillLimitsSection />
+            <HookCallRetentionSection />
             <StorageSection />
             <VersionSection />
         </SettingsShell>