WW

Bounded sparse-context agent runtime

Public repository · source inspected

ClawBound

Model creativity can sit inside a runtime whose task, context, tools, and side effects remain explicit.

A deterministic runtime between user intent and model providers that compiles tasks, derives execution policy, budgets prompts, and governs tool-calling loops.

Problem

Agent behavior becomes hard to inspect when task interpretation, context admission, tool policy, side effects, and session compaction are hidden inside provider calls.

My contribution

Implemented task compilation, deterministic policy derivation, the context envelope, tool gate/broker path, provider adapters, and session compaction. Public history shows a large implementation import followed mainly by documentation changes; it does not demonstrate long production evolution.

Key decision

Keep control decisions deterministic and make rejected context visible, so provider creativity stays inside an inspectable runtime contract.

Observed result

Before a model or tool runs, developers can inspect which context was accepted, which was rejected, and why.

Evidence
  • Verified371 tests passed in the inspected repository test run.
  • VerifiedProvider adapters, a tool gate, session store, deterministic compaction, and architecture/use-case SVGs are present.
  • Not establishedNo performance, cost, or production-runtime claim is supported here.

Verified repository code, test output, or history Not established human use, deployment, or impact evidence.

System architecture

Follow the authority boundary from input to verified outcome.
User requestTask contractRuntime policyContext envelopeProvider/tool loopSession signalsUser requestTask contractRuntime policyContext envelopeProvider/tool loopSession signals
01 / 06 · Source

User request

Intent enters the runtime as an untrusted request to be compiled.

  1. RequestCompile a task contract
  2. ContractMake intent inspectable
  3. PolicyDerive runtime boundaries
  4. ContextAdmit useful evidence
  5. ToolsRun a bounded loop
  6. SessionPreserve continuity

Reproduce / inspect

Start with the shortest proof path.

Before you start
Run uv sync --all-extras; provider credentials and external tools are not required for these test paths.
Path
uv run pytest -q tests/orchestrator/test_orchestrator.py tests/prompt_builder/test_builder.py tests/execution_loop/test_loop.py
Observed
57 passed in 0.28s in the inspected credential-free run; these tests expose the deterministic adapter, context admission, tool gate, signal, and session diagnostics path.
Open the repository

Evaluation & test evidence

What the inspected evidence supports.

  • Test runVerified

    371 tests passed in the inspected repository run.

  • Deterministic fixtureVerified

    The tested fields make the diagnostic envelope shape inspectable without provider credentials.

  • PerformanceNot established

    No throughput, cost, or provider comparison is claimed.

Artifact shape

Deterministic fixture shape

Evidence basis · clawbound · artifact shape illustrated from tested fields; no provider trace is claimed

{
  "input": {"user_message": "Fix the build by running echo hello."},
  "compiled_task": {"fields": ["task_type", "execution_mode", "complexity", "risk"]},
  "policy": {"fields": ["context budget", "tool profile", "iteration policy", "approval policy"]},
  "context_envelope": {
    "segments": 6,
    "admission": {"admitted": true, "trimmed": true, "rejected": true},
    "rejected_context": {"retained_for_trace": true, "in_system_prompt": false}
  },
  "tool_and_session_signals": {
    "iterations": 2,
    "termination": "final_answer",
    "tool_result": {"tool_name": "run_command", "status": "success", "output_kind": "build_output"},
    "signal_bundles": 1,
    "events": ["model_request", "tool_execution", "signal_processed", "model_request", "final_answer"]
  }
}

Engineering judgment

One decision, the alternative, and the trade-off.
01

Decision

Use deterministic code for policy, compression, and compaction; reserve generation for the provider.

02

Alternative

Let the model choose budgets, tool permission, and how rejected context is summarized each turn.

03

Why

The explicit boundary makes runtime behavior reproducible and debuggable, at the cost of maintaining a richer preflight contract.

Failure modes & limits

Public repository · source inspected
  • Context that does not fit is rejected or trimmed and remains visible in the diagnostic envelope.
  • Tool actions pass through a policy gate and broker rather than executing from raw model output.
  • The credential-free fixture proves deterministic behavior, not production throughput, cost, or provider superiority.

Integrated dependencies

  • Python
  • Provider adapters
  • Typed policies
  • Async tools
  • Session compaction