Full documentation

1. Introduction

2. Quick Overview

After registration, OmniLink opens in edit mode so you can set up content, integrations, and appearance. Use the side menu to navigate between configuration, billing, and support tools while you tailor the assistant.

The dashboard keeps the essentials in easy reach: the left rail holds navigation for settings, appearance, and deployment tools, while the main canvas previews the active assistant experience. A compact activity drawer along the right edge shows conversation transcripts, emitted commands, and connection health so you can validate behaviour without leaving the page.

Under the hood, the same workspace connects directly to the omnilink-lib Python package. The library hosts the OmniLink engine, MQTT bridge, and TCP adapters so your agent can speak to industrial controllers, smart home hubs, or any custom system. Install it with pip install omnilink-lib, point it at your deployment, and the dashboard immediately reflects the intents, feedback, and telemetry that your Python processes publish.

3. Use Cases

OmniLink adapts to environments ranging from individual homes to complex industrial floors. Below are two flagship scenarios that show how natural language control becomes reliable, safe action.

4. Quickstart

You are an agent who helps customers choose the best country to visit and arranges their travel based on their preferred mode of transportation.

book_flight_ticket_to_[country],
book_train_ticket_to_[country]

# Clone the example repo
git clone https://github.com/omni-link-tech/omni-link-travel-agent.git

cd omni-link-travel-agent

6. Agent Configuration

This section covers how to customize your agent.

• Main Task: The main task is the overall goal of your agent. It should be written as a general description that combines everything the agent needs to do.
  Example:

You are a hotel customer service agent who manages reservations and answers customer questions.

• Commands: Define patterns that map human-friendly input to structured commands. These should be descriptive phrases separated by underscores.
  Example:

book_room_number_1

But if you have 100 rooms, creating 100 commands is impractical. Instead, use variables inside square brackets:

book_room_number_[number]

Anything inside [] will be treated by the agent as a variable. You just have to describe the type of variable.
Example:

turn_on_light_in_[room]

• Custom Instructions: Write the rules your agent must follow.
  Example: Always ask the user for confirmation before executing a command.
• Knowledge: You can upload a file that will be treated as the knowledge base of the agent. This enriches the agent’s ability to answer questions and perform tasks.
• Short-term Memory Limit: Define how many previous exchanges the agent remembers when generating responses.

Memory model

OmniLink stores conversation history in short-term memory (the recent turns you configure) and blends it with the Main Task, Custom Instructions, and retrieved Knowledge. Short-term memory resets when you clear it manually or when the session ends.

• Persisted: Main Task, Custom Instructions, Available Commands, and Knowledge files.
• Session-only: recent conversation turns and transient tool output.
• Reset guidance: reset memory after changing the Main Task or Knowledge so the agent doesn’t mix old assumptions with new context.
• Knowledge interaction: retrieved Knowledge snippets are appended to the prompt alongside memory, so stale memory can still bias answers if not reset.

Knowledge authoring guide

• Structure for retrieval: write short sections with explicit headings and include “golden examples” that mirror real commands or error cases.
• Formatting: tables are ideal for command formats, parameters, and expected outputs.
• Chunking: split large manuals into multiple files so retrieval can grab the right section without hitting plan limits.
• Edge cases: document anti-examples and failure modes so the agent learns what not to do.
• Versioning: tag files with dates or semantic versions to track updates and prompt resets.

7. Command Parsing

Command parsing is the step where OmniLink converts a free-form utterance into a normalized payload that downstream systems can understand. You describe the shape of a command with a template, and the engine extracts the variables that appear between square brackets.

Here is a simple template for moving chess pieces:

move_[color]_[piece]_from_[location1]_to_[location2]

If you say: “Move the white knight from a2 to a3”, the engine extracts:

{
  "template": "move_[color]_[piece]_from_[location1]_to_[location2]",
  "vars": {
    "color": "white",
    "piece": "knight",
    "location1": "a2",
    "location2": "a3"
  }
}

This structured payload is then published to your chosen transport.

Command payload contract (recommended)

OmniLink emits commands as structured JSON. We recommend standardizing the envelope so every connector and runtime can validate it consistently.

