@frockbot/plugin-audit 0.0.0 → 0.1.1

package/src/client/AuditSection.vue

@@ -0,0 +1,363 @@
+<script setup lang="ts">
+// The Bot's audit log: every audited effect it has performed, newest first.
+//
+// It renders durable state and decides nothing. In particular it never infers
+// an outcome: an effect the durable event log cannot explain is shown as
+// "Unknown" in the same place a success or a failure would be, because that is
+// what the log says and hiding it would be the silent classification the
+// reconciliation rule forbids. The same goes for truncation — a table trimmed
+// to its retention bound says so above the rows rather than quietly answering
+// with fewer.
+import { UiAnchor, UiButton, UiIcon } from "@frockbot/client-ui";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { settingsLinkV1 } from "@frockbot/plugin-shell/settings-links";
+import { computed, inject, watch } from "vue";
+import {
+  AUDIT_KINDS_V1,
+  type AuditEntryV1,
+  type AuditKindV1,
+} from "../shared.js";
+import { auditStateKey } from "./state.js";
+
+const providedWeb = inject(frockBotWebDataKey);
+const providedState = inject(auditStateKey);
+if (!providedWeb || !providedState) {
+  throw new Error("Audit client services were not provided");
+}
+const web = providedWeb;
+const audit = providedState;
+
+const botId = computed(() => web.value.activeBotId);
+const anchorHref = computed(() =>
+  settingsLinkV1({ anchor: "bot-audit", botId: botId.value }),
+);
+const kinds = AUDIT_KINDS_V1;
+
+watch(
+  botId,
+  (id) => {
+    if (!id) return;
+    if (audit.value.botId !== id || !audit.value.loaded) {
+      void audit.value.load(id);
+    }
+  },
+  { immediate: true },
+);
+
+function selectKind(kind: AuditKindV1 | undefined): void {
+  const id = botId.value;
+  if (!id) return;
+  void audit.value.load(id, {
+    ...audit.value.filters,
+    ...(kind === undefined ? { kind: undefined } : { kind }),
+  });
+}
+
+/** Where the effect ran, in words rather than in the wire shape. */
+function target(entry: AuditEntryV1): string {
+  if (entry.target === "computer") return "This Computer";
+  if (entry.target.startsWith("machine:")) {
+    return `Machine ${entry.target.slice("machine:".length)}`;
+  }
+  return entry.target.slice("remote:".length);
+}
+
+function when(entry: AuditEntryV1): string {
+  const parsed = Date.parse(entry.at);
+  return Number.isFinite(parsed) ? new Date(parsed).toLocaleString() : entry.at;
+}
+</script>
+
+<template>
+  <UiAnchor
+    as="section"
+    anchor="bot-audit"
+    label="Audit log"
+    :href="anchorHref"
+    class="audit"
+  >
+    <header class="audit__header">
+      <span class="audit__icon" aria-hidden="true"
+        ><UiIcon name="history"
+      /></span>
+      <span class="audit__intro">
+        <strong>Audit log</strong>
+        <small>
+          Every shell command, browser action, remote tool call and Workspace
+          write this Bot has made. Arguments are never kept — only a digest and
+          a redacted preview.
+        </small>
+      </span>
+      <UiButton
+        type="button"
+        :disabled="!botId || audit.busy"
+        @click="botId && audit.rebuild(botId)"
+      >
+        Rebuild
+      </UiButton>
+    </header>
+
+    <p v-if="audit.error" class="audit__error" role="alert">
+      {{ audit.error }}
+    </p>
+
+    <p
+      v-if="audit.indexState === 'truncated'"
+      class="audit__banner"
+      role="status"
+    >
+      Older activity has been trimmed to this account's retention bound — 20 000
+      entries, or 180 days. Rebuilding restores everything the Bots' own turns
+      still hold.
+    </p>
+    <p
+      v-else-if="audit.indexState === 'rebuilding'"
+      class="audit__banner"
+      role="status"
+    >
+      A rebuild is in progress. What is shown may be incomplete until it
+      finishes.
+    </p>
+
+    <div v-if="audit.receipt" class="audit-receipt">
+      <strong>
+        Rebuilt {{ audit.receipt.entries }} entries across
+        {{ audit.receipt.bots }} Bots
+      </strong>
+      <small>
+        {{ audit.receipt.unknownOutcomes }} with an outcome the turn log cannot
+        explain, and {{ audit.receipt.hostJournalDiscrepancies }} effect(s) the
+        Computer host reported that no turn accounts for. A discrepancy is
+        counted here, never written in as if a turn had recorded it.
+      </small>
+      <div class="audit-receipt__actions">
+        <UiButton type="button" @click="audit.dismissReceipt()">
+          Done
+        </UiButton>
+      </div>
+    </div>
+
+    <div class="audit__chips" role="group" aria-label="Filter by kind">
+      <button
+        type="button"
+        class="audit-chip"
+        :data-active="audit.filters.kind === undefined ? 'yes' : 'no'"
+        @click="selectKind(undefined)"
+      >
+        All
+      </button>
+      <button
+        v-for="kind in kinds"
+        :key="kind"
+        type="button"
+        class="audit-chip"
+        :data-active="audit.filters.kind === kind ? 'yes' : 'no'"
+        @click="selectKind(kind)"
+      >
+        {{ kind }}
+      </button>
+    </div>
+
+    <p v-if="audit.loaded && audit.entries.length === 0" class="audit__empty">
+      No audited activity yet. A turn that only talks records nothing here.
+    </p>
+
+    <ol v-else class="audit__rows">
+      <li
+        v-for="entry in audit.entries"
+        :key="`${entry.runId}:${entry.occurrenceId}`"
+        class="audit-row"
+      >
+        <span class="audit-row__time">{{ when(entry) }}</span>
+        <span class="audit-row__kind" :data-kind="entry.kind">{{
+          entry.kind
+        }}</span>
+        <span class="audit-row__target">{{ target(entry) }}</span>
+        <span class="audit-row__preview" :title="entry.toolName">{{
+          entry.preview
+        }}</span>
+        <span class="audit-row__outcome" :data-outcome="entry.outcome">{{
+          entry.outcome
+        }}</span>
+      </li>
+    </ol>
+
+    <div v-if="audit.nextCursor" class="audit__more">
+      <UiButton
+        type="button"
+        :disabled="audit.busy"
+        @click="botId && audit.loadMore(botId)"
+      >
+        Load more
+      </UiButton>
+      <small>{{ audit.entries.length }} of {{ audit.total }}</small>
+    </div>
+  </UiAnchor>
+</template>
+
+<style scoped>
+.audit {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.audit__header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.audit__icon {
+  display: grid;
+  width: var(--frock-avatar-sm);
+  height: var(--frock-avatar-sm);
+  flex: 0 0 auto;
+  place-items: center;
+  border-radius: 8px;
+  color: var(--frock-action-primary);
+  background: var(--frock-surface);
+  box-shadow: inset 0 0 0 1px var(--frock-border);
+}
+
+.audit__intro {
+  display: flex;
+  min-width: 0;
+  flex: 1 1 auto;
+  flex-direction: column;
+}
+
+.audit__intro strong {
+  color: var(--frock-text);
+  font-size: var(--frock-text-md);
+  font-weight: 600;
+}
+
+.audit__intro small,
+.audit__empty,
+.audit__banner {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-sm);
+}
+
+.audit__error {
+  color: var(--frock-danger-text);
+  font-size: var(--frock-text-sm);
+}
+
+.audit__banner {
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-card);
+  padding: 8px 10px;
+  background: var(--frock-surface-subtle);
+}
+
+.audit-receipt {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-card);
+  padding: 12px;
+  background: var(--frock-surface-subtle);
+}
+
+.audit-receipt strong {
+  color: var(--frock-text);
+  font-size: var(--frock-text-sm);
+}
+
+.audit-receipt small {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-sm);
+}
+
+.audit-receipt__actions {
+  display: flex;
+  gap: 8px;
+}
+
+.audit__chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.audit-chip {
+  border: 1px solid var(--frock-border);
+  border-radius: 999px;
+  padding: 3px 10px;
+  color: var(--frock-text-muted);
+  background: var(--frock-surface);
+  cursor: pointer;
+  font-size: var(--frock-text-sm);
+}
+
+.audit-chip[data-active="yes"] {
+  color: var(--frock-action-primary);
+  border-color: var(--frock-action-primary);
+}
+
+.audit__rows {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.audit-row {
+  display: grid;
+  align-items: baseline;
+  gap: 8px;
+  grid-template-columns: auto auto auto 1fr auto;
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-card);
+  padding: 6px 10px;
+  background: var(--frock-surface-subtle);
+  font-size: var(--frock-text-sm);
+}
+
+.audit-row__time,
+.audit-row__target {
+  color: var(--frock-text-muted);
+  white-space: nowrap;
+}
+
+.audit-row__kind {
+  border: 1px solid var(--frock-border);
+  border-radius: 999px;
+  padding: 1px 8px;
+  color: var(--frock-text);
+}
+
+.audit-row__preview {
+  overflow: hidden;
+  color: var(--frock-text);
+  font-family: var(--frock-font-mono);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.audit-row__outcome {
+  color: var(--frock-text-muted);
+  white-space: nowrap;
+}
+
+.audit-row__outcome[data-outcome="error"],
+.audit-row__outcome[data-outcome="refused"] {
+  color: var(--frock-danger-text);
+}
+
+.audit__more {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.audit__more small {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-sm);
+}
+</style>

package/src/client/index.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  ClientPluginContext,
+  ClientSlotRegistration,
+} from "@frockbot/client-core";
+import { auditClientPlugin } from "./index.js";
+import { auditStateKey, type AuditClientState } from "./state.js";
+
+const ENTRY = {
+  schemaVersion: 1,
+  botId: "scout",
+  runId: "run-1",
+  occurrenceId: "tool:1:1:0",
+  turn: 1,
+  step: 1,
+  ordinal: 0,
+  effectId: "tool:1:1:0",
+  at: "2026-08-31T00:00:00.000Z",
+  kind: "shell",
+  target: "computer",
+  toolName: "computer_exec",
+  argumentDigest: "a".repeat(64),
+  preview: "ls -la",
+  outcome: "ok",
+};
+
+function mount(
+  overrides: {
+    hostedRequest?: ClientPluginContext["transport"]["hostedRequest"];
+  } = {},
+): {
+  state: { value: AuditClientState };
+  slots: ClientSlotRegistration[];
+  calls: Array<[string, string | undefined, string | undefined]>;
+  dispose(): void;
+} {
+  const slots: ClientSlotRegistration[] = [];
+  const calls: Array<[string, string | undefined, string | undefined]> = [];
+  let state: unknown;
+  const context: ClientPluginContext = {
+    transport: {
+      turn: () => Promise.resolve({ runId: "run", text: "", events: [] }),
+      hostedRequest:
+        overrides.hostedRequest ??
+        ((path, method, body) => {
+          calls.push([path, method, body]);
+          if (method === "POST") {
+            return Promise.resolve({
+              schemaVersion: 1,
+              status: "rebuilt",
+              entries: 1,
+              bots: 1,
+              indexState: "ready",
+              unknownOutcomes: 0,
+              hostJournalDiscrepancies: 2,
+            });
+          }
+          return Promise.resolve({
+            schemaVersion: 1,
+            entries: [ENTRY],
+            page: path.includes("before=")
+              ? { truncated: false }
+              : { truncated: true, nextCursor: "p1" },
+            total: 2,
+            indexState: "ready",
+          });
+        }),
+    },
+    inject: () => {
+      throw new Error("unexpected client provider");
+    },
+    provide: (key, value) => {
+      if (key === auditStateKey) state = value;
+      return () => {};
+    },
+    slot: (registration) => {
+      slots.push(registration);
+      return () => slots.splice(slots.indexOf(registration), 1);
+    },
+  };
+  const disposers = auditClientPlugin(context);
+  if (!Array.isArray(disposers)) throw new Error("expected registrations");
+  return {
+    state: state as { value: AuditClientState },
+    slots,
+    calls,
+    dispose: () => {
+      for (const dispose of disposers.toReversed()) dispose();
+    },
+  };
+}
+
+describe("Audit client contribution", () => {
+  test("mounts into the Bot settings outlet", () => {
+    const mounted = mount();
+    expect(mounted.slots.map((slot) => slot.slot)).toEqual([
+      "frockbot.bot-settings-sections",
+    ]);
+    mounted.dispose();
+  });
+
+  test("loads a Bot's activity and decodes it at the seam", async () => {
+    const mounted = mount();
+    await mounted.state.value.load("scout");
+    expect(mounted.state.value.entries).toHaveLength(1);
+    expect(mounted.state.value.total).toBe(2);
+    expect(mounted.state.value.botId).toBe("scout");
+    expect(mounted.calls[0]).toEqual([
+      "/api/audit?botId=scout",
+      undefined,
+      undefined,
+    ]);
+    mounted.dispose();
+  });
+
+  test("carries a filter chip into the query string", async () => {
+    const mounted = mount();
+    await mounted.state.value.load("scout", { kind: "mcp" });
+    expect(mounted.calls[0]?.[0]).toBe("/api/audit?botId=scout&kind=mcp");
+    mounted.dispose();
+  });
+
+  test("pages with the cursor the previous answer gave it", async () => {
+    const mounted = mount();
+    await mounted.state.value.load("scout");
+    await mounted.state.value.loadMore("scout");
+    expect(mounted.calls[1]?.[0]).toBe("/api/audit?botId=scout&before=p1");
+    expect(mounted.state.value.entries).toHaveLength(2);
+    expect(mounted.state.value.nextCursor).toBeUndefined();
+    // Nothing further to ask for: a second call is a no-op, not a repeat.
+    await mounted.state.value.loadMore("scout");
+    expect(mounted.calls).toHaveLength(2);
+    mounted.dispose();
+  });
+
+  test("holds the rebuild receipt, discrepancy count and all", async () => {
+    const mounted = mount();
+    await mounted.state.value.rebuild("scout");
+    expect(mounted.calls[0]).toEqual(["/api/audit/rebuild", "POST", "{}"]);
+    expect(mounted.state.value.receipt).toMatchObject({
+      status: "rebuilt",
+      hostJournalDiscrepancies: 2,
+    });
+    // And it reloads, so the rows on screen are the rebuilt ones.
+    expect(mounted.calls[1]?.[0]).toBe("/api/audit?botId=scout");
+    mounted.state.value.dismissReceipt();
+    expect(mounted.state.value.receipt).toBeUndefined();
+    mounted.dispose();
+  });
+
+  test("names a failure rather than showing an empty panel", async () => {
+    const mounted = mount({
+      hostedRequest: () => Promise.reject(new Error("the gateway is away")),
+    });
+    await mounted.state.value.load("scout");
+    expect(mounted.state.value.error).toBe("the gateway is away");
+    expect(mounted.state.value.loaded).toBe(false);
+    mounted.dispose();
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,125 @@
+/// <reference path="../env.d.ts" />
+
+// The Audit Package's hosted client Contribution.
+//
+// "The hosted client renders backend state and submits commands. It does not
+// become an alternate authority." Every read here is decoded at the seam
+// before a component sees it, and the one write is a rebuild — which changes
+// no durable fact, only the projection of facts the Bots already hold.
+import type { ClientPlugin } from "@frockbot/client-core";
+import { ref } from "vue";
+import {
+  decodeAuditRebuildReceiptV1,
+  decodeClientAuditPageV1,
+} from "../shared.js";
+import AuditSection from "./AuditSection.vue";
+import { auditStateKey, type AuditClientState } from "./state.js";
+
+function message(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+function queryString(
+  botId: string,
+  state: AuditClientState,
+  cursor?: string,
+): string {
+  const params = new URLSearchParams({ botId });
+  if (state.filters.kind) params.set("kind", state.filters.kind);
+  if (state.filters.target) params.set("target", state.filters.target);
+  if (cursor) params.set("before", cursor);
+  return params.toString();
+}
+
+export const auditClientPlugin: ClientPlugin = (ctx) => {
+  const request = (
+    path: string,
+    method?: "GET" | "POST",
+    body?: string,
+  ): Promise<unknown> => {
+    if (!ctx.transport.hostedRequest) {
+      throw new Error("Audit log is unavailable on this client");
+    }
+    return ctx.transport.hostedRequest(path, method, body);
+  };
+  const state = ref<AuditClientState>({
+    entries: [],
+    total: 0,
+    indexState: "ready",
+    filters: {},
+    loaded: false,
+    busy: false,
+    async load(botId, filters) {
+      state.value.busy = true;
+      if (filters) state.value.filters = filters;
+      try {
+        const page = decodeClientAuditPageV1(
+          await request(`/api/audit?${queryString(botId, state.value)}`),
+        );
+        state.value.botId = botId;
+        state.value.entries = page.entries;
+        state.value.total = page.total;
+        state.value.nextCursor = page.page.nextCursor;
+        state.value.indexState = page.indexState;
+        state.value.loaded = true;
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error = message(error, "Could not load audit log");
+      } finally {
+        state.value.busy = false;
+      }
+    },
+    async loadMore(botId) {
+      const cursor = state.value.nextCursor;
+      if (!cursor) return;
+      state.value.busy = true;
+      try {
+        const page = decodeClientAuditPageV1(
+          await request(
+            `/api/audit?${queryString(botId, state.value, cursor)}`,
+          ),
+        );
+        state.value.entries = [...state.value.entries, ...page.entries];
+        state.value.nextCursor = page.page.nextCursor;
+        state.value.indexState = page.indexState;
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error = message(error, "Could not load more audit entries");
+      } finally {
+        state.value.busy = false;
+      }
+    },
+    async rebuild(botId) {
+      state.value.busy = true;
+      try {
+        // The receipt is the point of the button, not a side effect of it: it
+        // says how many entries the Bots' own runs actually account for, how
+        // many outcomes the durable log cannot explain, and how many effects
+        // the Computer host claims that no session event does.
+        state.value.receipt = decodeAuditRebuildReceiptV1(
+          await request("/api/audit/rebuild", "POST", JSON.stringify({})),
+        );
+        state.value.error = undefined;
+      } catch (error) {
+        state.value.error = message(error, "Could not rebuild audit log");
+      } finally {
+        state.value.busy = false;
+      }
+      await state.value.load(botId);
+    },
+    dismissReceipt() {
+      state.value.receipt = undefined;
+    },
+  });
+
+  return [
+    ctx.provide(auditStateKey, state),
+    ctx.slot({
+      slot: "frockbot.bot-settings-sections",
+      order: 20,
+      component: AuditSection,
+    }),
+  ];
+};
+
+export default auditClientPlugin;

package/src/client/state.ts

@@ -0,0 +1,35 @@
+import type { InjectionKey, Ref } from "vue";
+import type {
+  AuditEntryV1,
+  AuditIndexStateV1,
+  AuditKindV1,
+  AuditRebuildReceiptV1,
+} from "../shared.js";
+
+/** The filters the Audit log can apply, as the chips set them. */
+export interface AuditFiltersV1 {
+  kind?: AuditKindV1;
+  target?: string;
+}
+
+export interface AuditClientState {
+  /** The Bot the loaded rows belong to; nothing is shown for another. */
+  botId?: string;
+  entries: AuditEntryV1[];
+  total: number;
+  nextCursor?: string;
+  indexState: AuditIndexStateV1;
+  filters: AuditFiltersV1;
+  loaded: boolean;
+  busy: boolean;
+  error?: string;
+  /** The receipt of the most recent rebuild, held until the next load. */
+  receipt?: AuditRebuildReceiptV1;
+  load(botId: string, filters?: AuditFiltersV1): Promise<void>;
+  loadMore(botId: string): Promise<void>;
+  rebuild(botId: string): Promise<void>;
+  dismissReceipt(): void;
+}
+
+export const auditStateKey: InjectionKey<Ref<AuditClientState>> =
+  Symbol("audit-state");

package/src/env.d.ts

@@ -0,0 +1,6 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+
+  const component: DefineComponent;
+  export default component;
+}