docs: document tool runtime bridge continuation

[cursor]

🧠 Noēsis Pull Request

Overview

Documents the tool-contract runtime bridge continuation path for approval-gated subprocess tools, including how prepared drafts pause episodes and how ns.resume_run(...) resumes the same draft after approval.

Type of Change

• 📚 Documentation or research notes
• 🧰 Developer experience (CLI, codemod, viewer, tooling)

Motivation & Context

Recent runtime bridge guardrails make subprocess-only prepared invocation continuation explicit in source and tests, but the docs did not fully explain the bridge entry points, resume behavior, operational inspection paths, or failure modes. This PR updates existing docs instead of adding a redundant page.

Technical Details

Docs added/updated:

• docs/guides/integrate-adapters.mdx: Adds the episode runtime bridge entry points, pause/resume flow, event ordering, identity rules, and troubleshooting cases.
• docs/reference/python-api.mdx: References runtime bridge helpers and typed bridge errors for adapter implementers.
• docs/explanation/artifacts.mdx: Adds final.json, checkpoints/, and tool_invocations/{prepared,approvals,idempotency}/ to the artifact layout, plus paused-vs-terminal constraints.
• docs/guides/human-in-the-loop.mdx: Cross-links human approval guidance to the prepared invocation bridge.

Codepaths covered:

• noesis.usecases.tool_invocation.runtime_bridge.ToolRuntimeBridgePorts
• build_tool_invocation_actuation_bindings(...)
• build_resumed_tool_invocation_actuation_bindings(...)
• ToolContractContinuationActuator
• noesis.core.resume_run(...) pending-draft continuation wiring
• filesystem repositories under noesis.infrastructure.tool_invocation.repositories

Key knowledge gaps addressed:

• How approval-gated subprocess tools pause before side effects.
• Where prepared, approval, and idempotency records are stored.
• Why paused runs lack terminal final.json/manifest.json artifacts.
• How ns.resume_run(...) resumes the existing draft without re-preparing it.
• Why unsupported protocols fail before draft persistence or run.resume mutation.

Validation

Required

• All tests pass locally (uv run pytest) or equivalent targeted suite
• Schema validation and export diff clean

Situational

• Cognitive loop tested end-to-end (Observe → Learn)
• Docs build successfully (pnpm run build in docs/)
• CLI smoke tests pass (python scripts/pre_release.py --check-all)
• Benchmarks / eval sweeps reproduced
• Artifact integrity checked (hashes, licensing, storage footprint)

Validation performed:

• python3 -m pytest tests/runtime/test_tool_invocation_runtime_bridge.py -q initially could not run because the base Python environment had no pytest.
• Installed python3.12-venv, created /tmp/noesis-docs-venv-2, installed .[dev], then ran /tmp/noesis-docs-venv-2/bin/python -m pytest tests/runtime/test_tool_invocation_runtime_bridge.py -q -> 8 passed in 0.55s.
• npx --yes mintlify@latest broken-links from docs/ -> success no broken links found.

Notes:

• This repository has no docs/package.json, so there is no pnpm run build command to run. Mintlify link validation was the available docs validation.
• Schema artifacts were not changed.

ADR-003 Schema Governance Checklist

• $schema_version bumped for every artifact whose stable fields changed
• docs/schema/** regenerated (no diff after python scripts/gen_schema.py)
• KPI updates include version bumps plus math/clamp/rationale updates in internal_docs/schema/kpi*.yaml
• Relevant entry added to MIGRATIONS.schema.md or MIGRATIONS.kpi.md
• python scripts/schema_guard.py --strict --json passes locally
• Docs under docs/app/reference/* updated when new fields/KPIs surface to users

Not applicable: documentation-only change; no schema fields changed.

Observability & Safety

Improves operational safety docs for approval-gated side effects by documenting the evidence chain, paused-run artifact expectations, and fail-fast protocol guardrails.

Educational / Research Value

Clarifies the ADR-016 prepared tool invocation model for adapter implementers and operators inspecting interrupted runs.

Screenshots / Logs

$ /tmp/noesis-docs-venv-2/bin/python -m pytest tests/runtime/test_tool_invocation_runtime_bridge.py -q
........                                                                 [100%]
8 passed in 0.55s

$ npx --yes mintlify@latest broken-links
success no broken links found

Related Issues / References

• ADR-016 tool-contract runtime bridge guardrails

  

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
noesis	🟢 Ready	View Preview	Jun 8, 2026, 4:24 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.