IF Commons GitHub

Identity agent operations

0042Active

0042-identity-agent-operations · owner if · domain data

Requirements

FR-001checkpassing

The contracts of delegate, revokeDelegation, recordToolCall, decideApproval and killAgent MUST pass the lint of operations against the identity domain, and each MUST run as the service and name the audit action it records.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity-operations.test.ts: a delegation can only attenuate, a delegate can do only what every delegation of its chain passes on and what the person at the root can do now, and revoking one revokes everything below it

Proved by: data/suite/identity-operations.test.ts

Written in: data/models/identity-agent/operations.ts

Tests: passed: suite/identity-operations.test.ts a delegation can only attenuate, a delegate can do only what every delegation of its chain

FR-002checkpassing

delegate MUST refuse, as a status and not an error, a delegation to oneself, one that is already over, one by a delegator or to a delegate that is not active, one for more than the delegator can do (for the first of a chain), and, for a sub-delegation, one by someone who is not the delegate of the delegation above it, from a delegation that cannot be passed on, with a depth that is not less, that outlives its parent, that is for a wider resource, or that passes on a permission the parent does not; and revokeDelegation MUST end the delegation and every delegation below it, saying how many, and say that it is already ended where it is.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity-operations.test.ts: a delegation can only attenuate, a delegate can do only what every delegation of its chain passes on and what the person at the root can do now, and revoking one revokes everything below it

Proved by: data/suite/identity-operations.test.ts

Written in: data/sql/extensions/operations/identity/agent.ts

Tests: passed: suite/identity-operations.test.ts a delegation can only attenuate, a delegate can do only what every delegation of its chain

FR-003checkpassing

recordToolCall MUST refuse a call by an agent that has not been granted the tool, whose run is not running, whose version is not approved or active, or that the decision engine refuses under the run's delegation, and MUST record every call, allowed or not, once for an index of a run, with a hash of its arguments.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity-operations.test.ts: a tool call is decided, budgeted and approved in one transaction: a granted tool within a delegation is allowed, a risky one waits for a person who owns the agent and may do it themselves, an approval is for one call and used once, and a budget is never exceeded; suite/identity-operations.test.ts: an approval that has expired cannot be decided or used, an approver who no longer holds the permission cannot approve, and a grant's call limit and end are exact

Proved by: data/suite/identity-operations.test.ts

Written in: data/sql/extensions/operations/identity/agent.ts

Tests: passed: suite/identity-operations.test.ts a tool call is decided, budgeted and approved in one transaction: a granted tool within a ; passed: suite/identity-operations.test.ts an approval that has expired cannot be decided or used, an approver who no longer holds th

FR-004checkpassing

A call to a tool that is risky (its risk at or above the agent's threshold, or a grant that always asks, or an obligation) MUST wait for an approval request; an approval MUST be usable once, for exactly the arguments and the action it was asked for and before it runs out, by one conditional update; and the budget of a run MUST be taken from by one conditional update, so that it is never exceeded and what is refused is not counted; and a call that is refused MUST use nothing up: the budgets are looked at before an approval is used, an approval is given back if a budget cannot be taken, and the budgets already taken are given back if another has no room.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity-operations.test.ts: a tool call is decided, budgeted and approved in one transaction: a granted tool within a delegation is allowed, a risky one waits for a person who owns the agent and may do it themselves, an approval is for one call and used once, and a budget is never exceeded; suite/identity-operations.test.ts: a refused call uses nothing up: an approval is not consumed and no budget is spent when another budget has no room, and an event whose fields were changed shows in the chain though its links are intact; suite/identity-operations.test.ts: an approval that has expired cannot be decided or used, an approver who no longer holds the permission cannot approve, and a grant's call limit and end are exact

Proved by: data/suite/identity-operations.test.ts

Written in: data/sql/extensions/operations/identity/agent.ts

Tests: passed: suite/identity-operations.test.ts a tool call is decided, budgeted and approved in one transaction: a granted tool within a ; passed: suite/identity-operations.test.ts an approval that has expired cannot be decided or used, an approver who no longer holds th; passed: suite/identity-operations.test.ts a refused call uses nothing up: an approval is not consumed and no budget is spent when an

FR-005checkpassing

decideApproval MUST refuse a decider that is not an active person (an agent never decides), one that is not the one who answers for the agent (its owner, or the person at the root of its delegation, or a holder of a named role) and one that cannot do the thing themselves, MUST decide a pending request once, and MUST say so where it is not pending or has run out.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity-operations.test.ts: the kill switch switches an agent off at once, and the audit trail is a chain in which a change to an event shows

Proved by: data/suite/identity-operations.test.ts

Written in: data/sql/extensions/operations/identity/agent.ts

Tests: passed: suite/identity-operations.test.ts the kill switch switches an agent off at once, and the audit trail is a chain in which a c

FR-006checkpassing

killAgent MUST, in one transaction, disable the agent, stop its running runs, end its delegations and those below them, revoke its credentials and cancel what waits for approval, say how many of each, say that it is already off where nothing changed, and refuse a principal that is not an agent.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity-operations.test.ts: the kill switch switches an agent off at once, and the audit trail is a chain in which a change to an event shows

Proved by: data/suite/identity-operations.test.ts

Written in: data/sql/extensions/operations/identity/agent.ts

Tests: passed: suite/identity-operations.test.ts the kill switch switches an agent off at once, and the audit trail is a chain in which a c

FR-007checkpassing

The operations of delegation and agents MUST take the identity of the one acting from the caller the project authenticated and never from an input: delegate, revokeDelegation, decideApproval and killAgent MUST refuse as a status a caller that is not the principal an input names as acting (caller-mismatch) and a call with no caller (unauthenticated); revokeDelegation MUST be allowed only to the one who delegated or to one who may delegation:revoke in the tenant; and killAgent MUST be allowed only to the one who answers for the agent or to one who may agent:kill in its tenant.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity-operations.test.ts: the identity of the actor is the caller's and never what an input says: a forged delegator, decider or killer is refused, no caller is refused, and only the one who answers for an agent, or who may, can switch it off or end a delegation

Proved by: data/suite/identity-operations.test.ts

Tests: passed: suite/identity-operations.test.ts the identity of the actor is the caller's and never what an input says: a forged delegator

Out of scope

  • A generated typed client and a server: the runtime is a function.
  • Operations that are not of delegation and agents (create a human, a session, a key, a device): later specifications.
  • Real concurrency: two connections at the same instant cannot be shown by these in-process engines; each operation's single conditional update is what decides.

Edge cases

  • DuckDB cannot update a row that another row refers to, so these operations run on PostgreSQL and SQLite, per FR-001.
  • A decision about a principal that is disabled is a refusal whatever it holds, per FR-001.
  • A delegation whose delegator loses the right it passed on stops working at once, because the root is asked again at every decision, per FR-001.

Assumptions

  • A role of a group is held by its members, and a group's members may be principals of any kind.
  • The clock is given to each operation, so that a test is the same every time.

Open questions

OQ-1open question

Whether an approval by two people (four eyes) is wanted for a critical action; the model supports one.

OQ-2open question

Whether the decision engine should be given bound parameters instead of literals, since agents supply free text.

Key entities

  • Decision - allow or deny, with why, what must happen first, and what decided.
  • Delegation chain - the delegations from a principal back to the person at the root.

Success criteria

SC-001success criterion

An agent can be given exactly the authority of a person for exactly one task, can be stopped at once, and leaves a trail in which a change shows.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Data, models/identity-agent/operations, sql/extensions/operations/identity/agent

Titles, headings, exports, tables, columns and requirements. Esc closes.