Command schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "OmniLink Command Envelope",
  "type": "object",
  "required": ["type", "name", "id", "timestamp"],
  "properties": {
    "type": { "const": "command" },
    "name": { "type": "string", "description": "Normalized command name" },
    "id": { "type": "string", "description": "Unique command identifier" },
    "timestamp": { "type": "string", "format": "date-time" },
    "args": { "type": "object", "additionalProperties": true },
    "correlationId": { "type": "string" },
    "source": { "type": "string", "description": "Agent or connector label" },
    "retries": { "type": "integer", "minimum": 0 },
    "timeoutMs": { "type": "integer", "minimum": 0 },
    "metadata": { "type": "object", "additionalProperties": true }
  }
}

ACK/response schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "OmniLink Command Ack",
  "type": "object",
  "required": ["type", "commandId", "timestamp", "ok"],
  "properties": {
    "type": { "const": "ack" },
    "commandId": { "type": "string" },
    "timestamp": { "type": "string", "format": "date-time" },
    "ok": { "type": "boolean" },
    "result": { "type": ["object", "array", "string", "number", "boolean", "null"] },
    "error": { "type": "string" },
    "retryable": { "type": "boolean" },
    "attempt": { "type": "integer", "minimum": 1 }
  }
}

Required vs optional fields

• Required: type, name, id, timestamp.
• Optional: args, correlationId, source, retries, timeoutMs, metadata.

Limits & validation

• Payload size: enforce a hard limit in your connector and broker. Keep commands small and send large data via object storage or links.
• Nesting: prefer shallow argument objects; deeply nested payloads are harder to prompt and debug.
• Escaping rules: if you need raw text that includes separators (underscores, brackets), place it inside args rather than in the template text.
• Type safety: coerce variables to numbers/booleans in your connector before forwarding to hardware.

Examples

Simple command:

{
  "type": "command",
  "name": "pause_simulation",
  "id": "cmd-2204",
  "timestamp": "2024-04-20T16:33:20.120Z"
}

Command with arguments:

{
  "type": "command",
  "name": "move_player",
  "id": "cmd-2205",
  "timestamp": "2024-04-20T16:33:25.120Z",
  "args": { "direction": "east", "steps": 3 }
}

Structured JSON result:

{
  "type": "ack",
  "commandId": "cmd-2205",
  "timestamp": "2024-04-20T16:33:25.440Z",
  "ok": true,
  "result": { "newPosition": { "x": 15, "y": 4 }, "energy": 87 }
}

Retries + error handling:

{
  "type": "ack",
  "commandId": "cmd-2205",
  "timestamp": "2024-04-20T16:33:25.980Z",
  "ok": false,
  "error": "Movement blocked by obstacle",
  "retryable": true,
  "attempt": 2
}

Common errors

• Command doesn’t trigger: command name doesn’t match the template or is missing from Available Commands.
• Command truncates: payload too large for the broker or transport; send only IDs and fetch details elsewhere.
• Inconsistent behavior: synonyms not normalized or connector isn’t coercing types consistently.

Templates can be as expressive as you need. The parser recognizes separator characters (underscores, hyphens, whitespace) and uses them to match the relevant segments. You can also add aliases for natural language variations through the <synonyms> attribute in the configuration UI.

Multiple Commands, One Template

A single template can capture a family of commands. For example, the following template handles several thermostat actions:

thermostat_[action]_to_[temperature]_degrees

Sample utterances and the extracted payloads:

// "Thermostat set to 72 degrees"
{
  "template": "thermostat_[action]_to_[temperature]_degrees",
  "vars": {
    "action": "set",
    "temperature": "72"
  }
}

// "Thermostat boost to 25 degrees"
{
  "template": "thermostat_[action]_to_[temperature]_degrees",
  "vars": {
    "action": "boost",
    "temperature": "25"
  }
}

Because both commands share the same structure, you can implement downstream logic that switches on the action variable without redefining multiple templates.

Optional Segments and Defaults

Add optional suffixes by chaining multiple templates. For example, you might support both open_[door] and open_[door]_for_[duration]_seconds. When the shorter version is triggered, your connector can provide a default duration before the door automatically closes.

Defaults can also be injected by the transport bridge. If a user omits a variable, use your connector to supply a fallback value so that the receiving device always receives a complete payload.

Using Synonyms

Natural language is messy. Pair your templates with synonym tables to map phrases such as “turn on”, “enable”, or “activate” to the same [action] variable. Here is a short example:

light_[action]_in_[room]

