connectonion 0.6.4__py3-none-any.whl → 0.6.5__py3-none-any.whl

connectonion/docs/design-decisions/023-trust-policy-system-design.md

@@ -0,0 +1,323 @@
+# Trust Policy System Design: Two-Tier Verification
+
+*February 2025*
+
+After designing the high-level trust architecture (see [020-trust-system-and-network-architecture.md](020-trust-system-and-network-architecture.md)), we needed to answer a harder question: how do we verify requests without burning tokens on every single one?
+
+---
+
+## The Token Problem
+
+Trust verification that uses an LLM costs tokens. Every verification burns money.
+
+A popular agent receives 1000 requests/day. If each verification costs $0.001 on average, that's $1/day just for trust decisions. $365/year spent on "should I trust this?" instead of doing actual work.
+
+Most verifications are trivial. "Is this client on the whitelist?" doesn't need LLM reasoning. "Does this client have a valid invite code?" is a simple lookup.
+
+90% of trust decisions are mechanical. Only 10% need judgment.
+
+---
+
+## Two-Tier Verification
+
+We split trust into two layers:
+
+```
+┌─────────────────────────────────────────────────────┐
+│  FAST RULES (no tokens, instant)                    │
+│                                                     │
+│  - Whitelist check                                  │
+│  - Blocklist check                                  │
+│  - Invite code verification                         │
+│  - Payment verification                             │
+│  - Client level checks (stranger, contact, etc.)   │
+│                                                     │
+│  90% of requests resolved here                      │
+└─────────────────────────────────────────────────────┘
+                      │
+                      │ Only when fast rules can't decide
+                      ▼
+┌─────────────────────────────────────────────────────┐
+│  TRUST AGENT (LLM, burns tokens, rare)              │
+│                                                     │
+│  - Behavior analysis                                │
+│  - Complex promotion decisions                      │
+│  - Edge cases                                       │
+│                                                     │
+│  10% of requests (at most)                          │
+└─────────────────────────────────────────────────────┘
+```
+
+Fast rules handle common cases. LLM handles complex ones. Most requests never reach the LLM.
+
+### Alternatives We Rejected
+
+**All LLM** - every request goes through trust agent:
+- Expensive ($365+/year for active agents)
+- Slow (LLM latency on every request)
+- Overkill for trivial decisions
+
+**All Code** - hardcoded rules only:
+- Inflexible (can't handle edge cases)
+- Brittle (every scenario needs explicit code)
+- No judgment for nuanced decisions
+
+Two tiers gives us cost efficiency (90% free), speed (instant for common cases), flexibility (LLM for edge cases), and progressive complexity.
+
+---
+
+## Client States
+
+We needed a clear model for how trust evolves:
+
+```
+Promotion Chain (earned trust):
+
+┌─────────────┐   verify    ┌─────────────┐  earn trust  ┌─────────────┐
+│  Stranger   │ ──────────► │   Contact   │ ───────────► │  Whitelist  │
+└─────────────┘             └─────────────┘              └─────────────┘
+      │                           │                            │
+      │ block                     │ demote                     │ demote
+      ▼                           ▼                            ▼
+┌─────────────┐             ┌─────────────┐              ┌─────────────┐
+│  Blocklist  │             │  Stranger   │              │   Contact   │
+└─────────────┘             └─────────────┘              └─────────────┘
+
+
+Admin (separate, manual only):
+
+┌─────────────┐  set_admin()   ┌─────────────┐
+│  Any Level  │ ─────────────► │    Admin    │
+└─────────────┘                └─────────────┘
+                                     │
+                               remove_admin()
+                                     │
+                                     ▼
+                               ┌─────────────┐
+                               │  Previous   │
+                               └─────────────┘
+```
+
+### Why Admin Is Separate
+
+Early design had `promote_to_admin()` as part of the chain. Wrong for several reasons:
+
+1. **Different nature**: Admin is about authority, not trust level. A contact can be admin. A whitelist member might not be.
+
+2. **Security**: Auto-promotion to admin is dangerous. Admin should be a deliberate, manual decision.
+
+3. **Audit trail**: Admin changes need explicit `by_admin` tracking. Who granted it? Who revoked it?
+
+4. **Simplicity**: Keeping admin separate makes the promotion chain cleaner.
+
+### The Atomic Functions
+
+Instead of generic `promote()` and `demote()`, we use explicit atomic functions:
+
+```python
+# Promotion (earned)
+promote_to_contact(client_id)    # Stranger → Contact
+promote_to_whitelist(client_id)  # Contact → Whitelist
+
+# Demotion
+demote_to_contact(client_id)     # Whitelist → Contact
+demote_to_stranger(client_id)    # Contact → Stranger
+
+# Blocking
+block(client_id, reason)
+unblock(client_id)
+
+# Admin (manual only)
+set_admin(client_id, by_admin)
+remove_admin(client_id, by_admin)
+```
+
+`promote_to_contact()` is clearer than `promote(client_id, level="contact")`. No ambiguity. No wrong level. Self-documenting.
+
+These functions serve as tools for both host (direct calls for fast rule actions) and trust agent (LLM calls for complex decisions).
+
+---
+
+## YAML + Markdown Format
+
+Trust policies need two things:
+1. Configuration for fast rules (structured, machine-readable)
+2. Instructions for trust agent (natural language, LLM-readable)
+
+We chose YAML frontmatter for config, Markdown body for instructions.
+
+```yaml
+# prompts/trust/careful.md
+---
+fast_rules:
+  - if: has_invite_code
+    action: verify_invite
+    on_success: promote_to_contact
+
+  - if: is_blocked
+    action: deny
+
+  - if: is_whitelist
+    action: allow
+
+  - if: is_stranger
+    action: deny
+
+use_agent:
+  - when: requests > 10
+    reason: "Evaluate for promotion"
+
+cache: 24h
+---
+
+# Trust Agent Policy
+
+You handle complex trust decisions.
+
+## Available Tools
+- promote_to_contact(client_id)
+- block(client_id, reason)
+
+## When to Promote
+Promote stranger to contact when:
+- 10+ requests with good behavior
+- No suspicious patterns
+```
+
+### Why YAML Frontmatter
+
+**Separate config file** (`careful.yaml` + `careful.md`): Two files to maintain, easy to get out of sync.
+
+**JSON in markdown**: Awkward to edit, syntax highlighting breaks.
+
+**Pure YAML file** with policy as multi-line string: Ugly, no markdown preview, harder to write prose.
+
+YAML frontmatter won: single file, standard format (Jekyll, Hugo, Obsidian all use it), editors understand it, clear separation between config and prose.
+
+### Fast Rules Structure
+
+We iterated on the syntax. First version had separate `verify:` and `fast_rules:` sections—confusing overlap, unclear precedence.
+
+Final version: everything under `fast_rules:`. Single place for all rules, order determines precedence.
+
+```yaml
+fast_rules:
+  - if: has_invite_code
+    action: verify_invite
+    on_success: promote_to_contact
+  - if: is_stranger
+    action: deny
+```
+
+---
+
+## TrustAgent Design
+
+### Why Inherit from Agent
+
+Should TrustAgent be a separate class or inherit from Agent?
+
+**Separate interface** (`TrustVerifier` Protocol): New abstraction to learn, can't reuse Agent features (tools, LLM, events), inconsistent with framework.
+
+**Inherit from Agent**: Consistent with framework, all Agent features available, same API users already know.
+
+```python
+class TrustAgent(Agent):
+    # Inherits: system_prompt, tools, input(), etc.
+    # Adds: should_allow(), verify_invite(), etc.
+```
+
+We went with inheritance.
+
+### No Formal Interface
+
+No formal Protocol/ABC. TrustAgent is just an Agent with specific methods.
+
+Python isn't Java—duck typing is idiomatic. If it has `should_allow()`, it's a trust agent. There's only one implementation, so no need to abstract. "TrustAgent inherits from Agent" is clearer than "TrustAgent implements ITrustVerifier which extends Protocol..."
+
+YAGNI. We can add an interface later if we need it.
+
+### Config vs system_prompt
+
+Early design: `TrustAgent(config="prompts/trust/careful.md")`
+
+We changed to: `TrustAgent(system_prompt="prompts/trust/careful.md")`
+
+Every Agent has `system_prompt`. TrustAgent is an Agent. Therefore TrustAgent uses `system_prompt`. The YAML frontmatter is parsed internally and stored as `self.trust_config`, but externally it looks like a normal Agent.
+
+---
+
+## Fixed Routes in Host
+
+### The Dynamic Routes Problem
+
+Early design: trust agent dynamically registers routes based on policy. Policy enables `verify_invite` → route appears. Policy disables it → route disappears.
+
+Problems: unpredictable (which routes exist depends on policy), documentation nightmare, client confusion (consumers don't know what endpoints to call).
+
+### Fixed Routes Solution
+
+Host provides fixed routes. Policy enables/disables behavior, not existence.
+
+```python
+# Always exist:
+/trust/verify/invite     # If disabled → returns clear error
+/trust/verify/payment
+/trust/promote
+/trust/demote
+/trust/block
+/trust/admin/set
+/trust/admin/remove
+/input
+```
+
+Same routes always exist. One set to document. Clients know what's available. No route registration logic.
+
+---
+
+## Security Considerations
+
+### Promote Injection
+
+TrustAgent has `promote_to_contact()` as a tool. During skill testing, a malicious agent could craft prompts to trick the trust agent into calling it—promoting itself, bypassing verification.
+
+Possible solutions (needs design decision):
+1. Skill-test mode with no list management tools
+2. Human confirmation for list changes
+3. Read-only trust agent instance for skill tests
+4. All promotions logged, easy to review/revert
+
+Open TODO. The design acknowledges the risk.
+
+### Why We Accept This Risk (For Now)
+
+Trust agent having tools is the right design. The injection risk is edge-case. Unexpected promotions are auditable and revertable. By documenting it, we ensure it's not forgotten.
+
+---
+
+## Principles
+
+**Simple things simple**: `host(agent, trust="careful")` just works. Full control when needed: `host(agent, trust=custom_trust_agent)`.
+
+**Progressive disclosure**: Level 0 (`host(agent)`) → Level 1 (`trust="strict"`) → Level 2 (`trust="./my_policy.md"`) → Level 3 (`trust=TrustAgent(...)`). Users at level 0 don't see levels 1-3.
+
+**Behavior over identity**: Trust levels (stranger, contact, whitelist) are earned through behavior, not granted through identity. Admin is the exception—identity matters (which existing admin granted it).
+
+**Explicit over implicit**: `promote_to_contact()` not `promote(level="contact")`. `set_admin(by_admin="...")` not `set_admin()`. `verify_invite` in YAML, not automatic route detection.
+
+---
+
+## Summary
+
+| Decision | Choice | Why |
+|----------|--------|-----|
+| Verification approach | Two-tier (fast rules + LLM) | 90% free, 10% smart |
+| Policy format | YAML frontmatter + Markdown | One file, clear separation |
+| Client states | Stranger → Contact → Whitelist (Admin separate) | Clear progression, admin is special |
+| Functions | Atomic (promote_to_contact, not promote) | Self-documenting, no ambiguity |
+| TrustAgent | Inherits from Agent | Consistent API, reuse features |
+| Interface | No formal Protocol | YAGNI, duck typing is fine |
+| Routes | Fixed in host | Predictable, documentable |
+| Config parameter | system_prompt (not config) | Consistent with Agent |
+
+The system balances cost (fast rules are free), flexibility (LLM for edge cases), simplicity (presets for common cases), and power (custom agents for advanced users).

connectonion/docs/network/README.md

@@ -1,6 +1,6 @@
 # Multi-Agent Networking
 
-Connect and collaborate between agents.
+Connect and collaborate between agents with automatic reliability and recovery.
 
 ## Core Concepts
 
@@ -8,6 +8,28 @@ Connect and collaborate between agents.
 - [connect.md](connect.md) - Connect to remote agents with `connect()`
 - [connection.md](connection.md) - Stream events and communicate with clients
 
+## Key Features
+
+### 🔄 Automatic Connection Recovery
+- WebSocket failures automatically fall back to HTTP polling
+- Page refresh doesn't lose your work
+- Results recoverable for 24 hours
+
+### 💓 Built-in Keep-Alive
+- Server sends PING every 30 seconds
+- Client automatically responds with PONG
+- Dead connections detected within 60 seconds
+
+### ⏱️ Extended Timeout
+- Default 10-minute timeout for long-running tasks
+- Configurable per request
+- Works even if agent takes hours (via polling)
+
+### 📦 Session Persistence
+- Results stored server-side for 24 hours
+- Session ID automatically managed
+- localStorage (browser) survives page refreshes
+
 ## Protocol Specifications
 
 - [protocol/agent-relay-protocol.md](protocol/agent-relay-protocol.md) - Agent relay protocol spec

connectonion/docs/network/connect.md

@@ -193,6 +193,141 @@ curl https://oo.openonion.ai/api/relay/agents/0x3d4017c3...
 
 ---
 
+## Connection Reliability & Recovery
+
+The ConnectOnion client (TypeScript/Python) automatically handles connection failures and recovers results seamlessly.
+
+### Automatic Keep-Alive
+
+**Server sends PING every 30 seconds:**
+- Client automatically responds with PONG
+- Keeps connection alive through proxies and firewalls
+- Detects dead connections within 60 seconds
+
+No configuration needed - handled automatically by the SDK.
+
+### Extended Timeout
+
+**Default timeout: 10 minutes** (600 seconds)
+
+Long-running agent tasks have plenty of time to complete:
+
+```typescript
+// TypeScript - default 10 minutes
+const response = await agent.input("Analyze this large dataset");
+
+// Override if needed (5 minutes)
+const response = await agent.input("Quick task", 300000);
+```
+
+### Automatic Session Recovery
+
+If the WebSocket connection fails (network drop, timeout, page refresh), the SDK **automatically polls** the server to retrieve your result:
+
+```
+1. Connection fails or times out
+   ↓
+2. SDK polls GET /sessions/{session_id} every 10s
+   ↓
+3. Server returns result when ready
+   ↓
+4. SDK returns result to your code
+   ↓
+5. You get the result as if nothing happened! ✅
+```
+
+**What this means for you:**
+- ✅ Page refresh during long tasks? No problem.
+- ✅ Network hiccup? Result still delivered.
+- ✅ Connection timeout? Automatically recovered.
+- ✅ Agent takes 15 minutes? You still get the result.
+
+**Configuration (TypeScript):**
+
+```typescript
+const agent = connect("0x123...", {
+  enablePolling: true,        // Default: true
+  pollIntervalMs: 10000,      // Poll every 10s (default)
+  maxPollAttempts: 30         // Try for 5 minutes (default)
+});
+```
+
+**Session persistence:**
+- Results stored server-side for **24 hours**
+- Session ID automatically generated and tracked
+- localStorage used (browser) to survive page refreshes
+
+### Connection Lifecycle
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Normal Operation (WebSocket)                       │
+├─────────────────────────────────────────────────────┤
+│  1. Connect via WebSocket                           │
+│  2. Send INPUT with session_id                      │
+│  3. Receive PING every 30s, respond with PONG       │
+│  4. Receive streaming events                        │
+│  5. Receive OUTPUT (result)                         │
+│  6. Close connection                                │
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│  Recovery Mode (HTTP Polling)                       │
+├─────────────────────────────────────────────────────┤
+│  1. WebSocket fails/timeout                         │
+│  2. SDK polls: GET /sessions/{session_id}           │
+│  3. Server responds: {"status": "running"}          │
+│  4. Wait 10s, poll again                            │
+│  5. Server responds: {"status": "done", "result"}   │
+│  6. SDK returns result to your code                 │
+└─────────────────────────────────────────────────────┘
+```
+
+### Error Scenarios Handled
+
+| Scenario | What Happens |
+|----------|-------------|
+| **Network disconnect** | Automatic polling recovers result |
+| **Page refresh** | Session ID in localStorage, poll for result |
+| **10-minute timeout** | Polling activates, waits for completion |
+| **Server restart** | Polling continues, result available when server back |
+| **Connection drops mid-stream** | Polling recovers final result |
+
+### Best Practices
+
+**1. For long-running tasks:**
+```typescript
+// Just call input() - recovery is automatic
+const response = await agent.input("Process 1GB of data");
+// Works even if it takes 20 minutes
+```
+
+**2. For user feedback:**
+```typescript
+agent.on('reconnecting', () => {
+  showMessage('Connection lost, recovering...');
+});
+
+agent.on('polling', () => {
+  showMessage('Checking for results...');
+});
+```
+
+**3. For critical operations:**
+```typescript
+try {
+  const response = await agent.input("Critical task");
+  console.log("Success:", response.text);
+} catch (error) {
+  // Only fails if:
+  // - Server down for 24+ hours
+  // - Session expired (24h TTL)
+  console.error("Failed:", error);
+}
+```
+
+---
+
 ## Message Protocol
 
 ### INPUT (Client → Relay → Agent)

connectonion/docs/network/host.md

@@ -359,7 +359,7 @@ curl http://localhost:8000/admin/sessions \
 
 ## WebSocket API
 
-WebSocket provides real-time communication. Connection stays alive via ping/pong (automatic).
+WebSocket provides real-time communication with automatic keep-alive and session recovery.
 
 ### Connect
 
@@ -372,7 +372,10 @@ const ws = new WebSocket("ws://localhost:8000/ws");
 ```javascript
 ws.send(JSON.stringify({
   type: "INPUT",
-  prompt: "Translate hello to Spanish"
+  prompt: "Translate hello to Spanish",
+  session: {
+    session_id: "550e8400-e29b-41d4-a716-446655440000"  // Optional: for session continuity
+  }
 }));
 ```
 
@@ -382,8 +385,12 @@ ws.send(JSON.stringify({
 ws.onmessage = (event) => {
   const msg = JSON.parse(event.data);
 
-  if (msg.type === "OUTPUT") {
+  if (msg.type === "PING") {
+    // Server keep-alive check (every 30s)
+    ws.send(JSON.stringify({ type: "PONG" }));
+  } else if (msg.type === "OUTPUT") {
     console.log("Result:", msg.result);
+    console.log("Session ID:", msg.session_id);
   } else if (msg.type === "ERROR") {
     console.error("Error:", msg.message);
   } else {
@@ -397,8 +404,10 @@ ws.onmessage = (event) => {
 
 | Type | Direction | Purpose |
 |------|-----------|---------|
-| INPUT | Client → Agent | Send prompt |
+| INPUT | Client → Agent | Send prompt with optional session |
 | OUTPUT | Agent → Client | Final result + session data |
+| PING | Agent → Client | Connection keep-alive (every 30s) |
+| PONG | Client → Agent | Acknowledge keep-alive |
 | tool_call | Agent → Client | Tool started |
 | tool_result | Agent → Client | Tool completed |
 | thinking | Agent → Client | Agent is processing |
@@ -406,6 +415,66 @@ ws.onmessage = (event) => {
 | approval_needed | Agent → Client | Tool approval required |
 | ERROR | Agent → Client | Error message |
 
+### Connection Keep-Alive
+
+The server automatically sends **PING** messages every 30 seconds to keep the connection alive and detect dead connections:
+
+```javascript
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+
+  if (msg.type === "PING") {
+    // Respond immediately to keep connection alive
+    ws.send(JSON.stringify({ type: "PONG" }));
+  }
+};
+```
+
+**Why it matters:**
+- Keeps connection alive through proxies and firewalls
+- Detects dead connections within 60 seconds
+- Prevents silent connection failures
+
+### Session Recovery
+
+If your WebSocket disconnects (network failure, timeout, page refresh), you can recover the result using the session_id:
+
+**1. Generate and save session_id before connecting:**
+```javascript
+const sessionId = crypto.randomUUID();
+localStorage.setItem('active_session', sessionId);
+```
+
+**2. Include session_id in INPUT:**
+```javascript
+ws.send(JSON.stringify({
+  type: "INPUT",
+  prompt: "Long running task...",
+  session: { session_id: sessionId }
+}));
+```
+
+**3. If connection drops, poll for result:**
+```javascript
+ws.onerror = async () => {
+  // Connection failed, try to recover result
+  const response = await fetch(`http://localhost:8000/sessions/${sessionId}`);
+  const data = await response.json();
+
+  if (data.status === "done") {
+    console.log("Recovered result:", data.result);
+  } else if (data.status === "running") {
+    // Still processing, poll again after delay
+    setTimeout(() => pollForResult(sessionId), 10000);
+  }
+};
+```
+
+**Session lifecycle:**
+- Results stored for **24 hours** (configurable via `result_ttl`)
+- Status can be `"running"` or `"done"`
+- Supports recovery after network failures, timeouts, or page refreshes
+
 ---
 
 ## Design: Stateless Sessions

connectonion/network/__init__.py

@@ -4,7 +4,7 @@ LLM-Note:
   Dependencies: imports from [host/, io/, connect.py, relay.py, announce.py, trust/] | imported by [__init__.py main package, user code] | tested via submodule tests
   Data flow: pure re-export module aggregating networking functionality
   State/Effects: no state
-  Integration: exposes host(agent, port, trust), create_app(), IO/WebSocketIO, SessionStorage/Session, connect(url), RemoteAgent, Response, relay server (relay_connect, serve_loop), announce (create_announce_message), trust (create_trust_agent, TRUST_LEVELS, prompts) | unified networking API surface
+  Integration: exposes host(agent, port, trust), create_app(), IO/WebSocketIO, SessionStorage/Session, connect(url), RemoteAgent, Response, relay server (relay_connect, serve_loop), announce (create_announce_message), trust (TrustAgent) | unified networking API surface
   Performance: trivial
   Errors: none
 Network layer for hosting and connecting agents.
@@ -16,7 +16,7 @@ This module contains:
 - relay: Agent relay server for P2P discovery
 - connect: Multi-agent networking (RemoteAgent)
 - announce: Service announcement protocol
-- trust: Trust verification system
+- trust: Trust verification system (TrustAgent is the single interface)
 """
 
 from .host import host, create_app, SessionStorage, Session
@@ -24,7 +24,7 @@ from .io import IO, WebSocketIO
 from .connect import connect, RemoteAgent, Response
 from .relay import connect as relay_connect, serve_loop
 from .announce import create_announce_message
-from .trust import create_trust_agent, get_default_trust_level, TRUST_LEVELS, get_trust_prompt, TRUST_PROMPTS
+from .trust import TrustAgent, Decision, get_default_trust_level, TRUST_LEVELS, parse_policy
 from . import relay, announce
 
 __all__ = [
@@ -40,11 +40,12 @@ __all__ = [
     "relay_connect",
     "serve_loop",
     "create_announce_message",
-    "create_trust_agent",
+    # Trust (TrustAgent is the single interface)
+    "TrustAgent",
+    "Decision",
     "get_default_trust_level",
     "TRUST_LEVELS",
-    "get_trust_prompt",
-    "TRUST_PROMPTS",
+    "parse_policy",
     "relay",
     "announce",
 ]

connectonion/network/asgi/__init__.py

@@ -23,6 +23,7 @@ def create_app(
     route_handlers: dict,
     storage,
     trust: str = "careful",
+    trust_config: dict | None = None,
     blacklist: list | None = None,
     whitelist: list | None = None,
 ):
@@ -32,6 +33,7 @@ def create_app(
         route_handlers: Dict of route handler functions
         storage: SessionStorage instance
         trust: Trust level (open/careful/strict)
+        trust_config: Parsed YAML config from trust policy (for /info onboard)
         blacklist: Blocked identities
         whitelist: Allowed identities
 
@@ -49,6 +51,7 @@ def create_app(
                 route_handlers=route_handlers,
                 storage=storage,
                 trust=trust,
+                trust_config=trust_config,
                 start_time=start_time,
                 blacklist=blacklist,
                 whitelist=whitelist,