petfishframework 0.3.2__tar.gz → 0.4.0__tar.gz

petfishframework-0.4.0/.sisyphus/plans/v0.4.0-plan.md

@@ -0,0 +1,236 @@
+# petfishFramework v0.4.0 开发计划
+
+> 基于 v0.3.3 状态 + 8 轮用户反馈 + 全部 deferred 项汇总
+> 目标：observability + deterministic replay + 生产化基础
+> 原则：**TDD 先行，pre_release.py 门禁，文档同步作为完成条件**
+
+## v0.4.0 使命
+
+> 让 Agent 运行时可观测（OTel）、可回放（确定性 RERUN/RESUME）、可治理（SIEM export）、可部署（Docker + 部署指南）。
+
+## Deferred 项汇总（从全部反馈中提取）
+
+| 来源 | Deferred 项 | v0.4.0 目标 |
+|---|---|---|
+| v0.3.0 §9.2 | deterministic rerun / resume | ✅ 实现 |
+| v0.3.0 §9.2 | MCP server mode | ⏳ v0.5.0（需完整 MCP server 实现） |
+| v0.3.0 §9.2 | deployment guide | ✅ Dockerfile + 部署文档 |
+| v0.3.0 §9.2 | OpenTelemetry | ✅ OTelSink |
+| v0.3.0 §9.2 | SIEM export | ✅ JSON-Lines trace export |
+| v0.3.0 §P2 | Vault adapter | ✅ HashiCorp Vault adapter (可选) |
+| v0.3.0 §P2 | threat model | ✅ 威胁模型文档 |
+| v0.3.0 §P2 | SBOM | ✅ cyclonedx 生成 |
+| v0.3.0 §P2 | signed release | ✅ sigstore cosign |
+| 多轮 | README Current Limitations 中 planned 项 | 清理为 available |
+
+---
+
+## Phase A: Deterministic Replay (RESUME + RERUN)
+
+### A1: RESUME — 检查点恢复
+
+**目标**：从检查点恢复执行，重注入已记录的模型响应直到检查点，之后继续新鲜调用。
+
+#### TDD 测试先行
+
+```python
+# tests/test_replay_resume.py
+
+def test_resume_replays_recorded_prefix():
+    """RESUME: 重注入检查点前的模型响应。"""
+
+def test_resume_continues_with_fresh_calls():
+    """RESUME: 检查点后用 live environment 新鲜调用。"""
+
+def test_resume_from_mid_session():
+    """RESUME: 从 Session 中间的检查点恢复。"""
+```
+
+#### 实现
+
+- `ResumableEnvironment`（已有 v0.1.x 基础）增强：
+  - `checkpoint_model_idx` / `checkpoint_tool_idx` 参数
+  - 检查点前用 `recording.model_responses[i]` 重注入
+  - 检查点后切换到 `live_env`
+- `Session.checkpoint()` 发出 `session.checkpoint` 事件 + 记录当前 model/tool 索引
+- `Session.resume_from(checkpoint_data)` 工厂方法
+
+### A2: RERUN — 确定性完整重放 + 偏离检测
+
+**目标**：完整重放一个 Session 的所有调用，验证轨迹一致。偏离时报告差异。
+
+#### TDD 测试先行
+
+```python
+# tests/test_replay_rerun.py
+
+def test_rerun_reproduces_identical_trajectory():
+    """RERUN: 完整重放，轨迹完全一致。"""
+
+def test_rerun_detects_model_call_count_divergence():
+    """RERUN: 模型调用次数不一致 → 报告偏离。"""
+
+def test_rerun_detects_tool_result_divergence():
+    """RERUN: 工具结果不一致 → 报告偏离。"""
+```
+
+#### 实现
+
+- `RerunEnvironment`：封装 `RecordingEnvironment` + `ReplayEnvironment`
+  - `rerun() -> RerunResult`：重放 + 比对
+  - `RerunResult.matches: bool` + `divergences: list[str]`
+  - 检测：调用次数偏离、工具名偏离、结果值偏离
+
+---
+
+## Phase B: Observability
+
+### B1: OpenTelemetry Sink
+
+**目标**：Session 事件 → OTel spans，可接入 Jaeger/Zipkin/DataDog。
+
+#### TDD 测试先行
+
+```python
+# tests/test_otel_sink.py
+
+def test_otel_sink_creates_span_per_tool_call():
+    """每个 tool.called 事件创建一个 span。"""
+
+def test_otel_sink_creates_span_per_model_call():
+    """每个 model.called 事件创建一个 span。"""
+
+def test_otel_sink_nests_tool_spans_under_session():
+    """工具 span 嵌套在 session trace 下。"""
+```
+
+#### 实现
+
+- `observability/otel_sink.py` — `OTelSink`:
+  - 接收 EventEmitter 事件
+  - Session → OTel Trace
+  - model.called → span (attributes: model name, tokens, cost)
+  - tool.called/blocked/masked → span (attributes: tool name, effect, duration)
+  - 使用 `opentelemetry-api`（可选依赖：`pip install petfishframework[otel]`）
+  - 无 OTel 安装时降级为 no-op
+
+### B2: SIEM Export (JSON-Lines Trace)
+
+**目标**：结构化事件导出，可导入 Splunk/Elastic/Datadog。
+
+#### TDD 测试先行
+
+```python
+# tests/test_siem_export.py
+
+def test_siem_export_produces_jsonlines():
+    """导出为 JSON-Lines 格式。"""
+
+def test_siem_export_redacts_credentials():
+    """导出中不含 secret。"""
+
+def test_siem_export_includes_policy_version():
+    """每条记录包含 policy_version。"""
+```
+
+#### 实现
+
+- `observability/siem_sink.py` — `SIEMSink`:
+  - 接收事件 → 写入 JSON-Lines 文件/流
+  - 每行：`{"timestamp", "session_id", "event_type", "tool_name", "effect", "executed", "policy_version", "duration_ms"}`
+  - 自动脱敏（复用 event_mask 逻辑）
+
+---
+
+## Phase C: Production Foundation
+
+### C1: Vault Adapter
+
+**目标**：CredentialBroker 支持 HashiCorp Vault 作为 secret 后端。
+
+#### TDD 测试先行
+
+```python
+# tests/test_vault_adapter.py
+
+def test_vault_adapter_reads_secret():
+    """Vault adapter 从 Vault 读取 secret。"""
+    # 使用 mock，不连真实 Vault
+
+def test_vault_adapter_caches_locally():
+    """读取后缓存，减少 Vault 调用。"""
+```
+
+#### 实现
+
+- `credentials/vault_adapter.py` — `VaultCredentialSource`:
+  - `read_secret(path: str) -> str` — 从 Vault 读取
+  - 可选依赖：`hvac` library
+  - 集成到 `CredentialBroker.register_credential_from_vault(path)`
+
+### C2: Dockerfile + 部署指南
+
+**文件**：
+- `Dockerfile` — 多阶段构建
+- `docker-compose.yml` — 开发环境
+- `docs/deployment.md` — 部署指南
+
+### C3: SBOM + Signed Release
+
+- `.github/workflows/publish.yml` 增强：
+  - 生成 SBOM (cyclonedx)
+  - cosign 签名
+- `docs/threat-model.md` — 威胁模型
+
+### C4: 文档 + README 更新
+
+- api.md: 新增 OTel + SIEM + Vault + Replay 章节
+- README: Current Limitations 清理（deterministic replay: Available; OTel: Available）
+- CHANGELOG: v0.4.0
+
+---
+
+## 执行顺序与依赖
+
+```
+A1 (RESUME) → A2 (RERUN)
+    ↓
+B1 (OTel) → B2 (SIEM)
+    ↓
+C1 (Vault) → C2 (Docker) → C3 (SBOM) → C4 (docs)
+```
+
+## 验收标准
+
+| # | 标准 | 验证方法 |
+|---|---|---|
+| V1 | RESUME 从检查点恢复执行 | `test_replay_resume.py` |
+| V2 | RERUN 完整重放 + 偏离检测 | `test_replay_rerun.py` |
+| V3 | OTel sink 生成 spans | `test_otel_sink.py` |
+| V4 | SIEM 导出 JSON-Lines + 脱敏 | `test_siem_export.py` |
+| V5 | Vault adapter 读取 secret（mock） | `test_vault_adapter.py` |
+| V6 | Dockerfile 可构建 | `docker build .` |
+| V7 | SBOM 生成 | CI workflow |
+| V8 | pre_release.py exit 0 | `python scripts/pre_release.py 0.4.0` |
+| V9 | 所有 284+ 现有测试通过 | pytest |
+| V10 | ruff clean | ruff check |
+| V11 | README Current Limitations 清理 | grep "Planned" |
+
+## 不做清单（v0.5.0+）
+
+- ❌ MCP server mode
+- ❌ MCP governance (allowlist, rate limit)
+- ❌ Tool sandbox (subprocess isolation)
+- ❌ Policy hot-reload
+- ❌ Multi-tenant policy namespace
+
+## 新测试预估
+
+| Phase | 测试数 |
+|---|---|
+| A1 RESUME | 3 |
+| A2 RERUN | 3 |
+| B1 OTel | 3 |
+| B2 SIEM | 3 |
+| C1 Vault | 2 |
+| **总计** | **~14 新测试** |

