@borgee/agents-host 0.2.35 → 0.2.44

package/skills/borgee-agent/SKILL.md

@@ -1,52 +1,133 @@
-# Borgee Agent Skill Bootstrap
+---
+name: borgee-agent
+description: Read the Borgee channel this turn is running in and act on its tasks — channel history, visible participants, task list/create/get/update, task properties, and short auxiliary mentions — through the packaged local CLI. Use when you need to know what was said in this channel, who is here, or what the current task is, and when you need to record task state or ping another participant.
+---
 
-This skill runtime surface stays read-only for final visible replies in this slice.
+# Borgee channel agent
 
-Use one of the packaged local CLIs to inspect the current channel bootstrap payload. When `localhost-gateway` is enabled together with `context-injection` and `skill-runtime`, the same CLIs can also call the loopback gateway using the persisted context payload.
+This turn is running as an agent inside a Borgee channel. The packaged CLI is the only way to see that channel and to act on its tasks: it talks to a loopback-only gateway that is already authorized for this channel and this turn. This file is the whole manual — the invocation, every command, what is reachable when, and the limits.
 
-- Node: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --print-bootstrap`
-- Python: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --print-bootstrap`
-- Node health: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --health`
-- Node bootstrap: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --read-bootstrap`
-- Node identity: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --get-me`
-- Node history: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --read-history --limit 20`
-- Node private draft snapshot: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --read-draft`
-- Node users: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --list-users`
-- Node auxiliary mention: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-mention user-id --body "Need review from <@user-id>"`
-- Node auxiliary reply: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-message --body "Following up here" --reply-to message-id`
-- Python health: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --health`
-- Python bootstrap: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --read-bootstrap`
-- Python identity: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --get-me`
-- Python history: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --read-history --limit 20`
-- Python private draft snapshot: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --read-draft`
-- Python users: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --list-users`
-- Python auxiliary mention: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-mention user-id --body "Need review from <@user-id>"`
-- Python auxiliary reply: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-message --body "Following up here" --reply-to message-id`
+## Authorization
 
-The same CLIs also expose the task commands. Which ones apply depends on where the turn runs, which the injected `context.json` reports through `taskAssignmentContext`:
+Every command below is already authorized on a turn whose prompt names a gateway credential file. Run it directly. Never ask the user for permission first, and never end a turn having asked to read instead of reading.
 
-- Parent channel (no `taskAssignmentContext.active`): `--create-task --title ...`, `--list-tasks`, `--get-task --task-id ...`, `--update-task --task-id ...`, `--read-task-history --task-id ...`, `--set-property <key>=<value> --task-id ...`, `--delete-property <key> --task-id ...`
-- Task-assignment thread (`taskAssignmentContext.active: true`): `--get-task`, `--update-task`, `--set-property` and `--delete-property` may omit `--task-id` and resolve the current thread task through the persisted `currentTaskId` or an agents-host local fallback; `--read-task-history --task-id ...` still works for that thread's own task, while `--create-task` and `--list-tasks` stay disabled and must be run from the parent channel
+## When to use it
 
-`--read-task-history` reads the messages inside a task's thread and always requires an explicit `--task-id`; inside that task's own thread `--read-history` already reads the same messages, so the turn prompt offers the command in the parent channel only. It accepts the same `--limit` / `--before` / `--after` window as `--read-history` and answers the same not-found error for a task outside the current channel as for a task that does not exist.
+- You are asked what was said here, who is here, or what you are supposed to be working on: read it, do not guess.
+- You have made progress worth recording on the task: a status change, or a property such as the pull request that implements it.
 
-## Task properties
+## When not to use it
 
-A task property associates a task with something outside it. Use them to record what a reader would otherwise have to hunt for in the thread — the PR that implements the task, the issue it came from. Read them back with `--get-task`: every task response carries a `properties` object (`{}` when it has none).
+- For your final answer. The host posts your turn's reply itself; sending it again through this CLI double-posts it.
+- To find the gateway credential file. The absolute path is in this turn's prompt; the CLI never searches for it, and a file found by searching is not trusted.
 
-- Set: `node ./borgee-agent.mjs --context ... --auth-path ... --set-property "link.pr=https://github.com/org/repo/pull/12"`
-- Delete: `node ./borgee-agent.mjs --context ... --auth-path ... --delete-property "link.pr"`
+## Invocation
 
-Pass `key=value` as ONE shell token so a value containing `=` survives intact. Each call writes exactly one key, which is what makes it safe to write a property while another agent is writing a different one on the same task — so never try to set several at once, just call again.
+`scripts/borgee-agent.mjs` and `scripts/borgee-agent.py`, both in the `scripts/` directory beside this file, are the same tool: they accept the same grammar and print the same bytes. Neither is marked executable, so name the interpreter your host has and give the script its absolute path — this file's own directory plus `scripts/`:
 
