@securecoms/agent-runtime 0.7.0 → 0.9.0

package/README.md

@@ -79,6 +79,66 @@ process (from `--identity`/`SECURECOMS_IDENTITY`) must match both the
 identity recorded in the connection file and the identity the local daemon
 reports on its health endpoint. Any mismatch refuses the connection outright.
 
+## Execution boundaries
+
+Every model request and response is limited to 128 KiB and the complete
+provider exchange has a 180-second deadline. The full model/tool turn has a
+five-minute deadline. The same cancellation signal reaches model fetches,
+network skills, SQLite subprocesses, and Postgres sockets when a turn times
+out, its WebSocket disconnects, or the runtime stops.
+
+Turns are serialized per channel because channel memory is mutable. One agent
+may run at most four turns across different channels; additional work is
+refused with a retryable busy response instead of entering an unbounded queue.
+Network skills retain their independent 10-second and 2-MiB fetch boundaries,
+and tool results retain the common 20,000-byte response boundary.
+
+### Retry idempotency for external side effects
+
+The reachable execution inventory is intentionally narrow. `echo`,
+`current_time`, `web_search`, `fetch_url`, `sql_query`, and GET-only
+`http_request` calls use read grants. The only currently supported
+state-changing surface is a configured `http_request` using POST, PUT, or
+DELETE. Custom scripts and every other current built-in fail closed if they
+are presented with a side-effect grant.
+
+A state-changing HTTP call is offered and executed only when an active
+per-turn grant binds all of the following: the tool, a canonical SHA-256 of
+the exact arguments, a confirmation id, an idempotency key, and an expiry.
+The runtime checks this binding both before execution and again inside the
+skill invoker. A read grant never authorizes a state-changing method, and a
+side-effect grant never authorizes GET.
+
+Before the external request starts, a per-agent mode-0600 SQLite ledger
+durably binds the idempotency key to the confirmed operation. A completed
+retry returns `already_applied` without repeating the request. A process loss,
+cancelled request, transport failure, or crash between the external response
+and ledger completion leaves an ambiguous claim; retries then fail closed and
+require reconciliation. The ledger stores only identifiers, hashes, states,
+and timestamps—not request bodies, responses, or message content—and refuses
+new operations after 10,000 claims rather than growing without bound.
+
+After a crash or host replacement, list unresolved effects without exposing
+request or response content:
+
+```
+securecoms-agent side-effects list --identity <identity_id> [--data-dir <dir>]
+```
+
+Verify the outcome against the external system using its own operation or
+idempotency record, then bind the decision to every identifier printed by the
+list command:
+
+```
+securecoms-agent side-effects resolve --identity <identity_id> [--data-dir <dir>] \
+  --idempotency-key <key> --operation-sha256 <digest> \
+  --confirmation-id <id> --outcome completed
+```
+
+Use `--outcome not_applied` only after independently proving the effect did not
+occur; that removes the pre-effect claim and permits one exact retry. `completed`
+keeps the durable suppression and all later retries return `already_applied`.
+
 ## Configuration
 
 All configuration is via `SECURECOMS_*` environment variables (see
@@ -101,6 +161,9 @@ All configuration is via `SECURECOMS_*` environment variables (see
 | `SECURECOMS_TOOL_ALLOW` | `echo`, `web_search`, `fetch_url`, `http_request`, `sql_query`, `current_time` | Comma-separated tool allow-list |
 | `SECURECOMS_TOOL_DENY` | unset | Comma-separated tool deny-list (wins over allow) |
 | `SECURECOMS_TOOL_DEFAULT` | `deny` | Fallback policy for a tool matched by neither list |
+| `SECURECOMS_LLM_MAX_OUTPUT_TOKENS` | `8192` | Output-token cap sent on every model request (`max_tokens`; `max_completion_tokens` for `api.openai.com`). Whole number ≥ 1 |
+| `SECURECOMS_LLM_DAILY_CALL_LIMIT` | `2000` | Model requests per UTC day. When spent, each channel gets one "daily usage limit" reply and the provider is not called again until 00:00 UTC. `0` = unlimited |
+| `SECURECOMS_LLM_DAILY_TOKEN_LIMIT` | `5000000` | Provider-reported tokens per UTC day, same behaviour as the call limit. `0` = unlimited. Counters persist in `<dataDir>/llm-budget-<identity>.json` (counts only, no content) |
 
 ### The LLM source: explicit vs managed
 
@@ -184,6 +247,10 @@ required. `handler` is one of:
 A manifest or `SKILL.md` with any other handler shape, or a missing required
 field, is skipped with a warning, and a skill invocation that throws is
 turned into a `tool_failed` tool message rather than dropping the turn.
+Every built-in and script result crosses the same 20,000-byte response
+boundary. Oversized plain text ends with `…[truncated]`; oversized JSON and
+errors remain valid JSON with `truncated: true` instead of being sliced into
+an invalid envelope.
 
 ### Gating a skill on configuration
 
@@ -207,7 +274,7 @@ the line — for example `requires: [endpoint:crm]` in
 
 Six built-in handlers ship with the runtime. All network built-ins refuse
 `localhost` and any private, loopback or link-local resolved address, and
-every tool result is capped at 20 kB (truncated, not an error). A redirect to a
+every tool result is capped at 20,000 UTF-8 bytes (truncated, not an error). A redirect to a
 different origin is followed without the caller's headers and without the
 request body, so a configured header value or a search key can never be handed
 to a host the operator did not name.
@@ -341,12 +408,12 @@ the local allow/deny gate before showing tools to the model, then repeats the
 same channel-grant check immediately before execution. Missing or malformed
 claims, inactive/unknown membership, and absent grants all fail closed.
 
-This staged release issues no channel grants yet, so no generic tool is offered
-even when it is installed and enabled. Read grants can enable only the curated
-read-only tools; `http_request` is additionally limited to GET at execution.
-Side-effect grant fields are reserved in the protocol, but side-effect calls
-remain denied until exact-operation confirmation, expiry, and idempotency are
-implemented end to end.
+The live bridge currently issues no channel grants, so no generic tool is
+offered even when it is installed and enabled. Read grants can enable only the
+curated read-only surfaces. The runtime now enforces the exact-operation,
+confirmation, expiry, and durable replay contract described above for future
+side-effect grants; that path remains dormant until an upstream confirmation
+producer deliberately issues such a grant.
 
 ### The generated tool paragraph is an installation summary