feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
# Tracing Standard API — v1 (draft)
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
The contract between **raven** (and any other adopter) and the in-tree
`raven.tracing` implementation. `raven-tracing` is the planned standalone
distribution, not a separate dependency of the current Raven package.
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
Principle: *tracing owns the standard, the app adopts it.* `raven.tracing` defines
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
what a span is, which fields each span kind carries, and how it renders. An app
(raven) instruments itself by calling one small, stable facade — `trace.span(...)`
— at points it chooses. Neither side depends on the other's internals; the only
coupling is this API's version + the semantic conventions below.
This mirrors the OpenTelemetry model (library defines the API + data model; the
app does manual instrumentation), so the same discipline applies: the API is
tiny and slow-moving, the SDK behind it (storage, viewer, on-disk format) iterates
freely without touching adopters.
Related: the on-disk record shape (`audit.span.v1` ) is defined in
`raven/tracing/spans.py` (`build_span` ) and summarized in §2; this document is
the **write-side** standard that produces those records.
---
## 1. Public API
One import, one primary call:
```python
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
from raven.tracing import trace
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
with trace.span("llm.call", {"llm.provider": provider, "llm.model": model}) as s:
resp = do_call(...)
s.set({"llm.usage.total_tokens": resp.usage.total, "llm.finish_reason": resp.finish_reason})
```
### `trace.span(name, attributes=None, *, kind=None, **kw) -> Span`
A context manager that opens a span on enter and finalizes + records it on exit.
- `name` — dotted semantic name, `<domain>.<verb>` (e.g. `llm.call` ). Drives the
default `kind` and the viewer's label/rendering (see §2).
- `attributes` — a mapping of fully-qualified dotted keys (the standard form,
e.g. `{"llm.provider": p, "llm.model": m}` ). Standard keys are dotted, so a
mapping is the primary form; `**kw` accepts bare keys for convenience (stored
verbatim, no auto-namespacing — the attribute namespace can differ from the
name domain, e.g. `session.turn` carries `turn.*` ).
- `kind` — optional override of the coarse category
(`session|model|tool|subagent|skill|memory|plugin` ). Default derived from the
name's domain; pass explicitly for custom nodes (§3).
Nesting is automatic via `contextvars` : a span opened while another is active
becomes its child; context survives `await` and is snapshotted onto tasks. The
root of a turn is a `session.turn` span; everything else nests beneath it.
### `Span` handle
| method | effect |
|---|---|
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
| `s.set(attributes=None, **kw)` | merge attributes onto the span (dotted-key mapping and/or bare kwargs) |
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
| `s.artifact(key, payload, *, kind="json")` | persist a large payload out-of-line; attach `<key>.artifact_path/_sha1/_bytes` + a truncated `preview` . Use for prompts / tool IO / recall results. |
feat(docker): run raven in a docker container and make a first run configurable from the page
## Summary
Two things arrive together because the second is what made the first usable.
**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.
**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.
Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.
## Type
- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands run on the branch head, with their results:
- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean
Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.
The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:
- nginx rewrites the `Origin` header, because the engine accepts only an Origin
naming its own loopback port and no browser reaching a published port can send
one. This drops a defence-in-depth layer. The session cookie is
SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
every page load, so anyone who can reach the published port is signed in. It
is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
deployment reachable from elsewhere. These are two settings that must agree,
and nothing warns when they do not.
Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).
Rollback is by revert; nothing here migrates state or changes an on-disk format.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
2026-09-11 03:27:52 +00:00
| `_spans.address_items(items)` | content-address a list of messages under `audit-artifacts/_messages/` ; returns `{"$msg": sha1}` references to embed in a payload. See `audit.artifact.v2` below. |
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
| `s.event(name)` | append a timeline event `{time, name}` |
| `s.error(exc)` | mark `status = ERROR` (done automatically if the block raises) |
Read-only: `s.trace_id` , `s.span_id` , `s.name` .
### Module helpers
| call | returns |
|---|---|
| `trace.enabled()` | whether recording is on (config/env) |
fix(tools): an array sent as its own JSON is still an array
## Summary
Reported as "deliver_files is broken". It is not: **the tool never ran.**
Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:
```
Error: Invalid parameters for tool 'deliver_files': files should be array
```
What the model sent was the array, spelled as a string:
```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```
`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.
## Type
- [x] Fix
- [ ] Feature
## The edge of the forgiving is the design
When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.
**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.
**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.
## Not just deliver_files
Six built-in tools declare an array or object parameter and were all exposed:
| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |
The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.
## Verification
```
make lint-python ruff check + ruff format --check, 1850 files
make lint-imports 9 contracts kept, 0 broken
pytest tests/ 19,699 passed, 7 failed (all pre-existing, see below)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string
**End to end, through the real tool**, with the exact payload that failed five times in production:
```
files sent as: str -> [{"path": ".../poster.png", "title": "..."}]
returned: Delivered 1 file(s): poster.png (72 B).
still "should be array": False
registered in the store: True
```
Twelve cases, five mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |
The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.
**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.
## Risk
- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.
- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.
Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).
## Deliberately not fixed
The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.
## Moved from !594
Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.
Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
2026-09-09 15:42:36 +00:00
| `trace.current()` | the active `TraceCtx` or `None` |
| `trace.use_context(ctx)` | context manager: re-enter a context captured with `current()` , for a span opened outside the turn that scheduled the work (a queue drained by a long-lived worker) |
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
### Hard guarantees (why an adopter is safe)
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
1. **No-op when off.** When tracing is disabled, `trace.span(...)` yields a
no-op handle: no spans or artifacts are written, and the `with` block runs
normally.
2. **Error boundaries.** Span creation, span emission, and artifact persistence
catch internal exceptions and log them at debug level. When tracing is
enabled and span creation succeeds, exceptions raised inside the `with`
block are re-raised after marking the span as an error. The handle methods
require correctly typed inputs: for example,
`s.set(42)` raises `TypeError` , which also propagates out of the block.
Pass a mapping as `s.set({...})` or `s.set(attributes={...})` ;
`attrs` is not an alias and would be stored as an ordinary attribute key.
When tracing is disabled, the no-op handle ignores these arguments, so
`s.set(42)` does not raise. Enabling tracing can therefore expose argument
errors that were hidden while it was off.
3. **Import-safe.** Importing `raven.tracing` and calling the API must succeed
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
even with no config present.
### `@trace.instrument(...)` — the decorator (primary adopter mechanism)
Adopters instrument a method by annotating it — the body is untouched, so this
does not change core logic (only adds an observation wrapper)::
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
from raven.observability import semconv
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
@trace .instrument("llm.call", extract=semconv.llm_call)
async def chat_with_retry(self, ...): ...
`trace.instrument(name, *, kind=None, seed=None, on_open=None, extract=None)`
wraps a sync **or** async method:
- `extract(span, bound_args, result, exc)` — runs in `finally` (input captured
even on error); fills final attributes/artifacts. `bound_args` is the call's
arguments by name; `result` is the return (`None` on error); `exc` the raised
exception (`None` on success). The standard extractors live in
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
`raven.observability.semconv` (`llm_call` , `tool_call` , `memory_*` , …).
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
- `seed(bound_args) -> dict` — returns `session_key` / `channel` / `chat_id` to
open a *root* span (a turn) whose identity every child inherits.
- `on_open(span, bound_args)` — runs right after open, before the body; used to
record input and `span.checkpoint()` an in-progress root for live viewing.
Extra `Span` methods used by extractors: `span.retype(name, kind)` (a `tool.call`
that turns out to be a `skill.read` ), `span.cancel()` (drop a conditional span,
e.g. `skill.inject` only when something was injected), `span.checkpoint()` ,
`span.elapsed_ms()` . Pass `detached=True` for a leaf marker that does NOT become
the active parent — required for cancellable spans so a child that opened before
the cancel doesn't dangle off an unemitted span.
Every span family is instrumented this way — including `subagent.run` : a
subagent runs the same decorated primitives (`chat_with_retry` / `tools.execute` ),
so its spans are captured by those decorators and nest under the `subagent.run`
node automatically via the contextvars snapshot `asyncio.create_task` takes at
spawn. No monkeypatch is used anywhere.
---
## 2. Semantic conventions (standard span kinds)
`kind` is a single-word category (drives node coloring/grouping). `name` is the
`<domain>.<verb>` identifier (drives the label + rendering). Attributes are
namespaced by domain. Adopters SHOULD populate the "required" columns; "optional"
adds richer rendering.
| name | kind | required | optional attributes |
|---|---|---|---|
| `session.turn` | `session` | — | `turn.input_preview` , `turn.output_preview` , `turn.in_progress` , `turn.capabilities.{tools,plugins,skills}` |
feat(docker): run raven in a docker container and make a first run configurable from the page
## Summary
Two things arrive together because the second is what made the first usable.
**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.
**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.
Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.
## Type
- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands run on the branch head, with their results:
- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean
Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.
The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:
- nginx rewrites the `Origin` header, because the engine accepts only an Origin
naming its own loopback port and no browser reaching a published port can send
one. This drops a defence-in-depth layer. The session cookie is
SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
every page load, so anyone who can reach the published port is signed in. It
is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
deployment reachable from elsewhere. These are two settings that must agree,
and nothing warns when they do not.
Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).
Rollback is by revert; nothing here migrates state or changes an on-disk format.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
2026-09-11 03:27:52 +00:00
| `llm.call` | `model` | `llm.provider` , `llm.model` | `llm.provider_class` , `llm.finish_reason` , `llm.call_id` , `llm.invocation_source` , `llm.usage.{input,output,total,cache_read,cache_write}_tokens` , `llm.usage.cost_total` , `llm.request_{bytes,images,image_bytes}` , `llm.http_status` , `llm.served_by` , `llm.response_id` ; artifacts `llm.input` (`audit.artifact.v2` : message references + tools, plus `request` = the messages+tools payload size and picture count, not the provider-final body, and `generation` = what the call asked the model for; see below), `llm.output` (plus `call` = the transport record) |
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
| `tool.call` | `tool` | `tool.name` | `tool.call_id` , `tool.duration_ms` , `tool.error` ; artifacts `tool.input` (params), `tool.output` (result) |
| `subagent.run` / `subagent.call` | `subagent` | — | `subagent.id` , `subagent.label` , `subagent.task` , `subagent.session_id` , `subagent.parent_trace_id` , `subagent.parent_span_id` , `subagent.trace_id` , `subagent.status` |
| `skill.read` / `skill.inject` | `skill` | — | `skill.name` , `skill.id` , `skill.source` , `skill.path` , `skill.scripts_dir` (present => a runnable bundle was materialized, vs instructions-only), `skill.read.via_tool` (`use_skill` /`read_skill` /`read_file` ), `skill.inject.{names,count,via}` |
| `memory.recall` / `.store` / `.feedback` / `.extract` / `.consolidate` / `.profile_refresh` | `memory` | — | `memory.scope` , `memory.hits` , `memory.message_count` , `memory.kind` , `memory.deposit_summary` , `memory.deposit_status` , `memory.surface` , `memory.sections_rewritten` ; artifacts per op |
| `plugin.load` / `tracing.bootstrap` | `plugin` | — | `plugin.name` , `plugin.contribution` , `plugin.id` |
feat(docker): run raven in a docker container and make a first run configurable from the page
## Summary
Two things arrive together because the second is what made the first usable.
**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.
**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.
Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.
## Type
- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands run on the branch head, with their results:
- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean
Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.
The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:
- nginx rewrites the `Origin` header, because the engine accepts only an Origin
naming its own loopback port and no browser reaching a published port can send
one. This drops a defence-in-depth layer. The session cookie is
SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
every page load, so anyone who can reach the published port is signed in. It
is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
deployment reachable from elsewhere. These are two settings that must agree,
and nothing warns when they do not.
Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).
Rollback is by revert; nothing here migrates state or changes an on-disk format.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
2026-09-11 03:27:52 +00:00
### Artifact formats
An artifact is either a plain JSON payload (v1, no discriminator) or
`audit.artifact.v2` , which carries `"artifactFormat": "audit.artifact.v2"` and
replaces each message with a `{"$msg": "<sha1>"}` reference to
`audit-artifacts/_messages/<sha1[:2]>/<sha1>.json` . Only `llm.input` is written
this way; every other kind stays v1, and a v1 artifact already on disk is never
rewritten. A shell's `request` and `generation` are carried verbatim: neither
holds message content, so referencing them would cost an indirection and save
nothing.
`raven/tracing/artifact_v2.py` is the format's single authority - canonical
serialization, envelope, reference validation, resolution - because the bundled
viewer mirrors it in JavaScript and a cross-language round-trip test compares
the two. A consumer that resolves a shell must apply two rules: `messages`
resolves to the list of message objects, while `systemPrompt` and `prompt`
resolve to their message's `content` coerced to text. A reference whose sha1 is
not 40 lowercase hex characters is data, not an address, and is passed through
untouched; a shell may also carry a raw message inline where its blob could not
be written.
For `llm.input` , `artifact_sha1` and `artifact_bytes` describe the shell, not
the conversation it references; `llm.request_bytes` is the request-size signal,
measured from the messages themselves and so unaffected by the shell. The shell
hashes over the references it lists, so tamper evidence localizes to one
message rather than only proving the payload changed.
Two resolution points turn a shell back into its v1 equivalent:
`raven/trajectory/bundle.py` when packing a trajectory (so a bundle carries no
dependency on the message store) and `readArtifact` in the bundled viewer's
`server.js` (so the UI never sees a reference). Consumers downstream of either
- replay, cassette minimization, the viewer's UI - read v1 shapes and need no
knowledge of v2.
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
**Provider labeling:** `llm.provider` is the *logical backend* the call routes to
(e.g. `openrouter` ), derived from the model's gateway prefix; `llm.provider_class`
feat(docker): run raven in a docker container and make a first run configurable from the page
## Summary
Two things arrive together because the second is what made the first usable.
**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.
**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.
Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.
## Type
- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands run on the branch head, with their results:
- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean
Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.
The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:
- nginx rewrites the `Origin` header, because the engine accepts only an Origin
naming its own loopback port and no browser reaching a published port can send
one. This drops a defence-in-depth layer. The session cookie is
SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
every page load, so anyone who can reach the published port is signed in. It
is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
deployment reachable from elsewhere. These are two settings that must agree,
and nothing warns when they do not.
Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).
Rollback is by revert; nothing here migrates state or changes an on-disk format.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
2026-09-11 03:27:52 +00:00
is the concrete class (e.g. `LiteLLMProvider` ) when it differs. `llm.served_by` is a
third thing: the backend the *response* names as having served the call, present only
when the upstream says so, which behind a gateway that fans out is the only way to tell
which one answered.
**The transport record.** `llm.output` 's `call` object holds what the exchange did rather
than what the model said: `http_status` , `served_by` , `served_model` , `response_id` ,
`headers` , and `body` -- the last filled only when the call delivered nothing, so a
usable answer is never stored twice. It is built solely by
`raven.providers.call_record` , which caps the body and the headers and replaces the value
of any credential-named header; nothing else may construct one. A request's own bytes are
never copied into a record: `llm.input` 's `request` object counts them
(`bytes` on the wire, `images` , `imageBytes` decoded) and image payloads are counted, not
logged.
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
Naming rules:
- `name` = `<domain>.<verb>` , lowercase dotted.
- attribute keys = `<domain>.<field>` , matching the span's domain.
- kind is a closed vocabulary: `session|model|tool|subagent|skill|memory|plugin` .
---
## 3. Custom nodes
Any adopter (or plugin) may record a custom span — no registration required:
```python
with trace.span("raven.sentinel.tick", {"sentinel.reason": r}, kind="plugin") as s:
s.set({"sentinel.fired": n})
```
Rules:
- Use an **owned namespace** for `name` (`raven.<subsystem>.<verb>` ) to avoid
clashing with the standard names in §2.
- Pass `kind` explicitly (falls back to a generic node kind otherwise).
- The viewer renders unknown names generically (title from `name` , subtitle from
a chosen attribute). For bespoke rendering, ship a **descriptor** entry
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
(`descriptors/*.json` ) whose `type` field matches the span's `name` .
Bundled descriptors are shipped under `raven/cli/tracing_viewer/descriptors/` ;
the viewer merges descriptor entries by `type` .
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
---
## 4. Adopter integration contract (raven)
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
1. Tracing ships inside Raven as `raven.tracing` ; no separate `raven-tracing`
dependency or `raven[tracing]` extra is required.
2. `from raven.tracing import trace` at instrumentation sites; wrap the operation
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
in `with trace.span(...)` . Instrumentation lives in the app's own code, moves
with refactors, and is visible in diffs (no external monkeypatch to silently
break).
3. Enable/disable via `[tracing].enabled` (raven config) or `RAVEN_TRACING=0`
(env override). The API no-ops when disabled.
4. The app never imports the SDK internals (storage/viewer) — only the facade.
There is no monkeypatch / auto-instrumentation path: all instrumentation is the
explicit `@trace.instrument` annotations in raven's own source, so it moves with
the code and shows up in diffs (never silently breaks on a refactor).
---
## 5. Versioning & governance
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
The API versioning rules below are proposed for the standalone distribution;
they do not describe an independently versioned package shipped by Raven today.
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
- The API + semantic conventions are versioned together as `standard-api.v1` ,
independent of the app.
- **Additive** changes (new optional attribute, new span name/kind) → minor bump,
backward compatible.
- **Breaking** changes (rename/remove an attribute or the API signature) → major
bump + a migration note; adopters pin a supported range and warn (not silently
degrade) on mismatch.
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
- A conformance snapshot test (frozen span names + required fields) should guard
the standalone contract in CI and require a version bump for contract changes.
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
- On-disk record format is versioned separately as `audit.span.v1`
(defined in `raven/tracing/spans.py` ); the two move independently.
---
## Status
In-tree, complete. Every span family (turn / llm / tool / memory / skill.inject /
plugin.load / subagent) is instrumented with `@trace.instrument` on raven's own
methods; there is no monkeypatch and no `instrument.install()` — the auto-probe
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
module was removed. `raven.observability.semconv` already owns the Raven-specific
attribute/artifact builders, separately from the tracing machinery.
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
Remaining for the standalone-OSS phase (P4), none blocking in-tree use:
- Make the import optional: raven core hard-imports `raven.tracing` at module load
(decorators applied at class-definition time), so it must ship with raven; a
no-op fallback shim is needed before tracing can be a truly optional extra.
docs: align bilingual documentation with runtime behavior (#551)
## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
- Keep the Raven-specific extractors in `raven.observability.semconv` ; package
only the generic API + schema + viewer in the standalone distribution.
- Decouple Raven-specific defaults and path resolution (`FRAMEWORK` , `RAVEN_*`
env, `~/.raven` paths) from the standalone package.
feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary
Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.
The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:
- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
re-raising the application's exception unchanged.
Open the dashboard with `raven tracing` (or `/tracing` in the TUI).
Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands run:
- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
attributes, artifacts, retype, invocation_source, and the frozen
contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
failure isolation confirmed by dedicated tests.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.
Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00
- Freeze `standard-api.v1` ; publish `raven-tracing` ; raven default-depends on it.