aicodeman 1.44.0 → 1.45.0

package/skills/codeman/preamble.sh

@@ -18,9 +18,9 @@ fi
 AUTH=(); [ -n "${CODEMAN_PASSWORD:-}" ] && AUTH=(-u "${CODEMAN_USERNAME:-admin}:$CODEMAN_PASSWORD")
 # -k: harmless on http, required on https (self-signed cert).
 # X-Codeman-Parent-Session: tags workers YOU spawn as your children, so the web UI can
-# draw the lineage. Set once here and every present and future create call carries it;
-# it is ignored on every other endpoint. Purely cosmetic (see §5.1) and it can never
-# fail a spawn, so there is no case where you would want to leave it off.
+# draw the lineage. Set once here and every present and future create call carries it.
+# The agent inbox reads it too, as "who is calling" (§5.15); every other endpoint ignores
+# it. It can never fail a spawn, so there is no case where you would want to leave it off.
 # X-Codeman-Agent-Origin: marks a case directory a spawn CREATES as agent scratch, so the
 # user can find and delete it long after your workers are gone (§5.14). Same deal: set
 # once, cosmetic, never fails a spawn, and it labels only directories Codeman creates.

package/skills/codeman/reference/endpoints.md

@@ -35,8 +35,13 @@ only and can never drive a session.
 with a parse error and `.errorCode` is simply absent (see
 [symptom 6](#6-jq-parse-error-instead-of-an-errorcode)). Ten failed attempts from one
 IP then get a plain-text `429 Too Many Requests` with `Retry-After`, decaying over 15
-minutes (`AUTH_FAILURE_MAX` = 10, `AUTH_FAILURE_WINDOW_MS` = 15 min). **Never retry a
-failing credential in a loop**: you will lock the address out of the login path for
+minutes (`AUTH_FAILURE_MAX` = 10, `AUTH_FAILURE_WINDOW_MS` = 15 min). In multi-user
+mode the per-IP cap is 50 (`AUTH_IP_FAILURE_MAX`) and each account allows 10 failed
+guesses per IP; both are checked before the password, so past either even a correct
+password from that address gets the 429 (for the per-account one, only for that
+account). From the 10th failed guess on, an account's wrong guesses also get the 429
+from every address, but a correct password still logs in. **Never retry a failing
+credential in a loop**: you will lock the address out of the login path for
 everything, including the user's browser through a tunnel (tunneled traffic arrives as
 127.0.0.1, so one bucket covers it all).
 
@@ -608,6 +613,22 @@ Approving a permission dialog on your own is exactly the laundering this skill f
 can access, which includes the user's own working sessions. An approval belonging to one
 of those is something you **report**, never something you answer.
 
+### Agent inbox: hand a worker text without typing into its pane
+
+Stored, not typed: the receiver reads it when it asks. Semantics, CLI form and the
+receiver loop: `verbs.md` §5.15.
+
+| Task | Call |
+|------|------|
+| post to a session's inbox | `POST /api/v1/sessions/:id/inbox` body `{"text":"…"}` → `.data.message.{id,from}`; 409 = inbox full, nothing stored |
+| read (yours marks seen, anyone else's is a peek) | `GET /api/v1/sessions/:id/inbox` → `.data.{receiver,pending,unseen,messages[]}` |
+| block until something unseen arrives | `GET /api/v1/sessions/:id/inbox?wait=60000` → `.data.wait.{posted,timedOut,ended}` |
+| remove what you handled (receiver only, idempotent) | `POST /api/v1/sessions/:id/inbox/ack` body `{"ids":["…"]}`; 403 from anyone else |
+| counts per session, never text | `GET /api/v1/agent-inbox/summary` → `.data.sessions[id].{pending,unseen,oldestUnseenAt,parked}` |
+
+`from` and "who is the receiver" both come from the `X-Codeman-Parent-Session` header the
+preamble's `CURL` sends, never from the body.
+
 ### The wait primitives
 
 Three bounded long-polls. Shared semantics:
@@ -801,7 +822,7 @@ response echoes.
 | sessions, per user | half the global cap (25 by default) in multi-user mode | the same 409, with a different message |
 | SSE clients, process-wide | 100 (`MAX_SSE_CLIENTS`) | plain-text `503 Too many SSE connections`; shared with every browser tab |
 | active bash tools tracked | 20 per session | oldest entries drop off `active-tools` |
-| auth failures per IP | 10, decaying over 15 min | plain-text 429 with `Retry-After`; locks out the login path, so never loop a bad credential |
+| auth failures per IP | 10, decaying over 15 min (multi-user: 50 per IP, plus 10 per account per IP) | plain-text 429 with `Retry-After`; locks out the login path, so never loop a bad credential |
 
 Case creation is **uncapped**, which is the one place restraint has to come from you:
 every `quick-start` with a new `caseName` creates a real directory on the user's disk.

package/skills/codeman/reference/verbs.md

@@ -764,3 +764,50 @@ Confirm cleanup with `GET /api/v1/sessions`, never with `/api/v1/sessions/unifie
 (that one folds in transcript history from the whole machine and will keep showing
 your worker forever).
 
+### 5.15 Agent inbox
+
+Every session has an inbox. A message posted there is stored, not typed: the receiver's
+pane is untouched, no turn starts, and the text may span several lines. The receiver
+reads when it is ready. Use it for results a worker hands back, for a follow-up task a
+busy worker should pick up after its current one, and for anything longer than one
+composer line. Use `send` when you want a turn to start now.
+
+```bash
+codeman agent post "$WORKER" "$(cat task.md)"   # ONE quoted argument; prints pending/unseen
+codeman agent inbox --wait --timeout 300000     # your own inbox; blocks while nothing is new
+codeman agent ack <id> [<id>…]                  # remove what you handled, by the full id inbox printed
+codeman agent inbox "$WORKER"                   # peek at someone else's: marks nothing
+codeman agent ls                                # INBOX column: pending (new), parked
+```
+
+The same over HTTP: `POST /api/v1/sessions/:id/inbox {"text":…}`, `GET
+/api/v1/sessions/:id/inbox?wait=<ms>`, `POST /api/v1/sessions/:id/inbox/ack {"ids":[…]}`,
+`GET /api/v1/agent-inbox/summary`. The preamble's `CURL` already sends
+`X-Codeman-Parent-Session`, which is how the server knows who you are.
+
+Rules that matter:
+
+- **Reading removes nothing.** Every read returns every pending message until you ack
+  it, so a crash between reading and doing loses nothing. Ack once the work is done,
+  not when you have read it: a sender looking at `ls` sees unacked mail as not done.
+- **Only the receiver's own read counts.** Your read of your own inbox marks messages
+  seen (`seen: true` on the next read); reading another session's inbox is a peek and
+  changes nothing for it. Only the receiver can ack (403 otherwise).
+- **`--wait` waits for something new.** It returns at once when there is unseen mail
+  and otherwise blocks until a post arrives; seen but unacked messages come back with it
+  and do not end the wait. Timeout is exit 2, and so is a wait the server cut short
+  (a restart): loop again. Exit 3 means the session list no longer has the session.
+  `--wait` on someone else's inbox returns at once while they have unseen mail (only
+  their read clears it); check `ls` instead.
+- **The sender is resolved, not claimed.** `from` is the session the header resolves to,
+  or `null` (the user). In single-user mode that is a hint, since every local process
+  holds the same credentials. In multi-user mode it is checked against the owner;
+  an admin can still act as any session of the receiver's owner.
+- **Full means refused.** 200 messages or 512 KiB per inbox, 16 KiB per message. A full
+  inbox answers 409 and stores nothing; the oldest is never dropped. Messages expire 12
+  hours after they were posted.
+- **Nobody is woken.** An idle receiver does not look at its inbox by itself, and the
+  server never types into its pane. When `ls` shows a worker idle with unread mail and
+  not parked, `send` it one line ("read your inbox: `codeman agent inbox`").
+- **Lifetime.** An inbox goes with its session on delete. A server restart empties all
+  inboxes unless the user turned on *Keep agent inbox across restarts* in Settings.