Expand model providers and harden the runtime

.env.example

@@ -1,14 +1,54 @@
-OPENAI_API_KEY=
-DEEPSEEK_API_KEY=
+# Provider selection. CHULK_MODEL is required for openai-compatible,
+# openrouter, anthropic, bedrock, and gemini.
 CHULK_LLM_PROVIDER=openai
 CHULK_MODEL=
 CHULK_LLM_FALLBACK_PROVIDERS=
-CHULK_PERMISSION_PROFILE=workspace-write
-CHULK_PROJECT_ROOT=
-CHULK_RUNTIME_DIR=.chulk
+
+# OpenAI
+OPENAI_API_KEY=
+
+# DeepSeek: CHULK_DEEPSEEK_API_KEY takes precedence over DEEPSEEK_API_KEY.
+CHULK_DEEPSEEK_API_KEY=
+DEEPSEEK_API_KEY=
 CHULK_DEEPSEEK_BASE_URL=https://api.deepseek.com
+
+# Local OpenAI-compatible server. The API key is optional.
 CHULK_LOCAL_BASE_URL=http://localhost:1234/v1
 CHULK_LOCAL_API_KEY=
+
+# Hosted OpenAI-compatible endpoint. Both fields are required.
+CHULK_OPENAI_COMPATIBLE_API_KEY=
+CHULK_OPENAI_COMPATIBLE_BASE_URL=
+
+# OpenRouter: CHULK_OPENROUTER_API_KEY takes precedence over OPENROUTER_API_KEY.
+CHULK_OPENROUTER_API_KEY=
+OPENROUTER_API_KEY=
+CHULK_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+
+# Anthropic: CHULK_ANTHROPIC_API_KEY takes precedence over ANTHROPIC_API_KEY.
+CHULK_ANTHROPIC_API_KEY=
+ANTHROPIC_API_KEY=
+CHULK_ANTHROPIC_BASE_URL=
+
+# Bedrock: set an explicit OpenAI-compatible endpoint; there is no default.
+# Key precedence: CHULK_BEDROCK_API_KEY, BEDROCK_API_KEY,
+# AWS_BEARER_TOKEN_BEDROCK. CHULK_BASE_URL is a legacy base-URL alias.
+CHULK_BEDROCK_API_KEY=
+BEDROCK_API_KEY=
+AWS_BEARER_TOKEN_BEDROCK=
+CHULK_BEDROCK_BASE_URL=
+CHULK_BASE_URL=
+
+# Gemini: CHULK_GEMINI_API_KEY, then GEMINI_API_KEY, then GOOGLE_API_KEY.
+CHULK_GEMINI_API_KEY=
+GEMINI_API_KEY=
+GOOGLE_API_KEY=
+CHULK_GEMINI_BASE_URL=
+
+# Runtime and safety configuration.
+CHULK_PERMISSION_PROFILE=workspace-write
+CHULK_PROJECT_ROOT=
+CHULK_RUNTIME_DIR=.chulk
 CHULK_HISTORY_LIMIT=20
 CHULK_MAX_SKILLS_PER_TURN=3
 CHULK_MAX_SKILL_CONTENT_CHARS=4000

.github/workflows/ci.yml

@@ -52,10 +52,10 @@ jobs:
       - name: Install development dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[dev,openai,mcp]"
+          python -m pip install -e ".[dev,providers,mcp]"
 
       - name: Typecheck package and external consumer
-        run: python -m mypy typing_tests
+        run: python -m mypy chulk typing_tests
 
       - name: Verify documentation contract
         run: python scripts/check_docs.py

CHANGELOG.md

@@ -9,13 +9,52 @@ API is still pre-1.0.
 
 ### Added
 