{petfishframework-0.3.2 → petfishframework-0.4.0}/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [0.4.0] — 2026-07-08
+
+### v0.4.0 Production Foundation
+
+#### Phase A+B: Deterministic Replay + Observability
+- Deterministic replay infrastructure (`petfishframework.reliability.replay`):
+  - `RecordingEnvironment` captures every model response, tool call, and retrieval
+  - `ReplayEnvironment` replays recorded calls for deterministic audit
+  - `ResumableEnvironment` replays prefix then switches to live execution
+  - `ReplayMode.AUDIT`, `RESUME`, `RERUN` semantics
+- OpenTelemetry sink (`OTelSink`) — creates spans for model/tool/session events
+- SIEM export (`SIEMSink`) — structured JSON audit events for downstream SIEMs
+
+#### Phase C: Vault Adapter + Deployment + Threat Model
+- `VaultCredentialSource` — reads secrets from HashiCorp Vault with lazy `hvac` import
+- `CredentialBroker.register_credential_from_vault(name, source, path)` — register
+  credentials fetched from Vault
+- Optional dependency group `vault = ["hvac>=1.0"]`
+- `Dockerfile` and `docker-compose.yml` for containerized deployment
+- `docs/deployment.md` — Docker deployment guide, environment variables, volume mounts,
+  credential-broker integration, and security notes
+- `docs/threat-model.md` — attack surface, trust boundaries, threats, mitigations,
+  and fail-closed defaults
+
+#### Documentation Sync
+- `docs/api.md` updated to v0.4.0
+- README: deterministic replay and OTel marked available, roadmap bumped to v0.4.x
+- Test count badge updated to 300
+
+## [0.3.2] — 2026-07-08
+
+### YAML Policy DSL Expansion
+- 13 new condition matchers (total 20): `amount_eq/gte/lte`, generic `field_eq` prefix, `role_count_gte`, `clearance_eq`, `tenant_id_eq`, `classification_eq`, `tags_contains`, `risk_level_eq`, `capabilities_contains`, `requires_credentials`, `session_risk_gt`, `prompt_risk_gt`
+- AND/OR/NOT combinators (`any`/`all`/`not`, nestable in `when:` blocks)
+- Policy schema validation (`policies/validator.py`): validates version, name, rules, effect values
+
+### CredentialBroker Phase 2
+- `BaseTool.credential_name` field — decouple tool name from credential name
+- `ScopedToken.max_uses` + use counting — one-time tokens (`max_uses=1`)
+- `ScopedToken.uses_remaining` property + `use()` method
+- `revoke_all_for_tool(tool_name)` — revoke tokens for a specific tool
+- `revoke_all()` — revoke everything (session-end cleanup)
+- `active_token_count` property + `list_active_tokens()`
+- Environment uses `credential_name` mapping when injecting tokens
+- Session-end credential cleanup
+
+## [0.3.1] — 2026-07-08
+
+### Credential Event Safety (P0 security fix)
+- Event log no longer stores `ScopedToken` objects — replaced with `{"credential_ref": ..., "tool_name": ..., "redacted": True}`
+- Untrusted event sinks cannot access `.get_secret()` via event introspection
+
+### Agent/Session credential_broker API
+- `Agent(credential_broker=broker)` — first-class parameter
+- `Session` passes broker to `RuntimeEnvironment`
+- `RuntimeEnvironment` field renamed `_credential_broker` → `credential_broker`
+
+### Documentation Sync
+- `docs/api.md` version updated
+- README roadmap: v0.3.x (current)
+- README: added YAML Policy Engine + CredentialBroker usage examples
+
 ## [0.3.0] — 2026-07-08
 
 ### v0.3.0 Policy Engine + Credential Broker Integration

