Skip to content

Let a person's agents act for them: Delegation rows for edit and a shared private scope - #56

Merged
kriszyp merged 9 commits into
mainfrom
feat/delegation
Nov 16, 2026
Merged

kriszyp merged 9 commits into
mainfrom
feat/delegation

Conversation

@kriszyp

@kriszyp kriszyp commented Nov 16, 2026 •

Copy link
Copy Markdown
Member
A girl tags a dog's collar so it can act for her, while an untagged robot is held back from a locked locker.

⊙ Problem

A person uses agent-memory through several principals: their own user, which owns their imported history, and one agent user per machine. Only the owner could edit a memory, and user:<self> is per principal, so the person's agents got 403 not_memory_owner on the person's memories and could not see each other's private notes. The 403 did not mention supersession (#55).

💡 Solution

An actsFor field on the agent's own ScopeGrant row, { id: "user:<agent>", actsFor: <person> }, read with the grants on every request, lets the agent:

  • edit the person's memories (one gate for revise, withdraw, confirm, link, candidates). ownerId stays the person; lastEditor, confirmed.by and a new withdrawnBy name the agent.
  • read and write user:<person>. Its private notes land there, owned by the person.

It still reads only through its own labels. The revise 403 now names supersedes: ["<id>"].

⚖️ Alternatives

actsFor lives on the user's grant row

Kept on the row each request already reads (owner ruling), so requests do main's two ScopeGrant reads. actsFor on a role: row grants nothing: a role is shared by many people's agents. Cost: a whole-row put that omits actsFor clears it (fails closed).

🤔 Who owns an agent's create

The person owns an agent's create only when its scopes are exactly ["user:<person>"]; mixed and shared creates stay the agent's. If the person owned every create, an agent without customer clearance would lose sight of its own write once it was flagged for customer content, and could not fix it.

🤔 An agent's rescope keeps the owner's read

An agent may move the person's memory to a label the person's grants lack; the person still reads it as owner. Not blocked: the agent can write the same content to user:<person> anyway, and checking the person's grants would need their role, which the agent's request lacks.

Approaches weighed at planning
Approach Why not
One principal per person Breaks per-host credential revocation and per-agent provenance (operator decision).
Shared Harper role owns the memories Roles carry permissions, not identity; eng-agents holds every engineer's agents.
Guidance in the 403 only Agents still cannot share private notes. Kept as part of this PR.
Read-only sharing of user:<person> Loses edit, the root fix in #55.
Agent-owned notes in user:<person> The person and their other agents could not edit notes in the person's own private scope.
A separate Delegation table One more primary-key read per request, for a row keyed by the same username as the user grant row. GET p99 was higher in all 4 benchmark runs with it.

🔧 Changes

What each caller gets, with A acting for P:

Caller P's global memory P's user:P note P's customer:acme memory
P read, edit read, edit read, edit
A (acts for P, global only) read, edit read, edit 404
A after actsFor is cleared read, 403 on edit 404 404
C (no row) read, 403 on edit 404 404

For a delegate, bootstrap recent and needsReview (with the read-rule backstop) and /MemoryEvents flag notices also cover memories in user:<actsFor>, not the principal's whole corpus, which would push the notes out of the 50-row recent section.

Files:

Product and architecture tour

Product and architecture tour

Who may edit and read

What does a delegation let an agent do, and what does it never open?

An edit, or access to user:<P>, succeeds only for P, super_user, or a principal acting for P (actsFor: P on its own user: grant row, or from a custom resolver); the customer-content review exception is unchanged. Labels stay gated by the caller's own grants: delegation adds exactly user:<P> and no ownership-based read.

actsAsOwner is the only new gate: the owner, or a principal acting for the owner that can read the memory through its own labels. Every owner check uses it: revise, withdraw, link, confirm and candidates. A delegate that cannot read the memory (no label, withdrawn, or flagged without customer:*) gets the 404 or 409 a stranger gets. user:<actsFor> joins both matchers, outside the 256-pattern cap, so search gains one scopes = user:<P> condition and never ownerId = P. Look hardest here: this is the authorization rule.

Where an agent's writes land

Who owns what a delegate creates?

A delegate's create with scopes exactly ["user:<P>"] belongs to P; every other create belongs to its writer.

createScopesAndOwner decides scopes and owner for both the planning read and the transaction. A delegate's private shorthand, and the no-scopes default, resolve to user:<actsFor>. Exact-private creates are never content-checked (no global), so an agent never loses sight of its own private note.

Revocation and live streams

How fast does clearing actsFor take effect?

The user grant row is read on every request. Live streams cache a principal for up to 5 s, and the hub's existing ScopeGrant subscription clears that cache on any grant row change, actsFor included. resolveCurrentPrincipal retries while an invalidation lands during a lookup and never caches such a result; this also fixes an existing race where a lookup that began before a ScopeGrant change repopulated the cache after it.

Clearing actsFor during an event

A lookup that overlaps the change is retried, so the event is judged without the delegation.

sequenceDiagram
    participant Hub
    participant Filter as Event filter
    participant Store as ScopeGrant
    Hub->>Filter: event for a user:P memory
    Filter->>Store: read role and user rows
    Store-->>Hub: user row's actsFor cleared
    Hub->>Hub: bump cache generation
    Store-->>Filter: old rows
    Filter->>Store: generation changed, read again
    Store-->>Filter: no delegation
    Filter-->>Hub: not delivered
Loading