// With synonyms: enable → on, activate → on, kill → off
// "Activate the lights in the kitchen"
{
  "template": "light_[action]_in_[room]",
  "vars": {
    "action": "on",
    "room": "kitchen"
  }
}

The parser resolves the synonym before delivering the payload, which keeps your downstream logic consistent regardless of how the user phrased the request.

Validation Tips

• Define guard rails in your connector to reject commands with missing or malformed variables.
• Log the raw utterance alongside the parsed payload to help diagnose template gaps.
• Use the debug console to replay commands and fine-tune the template patterns before deploying to production.

By combining expressive templates, synonym mappings, and validation, you can cover the majority of natural language variations while keeping the command contract deterministic for any automation stack.

8. Agent Connection

OmniLink communicates with your automation stack through a unified connection layer. Regardless of the transport you choose, the agent always emits the same contract: command → feedback → context. This section explains how to take advantage of the connection system in both local experiments and remote deployments.

Local vs. Remote Connection

Local Connection

• Perfect for development and debugging when everything runs on the same machine or LAN.
• Run your API connector (for example link.py) locally and point the OmniLink UI to ws://localhost:9001 or mqtt://localhost:1883, depending on your transport.
• Keep the debug window open to watch the command payloads in real time before they reach your hardware or services.

Remote Connection

• Use this when the agent and the automation targets live in different networks (cloud deployment, on-prem controllers, or hybrid setups).
• Expose your broker or bridge endpoints over the internet with TLS (WSS/HTTPS) and authentication. Reverse proxies such as Nginx or Traefik help terminate certificates and enforce IP allowlists.
• Synchronize environment variables in the OmniLink UI with the remote hostnames, ports, and credentials for your broker or HTTP/WebSocket services.

MQTT Communication

MQTT is the recommended transport for mission-critical automations because it supports pub/sub semantics and lightweight payloads. OmniLink uses the following topics by default:

• olink/commands – outbound commands published by the agent.
• olink/commands_feedback – acknowledgements and execution results from your services.
• olink/context – state updates that keep users informed.

Configure Quality of Service (QoS) according to your needs. QoS 1 ensures that every command is delivered at least once, while QoS 2 guarantees exactly-once delivery for sensitive actions. Retained messages on olink/context help late subscribers catch up with the latest status.

Setting Up Mosquitto

1. Install Mosquitto: use your package manager (sudo apt install mosquitto mosquitto-clients) or Docker (docker run -p 1883:1883 -p 9001:9001 eclipse-mosquitto).
2. Enable WebSockets: update /etc/mosquitto/conf.d/olink.conf (or the Docker-mounted configuration) with:

   listener 1883 0.0.0.0
   protocol mqtt
   
   listener 9001 0.0.0.0
   protocol websockets
   
   allow_anonymous false
   password_file /etc/mosquitto/passwords
               

3. Create credentials: sudo mosquitto_passwd -c /etc/mosquitto/passwords omni-link, then restart the broker (sudo systemctl restart mosquitto or restart the container).
4. Verify connectivity: publish and subscribe using mosquitto_pub and mosquitto_sub or connect through the OmniLink UI.

For remote deployments, secure Mosquitto further with TLS certificates, unique user accounts per service, and network firewalls.

Connector recipes (WebSocket, MQTT, REST)

Pick one transport and keep the envelope consistent: state → command → ack/error. The agent only needs a clean loop and reliable acknowledgements.

Minimal WebSocket relay

// pseudo-code
const ws = new WebSocket("wss://game.example.com");

ws.onmessage = ({ data }) => {
  const message = JSON.parse(data);
  if (message.type === "state") {
    publishContext(message.payload);
  }
};

onCommand((command) => {
  ws.send(JSON.stringify({
    type: "action",
    correlationId: command.id,
    payload: command
  }));
});

Minimal MQTT relay

# pseudo-code
subscribe("sim/state", handle_state)
subscribe("olink/commands", handle_command)

def handle_state(message):
    publish("olink/context", {"context": summarize(message.payload)})

def handle_command(command):
    publish("sim/action", {"type": "action", "correlationId": command["id"], "payload": command})

Minimal REST relay

# pseudo-code
GET /state  -> summarize into context
POST /action -> send command payload, return ack

Message schema conventions

Use a shared envelope to make debugging predictable.

