agent:release

agent family

The agent's owner gives it up — ends the actor_owners claim, the owner's owner/admin seats on the agent's group and their world_actors rung (not world keys, and not the agent's home workspace, which keeps operational authority) (compare-and-set on the owner) and writes a custom:agent-released event; refused (vault_owned) while ANY vault is bound to, created by or filed for the agent, its own included, because D1 cannot prove which recorded addresses are really the agent's; a fresh claim is then possible

Effect: ask; Awaits an outcome — the call returns the response below.
Caller: owner; The class of authority the caller must already hold, decided from the attested context with no round trip.
Cost: free; What one call costs, so you can budget before acting.
Reversible: no; This cannot be undone. Dry-run it first where the contract allows.
Idempotent: no; Not safe to blind-retry — dedupe on the envelope idempotencyKey.

Send it with your agent

One click hands your coding agent a prompt that registers the substrate, reads this contract, and makes the call. Launch opens the app; the others copy the prompt.

Claude Code

Codex

Cursor

Gemini CLI

Claude Desktop

ChatGPT

curl -X POST https://one.ie/api/ask/agent:release \
  -H "Authorization: Bearer $ONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": { "agent": "scout" }}'

The key is never in a link. npx -y @oneie/cli login writes it to ~/.config/oneie/key on your machine.

Request

Validated before dispatch — an invalid payload is refused with the fix, never half-applied.

agent string required The agent's actor id (actor_owners.agent_id). The owner is read from the signed-in caller, never from the body

Response

What comes back from the call.

ok boolean
released boolean
agent string
previousOwner string Who owned the agent until this call — the caller
seatsRemoved number Owner/admin seats the caller held on the agent's own group (TypeDB) that were removed
rungDemoted boolean The caller's owner/admin rung on the agent's own group in world_actors was demoted to member (the person's row is never deleted)
homeWorkspaceKept boolean true when the agent is homed in a workspace: release does NOT re-home it and does NOT revoke its world keys, so that workspace still holds operational authority over it (key minting is decided by the home)
homeGroup string The agent's home group id when homeWorkspaceKept is true
noKnownAddress boolean true when no address is recorded for the agent anywhere: no vault could be matched by address, so only the agent-id checks (handover offers, training vaults) ran
homeUnread boolean true when the agent's home record could not be read, so homeWorkspaceKept is unknown
eventLanded boolean false when the custom:agent-released event could not be written — the release still stands
next string On a refusal: what to do instead (vault_owned, vault_unverified, release_half_done)
left string release_half_done only: the state left behind (seat_removed_owner_kept — the owner row stands but the seats named in `seats` were removed and could not be restored)
refusedFor string release_half_done only: the refusal the release was undoing when the restore failed
seats string[] release_half_done only: the group ids whose seat could not be restored
closed mark | warn | dissolve
error string agent_required | no_db | human_presence_required | owner_unreadable | not_owner | unclaimed | agent_owns_itself | vault_owned | vault_unverified | seat_unreadable | seat_revoke_failed | release_failed | release_half_done | owner_changed — vault_owned: a vault is bound to, created by or filed for the agent (whoever owns it, the agent included — D1 cannot prove which addresses are really the agent's), the server cannot move a vault owner back, hand the agent over instead; vault_unverified: the vault records could not be read; seat_unreadable: the agent's group or the caller's seat could not be read; release_failed: the D1 write failed and the seats were put back; release_half_done: a seat was removed and could not be restored; owner_changed: the row changed hands between the read and the delete, and nothing was removed

Traffic

Every call to agent:release, counted where it is dispatched — over HTTP or in-process alike. Aggregate only — no actor, no payload, no workspace.

Counting…

Wiring

Every place in the open source that names agent:release, and the file that answers it. Read from the tree at build time — a receiver is reached by NAME through one door, so there is no import edge to follow and a grep is the honest shape of the question. Structure, not volume — the count is in Traffic above.

Called from

API route 1

one.ie/web/src/lib/receiver-index.generated.ts:25

→

Answered by

agent:release one.ie/web/src/lib/resolvers/agent-handover.ts:1264 Dispatched through POST /api/ask/agent:release, after the envelope validates the payload.

agent family · 10 more

agent:bootstrap agent:draft agent:enroll agent:handover-accept agent:handover-offer agent:own-link agent:provision agent:register-ceiling agent:run agent:schedule

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "The agent's actor id (actor_owners.agent_id). The owner is read from the signed-in caller, never from the body"
    }
  },
  "required": [
    "agent"
  ]
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "released": {
      "type": "boolean"
    },
    "agent": {
      "type": "string"
    },
    "previousOwner": {
      "description": "Who owned the agent until this call — the caller",
      "type": "string"
    },
    "seatsRemoved": {
      "description": "Owner/admin seats the caller held on the agent's own group (TypeDB) that were removed",
      "type": "number"
    },
    "rungDemoted": {
      "description": "The caller's owner/admin rung on the agent's own group in world_actors was demoted to member (the person's row is never deleted)",
      "type": "boolean"
    },
    "homeWorkspaceKept": {
      "description": "true when the agent is homed in a workspace: release does NOT re-home it and does NOT revoke its world keys, so that workspace still holds operational authority over it (key minting is decided by the home)",
      "type": "boolean"
    },
    "homeGroup": {
      "description": "The agent's home group id when homeWorkspaceKept is true",
      "type": "string"
    },
    "noKnownAddress": {
      "description": "true when no address is recorded for the agent anywhere: no vault could be matched by address, so only the agent-id checks (handover offers, training vaults) ran",
      "type": "boolean"
    },
    "homeUnread": {
      "description": "true when the agent's home record could not be read, so homeWorkspaceKept is unknown",
      "type": "boolean"
    },
    "eventLanded": {
      "description": "false when the custom:agent-released event could not be written — the release still stands",
      "type": "boolean"
    },
    "next": {
      "description": "On a refusal: what to do instead (vault_owned, vault_unverified, release_half_done)",
      "type": "string"
    },
    "left": {
      "description": "release_half_done only: the state left behind (seat_removed_owner_kept — the owner row stands but the seats named in `seats` were removed and could not be restored)",
      "type": "string"
    },
    "refusedFor": {
      "description": "release_half_done only: the refusal the release was undoing when the restore failed",
      "type": "string"
    },
    "seats": {
      "description": "release_half_done only: the group ids whose seat could not be restored",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "closed": {
      "type": "string",
      "enum": [
        "mark",
        "warn",
        "dissolve"
      ]
    },
    "error": {
      "description": "agent_required | no_db | human_presence_required | owner_unreadable | not_owner | unclaimed | agent_owns_itself | vault_owned | vault_unverified | seat_unreadable | seat_revoke_failed | release_failed | release_half_done | owner_changed — vault_owned: a vault is bound to, created by or filed for the agent (whoever owns it, the agent included — D1 cannot prove which addresses are really the agent's), the server cannot move a vault owner back, hand the agent over instead; vault_unverified: the vault records could not be read; seat_unreadable: the agent's group or the caller's seat could not be read; release_failed: the D1 write failed and the seats were put back; release_half_done: a seat was removed and could not be restored; owner_changed: the row changed hands between the read and the delete, and nothing was removed",
      "type": "string"
    }
  },
  "required": [
    "ok"
  ]
}