petfishframework 0.3.1__tar.gz → 0.3.3__tar.gz

{petfishframework-0.3.1 → petfishframework-0.3.3}/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [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.3.1 → petfishframework-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -34,7 +34,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: 259](https://img.shields.io/badge/tests-259-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 284](https://img.shields.io/badge/tests-284-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -279,7 +279,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              # 259 tests
+uv run pytest              # 284 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.3.1 → petfishframework-0.3.3}/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: 259](https://img.shields.io/badge/tests-259-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 284](https://img.shields.io/badge/tests-284-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -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              # 259 tests
+uv run pytest              # 284 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.3.1 → petfishframework-0.3.3}/docs/api.md

@@ -1,6 +1,6 @@
 # petfishFramework API Reference
 
-This document is the authoritative reference for the public API of `petfishFramework` v0.3.1. 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.3.2. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
 
 ## 1. Overview
 
@@ -1294,3 +1294,154 @@ 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()
+```

{petfishframework-0.3.1 → petfishframework-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "petfishframework"
-version = "0.3.1"
+version = "0.3.3"
 description = "A lightweight runtime framework for reliable, auditable, budget-aware, and permission-aware AI agents."
 readme = "README.md"
 license = "MIT"

{petfishframework-0.3.1 → petfishframework-0.3.3}/src/petfishframework/__init__.py

@@ -15,7 +15,7 @@ from .reasoning import LATS, LLMPlusP, ReAct
 from .reliability.replay import ReplayMode
 from .tools.base import BaseTool
 
-__version__ = "0.3.1"
+__version__ = "0.3.3"
 
 __all__ = [
     "Agent",

{petfishframework-0.3.1 → petfishframework-0.3.3}/src/petfishframework/core/environment.py

@@ -334,7 +334,10 @@ class RuntimeEnvironment(Environment):
             return
         if self.credential_broker is None:
             return
-        token = self.credential_broker.issue_token(tool.name, tool_name=tool.name)
+        credential_name = getattr(tool, "credential_name", None) or tool.name
+        token = self.credential_broker.issue_token(
+            credential_name, tool_name=tool.name, max_uses=1
+        )
         args["_credential_token"] = token
 
     def _prepare_tool_call(self, ref: ToolRef, args: dict) -> tuple[Tool | None, Any]:

{petfishframework-0.3.1 → petfishframework-0.3.3}/src/petfishframework/core/session.py

@@ -133,6 +133,7 @@ class Session:
         self._result = result
 
         self._save_conversation_history(result)
+        self._cleanup_credentials()
 
         self.events.emit(
             "session.end",
@@ -150,6 +151,21 @@ class Session:
         )
         return result
 
+    def _cleanup_credentials(self) -> None:
+        """Clean up scoped credentials at session end."""
+        broker = self.credential_broker
+        if broker is None:
+            return
+
+        cleanup_expired = getattr(broker, "cleanup_expired", None)
+        if callable(cleanup_expired):
+            cleanup_expired()
+
+        revoke_all_for_tool = getattr(broker, "revoke_all_for_tool", None)
+        if callable(revoke_all_for_tool):
+            for tool in self.tools:
+                revoke_all_for_tool(tool.name)
+
     def _save_conversation_history(self, result: Result) -> None:
         """Persist previous history plus the current user/assistant turn."""
         if self.conversation_store is None or self.conversation_id is None:

{petfishframework-0.3.1 → petfishframework-0.3.3}/src/petfishframework/credentials/broker.py

@@ -28,6 +28,7 @@ class CredentialBroker:
         name: str,
         tool_name: str,
         ttl_s: float | None = None,
+        max_uses: int = 0,
     ) -> ScopedToken:
         """Issue a scoped, time-limited token for a specific tool."""
         if name not in self._credentials:
@@ -42,6 +43,7 @@ class CredentialBroker:
             token_id=token_id,
             tool_name=tool_name,
             expires_at=expires_at,
+            max_uses=max_uses,
             _secret=secret,
         )
         self._active_tokens[token_id] = token
@@ -58,6 +60,38 @@ class CredentialBroker:
         """Revoke a token immediately."""
         self._active_tokens.pop(token_id, None)
 
+    def revoke_all_for_tool(self, tool_name: str) -> int:
+        """Revoke all active tokens issued for a specific tool.
+
+        Returns the number of tokens revoked.
+        """
+        token_ids = [
+            token_id
+            for token_id, token in self._active_tokens.items()
+            if token.tool_name == tool_name
+        ]
+        for token_id in token_ids:
+            del self._active_tokens[token_id]
+        return len(token_ids)
+
+    def revoke_all(self) -> int:
+        """Revoke all active tokens.
+
+        Returns the number of tokens revoked.
+        """
+        count = len(self._active_tokens)
+        self._active_tokens.clear()
+        return count
+
+    @property
+    def active_token_count(self) -> int:
+        """Return the number of currently active tokens."""
+        return len(self._active_tokens)
+
+    def list_active_tokens(self) -> list[str]:
+        """Return token IDs for all active tokens (secrets are not exposed)."""
+        return list(self._active_tokens.keys())
+
     def cleanup_expired(self) -> int:
         """Remove all expired tokens. Returns count removed."""
         expired = [

{petfishframework-0.3.1 → petfishframework-0.3.3}/src/petfishframework/credentials/token.py

@@ -5,7 +5,7 @@ import time
 from dataclasses import dataclass, field
 
 
-@dataclass(frozen=True)
+@dataclass
 class ScopedToken:
     """A time-limited, tool-scoped credential token.
 
@@ -15,23 +15,48 @@ class ScopedToken:
     token_id: str          # unique ID
     tool_name: str         # which tool this token is for
     expires_at: float      # unix timestamp
+    max_uses: int = 0      # 0 = unlimited uses
     _secret: str = field(default="", repr=False, compare=False)  # hidden from repr
+    _uses: int = field(default=0, repr=False)
 
     def is_valid(self) -> bool:
         """Check if token is still valid (not expired)."""
         return time.time() < self.expires_at
 
+    def use(self) -> bool:
+        """Consume one use of the token.
+
+        Returns True if the use is allowed, False if max_uses exceeded.
+        """
+        self._uses += 1
+        if self.max_uses > 0 and self._uses > self.max_uses:
+            return False
+        return True
+
+    @property
+    def uses_remaining(self) -> int | None:
+        """Remaining allowed uses, or None when unlimited."""
+        if self.max_uses <= 0:
+            return None
+        return max(0, self.max_uses - self._uses)
+
     def get_secret(self) -> str:
         """Get the actual secret. Only callable by trusted code."""
         if not self.is_valid():
             raise ValueError("Token expired")
+        if not self.use():
+            raise ValueError("Token exceeded max uses")
         return self._secret
 
     def __repr__(self) -> str:
         return (
             f"ScopedToken(token_id={self.token_id!r}, tool_name={self.tool_name!r}, "
-            f"expires_at={self.expires_at}, _secret='[REDACTED]')"
+            f"expires_at={self.expires_at}, max_uses={self.max_uses}, "
+            f"_secret='[REDACTED]')"
         )
 
     def __str__(self) -> str:
-        return f"ScopedToken({self.token_id}, tool={self.tool_name}, valid={self.is_valid()})"
+        return (
+            f"ScopedToken({self.token_id}, tool={self.tool_name}, "
+            f"valid={self.is_valid()}, uses_remaining={self.uses_remaining})"
+        )