Connect the world outside the graph

StateWeave owns causal state. Models and tools are explicit boundaries supplied to Agent.

Model contract

The public Agent loop currently calls complete(). Implement stream() for interface completeness and direct adapter use.
Keep adapters thin. Do not reconstruct transcripts or summarize state inside the adapter. input.prompt is already the compiled causal view.

Included adapters

  • MockModel provides deterministic tests.
  • AnthropicModel is a thin HTTP adapter without an Anthropic SDK dependency.
  • createModelFromEnv() selects mock or Anthropic-compatible configuration from environment variables.

Tool contract

A complete custom tool:
Descriptions become part of the provider system contract. The runtime validates arguments before execution and records both successful and failed results.

Default workspace tools

If tools is omitted, Agent creates four workspace-scoped tools:
  • read_file
  • write_file
  • edit_file
  • read-only bash_command
Pass tools: [] for no tools. Pass a custom array to replace the defaults.
Default file tools reject absolute paths, traversal, and symlink components. The shell tool is a no-profile, fixed-PATH, read-only command allowlist. It rejects pipes, redirects, command substitution, arbitrary interpreters, and network commands. These checks reduce accidental scope. They are not a process sandbox. For untrusted coding work, run the entire agent inside an isolated filesystem and process boundary.

Design tools for evidence

Return small structured values with stable identifiers, status, hashes, and mutation facts.
Structured results improve projection and inspection. Do not return secrets, unlimited logs, or data the next inference does not need.