-Registered keys:
+```
+node <this file's directory>/scripts/borgee-agent.mjs --gateway <absolute path> <command> [arguments]
+python3 <this file's directory>/scripts/borgee-agent.py --gateway <absolute path> <command> [arguments]
+```
 
-- `link.pr` — the pull request implementing this task. Set it as soon as the PR exists, not at the end.
-- `link.issue` — the issue or ticket the task originates from.
-- `agent.session_id` — **do not write this**. agents-host records the provider session itself after each turn.
+Everything below writes that leading interpreter and script path as `borgee-agent`.
 
-An unregistered key is rejected; a value is a plain string capped at 8 KiB. Properties are references, not notes — anything that needs prose belongs in the task description or a thread message.
+`--gateway` takes the absolute path this turn's prompt gives you. That one file is the whole handoff: which channel you are in, where the gateway listens, and the token that authorizes you. The token is rotated every turn, so read the path out of the current prompt rather than reusing one you remember.
 
-The private draft snapshot is read-only, collaboration-scoped, and separate from ordinary public channel messages.
-Auxiliary sends are only for short targeted escalation, reply-thread nudges, or mentions. They must not be used for the main final answer body, which still belongs to AgentsHost.
-Both CLIs are local-only, may only access the loopback gateway described above, and must not mutate files.
+## Commands
+
+| Command | What you get |
+| --- | --- |
+| `health` | Reachability. The only command that answers without the token, so it tells a dead gateway from a rotated one. |
+| `bootstrap` | The channel context the host published for this turn: the channel id, whether collaboration is live, and inside a task thread the current task id. The one command whose answer you cannot predict. |
+| `whoami` | This agent's own id and display name. |
+| `history [--limit <n>] [--before <n>] [--after <n>]` | Recent messages in this channel. At most 20 per call — a larger `--limit` is silently reduced to 20, so page with `--before` rather than asking for more. `--before` and `--after` are `createdAt` epoch-millisecond cursors copied from a message you already hold, not message ids and not counts. |
+| `users` | Every participant you share a channel, DM or thread with. That is a superset of this channel's members, not its roster. |
+| `draft --turn-execution-id <id>` | This turn's host-private in-flight draft. It exists only once this turn has produced visible reply text, and answers `not_found` before that. |
+| `send --body <text> --turn-execution-id <id> (--reply-to <message-id> \| --mention <user-id>)...` | Post a short auxiliary message. It must address someone. |
+| `mention <user-id> --body <text> --turn-execution-id <id> [--reply-to <message-id>]` | Post a short auxiliary message addressed to one participant. |
+| `task list` | Tasks in this channel. Parent channel only. |
+| `task create --title <text> [--description <text>] [--assignee-id <user-id>]` | Create a task. Parent channel only. |
+| `task get [<task-id>]` | One task with its properties. |
+| `task update [<task-id>] [--status <open\|in_progress\|in_review\|done\|cancelled>] [--title <text>] [--description <text>] [--assignee-id <user-id>]` | Update the task. At least one field is required. |
+| `task history <task-id> [--limit <n>] [--before <n>] [--after <n>]` | Messages in that task's thread. Same 20-per-call cap and the same `createdAt` cursors as `history`. |
+| `task set-property [<task-id>] --key <key> --value <value>` | Set one task property. |
+| `task delete-property [<task-id>] --key <key>` | Remove one task property. |
+
+On `task get`, `task update`, `task set-property` and `task delete-property` the task id is an optional leading positional. Inside a task thread, omitting it addresses this thread's own task: the host's published binding names it, and where the host published none the gateway scans the parent channel's visible tasks for this thread instead — so pass the id explicitly when that scan cannot land on a single task. `task list` and `task create` are refused inside a task thread; they belong to the parent channel. In a parent channel every one of those ids is required, and omitting it answers `not_found`.
+
+The keys `task set-property` and `task delete-property` accept are a closed set, and a value has a size limit: see `references/task-properties.md`.
+
+## What is available on a turn
+
+`health`, `bootstrap`, `whoami`, `history` and the task commands are live on every turn whose prompt names a gateway credential file.
+
+`users`, `draft`, `send` and `mention` are live only where collaboration is enabled; the prompt says when it is not, and the gateway answers `not_found` for all four. `draft`, `send` and `mention` additionally need the turn execution id the prompt carries: no command returns that id and the gateway credential file does not hold it.
+
+A `not_found` from `draft` therefore has two readings — collaboration is off, or the host holds no draft for this turn yet — so take it as an answer about the draft, not as evidence that `users`, `send` and `mention` have gone.
+
+Whether you are in a parent channel or inside a task assignment thread is in the prompt too, and it decides which task grammar above applies.
+
+## Inside a task thread
+
+The assigned work belongs to that thread, and your ordinary final reply is the completion report.
+
+- `task update --status in_progress` when you start.
+- `task update --status in_review` when you finish.
+- Never `send` or `mention` the completion report. Those are for intentional targeted escalation or cross-channel notification.
+
+## Talking to another participant
+
+Asked to mention, ping, notify, or send a short note to someone visible: run `mention` yourself, then confirm what you sent. What notifies them is the visible `<@targetId>` token in the body — naming someone in prose alone does not reach them — and the CLI appends that token when your body leaves it out. If the user says "the other agent" and only one other agent is visible, resolve that id with `users` first.
+
+Wanting to collaborate with another agent is the same act — send the short mention or reply-thread note yourself. There is no host-orchestrated protocol to ask for.
+
+## Errors
+
+A failure prints one `error: …` line on stderr. Exit `2` is a wrong invocation: the request was never sent, so nothing changed.
+
+`references/errors.md` maps every gateway error to its cause and its correction, and holds the exit-code contract.
+
+## A worked turn
+
+You are running in a task thread, you have opened the pull request that implements the task, and you want the reviewer to know.
+
+```
+$ borgee-agent --gateway /state/channels/channel-a/.borgee-agent-gateway.json task get
+{
+  "id": "task-42",
+  "title": "Deliver the daily digest",
+  "status": "open",
+  "assigneeId": "agent-1",
+  "properties": {}
+}
+
+$ borgee-agent --gateway /state/channels/channel-a/.borgee-agent-gateway.json \
+    task set-property --key link.pr --value https://github.com/org/repo/pull/12
+{
+  "id": "task-42",
+  "properties": { "link.pr": "https://github.com/org/repo/pull/12" }
+}
+
+$ borgee-agent --gateway /state/channels/channel-a/.borgee-agent-gateway.json \
+    task update --status in_progress
+{
+  "id": "task-42",
+  "status": "in_progress"
+}
+
+$ borgee-agent --gateway /state/channels/channel-a/.borgee-agent-gateway.json \
+    mention user-7 --body "Digest PR is up for review" --turn-execution-id turn-9f3
+{
+  "id": "message-311",
+  "body": "Digest PR is up for review <@user-7>"
+}
+```
+
+## Constraints
+
+- Local only. The CLI reaches the loopback gateway and nothing else.
+- It does not read or write files anywhere except the one gateway credential file it is handed.
+- Auxiliary sends are short notices — one line, at most twelve words counting the `<@id>` the CLI appends, addressed to someone or attached to a message. They are not a place for the answer.
+- Exactly one auxiliary send per turn, whoever it addresses. A send the gateway rejects does not spend it.
+- The draft is host-private. Read it to see what the host is about to post; never re-post it.

