a2a-Market-WebSocket-Realtime

Deliver real-time websocket updates for intent, quote, negotiation, order, and payment events. Use when implementing push channels, subscription authorizatio...

Security Scan

This is an instruction-only design/framework document for WebSocket realtime delivery that requests no credentials, binaries, or installs and is internally consistent with its stated purpose.

Purpose & Capability

The name/description (realtime websocket delivery for market events) matches the SKILL.md content: channel naming, auth guards, publish/subscribe/resume semantics and event types. No unrelated resources (cloud creds, unrelated binaries) are requested.

Instruction Scope

SKILL.md is an implementation/design guide and does not instruct the agent to read unrelated system files, exfiltrate data, or call external endpoints. It does reference a local 'runtime' codebase and running 'npm test', but no code files are bundled with the skill — be aware using this skill in an agent may assume access to a project workspace or local runtime package.

Install Mechanism

There is no install spec and no code files included (instruction-only). No downloads, package installs, or archive extracts are requested.

Credentials

The skill declares no environment variables, no credentials, and no config paths. The runtime instructions do not require secrets or tokens.

Persistence & Privilege

always is false and model invocation is allowed (platform default). The skill does not request persistent or elevated presence or modifications to other skills/configs.

Assessment

This skill is a design/integration guide rather than runnable code — it appears safe and coherent. Before using it, confirm whether your agent will try to access a local 'runtime' folder or run 'npm test' (there are no code files bundled). If you intend to run tests or execute the referenced runtime paths, only do so in a trusted project workspace and review the actual code and dependencies first.

Set up realtime delivery skeleton for buyer and operator clients.

Current status: publishable framework with stable event contracts, not full scale tuning.

Scope

• Define channel naming and auth guard for buyer, node, and admin roles.
• Push canonical domain events with predictable payload shape.
• Manage reconnect semantics and last-event cursor replay.

Suggested Project Layout

• app/interfaces/ws/socket_gateway.py
• app/application/services/realtime_service.py
• app/infrastructure/ws/connection_registry.py
• app/infrastructure/cache/replay_cursor_store.py

Minimum Contracts (MVP P0)

1. subscribe(channel, cursor) validates permission and registers stream.
2. publish_event(channel, event) fans out to online subscribers.
3. resume(channel, cursor) replays missed events within retention window.
4. heartbeat(connection_id) updates liveness and cleanup scheduling.

Required Event Coverage

• INTENT_CREATED
• QUOTE_RECEIVED
• NEGOTIATION_STARTED
• ORDER_CREATED
• PAYMENT_SUCCEEDED

Guardrails

• Keep payloads versioned and backward compatible.
• Limit per-connection queue to prevent memory blowups.
• Drop unauthorized subscription attempts with structured error codes.

Implementation Backlog

• Add presence channels and typing/status hints for negotiation UI.
• Add regional relay nodes for cross-region latency reduction.

Runtime Implementation

• Status: implemented in local runtime package.
• Primary code paths:
• runtime/src/interfaces/ws/event-bus.js
• Validation: covered by runtime/tests and npm test in runtime/.