{
  "type": "state", // "action" | "ack" | "error"
  "timestamp": "2024-04-20T16:33:12.120Z",
  "sequence": 1842,
  "correlationId": "cmd-2205",
  "payload": {}
}

• Timestamps: always send ISO 8601 timestamps so logs can be aligned.
• Sequence numbers: monotonic per source to detect drops or replays.
• Correlation IDs: match acks and errors to the originating command.

Rate limiting & backpressure

• Debounce state updates if the environment emits too frequently.
• Queue commands on the connector side and acknowledge only when the environment confirms receipt.
• Surface throttling status in feedback so operators understand delays.

Reconnection handling

• Reconnect with exponential backoff and jitter.
• On reconnect, request the latest state snapshot before acting on new commands.
• Reset sequence counters and send a “ready” context update to the agent.

Plugging commands into the agent

Ensure every command name matches the Available Commands templates. Map template variables into your action payload, and always emit an ACK so the agent can reason about success vs. failure.

Other Connection Options

• HTTP Bridge: send POST requests with command payloads for systems that prefer synchronous workflows.
• WebSocket Bridge: maintain a persistent duplex channel ideal for browser-based clients and dashboards.
• Custom Transports: extend the connection layer by adapting the command contract to your protocol (serial, gRPC, OPC-UA, etc.).

9. Context System

Give the agent a running description of the system it controls by publishing readable context messages. Provide the state as plain text so the LLM can interpret it the same way a human operator would.

Include the most relevant details—status, recent actions, or sensor readings—in sentences or short bullet points. This keeps the agent grounded without forcing it to decipher raw data dumps.

Example context payload:

{
  "context": "Robot arm is homed. Current task: assemble panel A. Last command succeeded at 14:32."
}

Publish these updates on olink/context whenever the system changes so the user stays informed. Longer payloads are also supported as long as they remain human-readable. Below are two expanded examples that keep the model grounded without overwhelming it with noise.

Manufacturing Line Example

{
  "context": "Assembly Line 3: Conveyor speed 1.2 m/s. Robot arm completed weld sequence at 15:02 and is waiting for the next chassis. Safety gate closed. QA camera flagged Panel B for manual inspection (scratched surface)."
}

This message blends operational metrics, recent actions, and follow-up requirements. The agent can reference it to justify pausing the line, dispatching a technician, or notifying quality control without asking the operator to repeat known details.

Smart Building Example

{
  "context": "HQ Lobby: Temperature 22.3°C, humidity 46%. Front desk kiosk rebooted at 09:14 after firmware update. Visitor traffic light; no VIP guests expected this hour. Security notified about a propped door on Level 2 Stairwell B."
}

Context streams like this give conversational agents enough situational awareness to answer questions such as "Why is the stairwell alarm active?" or "Is the lobby comfortable for visitors?" while still fitting in a single MQTT payload.

10. OmniLink-lib

OmniLink-lib is the open-source Python library that ships with this repository. Its omnilink module bundles the OmniLinkEngine core, the messaging helpers, and the bridges that link automations to MQTT, Supabase, and TCP systems. The code lives under omnilink-lib/src/omnilink and powers every demo and dashboard showcased across the OmniLink experience.

Visit the GitHub repository at https://github.com/omni-link-tech/omnilink-lib for the full source and contribution details. OmniLink-lib is open source, and everyone is welcome to improve it.

Library overview

• Pattern-driven engine: OmniLinkEngine compiles readable command templates into efficient regular expressions, routes matched events to handlers, and maintains metrics counters alongside a bounded history deque so operators can inspect recent activity.
• Typed parsing: TypeRegistry and CompiledPattern pair template slots with converters, transforming raw text into the Python objects your handlers expect before business logic executes.
• Middleware + lifecycle: Register before, after, and template-specific hooks to run validation, auditing, or fallback behaviors without scattering boilerplate across your project.
• Interactive messaging: AgentMessenger, AgentFeedback, AgentQuestion, and PendingQuestion give handlers a structured way to acknowledge commands, stream progress, and solicit clarifications from human operators or UI widgets.

Transport bridges & utilities