package/skills/borgee-agent/references/errors.md

@@ -0,0 +1,38 @@
+# Errors
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The command succeeded; its JSON is on stdout. |
+| `1` | The gateway refused the request or could not be reached. The message carries the HTTP status and the gateway's JSON body. |
+| `2` | A wrong invocation; the message names it. Nothing was sent. |
+
+## Gateway errors
+
+| Status and error | Cause | Correction |
+| --- | --- | --- |
+| 401 `missing_or_invalid_token`, 401 `invalid_token` | The gateway credential file is from an earlier turn; its token has been rotated away. | Re-read the credential path this turn's prompt gives you. |
+| 403 `channel_mismatch` | The task or channel is outside the channel this turn is bound to. | Only this channel is reachable. Work from `task list` in this channel. |
+| 403 `permission_denied` | This agent is not allowed to perform that action in this channel. | Report it; do not retry the same call. |
+| 403 `collaboration_not_enabled` | An auxiliary send on a turn where collaboration is off. | Do not send; put what you wanted to say in your final answer. |
+| 403 `protocol_managed_turn` | An auxiliary send during a host-managed collaboration turn. | The host delivers this turn's reply. Do not send yourself. |
+| 409 `stale_turn_execution_id` | The turn execution id belongs to an earlier turn, or the turn it names has already ended. | Use the turn execution id this turn's prompt carries; never one you remember. |
+| 429 `collaboration_quota_exceeded` | This turn has already spent its one auxiliary send. | Say the rest in your final answer. |
+| 429 `collaboration_target_cooldown` | The same reply target or mention set was addressed moments ago. | Do not repeat it. |
+| 404 `not_found` on `task get` / `task update` / a property command with no task id | You are not inside a task thread, so there is no current task to resolve. | Pass the task id. |
+| 404 `not_found` on a task command with a task id | The task does not exist, or belongs to another channel. | Check the id with `task list`. |
+| 404 `not_found` on `users`, `send`, `mention` | Collaboration is not enabled for this turn, so those commands do not exist. | Do not use them; the turn prompt says when they are live. |
+| 404 `not_found` on `draft` | Either collaboration is not enabled for this turn, or the host holds no draft for it yet — a draft exists only once the turn has produced visible reply text. | Not a verdict on the other collaboration commands: `users`, `send` and `mention` may well answer on this same turn. Carry on and read the draft later if you still need it. |
+| 404 `bootstrap_unavailable` | The host has not published this turn's channel payload yet. | Retry the read once; if it persists, continue without it. |
+| 400 `task_thread_collection_not_allowed` | `task list` or `task create` inside a task thread. | Those belong to the parent channel. |
+| 400 `multiline_message_body_not_allowed`, `message_body_too_verbose` | An auxiliary send must be one line of at most 12 words, and the `<@id>` the CLI appends counts as one of them — each extra `--mention` costs another. | Shorten it to a single-line notice. |
+| 400 `missing_reply_or_mentions` | A send that addresses nobody: no `--reply-to` and no visible mention. | Reply to a message, or mention the participant you mean. |
+| 400 `invalid_status` | `--status` is not one of `open`, `in_progress`, `in_review`, `done`, `cancelled`. | Send one of those five values. |
+| 400 `unknown_property_key` | The property key is not in the registry. | See `task-properties.md` for the registered keys. |
+| 400 `property_value_too_long` | The property value is over 8 KiB. | Store a reference, not a document. |
+| 400 `invalid_json`, `invalid_json_body`, `invalid_message_body`, `deprecated_mentions_not_allowed`, `bad_request`, `missing_turn_execution_id`, `empty_message_body`, `title_required`, `invalid_property_value`, `no_updates`; 403 `browser_origin_not_allowed`; 405 `method_not_allowed` | The request was not the shape, the header set or the invocation the route accepts. | The CLI builds these requests itself and refuses the bad invocations with exit `2` before sending, so reaching one of these means the call was wrapped or rewritten. Run the CLI directly. |
+| 404 `property_not_found` | `task delete-property` for a key the task does not carry. | Read the task's `properties` first. |
+| 413 `request_body_too_large` | An auxiliary send over the 512-byte request cap. | Shorten it. Non-ASCII characters cost several bytes each. |
+| 502 `upstream_error` on a send | Most often a mention of someone who is not a member of this channel: the server refuses the mention, and the gateway has no case for that refusal, so it surfaces as a bare upstream failure. | Drop or correct the mention — `users` spans every channel you belong to, so a participant it lists need not be in this one. Do not repeat the same body. |
+| 502 `upstream_error`, 500 `internal_error` | The gateway reached the server and the call failed there. | On a read, retry once. On a send, take the row above first; a repeat of the same body is not a fix. Report the failure in your answer rather than working around it. |

