diff --git a/CHANGELOG.md b/CHANGELOG.md index 9fde803..38fd18d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ All notable changes to `@harperfast/agent-memory` are documented here. The forma ### Fixed +- Live updates: a principal resolution that started before a `ScopeGrant` change is no longer cached after it, so a + revoked grant stops event delivery on the next event instead of up to 5 s later. + - Claude Code plugin: session start injects every entry the server packed, in the server's order, within `AGENT_MEMORY_BOOTSTRAP_BUDGET`, for entries whose metadata is within its framing estimate. It sends that estimate as `entryOverhead` and `sectionItemOverhead`, so the server packs only what fits; before, about 40% of the entries were dropped at the default budget, because @@ -20,6 +23,20 @@ All notable changes to `@harperfast/agent-memory` are documented here. The forma ### Added +- Delegation ([#55](https://github.com/HarperFast/agent-memory/issues/55)): `actsFor` on an agent user's + `ScopeGrant` row (`{ id: "user:", actsFor: }`) lets a person's agent users act for the person. A delegate may revise, + withdraw, confirm, link and list candidates for the principal's memories (`ownerId` stays the principal; `lastEditor`, + `confirmed.by` and the new `withdrawnBy` name the delegate) and reads and writes `user:`: its private + writes land there, owned by the principal, so the principal and every other delegate can edit them. A delegate + still reads only through labels, so it never reaches a memory its own grants do not. The row is read on every + request, and clearing `actsFor` revokes the delegation on the next one; `actsFor` on a `role:` row grants nothing. + `provision-user.sh --acts-for ` sets it. `resolvePrincipal` returns `actsFor`, and a custom + principal resolver may return it. +- A delegate's bootstrap `recent` and `needsReview` sections, and its `/MemoryEvents` flag notices, include memories in + its principal's private scope. +- The `403 not_memory_owner` from a revise (HTTP and the MCP `revise` tool) names the route left: a merged replacement + with `supersedes: [id]`. +- `withdrawnBy`: the principal that withdrew a memory. - `GET /Memory/bootstrap?entryOverhead=§ionItemOverhead=`: characters a client adds around each memory and each contributed section item it renders (`0..10000`, default `0`; `sectionItemOverhead` defaults to `entryOverhead`). Each packed entry is charged title + content + its overhead, so a client that frames entries can ask for its exact diff --git a/DESIGN.md b/DESIGN.md index ec51541..639bf29 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -39,6 +39,7 @@ allowlists, idempotent `PUT` create/revise with `If-Match` revision precondition | Supersession backfill: candidates for an existing memory, links between existing memories, created-order cursor | implemented (`src/lifecycle.ts`) | | Package exports reaching the plugin from another app (Extension points, Across apps) | implemented (`src/runtime.ts`) | | `scanMemories`, `getMemories`, bootstrap sections and search annotators for derived plugins (Extension points) | implemented (`src/extensions.ts`) | +| Delegation: one principal acting for another (Identity, Scopes and grants) | implemented (`src/scopes.ts`) | ## Data model @@ -63,7 +64,8 @@ database). every embed into another vector space, with no refusal to see. One write, import or search takes its model, caps and flag from one settings snapshot (`EmbeddingSettings`); the table embedder truncates only a row recorded under the configured `embeddingModel`. -- `ScopeGrant` — read/write scope patterns held by a Harper role or user. +- `ScopeGrant` — read/write scope patterns held by a Harper role or user; a user's row may also name the + principal it acts for (`actsFor`, Identity). - `MemoryPin` — a principal's pinned memories (`:`), loaded first at session bootstrap. - `MemoryWatch` — a principal's time-bounded interest in specific memories (live updates). @@ -73,7 +75,7 @@ See `schema/memory.graphql`. The table is not `@export`ed: every read and write Server-owned fields: `ownerId`, `status`, `revision`, `author`, `lastEditor`, `supersededBy`, `autoSupersedes`, `evidenceMemoryIds`, `needsReview`, `needsReviewSince`, `confirmed`, `contentFlag`, -`contentFlagged`, `scopeConfirmed`, `createdAt`, `embeddingModel`, `lastEventKind`. `createdAt` is set by the lifecycle rather than `@createdTime`, because Harper's +`contentFlagged`, `scopeConfirmed`, `withdrawnBy`, `createdAt`, `embeddingModel`, `lastEventKind`. `createdAt` is set by the lifecycle rather than `@createdTime`, because Harper's `@createdTime` overwrites a supplied value on insert and import must preserve it. `updatedAt` stays `@updatedTime`. `needsReviewSince` mirrors `needsReview.since` because Harper does not index object values; `lastEventKind` records the lifecycle event kind (`created`, `revised`, `superseded`, `withdrawn`, @@ -110,6 +112,20 @@ source? }`, or `undefined` for unauthenticated. `next()` is the default Harper-u Principal ids must not contain whitespace, `:` or `*`, and are capped at 122 characters, so that `user:` fits a 128-character scope label. +**Delegation.** A person often reaches the plugin through several principals: their own user (owning history +imported for them) and one agent user per machine. `actsFor` on the delegate's user grant row +(`ScopeGrant` `{ id: "user:", actsFor: }`) lets the delegate act for the principal: edit the +principal's memories and share its private scope (Scopes and grants). It sits on the user row because that row is +already keyed by the delegate and read on every request; a delegate whose grants all come from its role gets a +user row carrying only `actsFor`. One field per delegate, so a principal acts for at most one other and its private +writes have one destination; only the caller's own row is read, so it is not transitive. The default resolution +reads it on every request, so clearing it (or deleting the row) takes effect on the next request; a custom +resolver returns `actsFor` itself. An `actsFor` naming the principal itself, or not a valid principal id, grants +nothing and is logged. So does one on a `role:` row: a role is shared by many people's agents, so it can never +name the one principal they act for. +Delegation never merges the two principals: `author`, `lastEditor`, `confirmed.by` and `withdrawnBy` name the +delegate, and the delegate keeps its own grants and `user:`. + Memory ids are client-chosen (`^[A-Za-z0-9_-]{16,64}$`; clients normally generate a UUID) and share one table-wide namespace across all owners rather than per-owner id namespaces. Because `PUT /Memory/` creates when the id is absent, a `PUT` to an existing id that the caller cannot read answers `409 @@ -125,7 +141,7 @@ vocabulary with Reflex visibility scopes (Reflex #573): | Label | Meaning | | --------------- | ----------------------------------------------------- | | `global` | everyone with global read | -| `user:` | the owner only (private) | +| `user:` | the owner and its delegates only (private) | | `customer:` | people and agents cleared for that customer's content | | `team:` | a team | @@ -133,13 +149,14 @@ Each memory carries `scopes: [String]`. A caller sees a memory when **any** of i caller's readable set. To restrict content, use one specific label (`customer:acme`), not a list. Grants are `ScopeGrant` rows keyed `role:` or `user:`, with `read` and `write` -pattern lists. A pattern is an exact label or a namespace wildcard (`customer:*`); a wildcard never -covers the bare `global`. Every principal implicitly reads and writes `user:`, and no grant -reaches into the `user` namespace: `user:` means the owner only, so a pattern such as `user:*` or -`user:bob` is ignored rather than quietly opening private memories (reading everything is what -`super_user` is for). `super_user` reads and writes everything. Grant rows are read on every request, -so revoking one takes effect on the next request. An invalid pattern grants nothing and is logged; at -most 256 patterns per principal count, which bounds the condition every search carries. +pattern lists (a user row may also carry `actsFor`, Identity). A pattern is an exact label or a namespace wildcard (`customer:*`); a wildcard never +covers the bare `global`. Every principal implicitly reads and writes `user:`, a delegate also +`user:`, and no grant reaches into the `user` namespace: `user:` means the owner and its +delegates only, so a pattern such as `user:*` or `user:bob` is ignored rather than quietly opening private +memories (reading everything is what `super_user` is for). `super_user` reads and writes everything. Grant rows +are read on every request, so revoking one takes effect on the next request. An invalid pattern grants nothing +and is logged; at most 256 patterns per principal count (the implicit `user:` labels do not), which bounds the +condition every search carries. Rules: @@ -154,10 +171,18 @@ Rules: 2. **Write scopes**: creating or revising with scopes `S` requires every label of `S` to be writable by the caller — the resulting scopes, so revising a memory that stays `global` needs `global` write. `visibility: "private" | "shared"` is shorthand for `[user:]` / `[global]`; explicit - `scopes` wins when both are given. Withdrawal is exempt. -3. **Edit**: only the owner (or `super_user`) revises or withdraws, apart from the customer-content review - (rule 4). Read access never grants edit; a - reader that is not the owner gets 403 (`not_memory_owner`), and a non-reader gets 404 on `DELETE` + `scopes` wins when both are given. Withdrawal is exempt. A delegate's private create goes to + `[user:]`, and a create whose scopes are exactly that is owned by the principal, so the principal and + its other delegates can edit it; any other create is owned by its writer (`createScopesAndOwner`), which keeps an + uncleared writer able to read, and so fix, its own content-flagged write. +3. **Edit**: only the owner, a principal acting for the owner, or `super_user` revises, withdraws, confirms, + links or lists candidates, apart from the customer-content review (rule 4). A delegate must still read the + memory through its labels (`actsAsOwner`): delegation never adds the owner's other labels or the owner's + ownership-based reads (withdrawn, content-flagged), so a delegate that cannot read gets what a stranger gets. + The owner keeps its own read of whatever labels a delegate gives its memory, as it does after a customer + reviewer's rescope; a delegate can publish to the principal through `user:` anyway. + Read access never grants edit; a reader that is not the owner gets 403 (`not_memory_owner`; on a revise it + names the route left, a merged replacement with `supersedes: [id]`), and a non-reader gets 404 on `DELETE` or 409 `id_unavailable` on `PUT`. 4. **Supersede, review flags and customer-content review**: see below. They are the only writes that touch another principal's memory: a supersede changes only status fields (`status`, `supersededBy`, `revision`), @@ -166,8 +191,8 @@ Rules: confirm-scope changes only the content flag, `scopeConfirmed` and `revision`. 5. **Search pushes the readable set into the query**, applied before the limit in every lane, never as a post-filter on a top-k. The set compiles to conditions (`src/scopes.ts` `readableConditions`): - an `or` of `ownerId = self`, `scopes =