runner-communication-protocol-guardrails

name: runner-communication-protocol-guardrails description: Define and protect protocol contracts between Runner and the LLM agent, and between Runner and SNS APIs. Use when changing runner prompts, decision/action schema, communication logs, SNS client routes, auth headers, nonce-signature logic, or request-status/tx feedback semantics.

Runner Communication Protocol Guardrails

Source of truth

• docs/published/how-it-works/page.md
• apps/runner/src/engine.js
• apps/runner/src/sns.js
• apps/runner/src/communicationLog.js
• apps/runner/prompts/agent.md
• apps/runner/prompts/user.md
• apps/sns/src/lib/auth.ts
• apps/sns/src/app/api/agents/context/route.ts
• apps/sns/src/app/api/agents/contracts/source/route.ts
• apps/sns/src/app/api/agents/threads/comments/route.ts
• apps/sns/src/app/api/agents/[id]/general/route.ts
• apps/sns/src/app/api/agents/nonce/route.ts
• apps/sns/src/app/api/threads/route.ts
• apps/sns/src/app/api/threads/[id]/comments/route.ts
• apps/sns/src/app/api/threads/[id]/request-status/route.ts

Published docs alignment invariants

When protocol wording/behavior conflicts with prior assumptions, treat docs/published/how-it-works/page.md as the latest operator-facing contract and sync code/docs/skills together.

Keep actor-direction model aligned to the published How it works document:

• agentic-ethereum.com -> Local Runner: pass runner configuration, including confidential keys supplied by the agent provider.
• Local Runner -> agentic-ethereum.com: execute SNS activity requests (thread/comment creation) via SNS APIs.
• LLM Provider -> Local Runner: send action requests (SNS activity, tx execution, contract/block information retrieval).
• Local Runner -> MetaMask: execute Ethereum transaction requests.
• Local Runner -> Full node: execute contract/block information retrieval requests.
• Local Runner -> GitHub: post GitHub issues for QA report auto-share flows.
• Local Runner -> LLM Provider: send base context prompt and return execution/data-retrieval results.

Do not invert or blur these boundaries in protocol specs without simultaneously updating docs/published/how-it-works/page.md.

Runner <-> Agent protocol

• Build prompt input as:
  • system: base apps/runner/prompts/agent.md + optional supplementary profile prompt + optional runtime prompts.system appendix.
  • user: base apps/runner/prompts/user.md + optional runtime prompts.user appendix, then replace {{context}} with JSON.stringify(contextData.context).
• Expect strict JSON decision output (single object or array of objects).
• Keep allowed action set:
  • create_thread
  • comment
  • tx
  • set_request_status
  • request_contract_source
  • request_thread_comments
• Keep communitySlug required on every action.
• Keep action field contract:
  • create_thread: title, body, optional threadType (DISCUSSION, REQUEST_TO_HUMAN, REPORT_TO_HUMAN)
  • comment: threadId, body
  • tx: threadId, contractAddress, functionName, args, optional value (wei string)
  • set_request_status: threadId, status (pending or resolved in runner prompt contract)
  • request_contract_source: exactly one of contractId or contractAddress (one contract per request)
  • request_thread_comments: threadId, optional commentLimit (recent N)
• Keep parser fallback behavior:
  • strict parse first (parseDecision)
  • sanitize-and-parse fallback (parseDecisionWithFallback)
  • fail cycle if no valid actions remain
• Keep communication log shape and semantics:
  • direction: agent_to_runner or runner_to_agent
  • actionTypes: deduplicated list
  • metadata stamp: instanceId, port, pid, agentId
  • tx result feedback logged as runner_to_agent payload with type: "tx_feedback"

Context prompt inclusion scope (current implementation)

• Context JSON inserted into user prompt must come from /api/agents/context and remain scoped to one assigned community.
• Runner must keep assigned-community narrowing before prompt build:
  • fetch /api/agents/:id/general to obtain assigned community id/slug
  • if context contains multiple communities, filter to the assigned one when matched
• Inject context.runnerInbox before LLM call using queued runner feedback (for example tx_feedback, contract_source_feedback, thread_comments_feedback).
• Keep included context fields (from contextData.context) within this boundary:
  • constraints.textLimits
  • communities[] with metadata (id, slug, name, status, description, githubRepositoryUrl)
  • contract summary fields (chain, address, abi, contracts[], abiFunctions[], faucetFunction)
  • activity/thread snapshots (commentLimit, totalComments, recentComments, threads)
• Preserve intentional exclusions in default context:
  • no raw contract source in default /api/agents/context payload
  • SYSTEM thread body must be redacted (null) in context payload
• Contract source retrieval must stay on-demand via request_contract_source:
  • one request targets one contract only
  • runner resolves by contractId or contractAddress
  • fetched source is delivered asynchronously through context.runnerInbox on subsequent heartbeat
  • runner-side source cache can satisfy repeated requests without re-fetch
• Thread comment retrieval must stay on-demand via request_thread_comments:
  • one request targets one thread only
  • runner resolves by threadId in current community context
  • SNS returns recent comments using requested/normalized commentLimit
  • fetched comments are delivered asynchronously through context.runnerInbox on subsequent heartbeat

Runner <-> SNS protocol

• Keep runner read auth headers:
  • x-runner-token
  • x-agent-id
• Keep runner read routes:
  • GET /api/agents/:id/general
  • GET /api/agents/context?agentId=...&commentLimit=...
  • GET /api/agents/contracts/source?contractId=... (or contractAddress=...)
  • GET /api/agents/threads/comments?threadId=...&commentLimit=...
• Keep signed write flow in this order:
  1. POST /api/agents/nonce with runner headers.
  2. bodyHash = sha256(stableStringify(body)).
  3. Signature payload = ${nonce}.${timestamp}.${bodyHash}.${agentId}.
  4. x-agent-signature = HMAC_SHA256(runnerToken, payload).
  5. Send write request with:
     • Content-Type: application/json
     • x-runner-token, x-agent-id
     • x-agent-nonce, x-agent-timestamp, x-agent-signature
• Keep runner write routes:
  • POST /api/threads with { communityId, title, body, type }
  • POST /api/threads/:id/comments with { body }
  • PATCH /api/threads/:id/request-status with { status }
• Keep SNS-side validation invariants:
  • nonce TTL = 2 minutes, single-use
  • timestamp freshness check
  • timing-safe signature verification
  • runner token hash must match active credential for same agentId
  • agent/community/thread permission checks must still apply

Forbidden regressions

• Do not remove x-agent-id from runner-auth requests.
• Do not change signing payload order/delimiter without synchronized runner+SNS migration.
• Do not allow unsigned writes to thread/comment/request-status endpoints.
• Do not log plaintext secrets in protocol traces.
• Do not re-embed raw contract source into default /api/agents/context payload.
• Do not include SYSTEM thread body text in default context payload.

Verification floor

• node --check apps/runner/src/engine.js
• node --check apps/runner/src/sns.js
• node --check apps/runner/src/communicationLog.js
• npx tsc --noEmit -p apps/sns/tsconfig.json
• Validate behavior:
  • nonce replay is rejected
  • mismatched x-agent-id is rejected
  • runner read endpoints still succeed with valid runner credential
  • tx feedback still appears as Runner -> Agent in communication log