contracts

name	contracts
description	Shared interfaces and contracts between all agents. Every agent MUST read this skill before starting any implementation. This is the single source of truth for all cross-agent boundaries.

Contracts Skill

This skill is mandatory

Before writing any code, every agent must read and understand all contracts defined here. Never deviate from these interfaces without updating this file first.

ToolResult Contract

Every tool must return this exact shape:

@dataclass
class ToolResult:
    success: bool
    output: str
    artifact_path: str
    findings: list[dict]

Finding Contract

@dataclass
class Finding:
    severity: Literal["critical", "high", "medium", "low"]
    type: str        # "sqli", "xss", "open_port", "cve", ...
    target: str
    detail: str
    evidence: str    # artifact path or raw snippet
    timestamp: str

WebSocket Message Contract

All agent steps streamed to frontend must follow this protocol exactly:

{ "type": "think",   "content": "string" }
{ "type": "act",     "tool": "string", "args": {} }
{ "type": "observe", "output": "string", "target": "terminal|editor" }
{ "type": "finding", "severity": "critical|high|medium|low", "detail": "string" }
{ "type": "done",    "summary": "string" }
{ "type": "error",   "message": "string" }

Session Contract

@dataclass
class Session:
    session_id: str
    target: str
    status: Literal["idle", "running", "done", "error"]
    created_at: str
    workspace_path: str

Workspace Directory Contract

Every session workspace MUST follow this exact structure:

workspaces/{session_id}/
├── .agent/
│   ├── plan.json
│   ├── findings.json
│   └── context.json
├── scans/
├── exploits/
├── loot/
├── artifacts/
└── reports/

API Endpoints Contract

POST   /sessions                    → create session
GET    /sessions/{id}               → get session state
DELETE /sessions/{id}               → terminate session
GET    /sessions/{id}/workspace     → get workspace tree
WS     /sessions/{id}/stream        → real-time agent stream
POST   /sessions/{id}/message       → send user message

workspace_context Contract

Injected into LLM before every ReAct step:

{
  "session_id": "string",
  "target": "string",
  "completed_tasks": ["string"],
  "pending_tasks": ["string"],
  "recent_findings": ["Finding"],
  "open_artifacts": ["string"]
}

BaseTool Contract

class BaseTool(ABC):
    name: str
    description: str

    @abstractmethod
    async def run(self, session_id: str, **kwargs) -> ToolResult:
        pass

Violation Rule

If any agent produces code that deviates from these contracts, that code must be rejected and rewritten to comply.