petfishframework-0.4.0/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN pip install uv && uv sync --no-dev
+COPY src/ src/
+RUN uv pip install --system .
+ENTRYPOINT ["python", "-m", "petfishframework"]

{petfishframework-0.3.2 → petfishframework-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.3.2
+Version: 0.4.0
 Summary: A lightweight runtime framework for reliable, auditable, budget-aware, and permission-aware AI agents.
 Project-URL: Homepage, https://github.com/kylecui/petfishFramework
 Project-URL: Documentation, https://github.com/kylecui/petfishFramework/tree/master/docs
@@ -26,6 +26,11 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == 'mcp'
 Provides-Extra: openai
 Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: vault
+Requires-Dist: hvac>=1.0; extra == 'vault'
 Description-Content-Type: text/markdown
 
 # petfishFramework
@@ -34,7 +39,7 @@ Description-Content-Type: text/markdown
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 284](https://img.shields.io/badge/tests-259-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 300](https://img.shields.io/badge/tests-300-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -247,8 +252,8 @@ agent = Agent(model=model, reasoning=ReAct(), tools=tools, credential_broker=bro
 ## Roadmap
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
-- **v0.3.x** (current): YAML Policy Engine, CredentialBroker ✅
-- **v0.4.x**: Production hardening, deployment guides
+- **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
+- **v0.4.x** (current): Production hardening, deployment guides, Vault adapter, Docker, threat model ✅
 
 ## Current Limitations
 
@@ -263,8 +268,8 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | PARTIAL_ALLOW | ✅ Enforced (pre-execution arg filtering) |
 | MASK | ✅ Enforced (input mask before + output mask after) |
 | DEGRADE | ✅ Enforced (fallback tool switching) |
-| Session replay | ✅ Audit replay available |
-| Deterministic rerun / resume | 📋 Planned |
+| Session replay / deterministic rerun / resume | ✅ Available |
+| OpenTelemetry + SIEM observability | ✅ Available |
 | MCP client stdio | ✅ Available |
 | MCP server mode | 📋 Planned |
 | Structured output / conversation memory | ✅ Available |
@@ -279,7 +284,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 284 tests
+uv run pytest              # 300 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.3.2 → petfishframework-0.4.0}/README.md

@@ -4,7 +4,7 @@
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 284](https://img.shields.io/badge/tests-259-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 300](https://img.shields.io/badge/tests-300-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -217,8 +217,8 @@ agent = Agent(model=model, reasoning=ReAct(), tools=tools, credential_broker=bro
 ## Roadmap
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
-- **v0.3.x** (current): YAML Policy Engine, CredentialBroker ✅
-- **v0.4.x**: Production hardening, deployment guides
+- **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
+- **v0.4.x** (current): Production hardening, deployment guides, Vault adapter, Docker, threat model ✅
 
 ## Current Limitations
 
@@ -233,8 +233,8 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | PARTIAL_ALLOW | ✅ Enforced (pre-execution arg filtering) |
 | MASK | ✅ Enforced (input mask before + output mask after) |
 | DEGRADE | ✅ Enforced (fallback tool switching) |
-| Session replay | ✅ Audit replay available |
-| Deterministic rerun / resume | 📋 Planned |
+| Session replay / deterministic rerun / resume | ✅ Available |
+| OpenTelemetry + SIEM observability | ✅ Available |
 | MCP client stdio | ✅ Available |
 | MCP server mode | 📋 Planned |
 | Structured output / conversation memory | ✅ Available |
@@ -249,7 +249,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 284 tests
+uv run pytest              # 300 tests
 uv run ruff check src/ tests/
 ```
 

petfishframework-0.4.0/docker-compose.yml

@@ -0,0 +1,8 @@
+version: "3.9"
+services:
+  agent:
+    build: .
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+    volumes:
+      - ./examples:/app/examples

{petfishframework-0.3.2 → petfishframework-0.4.0}/docs/api.md

@@ -1,6 +1,6 @@
 # petfishFramework API Reference
 
-This document is the authoritative reference for the public API of `petfishFramework` v0.3.2. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
+This document is the authoritative reference for the public API of petfishFramework v0.4.0. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
 
 ## 1. Overview
 
@@ -1294,3 +1294,178 @@ decision.policy_name     # "enterprise-expense-policy"
 ```
 
 This lets audit logs trace each decision back to the policy file version that produced it.
+
+### AND/OR/NOT Combinators (v0.3.2)
+
+`when:` blocks support `any`/`all`/`not` combinators:
+
+```yaml
+when:
+  any:
+    - action.tool_name: approve_payment
+    - action.tool_name: transfer_funds
+
+when:
+  not:
+    subject.role_in: [admin]
+
+when:
+  not:
+    any:
+      - subject.role_in: [admin]
+      - subject.clearance_eq: secret
+```
+
+### Full matcher list (v0.3.2)
+
+| Key | Description | Example |
+|---|---|---|
+| `action.tool_name` | Exact tool name match | `approve_payment` |
+| `subject.role_in` | Any role in list matches | `[finance, admin]` |
+| `subject.role_not_in` | No role in list matches | `[intern]` |
+| `subject.role_count_gte` | Subject has ≥ N roles | `2` |
+| `subject.clearance_eq` | Clearance level match | `confidential` |
+| `subject.tenant_id_eq` | Tenant ID match | `acme-corp` |
+| `action.args.amount_gt` | `args["amount"] > value` | `5000` |
+| `action.args.amount_lt` | `args["amount"] < value` | `100` |
+| `action.args.amount_eq` | `args["amount"] == value` | `500` |
+| `action.args.amount_gte` | `args["amount"] >= value` | `1000` |
+| `action.args.amount_lte` | `args["amount"] <= value` | `200` |
+| `action.args.<field>_eq` | Generic field equality (prefix matcher) | `recipient_eq: alice@` |
+| `resource.classification_eq` | Resource classification match | `internal` |
+| `resource.tags_contains` | Resource has any of the listed tags | `[pii, sensitive]` |
+| `tool.side_effect` | Match tool metadata | `true` |
+| `tool.external_egress` | Match tool metadata | `true` |
+| `tool.requires_credentials` | Match tool metadata | `true` |
+| `tool.risk_level_eq` | Match risk level | `high` |
+| `tool.capabilities_contains` | Tool has any of listed capabilities | `[network, fs:write]` |
+| `context.session_risk_gt` | `context.session_risk > value` | `0.5` |
+| `context.prompt_risk_gt` | `context.prompt_risk > value` | `0.7` |
+
+Unknown condition keys are fail-closed (return `False`).
+
+### Policy schema validation (v0.3.2)
+
+```python
+from petfishframework.policies.validator import validate_policy, validate_policy_file
+
+errors = validate_policy_file("enterprise-expense.yaml")
+if errors:
+    for err in errors:
+        print(f"  - {err}")
+```
+
+Checks: version exists, name exists, rules is a list, each rule has name + valid effect, priority is integer.
+
+---
+
+## 16. Credential Broker
+
+### CredentialBroker
+
+```python
+from petfishframework.credentials import CredentialBroker
+
+broker = CredentialBroker(default_ttl_s=3600)
+broker.register_credential("github_app", os.environ["GITHUB_TOKEN"])
+broker.register_credential("db_connection", "postgres://...")
+```
+
+| Method | Description |
+|---|---|
+| `register_credential(name, secret)` | Register a real credential |
+| `issue_token(name, tool_name, ttl_s=None, max_uses=0)` | Issue a scoped, time-limited token |
+| `validate_token(token_id)` | Check if token is valid (not expired, not revoked) |
+| `revoke_token(token_id)` | Revoke a single token |
+| `revoke_all_for_tool(tool_name)` | Revoke all tokens for a specific tool (v0.3.2) |
+| `revoke_all()` | Revoke all active tokens (session-end cleanup) (v0.3.2) |
+| `cleanup_expired()` | Remove expired tokens, returns count removed |
+| `active_token_count` | Property: number of active tokens (v0.3.2) |
+| `list_active_tokens()` | Return list of active token_ids (v0.3.2) |
+
+### ScopedToken
+
+```python
+token = broker.issue_token("github_app", tool_name="github_tool", max_uses=1)
+token.token_id       # unique ID
+token.tool_name      # "github_tool"
+token.is_valid()     # True (not expired, uses remaining)
+token.get_secret()   # returns the actual secret (consumes one use if max_uses set)
+token.uses_remaining # remaining uses (v0.3.2)
+```
+
+`__repr__` and `__str__` never expose the secret:
+```python
+repr(token)  # "ScopedToken(token_id='abc...', tool_name='github_tool', ...)"
+str(token)   # "ScopedToken(abc..., tool=github_tool, valid=True)"
+```
+
+### Agent Integration
+
+```python
+agent = Agent(
+    model=model,
+    reasoning=ReAct(),
+    tools=tools,
+    credential_broker=broker,
+)
+# Tools with requires_credentials=True receive a ScopedToken in args["_credential_token"]
+```
+
+### Tool credential_name (v0.3.2)
+
+```python
+@dataclass
+class GitHubTool(BaseTool):
+    name: str = "github_create_issue"
+    requires_credentials: bool = True
+    credential_name: str = "github_app"  # maps to broker credential name
+```
+
+### Event Log Safety
+
+ScopedToken objects are **never** stored in event data. The Environment replaces them with:
+
+```python
+{"credential_ref": "token_id", "tool_name": "github_tool", "redacted": True}
+```
+
+### One-time Tokens (v0.3.2)
+
+```python
+token = broker.issue_token("secret_key", tool_name="signing_tool", max_uses=1)
+token.get_secret()  # works, uses_remaining becomes 0
+token.get_secret()  # raises ValueError("max uses exceeded")
+```
+
+### Session-End Cleanup
+
+```python
+# In Session._finalize_run():
+if session.credential_broker:
+    session.credential_broker.cleanup_expired()
+```
+
+### Vault Integration (v0.4.0)
+
+```python
+from petfishframework.credentials import CredentialBroker, VaultCredentialSource
+
+broker = CredentialBroker()
+source = VaultCredentialSource(
+    vault_url="https://vault.example.com",
+    token="hvs.CAES...",
+)
+broker.register_credential_from_vault("openai", source, path="secrets/openai")
+```
+
+`VaultCredentialSource` performs a lazy import of `hvac` and raises a clear
+`ImportError` if the optional dependency is missing. The secret is read once and
+cached locally for the lifetime of the source; subsequent reads of the same
+path do not call Vault again.
+
+Install the optional dependency with:
+
+```bash
+pip install petfishframework[vault]
+```