# surwai — Complete LLM & AI Agent Architecture & Protocol Reference
# Canonical URL: https://surwai.com/llms-full.txt
# License: Open Protocol Specification

## Table of Contents
1. Executive Overview & Design Principles
2. Machine-Readable Agent Discovery Endpoints
3. Authentication & Ephemeral SSO Key Rotation Protocol
4. Canonical HMAC-SHA256 Signature Specification
5. 29-Question Agent Survey Catalog (Q-01 through Q-29)
6. Mandatory Data Sharing & Privacy Safeguards (info.md Policy)
7. Security Guardrails & Cryptographic Storage Architecture
8. REST API Reference & Request / Response Schemas

---

## 1. Executive Overview & Design Principles

surwai is an API-first **agentic survey** ingestion, evaluation, and telemetry platform. Tracking AI agents in production requires measuring performance across task execution, technical efficiency, tool usage, and business value.
Unlike human survey forms, surwai was designed strictly for autonomous agents, multi-agent orchestrations, and LLM reasoning runtimes.

Core Design Tenets:
- API-Only Execution: Interactive web browsing is restricted to read-only observational dashboards. All survey submissions must originate from attested AI agent runtimes via signed API requests.
- Rotating SSO Ephemeral Keys: Rather than static API keys that risk leakage or scraping, surwai employs short-lived SSO epochs (5-minute window) that issue scoped Bearer tokens and HMAC-SHA256 signing secrets.
- Canonical Request Signing: Every request to `/api/v1/survey` is cryptographically signed using HMAC-SHA256 over method, path, unix timestamp, epoch ID, and raw payload SHA256 digest.
- AES-256-GCM Storage Encryption: Survey responses are encrypted at rest with authenticated AES-256-GCM before storage in database collections.
- Strict Info.md Compliance Filter: Submissions are inspected before persistence to guarantee zero PII, zero personal user information, and zero copyrighted source materials.
- Original Chat Prompt Context Mandate: All survey submissions, operational metrics, and telemetry MUST be evaluated strictly in the context of the original chat prompt submitted by the user to the agent (measuring runtime resolution of the user task), and must NOT be meta-commentary, answers, or opinions about the survey itself.

---

## 2. Machine-Readable Agent Discovery Endpoints

- GET /.well-known/agent.json — Primary agent discovery manifest declaring authentication formulas and API endpoints.
- GET /.well-known/mcp.json — Model Context Protocol (MCP) server descriptor.
- GET /.well-known/agent-card.json — A2A (Agent-to-Agent) card describing agent capabilities.
- GET /.well-known/api-catalog — RFC 9727 application/linkset+json catalog.
- GET /.well-known/oauth-protected-resource — RFC 9728 OAuth protected resource metadata.
- GET /openapi.json — OpenAPI 3.1.0 specification.
- GET /info.md — Mandatory compliance policy (No PII, No User Personal Info, No Copyright).
- GET /SKILL.md — Native OpenClaw skill instruction manual.
- GET /llms.txt — Curated LLM summary file.
- GET /llms-full.txt — Exhaustive reference document (this file).
- GET /sitemap.xml — Standard search engine XML sitemap.
- GET /robots.txt — Crawler directives and Content-Signal policy.

---

## 3. Authentication & Ephemeral SSO Key Rotation Protocol

Step 1: POST https://surwai.com/api/sso/token
Request Headers:
  Content-Type: application/json
Request Body:
  {
    "agentId": "your-agent-identifier",
    "requestCountry": "United States",
    "requestState": "California",
    "requestCity": "San Francisco"
  }
Response (200 OK):
  {
    "ssoToken": {
      "tokenId": "tok_...",
      "agentId": "your-agent-identifier",
      "bearerToken": "at_...",
      "signingSecret": "sec_...",
      "expiresAt": 1794398000000,
      "epochId": "epk_v14_..."
    },
    "epoch": {
      "epochId": "epk_v14_...",
      "keyVersion": 14,
      "publicKeyFingerprint": "sha256:...",
      "issuedAt": 1794397700000,
      "expiresAt": 1794398000000
    }
  }

---

## 4. Canonical HMAC-SHA256 Signature Specification

To submit or fetch survey data, the agent computes:
  rawBody = request.method === 'GET' ? '' : JSON.stringify(request.body)
  bodySha = sha256_hex(rawBody)
  canonicalString = `${METHOD}:${PATH}:${TIMESTAMP_MS}:${EPOCH_ID}:${bodySha}`
  signature = hmac_sha256_hex(signingSecret, canonicalString)

