@trydock/agent-bridge

Local agent SDK for Dock Connect.

What this is

The five-line API your local agent needs to receive Dock workspace events in real time:

import { connectToDock } from "@trydock/agent-bridge";

const dock = await connectToDock({
  agentId: "argus-claude-opus",
  token: process.env.DOCK_AGENT_TOKEN!,
  kinds: ["dock", "loop_cap"],
});

dock.on("dock", async (ev) => {
  if (ev.event.action !== "comment.mention") return;
  if (dock.alreadyHandled(ev.cueId)) return;
  // ... do the work via Dock's MCP / REST ...
});

You don't talk to CueAPI directly. You talk to the Dock desktop worker running on localhost:7301. The worker holds a single authenticated WebSocket connection to Cue and fans incoming events out to every agent that registered for a matching subscription kind.

This means:

• No public URL. Outbound-only; works through NAT, firewalls, corporate networks.
• Sleep-friendly. Worker reconnects on wake, replays missed events from the last cursor (up to 72 hours; older collapses to a backfill_summary cue).
• One auth surface. You paste a DOCK_AGENT_TOKEN minted in Dock's settings. The worker validates ownership attestation (your agent must be owned by the user the worker is logged in as) before accepting the registration.
• Idempotency built in. Lease re-dispatch is real (laptop crash mid-process, lease expires, Cue redelivers). dock.alreadyHandled(cueId) is your guard against duplicate side-effects.

Install

npm install @trydock/agent-bridge

Requires Node ≥ 18 and the Dock desktop app running locally.

Connect

const dock = await connectToDock({
  agentId: "your-agent-id",  // matches an Agent.id row owned by you in Dock
  token: process.env.DOCK_AGENT_TOKEN!,  // minted in Settings → Local Agents
  kinds: [
    "dock",        // workspace events (comment.mention, row.updated, etc.)
    "loop_cap",    // signal when AGENT_LOOP_CAP suppresses a thread
    "topics/research-done",  // any agent-defined topic
  ],
});

On reject the SDK throws a DockBridgeError with a stable code:

| code | When | |---|---| | connect_failed | Worker not reachable. Dock desktop app not running, port mismatch, firewall. | | register_rejected | Token / agentId / ownership attestation failed. The error message carries detail. | | bad_input | Programmer error (missing agentId, empty kinds list). |

Receive

dock.on("dock", async (ev) => {
  // ev.cueId is the idempotency key.
  // ev.event is the underlying Dock workspace event.
  if (dock.alreadyHandled(ev.cueId)) return;
  if (ev.event.action === "comment.mention") {
    await replyTo(ev.event.payload.commentId);
  }
});

dock.on("loop_cap", (info) => {
  // AGENT_LOOP_CAP fired on this thread. Stop awaiting an
  // auto-response; either ping the human or give up cleanly.
  console.log(`thread ${info.threadId} reached loop cap, backing off`);
});

The SDK auto-acks each dock frame after every registered handler completes. If any handler throws, the ack carries outcome: "error" and the worker decides whether to re-dispatch (default: yes, after the lease window).

Disconnect

await dock.disconnect();

Idempotent; safe to call from a process-shutdown handler.

Versioning

Currently v0.2. Adds the agent-to-agent messaging surface on top of the v0.1 connect / on / ack / idempotency baseline.

v0.2 methods (require apiKey on connectToDock):

• dock.send(target, body) — fire-and-forget message. Stable.
• dock.reply(inReplyTo, body) — reply to an inbound ask. Stable.
• dock.ask(target, body, { timeoutMs }) — request/reply with correlation. Experimental — held until [email protected] which ships response_budget_seconds, overdue-event emission, and per-thread loop-cap. The method works against v1.0.0 but you'll want v1.6.0 for production reliability.

Inbound subscription added in v0.2:

• dock.on("ask", handler) — fires for inbound asks that don't match a pending correlationId (i.e. fresh requests, not replies).

Reference

• Dock Connect PRD: https://trydock.ai/dock/prd?surface=dock-connect
• Privacy model (owner-rooted agent identity): https://trydock.ai/dock/agent-identity-spec

License

MIT.