Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 32 additions & 7 deletions .github/ci/check_review.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,23 @@ def summary_state(body):
return state


def clean_summary(state):
def completed_nonblocking_security(body, head):
"""Null security findings need the adjacent explicit nonblocking receipt."""
match = re.match(re.escape(SUMMARY)
+ r"\n<!-- codex-review-state:v1 \{[^\r\n]*\} -->"
+ r"\n<!-- codex-security-review:v1 (\{[^\r\n]*\}) -->", body)
if not match:
return False
try:
security = json.loads(match[1])
except ValueError:
return False
return (isinstance(security, dict) and security.get("headSha") == head
and security.get("status") == "completed"
and security.get("mergeGateEnabled") is False)


def clean_summary(state, body):
head = state["code_review"]["commit_sha"]
for name in ("code_review", "security_review"):
review = state.get(name)
Expand All @@ -45,10 +61,19 @@ def clean_summary(state):
("status", "commit_sha", "has_any_findings", "has_unresolved_findings"))):
continue
if (not isinstance(review, dict) or review.get("commit_sha") != head
or review.get("status") != "completed"
or review.get("has_any_findings") is not False
or review.get("has_unresolved_findings") is not False):
or review.get("status") != "completed"):
return False
if (review.get("has_any_findings") is False
and review.get("has_unresolved_findings") is False):
continue
# Codex omits security verdicts when its merge gate is disabled. This
# completion cannot weaken the explicit no-findings code review above.
if (name == "security_review"
and review.get("has_any_findings", False) is None
and review.get("has_unresolved_findings", False) is None
and completed_nonblocking_security(body, head)):
continue
return False
return True


Expand All @@ -73,16 +98,16 @@ def pages(path, key=None):


def eligible(pr, repo, head, base):
# Stacked PRs use their own base; policy still comes from trusted main.
return (pr["state"] == "open" and not pr["draft"]
and pr["base"]["ref"] == "main"
and (pr["head"].get("repo") or {}).get("full_name") == repo
and pr["head"]["sha"] == head and pr["base"]["sha"] == base)


