@securecoms/agent-runtime 0.6.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
@@ -98,9 +158,12 @@ All configuration is via `SECURECOMS_*` environment variables (see
 | `SECURECOMS_DATA_DIR` | `~/.securecoms/agent-runtime` | Root directory for per-channel state |
 | `SECURECOMS_SKILLS_CONFIG` | `<dataDir>/skills.json` (or `--skills-config <path>`) | Path to `skills.json` — named endpoints, databases and flags |
 | `SECURECOMS_LOG_LEVEL` | `info` | One of `debug`, `info`, `warn`, `error` |
-| `SECURECOMS_TOOL_ALLOW` | `echo`, `web_search`, `fetch_url`, `http_request`, `sql_query`, `current_time`, `remember` | Comma-separated tool allow-list |
+| `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
 
@@ -205,9 +272,9 @@ the line — for example `requires: [endpoint:crm]` in
 
 ## Curated skills
 
-Seven built-in handlers ship with the runtime. All network built-ins refuse
+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.
@@ -220,7 +287,6 @@ to a host the operator did not name.
 | `web_search` | `query`, `count` (1–10, default 5) | `requires: [search_provider]` — needs a readable, non-empty `SECURECOMS_BRAVE_KEY_FILE` or `SECURECOMS_TAVILY_KEY_FILE`; Brave is used first when both are set. |
 | `http_request` | `name` (a configured `endpoint:<name>`), `path` (a query string is kept, a `#fragment` is dropped), `method` (GET/POST/PUT/DELETE), `body` | `requires: [any_endpoint]`. The model names an endpoint and a path, never a host; a path that would leave the endpoint's `baseUrl` origin is refused. |
 | `sql_query` | `name` (a configured `database:<name>`), `sql` (read-only `SELECT` only; a `;` or a write keyword anywhere in the text — inside a string literal or a comment included — is refused) | `requires: [any_database]`. SQLite or Postgres (`pg` required separately for Postgres). Results capped at 200 rows. |
-| `remember` | `fact` (≤300 chars) | Appends a dated line to the agent-wide `MEMORY.md`. |
 
 ## skills.json
 
@@ -283,12 +349,16 @@ file that already exists, so a customized `IDENTITY.md` is safe to keep
 across a re-init. `securecoms-agent persona show` prints the assembled system
 prompt exactly as a turn would see it, useful for checking an edit landed.
 
-Separately, `MEMORY.md` in the data dir is **agent-wide** (not per-persona,
-not per-channel): the `remember` skill appends a dated, one-line fact to it,
-and its contents are injected as a system message on every turn across every
-channel. It is capped at 8 kB; once it overflows, the **oldest** lines are
-dropped first, on the theory that the newest remembered facts are the ones
-still likely to be true.
+Legacy `MEMORY.md` files are not active configuration. Earlier runtime versions
+injected one agent-wide file into every channel, which crossed channel
+audiences. On startup the runtime moves each legacy file to a mode-0600
+`MEMORY.quarantined*.md` file in the same directory without overwriting an
+existing quarantine. The quarantined content is never injected or writable by
+a tool. The runtime inventories that quarantine plus inactive per-channel JSON
+stores for the owner-review surface. Review offers a passphrase-encrypted
+export and exact-source deletion; the 90-day clock begins only after the
+machine successfully reports the source. Explicit fact-to-channel assignment
+is a separate migration step and never guesses or fans out an audience.
 
 ## Managed configuration (from the web app)
 
@@ -307,7 +377,7 @@ managed directory at all behaves exactly as it did before. `skills.json` is
 looked up the same way, and re-read on every turn — a new endpoint or a skill
 switched off in the app takes effect on the next message, with no restart.
 
-Two deliberate exceptions:
+One deliberate exception:
 
 - **The environment still wins for the tool policy.** `SECURECOMS_TOOL_ALLOW`
   overrides the `allow` list in the `tools` block of `skills.json`, so an
@@ -316,35 +386,55 @@ Two deliberate exceptions:
   rather than replacing it: deny is a safety mechanism, so one entry in the
   service unit must not silently un-deny every tool the owner switched off in
   the app. Everything the environment denies stays denied either way.
-- **Writes go to the data dir**, not the managed directory — except `MEMORY.md`,
-  which is written wherever the agent already keeps it. An existing
-  `<dataDir>/MEMORY.md` is copied into the managed directory once, at startup,
-  so the owner can read and prune it in the app.
 
-The runtime also writes `local-config.json` into the managed directory when one
-exists: what this agent's OWN persona files say, and a single boolean for
-whether it has a readable search key. It is written at startup and rewritten
-whenever the search-key answer changes, so a key file dropped in (or taken
-away) mid-run is reported without a restart. It is a report the daemon passes
-upward — nothing in the runtime reads it back, and it holds no key value.
+Runtime-owned writes go to the data directory, not the managed directory.
+Legacy `MEMORY.md` is handled only by the quarantine behavior described above.
+
+The runtime also writes mode-0600 `local-config.json` into the managed directory
+when one exists: what this agent's OWN persona files say, booleans for readable
+search/managed-LLM keys, and a bounded inventory of inert legacy-memory files.
+It is written at startup and rewritten whenever those answers or the inventory
+change. The daemon revalidates current regular-file bytes, removes local paths,
+and only then reports it upward. Nothing in the runtime reads the report back,
+and it holds no key value.
+
+### Per-turn channel authorization
+
+Installation configuration is only a ceiling. On every inbound message the
+bridge supplies an immutable, server-derived authorization claim containing
+the sender audience, membership state, and channel tool grants. The runtime
+intersects that claim with installed skills, configuration requirements, and
+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.
+
+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.
 
-### A known limitation: the generated tool paragraph
+### The generated tool paragraph is an installation summary
 
 The `AGENTS.md` the app delivers ends in a generated paragraph naming the tools
-this agent has. The backend derives that list from the saved configuration plus
-the search-key boolean above; it does not see the running process. Three things
-can therefore make it diverge from what the runtime actually offers:
+configured for the installation, and explicitly tells the model that the
+per-turn offered list is authoritative. The backend derives the installation
+list from saved configuration plus the search-key boolean above; it does not
+see the running process or a turn's channel grants. These things can therefore
+make the installation summary differ from what the runtime offers:
 
 - a `SECURECOMS_TOOL_ALLOW` or `SECURECOMS_TOOL_DENY` set in the service unit,
   which the backend cannot see;
 - a customer skill folder whose `requires:` is narrower than the shipped one, so
   the runtime withholds a tool the backend counted;
-- a custom skill the backend knows nothing about, so it is offered but unnamed.
+- a custom skill the backend knows nothing about, so it can be eligible but
+  unnamed;
+- the current channel has no matching server-issued read grant.
 
-In any of those cases the paragraph is advisory rather than exact. The gate is
-still authoritative — a tool named in the paragraph but denied by policy is
-still refused at call time — so the risk is a wrong claim in conversation, not
-a wrong permission.
+The paragraph is therefore an advisory configuration summary, not an authority
+claim. Channel authorization and the local gate are both enforced at call
+time, so a configured but ungranted or denied tool is still refused.
 
 ## Provenance