Repository navigation
Let a person's agents act for them: Delegation rows for edit and a shared private scope - #56
Merged
Merged
Conversation
…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
marked this pull request as ready for review
November 16, 2026 23:57
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
⊙ 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 got403 not_memory_owneron the person's memories and could not see each other's private notes. The 403 did not mention supersession (#55).💡 Solution
An
actsForfield on the agent's ownScopeGrantrow,{ id: "user:<agent>", actsFor: <person> }, read with the grants on every request, lets the agent:ownerIdstays the person;lastEditor,confirmed.byand a newwithdrawnByname the agent.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
actsForlives on the user's grant rowKept on the row each request already reads (owner ruling), so requests do
main's twoScopeGrantreads.actsForon arole:row grants nothing: a role is shared by many people's agents. Cost: a whole-rowputthat omitsactsForclears 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
eng-agentsholds every engineer's agents.user:<person>user:<person>Delegationtable🔧 Changes
What each caller gets, with A acting for P:
globalmemoryuser:Pnotecustomer:acmememoryactsForis clearedFor a delegate, bootstrap
recentandneedsReview(with the read-rule backstop) and/MemoryEventsflag notices also cover memories inuser:<actsFor>, not the principal's whole corpus, which would push the notes out of the 50-rowrecentsection.Files:
schema/memory.graphql:ScopeGrant.actsFor;Memory.withdrawnBy.src/principal.ts:actsForfrom the user grant row, ignored on a role row;PrincipalResolution.actsForfor custom resolvers; one bounded warning per invalid value.src/scopes.ts:Principal.actsFor; the implicituser:<actsFor>label outside the cap; an invalid or selfactsForgrants nothing;actsAsOwner;ownViewCondition;createScopesAndOwner;quarantineConditions, now shared withreadableConditions.src/lifecycle.ts: owner gates viaactsAsOwnerfor revise, withdraw, link and confirm; create ownership in the planning read and transaction; the revise 403 message;withdrawnByon withdraw and in views.src/supersession.ts: the candidates gate.src/mcp.ts: therevisetool description names the supersede route.src/search.ts:withdrawnByin view fields; the bootstrap lanes above.src/events.ts: the cache generation, fencing the existingScopeGrantsubscription, which now also carriesactsForchanges; own-flag delivery.deploy/engineering/provision-user.sh:--acts-for <user>upserts the agent'sactsForafter its credentials are delivered.scripts/copy-memories.mjs: the dry run countswithdrawnByas not carried.DESIGN.md: Identity › Delegation, rule 2, rule 3, rule 5, Live updates, Extension points, plus Lifecycle, bootstrap and Copy lines.README.md: how to setactsFor; the principal fields and copy notes.CHANGELOG.md: Added and Fixed.deploy/engineering/README.md: the engineering cluster's agent rows and--acts-for.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?
actsAsOwneris 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 withoutcustomer:*) gets the 404 or 409 a stranger gets.user:<actsFor>joins both matchers, outside the 256-pattern cap, so search gains onescopes = user:<P>condition and neverownerId = P. Look hardest here: this is the authorization rule.Where an agent's writes land
Who owns what a delegate creates?
createScopesAndOwnerdecides scopes and owner for both the planning read and the transaction. A delegate's private shorthand, and the no-scopes default, resolve touser:<actsFor>. Exact-private creates are never content-checked (noglobal), so an agent never loses sight of its own private note.Revocation and live streams
How fast does clearing
actsFortake 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
ScopeGrantsubscription clears that cache on any grant row change,actsForincluded.resolveCurrentPrincipalretries 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 aScopeGrantchange repopulated the cache after it.Clearing
actsForduring an eventA 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✅ Verification
npm test: 515/515. The delegation cases fail against basesrc/, including the cache race. New cases coveractsForon arole:row granting nothing, a user row carrying onlyactsFor, and exactly two grant reads per request.integrationTests/delegation.test.ts: 4/4, withactsForset and cleared throughupsertonScopeGrant. Full integration suite: 81/81.provision-user.sh --acts-for: checked against a stubssh(sendsadd_user, then the upsert; refuses self or unknown options), not a cluster.prettier --checkandtsc --noEmit: clean.main: twoScopeGrantreads. A delegate's search and bootstrap each gain one condition.README.md,DESIGN.md; HarperFast/documentation has no agent-memory pages.What the tests cover
test/delegation.test.js(15): delegate revise, confirm, withdraw, link and candidates on the person's memory; refusal withoutactsForand after clearing it; no second hop; private writes inuser:<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 acustomer: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/MemoryEventsown view; stream revocation; the cache generation, including a revocation during the retry.test/principal.test.js,test/scopes.test.js:actsForfrom 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.tson Harper: revise as a delegate, then 403 after clearingactsFor;user:<P>readable by the delegate and 404 to another user; a global-only delegate gets 404 on P'scustomer:memory; delegate bootstrap; clearingactsForstops events on an open SSE stream.integrationTests/memory.test.tsexpectsactsFor: nullon the exported principal;test/copy-memories.test.jscountswithdrawnBy;test/helpers/harper-stub.mjsemits delete events as Harper does.🤖 Generated by Claude Opus 5.5; posted via @kriszyp.
Related PRs: none found
Complexity: complicated
Deferred findings
5bfeec756cfec4bfminor security —src/events.ts— in-flight principal resolution returns invalidated authority for one held event — NOT FILEDe417c34fbc7967d1nit reliability —src/events.ts— MemoryEvents own-flag precheck uses connect-time principal — NOT FILED1bed3796d5a82276nit security —src/lifecycle.ts— delegate rescope of P-owned memory into labels P lacks keeps P's ownership read — NOT FILED8c4564bd5df4ccb6nit test-coverage —test/helpers/harper-stub.mjs— delegate MemoryEvents path stub-only; sparse-scopes branch never runs — NOT FILED4e890a816efa4413nit reliability —src/events.ts— resolveCurrentPrincipal retries without bound under sustained ScopeGrant/Delegation churn — NOT FILEDAccepted behavior
Behavior the owner ruled intended, so there is nothing to file.
2 minor or nit
a7f0076c79d3a3e6nit maintainability —src/lifecycle.ts— withdraw/confirm/link 403 messages do not name the supersede route — accepted: task owner scoped the guidance to revise in issue Let a person's agents act for them: delegated edit and shared private scope #55 ("not_memory_owner from revise (HTTP and MCP) says how to proceed") and the dispatch brief8d6d275cff758bf0nit documentation —src/principal.ts— custom resolvers not calling next() ignore Delegation rows — accepted: task owner (dispatch brief for Let a person's agents act for them: delegated edit and shared private scope #55, decision 1) ruled delegation is read per request like ScopeGrant, which only the default resolution reads; custom resolvers supply actsFor as they supply grants (DESIGN Identity)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-1Review-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