• MQTT orchestration: OmniLinkMQTTBridge listens to olink/commands, publishes acknowledgements, feedback, and questions, and mirrors engine state with helpers such as give_context() and start_periodic_context().
• Remote polling: OmniLinkRemoteCommandBridge and RemoteCommandClient integrate with Supabase REST endpoints so cloud dashboards can queue commands and receive structured JSON replies without direct socket access.
• Legacy support: OmniLinkTCPAdapter and the tcp_client helpers relay commands to newline-delimited TCP services, making it easy to modernize existing controllers without replacing them overnight.
• Inline scripting: The InlineCodeMessage helpers and the mqtt_inline_code_executor.py example demonstrate how to execute curated Python snippets streamed over MQTT when experimentation is required.
• Scenario loaders: use_case_loader.py and the demos under omnilink/examples showcase practical agent flows, from conversational question relays to remote control centers and industrial gateways.

Example workflow snapshot

A typical deployment loads templates from disk, initializes OmniLinkEngine with a TypeRegistry, registers command handlers, and boots an MQTT bridge. The engine records every attempt in its metrics counters, while PendingQuestion objects pause handler execution until operators reply. Meanwhile start_periodic_context() keeps dashboards up to date with rolling telemetry pushed over the configured MQTT topics.

The library keeps advanced workflows close at hand: run omnilink/examples/messaging_demo.py to see question handling in action, remote_control_center_demo.py for a Supabase-backed command loop, or tcp_forwarding_demo.py when bridging to a legacy socket service. Each script imports the same omnilink package, proving the engine and its bridges stay cohesive no matter the transport.

OmniLink-lib adventure log (1000+ lines of fun)

We recommend starting with the demos on our GitHub page to get familiar with OmniLink. But if you’re one of those legendary developers who prefer the hard path, don’t worry, we’ve got you covered with a thousand paragraphs explaining every detail of the library.

11. Tutorials

Hello World: state → decision → action

This is the first production-shaped tutorial after the basic chat agent. You will stream state, let the agent decide, emit an action, receive an acknowledgement, and log metrics end-to-end.

1. Spin up a tiny state source. Choose a WebSocket server, MQTT broker, or REST endpoint that publishes a state payload on a timer (every 250–1000 ms).
2. Run a tiny environment. Use a browser game or simulator that reacts to simple actions (move, jump, rotate, fire).
3. Subscribe to state. Your connector receives state updates and forwards the most relevant fields to OmniLink as human-readable context.
4. Decide + send action. The agent chooses a command, your connector maps it to an action payload, and you post it to the environment.
5. Receive ACK + metrics. The environment responds with success/failure and latency. Log it and publish feedback to the agent.

Recommended state/action/ack envelope:

{
  "type": "state",
  "timestamp": "2024-04-20T16:33:12.120Z",
  "sequence": 1842,
  "correlationId": "round-204",
  "payload": {
    "playerPosition": { "x": 12, "y": 4 },
    "targetVisible": true,
    "health": 92
  }
}

Keep a running log of state → command → action → ack so you can replay or debug. The simplest MVP is a console logger; the next step is a CSV or JSONL stream you can diff between runs.

Testing & evaluation methodology

• Regression suite: Save a list of conversations and expected commands in a test file to re-run after every change.
• Deterministic command tests: Feed the same state snapshots in the same order and verify identical commands + arguments are produced.
• Record/replay: Capture state/action traces, then replay them offline to reproduce edge cases.
• Metrics: Track success rate, end-to-end latency, error rate, and human intervention rate.

Agent refactor checklist

1. Update Main Task to match the new purpose.
2. Revise Commands so names + arguments match your connector.
3. Upload or prune Knowledge documents.
4. Reset memory after changing Main Task or Knowledge.
5. Run smoke tests from the regression suite.
6. Deploy and monitor the first live session.

• Chess Demo: Full GitHub project (omni-link-tech/omni-link-chess). Demonstrates command parsing, context updates, and UI sync.
• Travel Agent Demo: (explained above) shows how to build a conversational API connector.
• Smart Home Demo: Coming soon.

12. Security

OmniLink ships with the default edit-mode password omnilink. Before you deploy an agent for others to use, open Settings → Security, set a new password, and share it only with trusted collaborators. This password controls access to edit mode, so rotating it regularly keeps your deployment safe.

If you are the developer of the agent, please don't give the app password to any of your users, as they can then change the agent's configuration and alter its behavior. It is always best practice to add one more safety layer in your system to verify the commands coming from the agent.

Security model for real systems