✅ Verification

  • npm test: 515/515. The delegation cases fail against base src/, including the cache race. New cases cover actsFor on a role: row granting nothing, a user row carrying only actsFor, and exactly two grant reads per request.
  • Real Harper, integrationTests/delegation.test.ts: 4/4, with actsFor set and cleared through upsert on ScopeGrant. Full integration suite: 81/81.
  • provision-user.sh --acts-for: checked against a stub ssh (sends add_user, then the upsert; refuses self or unknown options), not a cluster.
  • prettier --check and tsc --noEmit: clean.
  • Performance: per-request I/O is the same as main: two ScopeGrant reads. A delegate's search and bootstrap each gain one condition.
  • Docs: README.md, DESIGN.md; HarperFast/documentation has no agent-memory pages.
  • PR QA: skipped @ 4c1f10f — PR-time QA covers harper and harper-pro only.
What the tests cover
  • test/delegation.test.js (15): delegate revise, confirm, withdraw, link and candidates on the person's memory; refusal without actsFor and after clearing it; no second hop; private writes in user:<person> owned by the person, editable by its other agents, 404/409 to others; shared, mixed and own-private creates stay the agent's; a global-only delegate gets 404/409 on a customer: memory everywhere; content-flagged memories hidden from an uncleared delegate, and its own private note never flagged; the revise 403 over HTTP and MCP; bootstrap and /MemoryEvents own view; stream revocation; the cache generation, including a revocation during the retry.
  • test/principal.test.js, test/scopes.test.js: actsFor from the user row per request, ignored on a role row, exactly two grant reads, malformed values, custom resolvers, the label cap, actsAsOwner, createScopesAndOwner, the search conditions.
  • integrationTests/delegation.test.ts on Harper: revise as a delegate, then 403 after clearing actsFor; user:<P> readable by the delegate and 404 to another user; a global-only delegate gets 404 on P's customer: memory; delegate bootstrap; clearing actsFor stops events on an open SSE stream.
  • integrationTests/memory.test.ts expects actsFor: null on the exported principal; test/copy-memories.test.js counts withdrawnBy; test/helpers/harper-stub.mjs emits delete events as Harper does.

🤖 Generated by Claude Opus 5.5; posted via @kriszyp.

Related PRs: none found
Complexity: complicated

Deferred findings

  • 5bfeec756cfec4bf minor security — src/events.ts — in-flight principal resolution returns invalidated authority for one held event — NOT FILED
  • e417c34fbc7967d1 nit reliability — src/events.ts — MemoryEvents own-flag precheck uses connect-time principal — NOT FILED
  • 1bed3796d5a82276 nit security — src/lifecycle.ts — delegate rescope of P-owned memory into labels P lacks keeps P's ownership read — NOT FILED
  • 8c4564bd5df4ccb6 nit test-coverage — test/helpers/harper-stub.mjs — delegate MemoryEvents path stub-only; sparse-scopes branch never runs — NOT FILED
  • 4e890a816efa4413 nit reliability — src/events.ts — resolveCurrentPrincipal retries without bound under sustained ScopeGrant/Delegation churn — NOT FILED

Accepted behavior

Behavior the owner ruled intended, so there is nothing to file.

2 minor or nit
Origin — the dispatch brief this PR was written from

Implement #55: a Delegation grant that lets principal A act for principal P. A may revise/withdraw/confirm memories owned by P (ownerId stays P, lastEditor/author record A) and reads/writes P's private scope user:

(a private write by A while delegating lands in user:

). Delegation never widens label access: A still needs its own grants for every label it reads or writes. Also make not_memory_owner (HTTP and the MCP revise tool) tell the caller to write a merged replacement with supersedes: [id]. Follow the issue's proposal and acceptance list.

Acceptance

Tests for every acceptance bullet in #55, each shown failing on main first; existing suites pass; integration test with two principals on a running app covering revise-as-delegate, revoke-then-403, user:

visibility to A and 404 to a non-delegate, and a global-only delegate denied a customer:-scoped memory owned by P. No change to supersession semantics or the import/copy scripts beyond carrying the new table in copy-memories if it copies grants.

Dispatch: task agent-memory-55-delegation · queued by kris-session · ran by claude/opus/xhigh · worker kzyp-xps-1

Review-Coverage: authored=claude; ran=cursor-composer,gemini,codex,gemini-carbon,cursor-grok; late=gemini-carbon:adjudicated,cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=7; full=3 @ 4c1f10f

Review-Attention: study ~12m (critical: memory.graphql; decisions: actsfor-on-user-grant-row, delegation-trust-boundary, do-less-alternative) @ 4c1f10f

kriszyp and others added 9 commits November 16, 2026 13:33
…private scope

A Delegation row (keyed by the delegate's principal id, actsFor the principal it
acts for) lets a person's agents revise, withdraw, confirm, link and list
candidates for the person's memories, and read and write user:<person>. A
delegate still reads only through labels; ownership-based reads are not shared.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-55-delegation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-55-delegation
…ation test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-55-delegation
…ion, trim bootstrap conditions and comments

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-55-delegation
… own lanes with the read rule

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-55-delegation
…he next event

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-55-delegation
…d; trim comments

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-55-delegation
actsFor moves from a separate Delegation table onto the delegate's own
`user:<username>` ScopeGrant row, which resolveHarperUser already reads, so a
request is back to the two grant reads and revocation on open MemoryEvents
streams rides the existing ScopeGrant hub subscription (generation fence kept).
actsFor on a `role:` row grants nothing and warns once. provision-user.sh gains
--acts-for, which upserts the row after the credentials are delivered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-56-fold-delegation-into-scopegrant
… note that a whole-row put clears actsFor

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispatch-Task: agent-memory-56-fold-delegation-into-scopegrant
@kriszyp
kriszyp marked this pull request as ready for review November 16, 2026 23:57
@kriszyp
kriszyp merged commit c00718c into main Nov 16, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant