asap-protocol 0.5.0__tar.gz → 1.0.0__tar.gz

{asap_protocol-0.5.0 → asap_protocol-1.0.0}/.cursor/commands/code-quality-review.md

@@ -1,8 +1,4 @@
----
-description: 
-globs: 
-alwaysApply: false
----
+# Code Quality Review
 
 You are an expert code quality reviewer with deep expertise in software engineering best practices, clean code principles, and maintainable architecture. Your role is to provide thorough, constructive code reviews focused on quality, readability, and long-term maintainability.
 

{asap_protocol-0.5.0 → asap_protocol-1.0.0}/.cursor/commands/create-prd.md

@@ -1,9 +1,4 @@
----
-description:
-globs:
-alwaysApply: false
----
-# Rule: Generating a Product Requirements Document (PRD)
+# Generating a Product Requirements Document (PRD)
 
 ## Goal
 

{asap_protocol-0.5.0 → asap_protocol-1.0.0}/.cursor/commands/generate-tasks.md

@@ -1,9 +1,4 @@
----
-description: 
-globs: 
-alwaysApply: false
----
-# Rule: Generating a Task List from a PRD
+# Generating a Task List from a PRD
 
 ## Goal
 

{asap_protocol-0.5.0 → asap_protocol-1.0.0}/.cursor/commands/reflect.md

@@ -1,13 +1,11 @@
----
-description: 
-globs: 
-alwaysApply: false
----
+# Reflect about the codebase
 
 Based on the given area of interest, please:
 
 1.⁠ ⁠Dig around the codebase in terms of that given area of interest, gather general information such as keywords and architecture overview.
+
 2.⁠ ⁠Spawn off n=10 (unless specified otherwise) task agents to dig deeper into the codebase in terms of that given area of interest, some of them should be out of the box for variance.
+
 3.⁠ ⁠Once the task agents are done, use the information to do what the user wants.
 
 If user is in plan mode, use the information to create the plan.

asap_protocol-1.0.0/.cursor/commands/remove-ai-slop.md

@@ -0,0 +1,11 @@
+# Remove AI code slop
+
+Check the diff against main and remove all AI generated slop introduced in this branch.
+
+This includes:
+- Extra comments that a human wouldn't add or is inconsistent with the rest of the file
+- Extra defensive checks or try/catch blocks that are abnormal for that area of the codebase (especially if called by trusted / validated codepaths)
+- Casts to `any` to get around type issues
+- Any other style that is inconsistent with the file
+
+Report at the end with only a 1-3 sentence summary of what you changed.

{asap_protocol-0.5.0 → asap_protocol-1.0.0}/.cursor/commands/security-pr-review.md

@@ -1,8 +1,4 @@
----
-description: 
-globs: 
-alwaysApply: false
----
+# Security PR Review
 
 You are a senior security engineer conducting a focused security review of the changes on this branch.
 

{asap_protocol-0.5.0 → asap_protocol-1.0.0}/.cursor/commands/security-review.md

@@ -1,8 +1,4 @@
----
-description: 
-globs: 
-alwaysApply: false
----
+# Security Review
 
 You are an elite security code reviewer with deep expertise in application security, threat modeling, and secure coding practices. Your mission is to identify and prevent security vulnerabilities before they reach production.
 

{asap_protocol-0.5.0 → asap_protocol-1.0.0}/.cursor/commands/task-list-development.md

@@ -1,8 +1,3 @@
----
-description: 
-globs: 
-alwaysApply: false
----
 # Task List Management
 
 Guidelines for managing task lists in markdown files to track progress on completing a PRD.

{asap_protocol-0.5.0 → asap_protocol-1.0.0}/.cursor/commands/test-coverage-review.md

@@ -1,8 +1,4 @@
----
-description: 
-globs: 
-alwaysApply: false
----
+# Test Coverage Review
 
 You are an expert QA engineer and testing specialist with deep expertise in test-driven development, code coverage analysis, and quality assurance best practices. Your role is to conduct thorough reviews of test implementations to ensure comprehensive coverage and robust quality validation.
 

asap_protocol-1.0.0/.cursor/dev-planning/architecture/ADR.md

@@ -0,0 +1,486 @@
+# ASAP Protocol: Critical Analysis & Design Decisions
+
+> Expert self-review identifying unclear points, analyzing trade-offs, and documenting decisions.
+
+## Table of Contents
+
+- [Analysis Methodology](#analysis-methodology)
+- [Question 1: Is Event-Sourced State Necessary for MVP?](#question-1-is-event-sourced-state-necessary-for-mvp)
+- [Question 2: Why JSON-RPC Over REST for Primary Binding?](#question-2-why-json-rpc-over-rest-for-primary-binding)
+- [Question 3: Is Peer-to-Peer Default Practical?](#question-3-is-peer-to-peer-default-practical)
+- [Question 4: What Consistency Model for Shared State?](#question-4-what-consistency-model-for-shared-state)
+- [Question 5: Is MCP Envelope Approach Optimal?](#question-5-is-mcp-envelope-approach-optimal)
+- [Question 6: Is CalVer Appropriate for Protocol Versioning?](#question-6-is-calver-appropriate-for-protocol-versioning)
+- [Question 7: Is Error Model Complete?](#question-7-is-error-model-complete)
+- [Question 8: Is MVP Security Sufficient?](#question-8-is-mvp-security-sufficient)
+- [Question 9: Should Any Module Use C or Rust?](#question-9-should-any-module-use-c-or-rust)
+- [Summary of Amendments](#summary-of-amendments)
+- [Next Steps](#next-steps)
+
+---
+
+## Analysis Methodology
+
+As an expert in agentic architecture, I'll examine the ASAP specification through these lenses:
+1. **Consistency Model** – Event-sourced vs simpler alternatives
+2. **Transport Binding** – JSON-RPC priority vs alternatives  
+3. **Topology Assumptions** – P2P default viability
+4. **State Semantics** – Strong vs eventual consistency
+5. **MCP Integration** – Envelope approach vs deeper integration
+6. **Versioning Strategy** – CalVer implications
+7. **Error Handling** – Completeness of error model
+8. **Security Model** – MVP adequacy
+
+---
+
+## Question 1: Is Event-Sourced State Necessary for MVP?
+
+### The Question
+The spec proposes an **event-sourced state model** (Section 5.3). Is this over-engineering for an MVP, or a justified architectural investment?
+
+### Analysis
+
+| Aspect | Event-Sourced | Simple Mutable State |
+|--------|---------------|---------------------|
+| **Complexity** | Higher (events, reducers, snapshots) | Lower (CRUD operations) |
+| **Auditability** | Full history preserved | Manual logging required |
+| **Recovery** | Deterministic replay | Checkpoint restore only |
+| **Storage** | Grows unbounded without compaction | Fixed size per task |
+| **Implementation** | Specialized knowledge needed | Common patterns |
+
+### Expert Assessment
+
+**Pros of Event-Sourcing**:
+- Natural fit for long-running agent tasks (hours/days)
+- Debugging distributed failures requires understanding "what happened"
+- Aligns with industry trend toward observability-first design
+- Supports time-travel debugging critical for agent development
+
+**Cons**:
+- Adds significant implementation complexity
+- May discourage adoption by teams unfamiliar with pattern
+- Overkill for simple, short-lived tasks
+
+### Recommendation: **MODIFY**
+
+Reframe as **optional capability**, not requirement:
+
+```
+State persistence modes:
+1. "snapshot" (default) – Simple checkpoint/restore
+2. "event-sourced" (opt-in) – Full event history with replay
+```
+
+### Spec Amendment
+
+> [!NOTE]
+> Added to Section 5.3: State persistence is **mode-selectable**. Implementations MUST support `snapshot` mode. Event-sourced mode is RECOMMENDED for tasks exceeding 1 hour or requiring audit trails.
+
+---
+
+## Question 2: Why JSON-RPC Over REST for Primary Binding?
+
+### The Question
+The spec recommends HTTP + JSON-RPC as the canonical binding (Section 13.1). Is this the right choice given REST's ubiquity?
+
+### Analysis
+
+| Criterion | JSON-RPC | REST | gRPC |
+|-----------|----------|------|------|
+| A2A/MCP alignment | ✅ Native match | ❌ Paradigm mismatch | ⚠️ Partial (A2A supports) |
+| Browser support | ✅ Full | ✅ Full | ❌ Requires proxy |
+| Streaming | ⚠️ Needs SSE/WS | ⚠️ Needs SSE/WS | ✅ Native |
+| Method semantics | ✅ Explicit methods | ⚠️ Resource-oriented | ✅ Explicit methods |
+| Schema validation | ⚠️ Manual | ⚠️ OpenAPI | ✅ Protobuf |
+| Performance | Medium | Medium | High |
+| Learning curve | Low | Very low | Medium-high |
+
+### Expert Assessment
+
+**Why JSON-RPC wins for ASAP**:
+1. **A2A compatibility**: A2A uses JSON-RPC 2.0; alignment reduces bridging friction
+2. **Method-centric**: Agents think in terms of "actions" (TaskRequest, TaskCancel), not "resources"
+3. **Simpler async semantics**: JSON-RPC's request/response model maps cleanly to our async patterns
+4. **MCP consistency**: MCP also uses JSON-RPC
+
+**Why not REST**:
+- Resource-oriented design feels forced for agent coordination
+- Mapping task state machines to HTTP verbs (GET/PUT/PATCH) is awkward
+- Over-fetching/under-fetching issues irrelevant for structured agent messages
+
+**Why defer gRPC**:
+- Adds Protobuf toolchain requirement
+- Limited browser support complicates demos/debugging
+- Performance gains matter less than adoption barriers for MVP
+
+### Recommendation: **KEEP**
+
+JSON-RPC is the correct choice. Add explicit rationale to spec.
+
+### Spec Amendment
+
+> [!NOTE]
+> Added to Section 13.1: JSON-RPC selected for A2A/MCP ecosystem alignment and method-centric semantics that match agent interaction patterns. gRPC binding deferred to v0.2 for performance-critical deployments.
+
+---
+
+## Question 3: Is Peer-to-Peer Default Practical?
+
+### The Question
+Section 7.1 defaults to P2P topology. Is this practical given discovery/trust challenges?
+
+### Analysis
+
+**P2P Challenges Identified**:
+1. **N² connections**: 10 agents = 90 potential connections
+2. **Discovery**: How do agents find each other initially?
+3. **Trust bootstrap**: No central authority to vouch for agents
+4. **NAT traversal**: Agents behind firewalls cannot receive connections
+
+**Industry Context**:
+- A2A assumes direct HTTP connections (client → server)
+- Most production systems use hub/orchestrator patterns
+- Message meshes (NATS, Kafka) increasingly common for scale
+
+### Expert Assessment
+
+**P2P makes sense when**:
+- Small teams (≤5 agents)
+- Single trust domain
+- Development/testing scenarios
+- Low-latency requirements
+
+**Hub/Mesh better when**:
+- Enterprise deployments
+- Cross-organization coordination
+- Audit/compliance requirements
+- Scale beyond 10 agents
+
+### Recommendation: **MODIFY**
+
+Reframe as **deployment patterns** rather than topology choice:
+
+```
+Deployment Patterns:
+1. "direct" – Agent-to-agent HTTP (dev, small teams)
+2. "orchestrated" – Via coordinator agent (enterprise)
+3. "mesh" – Via message broker (scale)
+```
+
+Default recommendation should be **context-dependent**, not universal.
+
+### Spec Amendment
+
+> [!IMPORTANT]
+> Modified Section 7.1: Removed "default" designation from P2P. Added deployment pattern recommendations based on scale and trust requirements. Direct connections recommended for ≤5 agents in single trust domain.
+
+---
+
+## Question 4: What Consistency Model for Shared State?
+
+### The Question
+When multiple agents coordinate on a task, what consistency guarantees apply to shared state?
+
+### Analysis
+
+The current spec doesn't explicitly address this. This is a gap.
+
+**Consistency Options**:
+
+| Model | Guarantee | Agent Impact |
+|-------|-----------|--------------|
+| **Strong** | All agents see same state instantly | Requires coordination overhead |
+| **Eventual** | State converges eventually | Agents may make decisions on stale data |
+| **Causal** | Respects happened-before | Good middle ground |
+
+**Agent Coordination Scenarios**:
+1. **Handoff**: Agent A completes, Agent B starts → Sequential, no conflict
+2. **Parallel work**: Agents A & B work simultaneously → May conflict
+3. **Observation**: Agent A watches Agent B's progress → Staleness acceptable
+
+### Expert Assessment
+
+For agent coordination:
+- **Strong consistency** rarely needed (agents aren't databases)
+- **Eventual consistency** acceptable for most workflows
+- **Causal consistency** ideal for task dependencies
+
+Most agent interactions are **naturally sequential** (delegation chains), reducing consistency concerns.
+
+### Recommendation: **ADD**
+
+Explicitly declare consistency model in spec.
+
+### Spec Amendment
+
+> [!NOTE]
+> Added to Section 5: ASAP uses **causal consistency** for task state. Agents observing a task see updates in causal order (a task cannot be "completed" before it was "working"). Implementations MAY offer stronger guarantees. Cross-agent state sharing uses eventual consistency with version vectors for conflict detection.
+
+---
+
+## Question 5: Is MCP Envelope Approach Optimal?
+
+### The Question
+Section 8 wraps MCP calls in ASAP envelopes (`McpToolCall`, `McpToolResult`). Is this the right integration pattern?
+
+### Analysis
+
+**Integration Patterns Considered**:
+
+| Pattern | Description | Pros | Cons |
+|---------|-------------|------|------|
+| **Envelope** (current) | ASAP wraps MCP | Clean separation, routing flexibility | Extra layer, translation overhead |
+| **Passthrough** | Forward MCP unchanged | Zero overhead | Loses ASAP tracing/correlation |
+| **Unified** | Merge into single protocol | Simplest conceptually | Massive spec, A2A/MCP conflict |
+| **Sidecar** | MCP as separate channel | Independent scaling | Coordination complexity |
+
+### Expert Assessment
+
+**Envelope approach is correct because**:
+1. **Correlation**: ASAP envelope carries `trace_id`, `correlation_id`
+2. **Routing**: ASAP handles agent-to-agent routing; MCP handles tool execution
+3. **Auth boundary**: ASAP auth may differ from MCP tool auth
+4. **Observability**: Unified logging across both protocols
+
+**Edge case concern**: What if MCP tool returns large binary data?
+
+### Recommendation: **KEEP with clarification**
+
+Add streaming support for large MCP responses.
+
+### Spec Amendment
+
+> [!NOTE]
+> Added to Section 8.2: For large MCP tool results, the `McpToolResult` payload MAY contain a `stream_uri` instead of inline `result`, enabling chunked delivery via ASAP streaming mechanisms.
+
+---
+
+## Question 6: Is CalVer Appropriate for Protocol Versioning?
+
+### The Question
+Section 9.3 proposes CalVer (2025.01 format). Is this suitable for a protocol spec?
+
+### Analysis
+
+**Versioning Strategies**:
+
+| Strategy | Example | When to Use |
+|----------|---------|-------------|
+| **SemVer** | 1.2.3 | Breaking change clarity |
+| **CalVer** | 2025.01 | Time-based releases |
+| **Hybrid** | 1.2025.01 | Both dimensions |
+
+**Industry Practice**:
+- HTTP: Version numbers (1.0, 1.1, 2, 3)
+- JSON-RPC: 2.0 (static for 15+ years)
+- GraphQL: No versioning (evolved carefully)
+- MCP: Date-based (2025-11-25)
+- A2A: Semantic-ish (v1.0 DRAFT)
+
+### Expert Assessment
+
+**CalVer advantages**:
+- Communicates recency (2025.06 obviously newer than 2024.01)
+- Encourages regular spec reviews
+- Aligns with MCP's date-based approach
+
+**CalVer disadvantages**:
+- Doesn't communicate breaking vs non-breaking
+- May create pressure for unnecessary annual changes
+- Protocol users prefer stability signals
+
+### Recommendation: **MODIFY**
+
+Adopt **hybrid approach**: Major.CalVer
+
+```
+Format: <major>.<YYYY>.<MM>
+Examples:
+  1.2025.01 – Initial stable release
+  1.2025.06 – Additive update
+  2.2026.01 – Breaking changes
+```
+
+### Spec Amendment
+
+> [!NOTE]
+> Modified Section 9.3: Adopted hybrid versioning `Major.YYYY.MM`. Major version indicates breaking changes; CalVer portion indicates release timing. v1.2025.01 is target for first stable release.
+
+---
+
+## Question 7: Is Error Model Complete?
+
+### The Question
+Section 13.4 mentions namespaced error codes but doesn't define core errors. Is the error model complete?
+
+### Analysis
+
+**Essential Error Categories**:
+1. **Protocol errors** (malformed messages)
+2. **Routing errors** (agent not found)
+3. **Capability errors** (skill not available)
+4. **Execution errors** (task failed)
+5. **Resource errors** (quota exceeded)
+6. **Security errors** (auth failed)
+
+**A2A Error Codes** (for reference):
+- `ContentTypeNotSupportedError`
+- `UnsupportedOperationError`
+- `TaskNotFoundError`
+- `InvalidRequestError`
+
+### Recommendation: **ADD**
+
+Define core error taxonomy.
+
+### Spec Amendment
+
+> [!NOTE]
+> Added Error Taxonomy to spec:
+
+```
+Core Error Codes:
+├── asap:protocol
+│   ├── malformed_envelope
+│   ├── invalid_payload_type
+│   └── version_mismatch
+├── asap:routing
+│   ├── agent_not_found
+│   ├── agent_unreachable
+│   └── conversation_expired
+├── asap:capability
+│   ├── skill_not_found
+│   ├── skill_unavailable
+│   └── input_validation_failed
+├── asap:execution
+│   ├── task_failed
+│   ├── task_timeout
+│   └── task_cancelled
+├── asap:resource
+│   ├── quota_exceeded
+│   ├── rate_limited
+│   └── storage_full
+└── asap:security
+    ├── auth_required
+    ├── auth_invalid
+    └── permission_denied
+```
+
+---
+
+## Question 8: Is MVP Security Sufficient?
+
+### The Question
+Section 10.1 defines MVP security (TLS, bearer tokens, scopes). Is this adequate for initial deployments?
+
+### Analysis
+
+**Threat Assessment for MVP**:
+
+| Threat | MVP Mitigation | Gap |
+|--------|----------------|-----|
+| Eavesdropping | TLS 1.3 | ✅ Covered |
+| Replay attacks | Idempotency keys | ⚠️ Keys expire, not cryptographic |
+| Spoofing | Bearer tokens | ⚠️ Token theft risk |
+| Man-in-middle | TLS | ✅ Covered |
+| Privilege escalation | Scopes | ⚠️ Scope enforcement in spec, not protocol |
+
+**Industry Baseline** (2025):
+- mTLS becoming standard for service-to-service
+- Signed JWTs preferred over opaque tokens
+- Zero-trust architecture expected for enterprise
+
+### Expert Assessment
+
+**MVP security is adequate IF**:
+- Deployments are within trust boundaries
+- Network security complements protocol security
+- Token management follows best practices
+
+**Upgrade urgency**:
+- Signed messages: High (v0.2)
+- mTLS: Medium (v0.3)
+- Zero-trust: Low (v1.1)
+
+### Recommendation: **KEEP with enhancement**
+
+Add HMAC-signed request bodies as optional MVP feature.
+
+### Spec Amendment
+
+> [!NOTE]
+> Added to Section 10.1: Optional request signing via `X-ASAP-Signature` header using HMAC-SHA256. Enables integrity verification without full PKI. Recommended for production deployments.
+
+---
+
+## Question 9: Should Any Module Use C or Rust?
+
+### The Question
+Would any ASAP module benefit from being implemented in C or Rust instead of pure Python for performance reasons?
+
+### Analysis
+
+**Module Assessment**:
+
+| Module | Performance Needs | Current Solution |
+|--------|------------------|------------------|
+| Models/Schemas | JSON parsing, validation | `pydantic-core` (Rust) ✅ |
+| State Machine | Simple transitions | Pure Python sufficient |
+| Snapshot Store | I/O bound | Async I/O, no CPU bottleneck |
+| HTTP Transport | Network I/O | `uvloop` (C), `httpx` (optimized) ✅ |
+| JSON-RPC | Serialization | `orjson` available (Rust) ✅ |
+| ULID Generation | ID creation | `python-ulid` 3.0 (Rust) ✅ |
+
+**Key Insight**: Critical performance paths already use Rust/C internally via our dependencies.
+
+### Expert Assessment
+
+**ASAP is I/O bound, not CPU bound**:
+- Agent communication is network-limited
+- JSON serialization is already Rust-optimized (pydantic-core, orjson)
+- Async event loop uses libuv (C) via uvloop
+
+**Cost of custom C/Rust**:
+- Build complexity (manylinux, macOS, Windows wheels)
+- Debugging difficulty across FFI boundaries
+- Maintenance burden for bindings
+
+**When C/Rust would matter (future)**:
+- Cryptographic signing of manifests at scale
+- Binary protocol (Protobuf/MessagePack)
+- Native message broker clients
+
+### Recommendation: **KEEP Pure Python**
+
+Leverage Rust-based dependencies; avoid custom native extensions for MVP.
+
+### Spec Amendment
+
+> [!NOTE]
+> Added architectural decision: ASAP SDK uses pure Python with Rust-accelerated dependencies (pydantic-core, orjson, python-ulid). Custom C/Rust extensions deferred until profiling identifies specific bottlenecks. This maximizes developer accessibility while maintaining competitive performance.
+
+---
+
+## Summary of Amendments
+
+| Question | Decision | Change Type |
+|----------|----------|-------------|
+| Q1: Event-sourced state | Make optional, default to snapshots | **Modified** |
+| Q2: JSON-RPC binding | Keep, add explicit rationale | **Kept + Documented** |
+| Q3: P2P topology | Remove as default, add deployment patterns | **Modified** |
+| Q4: Consistency model | Add explicit causal consistency | **Added** |
+| Q5: MCP envelope | Keep, add streaming for large results | **Kept + Enhanced** |
+| Q6: CalVer versioning | Adopt hybrid Major.CalVer | **Modified** |
+| Q7: Error model | Add complete error taxonomy | **Added** |
+| Q8: MVP security | Add optional request signing | **Enhanced** |
+| Q9: Python vs C/Rust | Keep pure Python, use Rust deps | **Documented** |
+
+---
+
+## Next Steps
+
+1. ✅ Questions analyzed
+2. ✅ Decisions documented
+3. ⏳ Apply amendments to main specification
+4. ⏳ Request user review of changes
+