def clean_body(body):
if body.startswith(SUMMARY):
state = summary_state(body)
return state is not None and clean_summary(state)
return state is not None and clean_summary(state, body)
# Current Codex receipts prepend this exact marker; older comments do not.
body = body.removeprefix("<!-- codex-review-receipt:v1 -->").lstrip()
return body.startswith(CLEAN)
Expand All @@ -99,7 +124,7 @@ def current_verdict(head, comments, reviews, resolve_commit):
if state is not None and state["code_review"]["commit_sha"] != head:
continue
verdicts.append((item["updated_at"], item["id"], item,
state is not None and clean_summary(state)))
state is not None and clean_summary(state, item["body"])))
continue
match = re.search(r"\*\*Reviewed commit:\*\* `([0-9a-f]{10,40})`", item["body"])
if not match or not head.startswith(match[1]):
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.20.2
1.20.7
10 changes: 5 additions & 5 deletions docs/api/AdminAPI.md
Original file line number Diff line number Diff line change
Expand Up @@ -562,7 +562,7 @@ Agent account response fields:
| `accounts[].bedrock_usage.currency` | string | | Always `USD` (the catalog rates' currency). |
| `accounts[].bedrock_usage.requests` | number | | Allowed Bedrock invocations forwarded this month. |
| `accounts[].bedrock_usage.metered_requests` | number | | Invocations whose response carried a parseable usage record. A gap below `requests` means AWS errors or unparsed responses, that is, possible undercounting. A model outside the price table is still metered; its tokens count but it adds nothing to `month_to_date`. |
| `accounts[].bedrock_usage.input_tokens`, `.output_tokens`, `.cache_read_tokens`, `.cache_write_tokens` | number | | Month-to-date token totals as AWS reported them per response. The cached-token counters mirror the Converse usage shape but stay zero: Bedrock prompt caching covers only model families outside this catalog. |
| `accounts[].bedrock_usage.input_tokens`, `.output_tokens`, `.cache_read_tokens`, `.cache_write_tokens` | number | | Month-to-date token totals as AWS reported them per response. The cached-token counters mirror the Converse usage shape, including cache reads and writes reported for supported models. |

Codex OAuth login response:

Expand Down Expand Up @@ -724,7 +724,7 @@ Send message request:
```json
{
"agent_runtime": "codex",
"model": "gpt-6.1-sol",
"model": "gpt-6.2-sol",
"effort": "high",
"message": "Implement this change and report the result."
}
Expand All @@ -736,7 +736,7 @@ Send message request fields:
| --- | --- | --- | --- |
| `message` | Yes | string | Message for the agent runtime. Must be 1 to 50,000 characters. The host handles idle and running threads; callers use the same operation for both. |
| `agent_runtime` | New thread or configuration change | enum | Runtime for the thread: `codex`, `codex-2`, `codex-3`, `claude_code`, `grok`, `grok-2`, or `hermes`. Supply it together with `model` and `effort`. On an existing thread, a matching triple resumes or steers the current provider session; a different triple starts a fresh provider session only while the thread is idle. |
| `model` | New thread or configuration change | enum | Model for this session. Codex accepts `gpt-6.1-sol`, `gpt-6-luna`, or `gpt-6-astra`; Claude Code accepts `claude-opus-5-5`, `claude-fable-5-2`, or `claude-sonnet-5-5`; Grok accepts `grok-4.7`; Hermes accepts the Bedrock model ids `deepseek.v3.2`, `qwen.qwen3-coder-next`, `moonshotai.kimi-k2.5`, or `zai.glm-5`. Must be supplied together with `agent_runtime` and `effort`. A thread created under an earlier catalog keeps its recorded model and stays readable. It can continue by switching to an offered complete triple while idle; the superseded value cannot start a new provider session. |
| `model` | New thread or configuration change | enum | Model for this session. Codex accepts `gpt-6.2-sol`, `gpt-6.2-astra`, or `gpt-6-luna`; Claude Code accepts `claude-opus-5-5`, `claude-fable-5-2`, or `claude-sonnet-5-5`; Grok accepts `grok-4.7`; Hermes accepts the Bedrock model ids `deepseek.v3.2`, `qwen.qwen3-coder-next`, `us.moonshotai.kimi-k3.1`, `us.zai.glm-5.3`, or `minimax.minimax-m2.5`. Must be supplied together with `agent_runtime` and `effort`. List and get responses expose the current session configuration; retained conversation and usage records preserve their history. |
| `effort` | New thread or configuration change | enum | Effort for this session. Codex accepts `high`, `max`, `ultra`, `high-fast`, or `high-ultrafast`, except Luna accepts only `high` and `max`. The two speed presets request High reasoning with Fast or Ultrafast processing; the other presets send no speed override. Model, plan, and workspace availability are enforced by Codex; Kern surfaces provider errors without falling back. Claude Code accepts `high`, `max`, or `ultracode`; `ultracode` enables its xhigh effort plus dynamic workflow orchestration. Grok accepts `xhigh` or `high`. Hermes accepts `high` (its headless CLI exposes no effort control). Must be supplied together with `agent_runtime` and `model`. |

The path's `thread_id` must be at most 64 lowercase letters, digits, or
Expand Down Expand Up @@ -785,7 +785,7 @@ Send message response:
"thread": {
"thread_id": "thread-feature-1",
"agent_runtime": "codex",
"model": "gpt-6.1-sol",
"model": "gpt-6.2-sol",
"effort": "high",
"last_used_at": "2026-06-08T00:00:00Z",
"status": "running"
Expand Down Expand Up @@ -844,7 +844,7 @@ Thread list response:
{
"thread_id": "thread-feature-1",
"agent_runtime": "codex",
"model": "gpt-6.1-sol",
"model": "gpt-6.2-sol",
"effort": "high",
"last_used_at": "2026-06-08T00:05:00Z",
"status": "running"
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/admin-api-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,7 @@ the [Admin API reference](../api/AdminAPI.md).
| `GET /v1/agent-runtime/{status,account}`, runtime refresh, OAuth login/completion, Bedrock credential, and linked-account reset routes | Session + CSRF | Normal shared handler on both operator paths |
| `GET /v1/threads`, `/v1/threads/<id>`, thread message/stop/event routes, and `GET /v1/events` | Session + CSRF | Operator sees the host-wide thread namespace |
| `GET\|POST\|PUT\|DELETE /v1/workspace/{chat,web-apps,memory,schedules,reminders,getting-started}/...` | Session + CSRF | Proxy targets only the fixed Workspace backend and adds a fixed route prefix without forwarding credentials |
| `GET /v1/agent-files`, file read/content/download/upload routes, and `GET /v1/agent-processes` | Session + CSRF | Content, download, and upload use bounded streaming handlers after authentication |
| `GET /v1/agent-files`, file read/content/image-preview/download/upload routes, and `GET /v1/agent-processes` | Session + CSRF | Content, download, and upload use bounded streaming handlers after authentication |
| `GET\|PUT /v1/network/policy`, `GET /v1/network/events`, and GitHub credential/audit/pending-push routes under `/v1/network-tools/` | Session + CSRF | Method-specific mutation validation and root-helper boundaries still apply |
| Tool catalog/config/enablement/OAuth/approval routes and tool events under `/v1/tools` | Session + CSRF | Tool-specific authorization and approval state run after operator authentication |
| `GET /v1/host-diagnostics[/<id>]` and `POST /v1/host-runtime/reboot` | Session + CSRF | Diagnostic read or fixed privileged helper after authentication |
Expand Down
28 changes: 27 additions & 1 deletion docs/architecture/admin-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,9 @@ and show up in the same agent slice.
internal send path used after host restart; there is no retry endpoint.
`GET /v1/threads` and `GET /v1/threads/{id}` include an optional
`retry: {"attempt": 1, "at": "2026-10-05T12:05:00Z"}` on a thread while
an attempt is pending. `attempt` is 1–5 and `at` is a UTC timestamp. The
an attempt is pending. `attempt` is 1–5 and `at` is a UTC timestamp. Additional fields are
`kind` (`transient`, `limit`, `restart`) and `target_runtime`. Only confirmed
retries appear here; usage checks have no persisted or API state. The
field is absent when no retry is pending; the thread remains `idle` while
waiting. See [automatic continuation](agent-provider-lifecycle.md#automatic-continuation-after-a-failed-model-turn)
for backoff and reset behavior.
Expand Down Expand Up @@ -376,3 +378,27 @@ The auto-approver calls the same tools decision path as manual approval and
records its decision before that call. Call errors are stored separately from
the decision and tool execution status. The tools service receives no auto-approval
metadata. See [Host AI inference](host-ai-inference.md#auto-approval).

## Chat workspace image previews

Chat renders native workspace links to JPEG, PNG and WebP images as compact,
uncropped previews, with a fullscreen modal on activation. Both Markdown links
and Markdown image syntax use absolute agent-home paths. Other files retain the
Files action; remote images are not fetched automatically.

`GET /v1/agent-files/image-preview?path=...` uses the same operator session and
CSRF checks, confined file helper, MIME allowlist and response security headers
as Files content streaming. It checks image signatures and rejects non-image
extensions and files above
5 MiB before sending image bytes. Preview data is buffered within that byte cap
to read image dimensions without decoding pixels; images above 16 megapixels or
8192 pixels per edge are rejected before the browser receives image data. The Files content/download limits are unchanged.
The browser fetches at most two previews concurrently near the viewport, releases
object URLs for removed or offscreen previews, and retains a Files link if a file
is missing, unsupported, oversized or cannot be decoded. Temporary network,
timeout and server failures offer a Retry preview button. The modal traps focus,
closes with Escape or its Close button, and returns focus to the preview.

Agent-facing examples live in the installed
[workspace file and image guidance](../../host/bootstrap/agent-home/references/workspace-files.md),
shared by the Codex, Claude and Grok harnesses.
1 change: 1 addition & 0 deletions docs/architecture/agent-messages.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ The standard event envelope contains `seq`, `event_id`, `timestamp`, `thread_id`
| --- | --- | --- |
| Delivered input | `reminder`, `scheduled_trigger`, `approval_outcome`, `restart`, `retry`, `agent_message` | `source: "user"`, `message`: exact provider input, including its routing preamble |
| Context | `history_transfer`, `memory_injection`, `memory_suggestion` | `message`: summary; memory notices retain `memory_page_ids` and `memory_recall_details`; confirmed injections also retain the exact injected message in `notice.details`; transfers retain `historical_context` |
| Recovery decisions | `recovery` | `notice.details`: classification, attempt, deadline, subscription choice or stop reason |
| Messaging and agents | `agent_message_sent`, `agent_spawned`, `agent_archived`, `agent_stopped` | `notice.details`: outcome and request |
| Memory writes | `self_memory_saved`, `shared_memory_saved`, `shared_memory_deleted`, `private_note_saved`, `private_note_deleted` | `notice.details`: outcome and request |
| Standing agents | `standing_agent_created`, `standing_agent_updated`, `standing_agent_deleted` | `notice.details`: outcome and request |
Expand Down
50 changes: 26 additions & 24 deletions docs/architecture/agent-provider-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -517,30 +517,32 @@ another refresh holding the runtime's refresh lock.

## Automatic continuation after a failed model turn

Failed model turns get up to five automated continuations, waiting 5 minutes,
20 minutes, 1 hour, 4 hours, then 12 hours after each failure. A host worker
checks in-memory deadlines every 15 seconds and sends an ordinary `retry`
notice using the thread's recorded runtime, model and effort. The message asks
the agent to check completed work before continuing. A successful turn ends the
chain. New admitted messages start a fresh chain; accepted steering resets the running turn's retry count.

Only failed turn completion schedules this work. Operator stops, successful
turns, cleanup-only errors, and Bash scripts do not. New admitted work, Stop,
and clearing working memory cancel attempts still waiting. Chat, standing-agent
and App composers show the next attempt and let the operator cancel it.

Once the worker claims an attempt, it sends through the same host path as
restart continuation. Normal delivery handles any concurrent messages; there
is no extra locking or Workspace eligibility policy. A delivery failure is
logged and ends the chain, just like a failed restart continuation. Only a
failed model turn schedules the next attempt. There is no error-text classifier
or model fallback.

Retry deadlines and counters are deliberately process memory only. Restarting
or redeploying discards pending retries. The existing one-shot continuation for
turns interrupted by a host restart remains separate and starts a fresh chain
if that continuation fails. No retry database state, recovery scan or schema
migration is involved.
Model threads share a persistent cap of five automatic recovery attempts,
including subscription switches and restart continuations. Success resets it;
new messages and settings changes do not. Bash scripts do not retry.

| Error | Recovery |
| --- | --- |
| Contains `timed`, `timeout` or `capacity` (case-insensitive) | Back off by shared attempt number: 5m, 20m, 1h, 4h, 12h. |
| Contains `limit`, on Codex or Grok | Check fresh usage. Switch permanently to an enabled compatible subscription below 100% in every applicable window, preserving model/effort and App/Standing settings. Otherwise keep the current subscription and wait for its own reset. |
| Contains `limit`, on Claude | Wait until all exhausted applicable windows reset: session, weekly, and Fable weekly only for Fable models. |
| Unknown error, Hermes limit, failed/inconclusive usage check | Stop recovery. |

Limit matching takes precedence over transient matching. Only usage ≥100%
means exhausted; 99% remains eligible. Reset deadlines come from usage, not
error text, with a one-minute buffer. Grok currently exposes one billing window;
missing percentages remain unknown. Usage checks are one-shot and in memory:
only a confirmed retry or switch is saved, and unfinished checks are lost on restart.

Typed `thread_recovery` columns persist the counter and pending retry. Boot
restores future/overdue retries and queues interrupted model turns through the
same worker. Stop, context clear and newly admitted work cancel pending retries.
Recovery is best effort: changed settings, unavailable destinations or failed
admission stop it rather than starting another recovery mechanism.

The UI shows the retry date/time and cancellation control. `recovery` notices
record decisions; MCP history includes bounded thread errors. Continuations must
reconcile completed actions before proceeding; they never authorize duplicate writes.

## Optional additional accounts

Expand Down
1 change: 1 addition & 0 deletions docs/architecture/database-retention.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ The categories are:
| `operator_connections` | fixed | At most one SSH and one tunnel row. |
| `counters` | fixed | Internal named counters, including four lifetime token totals. Never pruned with detailed usage. |
| `thread_sessions` | retention | Sessions referenced by retained events or turn usage are preserved; unreferenced sessions retain the newest 100,000 per runtime. |
| `thread_recovery` | current state | One counter and optional pending retry per thread; removed with its session mapping. Success resets the counter and clears pending recovery. |
| `agent_events` | retention | Newest 100,000,000-event sequence window, with at most 499 rows of amortization slack; sequence gaps can leave fewer rows. Large details expire only when both outside the newest 1,000,000-event sequence window globally and older than three calendar months. Message text is length-bounded and survives detail expiry. |
| `conversation_message_embeddings` | retention | Derived vectors for the newest 250,000 user/agent messages, with at most roughly 800 newly indexed messages of amortization slack; activity and lifecycle events do not consume this quota. Rows cascade with source events. |
| `oauth_logins` | fixed | At most one row for each supported OAuth runtime. |
Expand Down
Loading
Loading