+- Added native Anthropic and Gemini providers plus OpenAI-compatible,
+  OpenRouter, and AWS Bedrock provider adapters.
+- Added an all-provider `providers` installation extra while retaining the
+  individual `openai`, `anthropic`, and `gemini` extras.
+- Added explicit provider profiles, shared connection binding, capability
+  metadata, and offline provider conformance tests with injected fake clients.
+- Added native async model and structured-action requests for every built-in
+  provider transport, including async fallback chains and cancellation
+  propagation.
+- Added deterministic offline evaluation helpers, versioned trace envelopes,
+  trace replay, and provider-free regression coverage.
+- Added plan-step retry accounting and tool-attempt metadata to runtime state
+  and traces.
 - Added MIT licensing for repository and package consumers.
 - Added a security policy for responsible vulnerability reporting.
 - Added GitHub Actions CI for Python 3.11, 3.12, and 3.13.
 - Added clean-wheel install validation for public imports, packaged presets,
   bundled skills, runtime defaults, and example imports.
 
+### Changed
+
+- Centralized validated model-action parsing inside the LLM boundary and kept
+  synchronous custom clients compatible through explicit adapter paths.
+- Improved fallback behavior with shared context budgets, duplicate-request
+  prevention, and normalized timeout, connection, rate-limit, and server
+  failure classification.
+- Extended CI type checking from the external SDK fixture to the package
+  implementation and retained the original custom-provider factory contract.
+- Extended `chulk doctor` to validate requirements for every primary and
+  fallback provider.
+
+### Security
+
+- Reject credential-like content before durable memory storage.
+- Deny model-facing reads of secret files, Git and trace data, SQLite state,
+  and private key material by default.
+- Bound shell output while it is produced, terminate timed-out process groups,
+  and expose an explicit host-owned execution policy and containment gate.
+- Sanitize provider base URLs in `--show-config` so user information, query
+  parameters, and fragments are never printed.
+
 ### Documented
 
+- Documented all provider names, optional dependencies, exact credential alias
+  precedence, explicit-model requirements, and Bedrock endpoint requirements.
+- Clarified that provider tests are offline and live account validation remains
+  the responsibility of the application owner.
 - Documented that `chulkharness` is the install/package name and `chulk` is the
   import package and CLI command.

README.md

@@ -21,7 +21,9 @@ python examples/00_sdk_quickstart.py
 ```
 
 The first example is deterministic and needs no credentials. Hosted providers
-are optional; for OpenAI use `python -m pip install "chulkharness[openai]"`.
+are optional. Install every provider dependency with
+`python -m pip install "chulkharness[providers]"`, or choose an individual
+extra from the [provider guide](docs/providers.md).
 
 ## SDK
 
@@ -49,7 +51,9 @@ under `.chulk/`. Read [configuration](docs/configuration.md),
 
 ## CLI
 
-Install a provider extra, configure its credentials in a local `.env`, then run:
+Install a provider extra, configure its credentials in a local `.env`, then run.
+The exact provider names are `openai`, `deepseek`, `local`,
+`openai-compatible`, `openrouter`, `anthropic`, `bedrock`, and `gemini`.
 
 ```bash
 chulk

TODO.md

@@ -108,13 +108,13 @@ Module responsibilities:
 - [ ] `chulk/core/prompt_builder.py`
   - [ ] Compose prompts from base instructions, memory, skills, tools, and history.
 
-- [ ] `chulk/llm/`
-  - [ ] Wrap the model provider API.
-  - [ ] Support OpenAI first.
-  - [ ] Hide provider-specific request and response details from the agent loop.
-  - [ ] Provide text completion and structured JSON completion helpers.
-  - [ ] Handle retries, timeouts, rate limits, and provider errors.
-  - [ ] Register providers through a provider registry and explicit capability metadata.
+- [x] `chulk/llm/`
+  - [x] Wrap the model provider API.
+  - [x] Support OpenAI first.
+  - [x] Hide provider-specific request and response details from the agent loop.
+  - [x] Provide text completion and structured JSON completion helpers.
+  - [x] Handle retries, timeouts, rate limits, and provider errors.
+  - [x] Register providers through a provider registry and explicit capability metadata.
 
 - [x] `chulk/memory/`
   - [x] Manage short-term conversation history.
