Agent runners treat any agents.md as an instruction file for themselves, and this page is user documentation about relay agents, so it now lives at docs/agent-access.md. Links follow.
- commit
- d90c59f67254b76283f04ee589f96a266ab4db30
- parent
- 4c4f3249a74b6ad0148005dcd96d5f8287e4406e
- author
- Dami <dami.etoile@gmail.com>
@@ -104,7 +104,7 @@ See [Social](docs/social.md) for notes, long-form articles, NIP-10 and NIP-22 co
104104 105105 See [Installed app](docs/app.md) for installing the relay as an app, sharing files to it, opening Nostr links and device notifications.106106 107-See [Agent identities](docs/agents.md) for granting an assistant or bot its own scoped key, what the relay enforces and how to pause or revoke it.107+See [Agent identities](docs/agent-access.md) for granting an assistant or bot its own scoped key, what the relay enforces and how to pause or revoke it.108108 109109 See [Wiki](docs/wiki.md) for pages, versions and forks, merge requests and redirects.110110 @@ -23,7 +23,7 @@ Start with the relay's `/llms.txt` endpoint for its URLs, authentication rules,
2323 | Task | Guide |2424 | --- | --- |2525 | Authenticate and call tools, upload attachments or publish sites | [MCP](mcp.md) |26-| Grant an agent access, request missing permissions, ask for decisions or run tasks | [Agents](agents.md) |26+| Grant an agent access, request missing permissions, ask for decisions or run tasks | [Agents](agent-access.md) |2727 | Use tools through a connected browser signer | [Browser tools](webmcp.md) |2828 2929 Agents sign with their own keys. A request for more access waits for the current operator's signed grant; a reaction alone does not change permissions. The optional `tiny agent` runner starts separately from the relay daemon.No content changes.
@@ -28,7 +28,7 @@ Notifications are off until you turn them on, and each device is enabled separat
2828 2929 Each device chooses what wakes it: private messages, replies to your posts, issues and pull requests, mentions, requests for a decision, access-grant requests awaiting review, and relay notices such as a report awaiting moderation or a finished job. A burst of activity produces one notification per category. The text is encrypted to the device, so the push service never reads it. The app icon shows how many conversation events arrived since you last opened Chat, plus the requests that still wait for your decision. Opening Chat clears the conversation count, and answering a request clears that request. Devices that stop accepting messages are removed.3030 31-A request for a decision arrives with **Approve**, **Deny** and **Reply** buttons on the notification; a question offers only **Reply**. Each button opens the request on the **Approvals** page, where Approve and Deny ask you to confirm before your signer signs the answer, and Reply opens the reply box. Nothing is signed from the notification alone. See [Asking a person](agents.md#asking-a-person) for how requests are made and answered.31+A request for a decision arrives with **Approve**, **Deny** and **Reply** buttons on the notification; a question offers only **Reply**. Each button opens the request on the **Approvals** page, where Approve and Deny ask you to confirm before your signer signs the answer, and Reply opens the reply box. Nothing is signed from the notification alone. See [Asking a person](agent-access.md#asking-a-person) for how requests are made and answered.3232 3333 An agent's access request offers **Review access** instead. It opens the proposed grant changes in Approvals. Only the current grant operator can approve them by signing the replacement grant; the notification itself cannot authorize more access.3434 @@ -51,7 +51,7 @@ Consumers declare interfaces around the operations they need. `records.Community
5151 5252 Client publication and imported events use the shared event persistence and projection path. Each entry point applies its admission rules and protocol actions. Signed repository state stays pending until its referenced Git objects are available; promotion makes it visible and plans its optional follow-up work.5353 54-Callbacks and custom views are optional. A planning intent commits with an accepted event and captures its eligible registrations or failed local lookups. Recovery rechecks the source and current registrations, with at most three worker attempts and a 15-minute age limit. Stable child intent IDs preserve completed work. Remote delivery and transforms have their own retry policies. See [callbacks](agents.md#retries-and-pauses) and [custom views](views.md#failures).54+Callbacks and custom views are optional. A planning intent commits with an accepted event and captures its eligible registrations or failed local lookups. Recovery rechecks the source and current registrations, with at most three worker attempts and a 15-minute age limit. Stable child intent IDs preserve completed work. Remote delivery and transforms have their own retry policies. See [callbacks](agent-access.md#retries-and-pauses) and [custom views](views.md#failures).5555 5656 ## Browser boundaries5757 @@ -8,7 +8,7 @@
88 | Owner | `internal/community` request parsing, patching and replacement validation; `internal/gates` admission/privacy; `internal/daemon` MCP preparation, approvals and history. |99 | Wire | Agent-signed kind `1111` with `request=grant`; operator-signed kind `30392` replacement. |1010 11-The [catalog's audit baseline and transport rules](README.md) apply. [NIP-22](https://github.com/nostr-protocol/nips/blob/master/22.md) supplies the kind 1111 comment/reference foundation; [NIP-25](https://github.com/nostr-protocol/nips/blob/master/25.md) supplies kind 7 reactions; NIP-01 and NIP-40 supply signed event and expiration foundations. The `grant` request type, JSON patch, provenance and authority rules are project additions to those foundations. No upstream revision or full NIP-22 conformance audit is asserted. This is not the general-purpose approval convention or upstream delegation. See [Agent identities](../agents.md#requesting-additional-access) for the workflow.11+The [catalog's audit baseline and transport rules](README.md) apply. [NIP-22](https://github.com/nostr-protocol/nips/blob/master/22.md) supplies the kind 1111 comment/reference foundation; [NIP-25](https://github.com/nostr-protocol/nips/blob/master/25.md) supplies kind 7 reactions; NIP-01 and NIP-40 supply signed event and expiration foundations. The `grant` request type, JSON patch, provenance and authority rules are project additions to those foundations. No upstream revision or full NIP-22 conformance audit is asserted. This is not the general-purpose approval convention or upstream delegation. See [Agent identities](../agent-access.md#requesting-additional-access) for the workflow.1212 1313 ## Request envelope1414 @@ -8,7 +8,7 @@
88 | Owner | `internal/community` parses grants and owns their effective state; `internal/gates` enforces admission; `internal/daemon` binds management, storage and feature authority. |99 | Wire | Kind `30392`; address `30392:<operator pubkey>:<agent pubkey>`. |1010 11-The [catalog's audit baseline and transport rules](README.md) apply. Foundations are [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) signed/addressable events, [NIP-09](https://github.com/nostr-protocol/nips/blob/master/09.md) deletion, [NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md) expiration, and NIP-86/NIP-98 management. Kind 30392, its grant tags, the agent role and the management methods below are project conventions, not an upstream delegation standard. No upstream revision or complete conformance audit is asserted. The user guide is [Agent identities](../agents.md).11+The [catalog's audit baseline and transport rules](README.md) apply. Foundations are [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) signed/addressable events, [NIP-09](https://github.com/nostr-protocol/nips/blob/master/09.md) deletion, [NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md) expiration, and NIP-86/NIP-98 management. Kind 30392, its grant tags, the agent role and the management methods below are project conventions, not an upstream delegation standard. No upstream revision or complete conformance audit is asserted. The user guide is [Agent identities](../agent-access.md).1212 1313 ## Event fields1414 @@ -8,7 +8,7 @@
88 | Owner | `internal/daemon` callback service, registration, matching and delivery; host visibility is supplied by `internal/gates`. |99 | Wire | Project management methods plus HTTPS POST of one signed Nostr event. No registration event kind. |1010 11-The [catalog's audit baseline and transport rules](README.md) apply. [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) supplies events and filter matching; NIP-86/NIP-98 supply the management/authentication foundations. Registration, HMAC headers, retries and quotas are project extensions, not NIP-01 subscriptions or an upstream webhook standard. No upstream revision or full conformance audit is asserted. See the [callback guide](../agents.md#callbacks) for receiver examples.11+The [catalog's audit baseline and transport rules](README.md) apply. [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) supplies events and filter matching; NIP-86/NIP-98 supply the management/authentication foundations. Registration, HMAC headers, retries and quotas are project extensions, not NIP-01 subscriptions or an upstream webhook standard. No upstream revision or full conformance audit is asserted. See the [callback guide](../agent-access.md#callbacks) for receiver examples.1212 1313 This contract is **not** the signed push-registration/replication callback implemented by [`internal/replication/push.go`](../../internal/replication/push.go). That service has a different registration, payload and authority model. Sharing the pinned HTTP client does not make the protocols interchangeable.1414 @@ -53,7 +53,7 @@ Write tools, added with `--allow-writes`:
5353 5454 `--tools` replaces the default with the named tools, in the order given. Each name must belong to one of the two lists, and a write tool still needs `--allow-writes`; otherwise the process exits at startup with the offending name. Names the relay does not serve are accepted and simply absent from `tools/list`.5555 56-`tiny_diagnose` is the one tool the facade answers itself. It is always offered, whatever `--tools` names, and no relay tool carries the name. It takes optional `rooms` and `kinds` arrays and returns the report of `tinyagent diagnose` as `structuredContent`, with `<verdict>: <advice>` as the text block: whether the relay answers, whether it accepts the key's signature, membership and role, the grant and its state, and the named rooms and kinds the grant lacks. The verdict is `ok`, `needs-grant`, `not-a-member`, `unauthorized` or `unreachable`; a refused signature is reported as `unauthorized`, never as `unreachable`. The tool calls the relay's `browsegrant` browse method over the signed NIP-86 endpoint rather than `/mcp`, and its report is a result rather than an error whatever the verdict. See [Diagnostics](../agents.md#diagnostics).56+`tiny_diagnose` is the one tool the facade answers itself. It is always offered, whatever `--tools` names, and no relay tool carries the name. It takes optional `rooms` and `kinds` arrays and returns the report of `tinyagent diagnose` as `structuredContent`, with `<verdict>: <advice>` as the text block: whether the relay answers, whether it accepts the key's signature, membership and role, the grant and its state, and the named rooms and kinds the grant lacks. The verdict is `ok`, `needs-grant`, `not-a-member`, `unauthorized` or `unreachable`; a refused signature is reported as `unauthorized`, never as `unreachable`. The tool calls the relay's `browsegrant` browse method over the signed NIP-86 endpoint rather than `/mcp`, and its report is a result rather than an error whatever the verdict. See [Diagnostics](../agent-access.md#diagnostics).5757 5858 ## Sign and resubmit5959 @@ -59,7 +59,7 @@ Each uploader pays the full size of every file they claim, even when another upl
5959 6060 Agents can upload room attachments through MCP with `upload_attachment`, passing bounded Base64 bytes, a MIME type and an optional filename. The result includes the Blossom URL, SHA-256, size and NIP-92 metadata. Pass it to `post_message`, `start_thread` or `reply_in_thread` in an `attachments` array. `read_attachment` retrieves up to 4 MiB by hash, with native MCP content for images and audio. Room uploads follow room access rules. See [MCP room attachments](mcp.md#room-attachments) for upload limits and the HTTP endpoint for larger files.6161 62-An agent whose grant carries a `sites` tag with a ttl uploads on a clock: each file it stores is kept for the longest ttl among the grant's site entries, then removed by maintenance. A person who claims the same file keeps it, and the agent's claim alone is released. An agent whose grant says `encrypted` may store only encrypted blobs and manifests. See [Static sites](agents.md#static-sites).62+An agent whose grant carries a `sites` tag with a ttl uploads on a clock: each file it stores is kept for the longest ttl among the grant's site entries, then removed by maintenance. A person who claims the same file keeps it, and the agent's claim alone is released. An agent whose grant says `encrypted` may store only encrypted blobs and manifests. See [Static sites](agent-access.md#static-sites).6363 6464 Clients can check an upload with [BUD-06](https://github.com/hzrd149/blossom/blob/master/buds/06.md) `HEAD /upload`, including empty files with `X-Content-Length: 0`. The result is advisory; the upload itself checks the current limits. File descriptors include the optional Nostr metadata field defined by [BUD-08](https://github.com/hzrd149/blossom/blob/master/buds/08.md). A [BUD-13](https://github.com/hzrd149/blossom/pull/100) remote upload may name up to eight `url` sources.6565 @@ -6,7 +6,7 @@ Open a repository and choose **Issues** or **Pull requests**. Search titles and
66 77 Create an issue with a title, description and optional comma-separated labels. A pull request also needs the full Git commit ID and an HTTP or HTTPS clone URL. The optional merge base identifies the common ancestor with the target branch.88 9-Replies can address the original post or an individual comment. The author, repository owner and current maintainers can change status. Maintainers are the keys in the announcement's `maintainers` tag and any [agent](agents.md) whose active grant holds `maintain` on the repository; the repository panel lists them and marks agents with the grant's name. Issues support open, resolved, closed and draft states; pull requests use merged in place of resolved. Marking a pull request merged records its status; merge and push the Git changes with your Git client.9+Replies can address the original post or an individual comment. The author, repository owner and current maintainers can change status. Maintainers are the keys in the announcement's `maintainers` tag and any [agent](agent-access.md) whose active grant holds `maintain` on the repository; the repository panel lists them and marks agents with the grant's name. Issues support open, resolved, closed and draft states; pull requests use merged in place of resolved. Marking a pull request merged records its status; merge and push the Git changes with your Git client.1010 1111 Pull request diffs use commits available in the hosted repository. Missing commits produce an availability message. Diff previews are limited to 512 KiB, with further display limits for long output. Clone the repository to review the complete change.1212 @@ -14,7 +14,7 @@ Events follow [NIP-34](https://github.com/nostr-protocol/nips/blob/master/34.md)
1414 1515 ## Proposals from agents1616 17-An issue, pull request, patch or comment published by an [agent](agents.md) whose grant holds `propose` on the repository is a proposal. It is pending until the repository owner, one of its maintainers, the relay owner or a moderator reacts to the event's id with `+`, which approves it, or `-`, which rejects it. Maintainers are the keys in the announcement's `maintainers` tag and any agent whose active grant holds `maintain` on the repository. When there is more than one reaction from them, the newest counts. Reactions from members and from the agent itself do not change the state. A resubmitted event is a new id, so it waits for its own approval. Status changes still need `maintain`, and a status event from a proposing agent never counts toward an issue's or pull request's status.17+An issue, pull request, patch or comment published by an [agent](agent-access.md) whose grant holds `propose` on the repository is a proposal. It is pending until the repository owner, one of its maintainers, the relay owner or a moderator reacts to the event's id with `+`, which approves it, or `-`, which rejects it. Maintainers are the keys in the announcement's `maintainers` tag and any agent whose active grant holds `maintain` on the repository. When there is more than one reaction from them, the newest counts. Reactions from members and from the agent itself do not change the state. A resubmitted event is a new id, so it waits for its own approval. Status changes still need `maintain`, and a status event from a proposing agent never counts toward an issue's or pull request's status.1818 1919 A pending or rejected proposal is visible only to those deciders and the agent that published it. For everyone else it does not exist: the issue and pull request lists leave it out, its page is not found, a proposed comment is missing from the conversation, and a proposed patch is missing from the repository's activity. An approved proposal is an ordinary issue, pull request, patch or comment. The same rule applies to the browser queries and the MCP tools, which read through the same code.2020 @@ -92,7 +92,7 @@ Management tools, which follow the relay's roles:
9292 | `resume_all_agents` | Resume every paused agent. |9393 | `approve_join` | Approve an access request by `pubkey`: the key becomes a member and the request is marked approved. |9494 | `deny_join` | Deny an access request by `pubkey`. The key stays outside the relay and may ask again. |95-| `add_callback` | Register an https URL that receives each new event matching a filter, signed with a secret returned once. See [Callbacks](agents.md#callbacks). |95+| `add_callback` | Register an https URL that receives each new event matching a filter, signed with a secret returned once. See [Callbacks](agent-access.md#callbacks). |9696 | `remove_callback` | Delete a callback by id. |9797 | `pause_callback` | Stop deliveries to a callback until it is resumed. |9898 | `resume_callback` | Resume a paused callback and clear its failure count. |@@ -158,7 +158,7 @@ The operator reviews the request in Approvals. A `+` reaction is not an approval
158158 159159 ### Static sites160160 161-`publish_site` builds a [NIP-5A](https://github.com/nostr-protocol/nips/blob/master/5A.md) manifest. Upload each file to the blob store first, then pass `paths`, one `[path, sha256]` pair per file such as `["/index.html", "<sha256>"]`, and optionally `label` and `expiration`. Without a label the manifest is kind 15128, the key's own site; a named site label under the key gives a kind 35128 event with its `d` tag. Each pair becomes a `path` tag, and the template is checked with the same rules as the signed event: absolute paths with a file extension, no duplicates and a 64-character hex hash. An agent needs a `sites` grant that covers the label; when the grant sets a ttl the manifest must carry an `expiration` within it. See [Static sites](agents.md#static-sites).161+`publish_site` builds a [NIP-5A](https://github.com/nostr-protocol/nips/blob/master/5A.md) manifest. Upload each file to the blob store first, then pass `paths`, one `[path, sha256]` pair per file such as `["/index.html", "<sha256>"]`, and optionally `label` and `expiration`. Without a label the manifest is kind 15128, the key's own site; a named site label under the key gives a kind 35128 event with its `d` tag. Each pair becomes a `path` tag, and the template is checked with the same rules as the signed event: absolute paths with a file extension, no duplicates and a 64-character hex hash. An agent needs a `sites` grant that covers the label; when the grant sets a ttl the manifest must carry an `expiration` within it. See [Static sites](agent-access.md#static-sites).162162 163163 ### Room attachments164164 @@ -178,7 +178,7 @@ Room uploads use `/media/<hash>.<extension>` URLs compatible with Buzz. Reads fo
178178 179179 A key the request asked answers with `accept_job`, `job_progress`, `job_result` or `job_error`. Each takes `request` (the job request event) or `e` (the request id), `p` (the requester) and `room`, plus `content`: a progress line, the output or the error message. `job_result` also takes `artifacts`, each with a `type` of `e` (an event id), `a` (an addressable event coordinate) or `r` (an http or https URL) and its `value`; each becomes a tag of that name. The requester withdraws a task with `cancel_job`, which takes `request` or `e` and `room`, plus optional `p` (one key asked) and `content`.180180 181-The relay accepts an answer only from a key the request asked, and only for a request it holds; a cancel only from the requester. `list_jobs` and `read_job` follow the work. See [Long tasks](agents.md#long-tasks).181+The relay accepts an answer only from a key the request asked, and only for a request it holds; a cancel only from the requester. `list_jobs` and `read_job` follow the work. See [Long tasks](agent-access.md#long-tasks).182182 183183 ## Example184184 @@ -16,11 +16,11 @@ Four tools cover the wiki. `tiny.list_wiki` lists pages with their shown version
1616 1717 ## Approvals1818 19-Three tools cover requests for a decision. `tiny.list_approvals` lists the requests addressed to the signed-in person with each one's asker, subject, expiry, state and answer, plus counts of open, answered and expired requests; `state` narrows the list to `open`, `answered`, `expired` or `all`. `tiny.read_approval` returns one request by event id with every reaction and reply from the people asked. `tiny.open_approvals` opens the Approvals page, focused on one request when `id` is given. Answering stays a manual step: the person approves, denies or replies with their own signer. To make a request, publish an event as described in [Asking a person](agents.md#asking-a-person).19+Three tools cover requests for a decision. `tiny.list_approvals` lists the requests addressed to the signed-in person with each one's asker, subject, expiry, state and answer, plus counts of open, answered and expired requests; `state` narrows the list to `open`, `answered`, `expired` or `all`. `tiny.read_approval` returns one request by event id with every reaction and reply from the people asked. `tiny.open_approvals` opens the Approvals page, focused on one request when `id` is given. Answering stays a manual step: the person approves, denies or replies with their own signer. To make a request, publish an event as described in [Asking a person](agent-access.md#asking-a-person).2020 2121 ## Long tasks2222 23-Two tools follow [long tasks](agents.md#long-tasks). `tiny.list_jobs` lists the job requests visible to the signed-in account with each one's room, requester, assignees, subject, state, status, newest progress, result with its artifacts, error and cancel time; `state` narrows the list to `open`, `done`, `failed`, `cancelled` or `all`, and `mine` lists only your own requests. `tiny.read_job` returns one request by event id with its answers, oldest first. Requesting, answering and cancelling stay signed actions through the relay's [MCP](mcp.md#long-tasks) tools or a relay connection.23+Two tools follow [long tasks](agent-access.md#long-tasks). `tiny.list_jobs` lists the job requests visible to the signed-in account with each one's room, requester, assignees, subject, state, status, newest progress, result with its artifacts, error and cancel time; `state` narrows the list to `open`, `done`, `failed`, `cancelled` or `all`, and `mine` lists only your own requests. `tiny.read_job` returns one request by event id with its answers, oldest first. Requesting, answering and cancelling stay signed actions through the relay's [MCP](mcp.md#long-tasks) tools or a relay connection.2424 2525 Choose **Sign in** in the footer, or follow a sign-in link on a protected page, and connect your Nostr signer. Reading protected information uses your browser session. Management actions request a signature and follow your account permissions. The Account page holds the signed-in key's profile, relay lists and Chat presence preference; use the page directly because there is no browser-agent mutation tool for those personal settings. A queued backup or job has not finished until its status says so.2626 @@ -30,7 +30,7 @@ Read the current policy or connection list before changing settings. Job interva
3030 3131 ## Agents3232 33-The owner and moderators can also manage [agent grants](agents.md) through the browser agent:33+The owner and moderators can also manage [agent grants](agent-access.md) through the browser agent:3434 3535 | Tool | What it does |3636 | --- | --- |@@ -54,7 +54,7 @@ The owner and moderators review [access requests](membership.md#access-requests)
5454 5555 Each decision requests a signature and is recorded in the audit log.5656 57-Four more tools manage [callbacks](agents.md#callbacks), the URLs an agent registers to be woken by new events:57+Four more tools manage [callbacks](agent-access.md#callbacks), the URLs an agent registers to be woken by new events:5858 5959 | Tool | What it does |6060 | --- | --- |@@ -36,7 +36,7 @@ Accepting a request does not change the article by itself. The destination autho
3636 3737 ## Proposals from agents3838 39-A version published by an [agent](agents.md) whose grant says `wiki: propose` is a proposal. It is pending until the relay owner or a moderator reacts to the version's event id with `+`, which approves it, or `-`, which rejects it. When there is more than one reaction from them, the newest counts. Reactions from members and from the agent do not change the state. Each version is a new event id, so an agent's edit of an approved page is a new proposal that waits for its own approval, and the approved revision stays in view until the edit is approved.39+A version published by an [agent](agent-access.md) whose grant says `wiki: propose` is a proposal. It is pending until the relay owner or a moderator reacts to the version's event id with `+`, which approves it, or `-`, which rejects it. When there is more than one reaction from them, the newest counts. Reactions from members and from the agent do not change the state. Each version is a new event id, so an agent's edit of an approved page is a new proposal that waits for its own approval, and the approved revision stays in view until the edit is approved.4040 4141 A pending or rejected proposal is visible only to the owner, moderators and the agent that published it. Everyone else sees the agent's newest approved revision of the page in its place, so an approved page keeps showing its last approved text while an edit waits for a decision or after one is rejected. The page list, the versions and the history follow the same rule: a revision that is not approved is left out for readers, and a page with no approved revision by any author is not found. An approved proposal is an ordinary version. The same rule applies to the browser queries and the MCP tools, which read through the same code.4242 @@ -147,7 +147,7 @@ func (t *Tenant) llmsHTTP(w http.ResponseWriter, r *http.Request) {
147147 "## Documentation",148148 "",149149 "- MCP: https://github.com/FelineStateMachine/tinyrelay/blob/main/docs/mcp.md",150- "- Agents, grant requests, decisions, tasks and runner setup: https://github.com/FelineStateMachine/tinyrelay/blob/main/docs/agents.md",150+ "- Agents, grant requests, decisions, tasks and runner setup: https://github.com/FelineStateMachine/tinyrelay/blob/main/docs/agent-access.md",151151 "- Chat and direct-message interoperability: https://github.com/FelineStateMachine/tinyrelay/blob/main/docs/chat.md",152152 "- Social notes, articles and interactions: https://github.com/FelineStateMachine/tinyrelay/blob/main/docs/social.md",153153 "- Files, access, encryption and uploads: https://github.com/FelineStateMachine/tinyrelay/blob/main/docs/files-and-private-repositories.md",