• Authentication: use API keys or service accounts for connectors, and rotate credentials on a fixed schedule.
• Secrets storage: store secrets in environment variables or a secrets manager, not inside knowledge files or prompts.
• Least privilege: scope tokens to the minimal set of endpoints required for the agent.
• Audit logs: log command IDs, timestamps, and operator approvals for compliance and incident review.
• Safe mode: enable “confirm before actuation” flows for physical systems or high-impact actions.

Operational best practices

• Require human confirmation for any command that moves hardware, spends money, or changes access.
• Validate inputs at the connector boundary before they reach downstream systems.
• Use separate credentials for dev, staging, and production environments.

13. Usage Management

Use this section to understand how to make the most of your credits and keep on track with the plan you've chosen.

Open the Usage page from the side menu whenever you want a snapshot of your current activity. The charts and totals show the time you talk to the agent, the time the agent talks to you, and requests made with the G1 Engine and G2 Engine so you always know where your credits are going.

If you notice one category climbing faster than expected, try a few quick adjustments:

• Trim long audio recordings or switch off live transcription when you only need text responses to lower speech-to-text usage.
• Keep replies concise and reuse message templates to reduce text-to-speech output.
• Choose between the G1 and G2 Engines based on the level of reasoning you need—G1 is more lightweight, while G2 handles complex tasks. Swap as needed to balance quality and cost.

Plans cap total monthly credits. The built-in plans are Free ($0 for 5 credits), Silver ($20 for 20 credits), Gold ($50 for 50 credits), and Diamond ($100 for 100 credits). Upgrade when your monthly usage approaches your plan's credit limit so the agent stays available to your users.

Plan limits & platform constraints

Limits vary by plan and are enforced across the UI and APIs. Check these before you scale a deployment:

• Agent profiles: total number of saved agents.
• Knowledge uploads: file size, chunk count, and total storage limits.
• Tool usage: maximum tool calls, concurrent sessions, or runtime limits.
• Retention: how long conversations, logs, and metrics are stored.

We recommend linking these limits in onboarding and tooltips so teams don’t discover them mid-build.

Usage examples

Here are a few ways teams use the Usage page to balance different engines and input modes:

• Text-only support with the G1 Engine: Keep conversations in chat mode and have the agent reply in text so credits mainly fall under AI processing. For example, if the Usage page shows 6 G1 credits consumed during the first week on the Silver plan (20 credits total), multiply 6 × 4 to project 24 credits for the month—a signal to trim low-priority chats or upgrade before you cross the limit.
• Voice concierge powered by the G2 Engine: Run continuous listening with wake-word activation and spoken responses for premium scenarios. When the Usage view reports 3 listening credits + 2 speaking credits + 5 G2 credits after a busy day, you know you spent 10 credits; at that pace a Diamond plan (100 credits) gives room for roughly ten similar days before you should scale back or optimize prompts.
• Hybrid handoff between text and voice: Start in click-to-talk text mode for quick questions, then switch to live audio when tasks get complex. If a launch week mix shows 8 listening + 4 speaking + 6 G1 credits, that’s 18 credits in total; divide by the seven days you’ve tracked to see the team averaging ≈2.6 credits/day, which keeps a Gold plan (50 credits) on track for the full month while still leaving headroom for spikes.

14. FAQ

Q: Can I run OmniLink fully offline?
Not yet. In the future will there will be the option to have Local AI Engines

Q: Does it support multiple languages?
Soon. For now only Engilsh is supported.

Q: What should I do if I forget my edit-mode password?
You will need to contact us via OmniLink chat.

Q: Can multiple teammates collaborate on the same agent?
Absolutely. Share the edit-mode password with trusted collaborators so they can sign in and contribute in real time.

Q: Where can I monitor system status and incidents?
Visit the Status page from the side navigation to review uptime history and subscribe to notifications.

Debugging playbook

• Agent not following the Main Task: check instruction precedence, memory drift, and conflicting knowledge files.
• Command not firing: confirm JSON validity, command name matching, and whether the prompt phrasing matches the template.
• Tool calls failing: verify CORS, network access, and authentication headers in the connector.
• WebSocket issues: confirm origin, ports, message schema, and reconnect loops.
• It worked once then stopped: look for state drift, memory resets, or tool runtime restarts.

Logging tips: capture raw state, command, and ack payloads with timestamps. Add correlation IDs so you can trace a single command through every hop.