@@ -263,10 +263,10 @@ Build a small provider wrapper before adding agent complexity.
 
 Future provider support:
 
-- [ ] Add a minimal local/mock provider for tests.
-- [ ] Add support for local LLMs later.
+- [x] Add a minimal local/mock provider for tests.
+- [x] Add support for local LLMs later.
 - [x] Add DeepSeek as an additional hosted provider.
-- [ ] Add support for additional hosted providers later.
+- [x] Add support for additional hosted providers later.
 - [x] Keep response normalization in one place.
 
 ## 5. Tool System
@@ -1154,7 +1154,7 @@ Optional future directions:
 - [x] MCP-like tool interface.
 - [ ] Vector database.
 - [ ] Multi-agent mode.
-- [ ] Local LLM support.
+- [x] Local LLM support.
 - [ ] OpenTelemetry-style traces.
 - [ ] Permission UI.
 - [ ] Skill marketplace or folder installer.
@@ -1164,7 +1164,7 @@ Optional future directions:
 - [ ] Docker development environment.
 - [ ] Configurable model/provider profiles.
 - [ ] Import/export memories.
-- [ ] Agent evaluation scripts.
+- [x] Agent evaluation scripts.
 - [ ] Benchmark prompts for regression testing.
 
 ## 17. Agent Harness Feature Backlog
@@ -1248,8 +1248,11 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 - [x] Add a `Capabilities` config object or equivalent structured tool capability surface.
 - [ ] Add custom permission profiles in config.
 - [ ] Add workspace root allowlists.
-- [ ] Add path deny rules for secrets, traces, SQLite stores, dependency folders, build artifacts, and credentials.
+- [x] Add model-facing path deny rules for secrets, traces, Git metadata, SQLite/runtime state, private keys, and credentials.
+- [ ] Extend explicit-read deny rules to dependency folders and build artifacts; directory search already excludes them.
 - [ ] Add command prefix rules: allow, prompt, and deny.
+- [x] Add a host-owned shell execution policy boundary with explicit allow/deny and containment assertions.
+- [x] Bound shell output during execution and terminate timed-out process groups.
 - [ ] Add network allow/deny domain rules.
 - [ ] Add trusted command catalog for low-risk read-only commands.
 - [ ] Add approval prompts with approve once, deny once, always allow, and always deny choices.
@@ -1271,21 +1274,21 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 #### Phase E: Trace Productization
 
 - [ ] Treat traces as a public product surface, not only internal logs.
-- [ ] Add a trace schema version to every JSONL event.
-- [ ] Standardize trace event envelope fields: schema version, event/type, conversation id, turn id, timestamp, and payload.
+- [x] Add a trace schema version to every JSONL event.
+- [x] Standardize trace event envelope fields: schema version, event/type, conversation id, turn id, timestamp, and payload.
 - [x] Add a public trace reader: `Trace.from_jsonl(path)`.
 - [x] Expose typed trace events with event type and timestamp.
 - [x] Add `chulk trace inspect <path>`.
 - [x] Add `chulk trace export <path> --format html`.
-- [ ] Add `chulk trace replay <path>`.
+- [x] Add `chulk trace replay <path>`.
 - [x] Add a minimal HTML trace export.
 - [ ] Include user request, prompt context, loaded memories, loaded skills, tool calls, tool outputs, permission decisions, final answer, errors, token usage, and cost usage in trace exports.
 - [ ] Log available tools in traces.
-- [ ] Log timing information in traces.
-- [ ] Add `session_started` and `session_finished` trace events.
+- [x] Log timing information in traces.
+- [x] Add `session_started` and `session_finished` trace events.
 - [ ] Make it obvious why a tool was called where the model/action metadata supports it.
 - [ ] Make it obvious which memories were injected.
-- [ ] Add trace redaction tests.
+- [x] Add trace redaction tests.
 - [ ] Add artifact reader support for full truncated outputs saved under traces.
 - [ ] Add replay-friendly event coverage for regression tests.
 