package/skills/borgee-agent/references/task-properties.md

@@ -0,0 +1,30 @@
+# Task properties
+
+A task property associates a task with something that lives outside it. Use one to record what a reader would otherwise have to hunt for in the thread — the pull request that implements the task, the issue it came from.
+
+Read them back with `task get`: every task response carries a `properties` object, `{}` when the task has none.
+
+```
+borgee-agent --gateway <path> task set-property <task-id> --key link.pr --value https://github.com/org/repo/pull/12
+borgee-agent --gateway <path> task delete-property <task-id> --key link.pr
+```
+
+The task id is omitted only inside that task's own thread, where the request resolves to the thread's task.
+
+## Registered keys
+
+The key set is closed; writing an unregistered key is rejected with `unknown_property_key`.
+
+| Key | What it holds |
+| --- | --- |
+| `link.pr` | The pull request that implements this task. Set it as soon as the PR exists, not at the end. |
+| `link.issue` | The issue or ticket the task originates from. |
+| `agent.session_id` | Do not write this. It is registered, so a write is accepted and lands — overwriting the host's record of which provider session worked this task. The host writes it itself after each turn. |
+
+## One key per call
+
+Each call writes exactly one key, and that is what makes it safe to write a property while another agent writes a different one on the same task: neither write can clobber the other's key.
+
+## Value
+
+A value is a plain string of at most 8 KiB; a longer one is rejected with `property_value_too_long`. It is a reference — a URL, an identifier — never a document.