---
title: "History Kit"
description: "Version and audit APIs, undo/redo foundations, and app-owned history UI."
---

# History Kit

The History Kit provides versioning, access-scoped history actions, and undo/redo foundations. Apps compose their own timelines, previews, diffs, and restore controls around these APIs; Toolkit does not ship a drop-in history panel.

<WireframeBlock id="doc-block-toolkit-history">
  <Screen
    surface="desktop"
    html={
      "<div style='min-height:540px;box-sizing:border-box;padding:26px;display:grid;grid-template-columns:1fr 300px;gap:18px'><main class='wf-card' style='display:flex;flex-direction:column;gap:12px'><div style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Launch plan</h2><span class='wf-pill'>v12</span><div style='flex:1'></div><button><span data-icon='arrowLeft'></span> Undo</button><button>Redo</button></div><div style='display:flex;flex-direction:column;gap:8px'><div style='height:11px;width:80%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:92%;background:var(--wf-line);border-radius:4px'></div></div><div style='border:1.6px solid var(--wf-accent);border-radius:var(--wf-radius);padding:12px;background:var(--wf-accent-soft);display:flex;flex-direction:column;gap:6px'><small class='wf-muted'>Changed in v12</small><div>Ship the beta the week of Aug 4.</div></div><div style='display:flex;flex-direction:column;gap:8px'><div style='height:11px;width:70%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:88%;background:var(--wf-line);border-radius:4px'></div></div><div style='flex:1'></div><button class='primary'>Restore this version</button></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>History</strong><div style='display:flex;align-items:center;gap:10px;padding:8px;border-radius:8px;background:var(--wf-accent-soft)'><div style='width:26px;height:26px;border-radius:999px;background:var(--wf-accent);flex:none'></div><div style='flex:1;min-width:0'><strong>v12 Agent</strong><br/><small class='wf-muted'>Edited chart text - 2m ago</small></div></div><div style='display:flex;align-items:center;gap:10px;padding:8px'><div style='width:26px;height:26px;border-radius:999px;background:var(--wf-accent-soft);flex:none'></div><div style='flex:1;min-width:0'><strong>v11 Maya</strong><br/><small class='wf-muted'>Added notes - 1h ago</small></div></div><hr/><div style='display:flex;align-items:center;gap:8px'><span data-icon='user'></span><small class='wf-muted'>Audit: visibility changed to Org</small></div></aside></div>"
    }
  />
</WireframeBlock>

This mock shows one app-owned history interface built from the APIs below. The timeline, diff summary, and restore button are examples, not exported Toolkit components.

## Pieces {#pieces}

| Piece                         | Purpose                                                                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `registerVersionedResource()` | Register a resource type, access resolver, optional `getSnapshot()`, and optional `restoreSnapshot()` handler.                        |
| Version actions               | `create-resource-version`, `list-resource-versions`, `get-resource-version`, `restore-resource-version`, and `list-resource-history`. |
| App-owned history UI          | Compose a timeline, preview, diff, or restore flow with the history APIs.                                                             |
| History hooks                 | `useResourceVersions()`, `useResourceHistory()`, `useCreateResourceVersion()`, and `useRestoreResourceVersion()`.                     |
| Audit log                     | Durable record of human and agent actions, scoped by access, included by `list-resource-history`.                                     |
| `useCollabUndo()`             | CRDT undo/redo for collaborative document edits.                                                                                      |
| `useLocalOpUndo()`            | App-local inverse operations for commands outside the Yjs document.                                                                   |
| Diff and compare UI           | App-owned presentation built from version snapshots and domain-specific comparison rules.                                             |

## Register A Resource {#register-resource}

```ts
import { registerVersionedResource } from "@agent-native/core/history";

registerVersionedResource({
  type: "document",
  async resolveAccess(resourceId, ctx) {
    return {
      role: "owner",
      ownerEmail: ctx?.userEmail,
      orgId: ctx?.orgId,
      visibility: "private",
    };
  },
  async getSnapshot({ resourceId }) {
    return loadDocumentSnapshot(resourceId);
  },
  async restoreSnapshot({ resourceId, snapshot }) {
    return restoreDocumentSnapshot(resourceId, snapshot);
  },
});
```

When a resource is already registered with the Sharing Kit, History can reuse
that access model. Register a History adapter when the app wants automatic
snapshot capture or restore behavior.

## Compose an app-specific history surface {#ui-usage}

The Core client exports `useResourceVersions()`, `useResourceHistory()`,
`useCreateResourceVersion()`, and `useRestoreResourceVersion()` from
`@agent-native/core/client/history`. Use these hooks or the corresponding
actions to build the interface your resource needs. The app decides how to
present diffs, identify authors, and confirm restores.

## UX Standard {#ux-standard}

- History should identify human vs agent edits.
- Restore is a new action, not a silent database rewind.
- Undo should be scoped to the user's local intent and never erase remote edits
  unexpectedly.
- Audit logs should be access-scoped; users see events for resources they can
  read.
- Snapshot data should be app-owned JSON. The kit stores and scopes it; the app
  decides how to render, diff, and restore it.

## What's next

- [**Audit Log**](/docs/audit-log) — the durable event trail the history
  timeline's audit view reads from.
- [**Realtime Collaboration**](/docs/real-time-collaboration) — the CRDT
  editing surface `useCollabUndo()` wraps.
- [**Component API**](/docs/components) — the generated reference for public React exports.