@@ -1300,7 +1303,9 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 - [x] Add tool-level retry policy.
 - [ ] Add tool testing helpers such as `assert_tool_schema(...)` and `invoke_tool(...)`.
 - [x] Continue supporting async tools through the public decorator.
-- [ ] Add native async runtime later with async LLM calls, async tools, cancellation, timeouts, streaming events, concurrent read-only tools, and cleanup hooks.
+- [x] Add native async LLM and structured-action calls for built-in providers and fallback chains.
+- [x] Propagate native provider cancellation without wrapping it or advancing to a fallback provider.
+- [ ] Complete the async runtime with concurrent read-only tools and async provider cleanup hooks.
 - [ ] Add memory namespaces for user and workspace isolation.
 - [x] Add explicit memory modes: off, read-only, manual read/write, and automatic read/write.
 - [x] Default SDK inferred-memory writes to off or manual review unless the developer opts in.
@@ -1317,9 +1322,10 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 - [ ] Split docs by audience under `docs/`: index, quickstart, sdk, cli, tools, permissions, skills, memory, tracing, providers, mcp, safety, and release policy.
 - [ ] Add one end-to-end `examples/repo_review_bot/` killer example.
 - [ ] Include a sample trace export in the repo review example.
-- [ ] Add fake provider or fake LLM support for examples and CI.
-- [ ] Run examples with fake LLM in CI.
-- [ ] Add a small eval harness with deterministic evals for tool calling, memory retrieval, skill selection, plan approval, and safety refusal.
+- [x] Add fake provider or fake LLM support for examples and CI.
+- [x] Run examples with fake LLM in CI.
+- [x] Add a small deterministic, offline eval harness for agent outcomes, tool sequences, and trace sequences.
+- [ ] Add bundled eval scenarios for memory retrieval, skill selection, plan approval, and safety refusal.
 - [ ] Add optional live-model evals separately from deterministic CI.
 - [ ] Improve plan mode as a public workflow primitive with richer `Plan` and `PlanStep` objects.
 - [ ] Add plan step fields for risk, tools, and acceptance criteria in the public object.
@@ -1383,7 +1389,8 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 - [x] Add built-in permission profiles: read-only, workspace-write, trusted-local, and full-access.
 - [ ] Add custom permission profiles in config.
 - [ ] Add workspace root allowlists.
-- [ ] Add path deny rules for secrets, traces, SQLite stores, dependency folders, and build artifacts.
+- [x] Add default file-read deny rules for secrets, traces, Git metadata, SQLite/runtime state, and private keys.
+- [ ] Extend explicit-read deny rules to dependency folders and build artifacts.
 - [ ] Add network allow/deny domain rules.
 - [ ] Add command prefix rules: allow, prompt, deny.
 - [ ] Add trusted command catalog for low-risk read-only commands.
@@ -1589,7 +1596,7 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 - [ ] Add review against a base branch.
 - [ ] Add review of a selected commit.
 - [ ] Add custom review instructions.
-- [ ] Add eval scripts for agent workflows.
+- [x] Add eval scripts for agent workflows.
 - [ ] Add benchmark prompts for regression testing.
 - [ ] Add trace-based regression replay.
 - [ ] Add golden tests for tool-use loops.

chulk/__init__.py

@@ -52,6 +52,9 @@
     RunStartedPayload,
     RunStatus,
     SafetyError,
+    ShellExecutionDecision,
+    ShellExecutionPolicy,
+    ShellExecutionRequest,
     ToolExecutionError,
     ToolOutputPolicy,
     ToolRetryPolicy,
@@ -129,6 +132,9 @@
     "RunStartedPayload",
     "RunStatus",
     "SafetyError",
+    "ShellExecutionDecision",
+    "ShellExecutionPolicy",
+    "ShellExecutionRequest",
     "Skills",
     "Tool",
     "ToolContext",