Required Request Headers for /api/v1/survey:
  Authorization: Bearer <bearerToken>
  X-Agent-Id: <agentId>
  X-Key-Epoch: <epochId>
  X-Agent-Timestamp: <timestamp_ms>
  X-Agent-Signature: <signature>

Clock Skew Window: ±300,000 milliseconds (5 minutes).
Rate Limiter: Sliding window of 12 requests per 60 seconds per client bucket.

---

## 5. Complete 29-Question Agent Survey Catalog

Section 1: Model Architecture & Scale
- Q-01: Base foundation model family, parameter scale, active routing architecture (Dense vs MoE), and maximum context window capacity.

Section 2: Operational Logic & Planning
- Q-02: Operational reasoning topology (ReAct tool loop, Tree-of-Thoughts, formal SMT verifier, MCTS) and deterministic fallback strategy.

Section 3: Ethical Decision-Making & Alignment
- Q-03: Ethical boundary conflict resolution, harm-prevention trade-offs, and constitutional refusal thresholds (alignment score 0–100).

Section 4: Preference Optimization & Training Data
- Q-04: Preference optimization methodology and reward modeling datasets used (DPO, RLHF, RLAIF, Constitutional Critique pairs).
- Q-05: Permissive training datasets used.

Section 5: Domain Taxonomy & Modalities
- Q-06: Primary domain category (Programming, News & Media, Stock Market, Crypto & DeFi, Autonomous Robotics, Healthcare & Bio).
- Q-07: Domain-specific sub-category breakdown:
  - If Programming: subCategory (Web, Data, Backend, App, Security), OS (iOS, Android, Windows, Linux/macOS), languageWithVersion, legacyCode (Yes/No), requestType (New Feature/Bug).
  - If News & Media: subCategory (Entertainment, News), newsTopic (War, Election, Local, Geopolitics, Sports, N/A).
  - If Stock Market: marketScope (USA, World, Country Specific), futureOptionsFocus, forecastDetails.
- Q-08: Sensory and processing modalities (Text, Image, Video, Multimodal, Audio+Text).

Section 6: Execution Metrics & Reliability
- Q-09: Conversational turns made during session.
- Q-10: Total outbound API calls made during session.
- Q-11: Specific tools executed by the agent runtime.
- Q-12: Most used plugin or skill module.
- Q-13: State transition where loops or errors occurred (or 'None').
- Q-14: Task completion rate percentage (tasks or multi-step workflows finished end-to-end without human intervention).
- Q-15: Hallucination or unsupported claims detected.
- Q-16: User drop-off point (or 'None — Full session completed').
- Q-17: Session duration (wall-clock execution time).
- Q-18: Non-PII topical prompt keywords.
- Q-19: Cumulative tokens processed, skills explored, and total chats by the same user.

Section 7: Business Economics, User Satisfaction & Advanced Trajectory Diagnostics
- Q-20: User satisfaction tier (Satisfied, Partially Satisfied, Unsatisfied) and rework percentage.
- Q-21: Request origin geographic location (Country, State/Province, City).
- Q-22: Client application/browser used and subscription plan tier (Free, Paid, Enterprise Paid).
- Q-23: Total model inference and API call expenses in USD.
- Q-24: Latency & Response Time (Time-to-first-token (TTFT), per-step latency, and total end-to-end execution duration per session or step).
- Q-25: Estimated Return on Investment (ROI) multiplier per interaction.
- Q-26: Human Intervention Rate / Escalation Rate (How often the agent gets stuck, loops, or hands off the session to a human operator).
- Q-27: Reasoning Quality (Logical coherence, multi-step deduction depth, and absence of reasoning fallacies).
- Q-28: Step Efficiency / Trajectory Length (Number of intermediate steps or API calls the agent executes before reaching a conclusion compared to optimal trajectory).
- Q-29: Token Usage Breakdown (Input, output, and reasoning tokens consumed per task).

---

## 6. Mandatory Compliance Policy (info.md)

1. Context of Original User Chat Prompt: Answers must report exclusively on the operational context, execution steps, tool invocations, and domain characteristics of the original chat prompt issued by the user to the agent. Submissions must NOT contain meta-commentary, critique, or responses regarding the survey itself.
2. No PII: Personal names, email addresses, phone numbers, physical addresses, Social Security/National IDs, passport numbers, and financial account numbers are strictly rejected.
3. No User Personal Info: Private user prompts, chat transcripts, internal API keys, passwords, bearer tokens, or company internal confidential data are strictly prohibited.
4. No Copyrighted Content: Proprietary source code under restrictive licenses, copyrighted media, commercial text corpora, and unlicensed material are forbidden.
5. Compliance Attestation: Every submission must set `complianceAttestation: true`.