dsh-device-fleet 0.0.0-stage → 0.1.0-dev.10

package/src/host/tools.js

@@ -0,0 +1,590 @@
+// Model-facing fleet tools (ADR-0014, ADR-0022).
+//
+// fleet_list / fleet_tools / fleet_call are the fixed tool surface; fleet_read,
+// fleet_fetch and fleet_run are typed shortcuts over the same fleet.call path.
+import { DirectCallClient } from './direct-call.js'
+
+/** Shared text output contract (same shape the harness's own tools use). */
+export function textOutput() {
+  return {
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { text: { type: 'string', required: true } },
+    },
+    render: (_args, value) => [{ type: 'text', text: value.text }],
+  }
+}
+
+function fail(error) {
+  const code = error?.code ?? 'error'
+  return { text: `Error: [${String(code)}] ${String(error?.message ?? error)}` }
+}
+
+/** Pure handlers; wrapped into ToolDefinitions by `createFleetToolDefinitions`. */
+export function createFleetHandlers({
+  node,
+  client = new DirectCallClient({ node }),
+  pairing = null,
+  onPeerHint = null,
+  approvals = null,
+  rooms = null,
+}) {
+  return {
+    async fleet_approvals() {
+      if (!approvals?.list) return { text: 'Error: [unsupported] the approval inbox is unavailable' }
+      const items = approvals.list()
+      if (items.length === 0) return { text: '(no pending approvals)' }
+      const lines = items.map(
+        (item) =>
+          `- ${item.id} · ${item.fromDeviceId} · ${item.capability}${item.tool ? `/${String(item.tool)}` : ''} · ${item.expiresInMs}ms left · ${item.argsSummary}`,
+      )
+      return { text: lines.join('\n') }
+    },
+
+    async fleet_approve({ id, scope }) {
+      if (!approvals?.approve) return { text: 'Error: [unsupported] the approval inbox is unavailable' }
+      try {
+        const result = approvals.approve(id, { scope: scope ?? 'once' })
+        return { text: `approved ${result.id} (${result.scope})` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_deny({ id, reason }) {
+      if (!approvals?.deny) return { text: 'Error: [unsupported] the approval inbox is unavailable' }
+      try {
+        const result = approvals.deny(id, reason ?? 'denied by local user')
+        return { text: `denied ${result.id}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_simulate_request({ fromDeviceId, capability, tool, reason }) {
+      if (!approvals?.simulate) return { text: 'Error: [unsupported] approval simulation is disabled' }
+      try {
+        return { text: await approvals.simulate({ fromDeviceId, capability, tool, reason }) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+    async fleet_status() {
+      if (typeof node.status !== 'function') return { text: 'Error: [unsupported] status is unavailable' }
+      return { text: JSON.stringify(node.status(), null, 2) }
+    },
+
+    async fleet_connect({ host, port }) {
+      if (typeof node.connectAddress !== 'function') return { text: 'Error: [unsupported] manual connect is unavailable' }
+      try {
+        node.addPeerHint?.({ host, port })
+        const peer = await node.connectAddress(host, port)
+        await onPeerHint?.({ host, port })
+        return { text: `connected to ${peer.deviceId} (${peer.name ?? 'device'}) at ${host}:${port}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_invite() {
+      if (!pairing?.invite) return { text: 'Error: [unsupported] this device cannot create an invite' }
+      try {
+        const code = await pairing.invite()
+        return {
+          text: [
+            'Fleet invite for another device (single use, keep it private):',
+            '',
+            code,
+            '',
+            'On the other device install this plugin, then ask its agent to join with this code (`fleet_join`). It takes effect after that DSH restarts.',
+          ].join('\n'),
+        }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_join({ code }) {
+      if (!pairing?.join) return { text: 'Error: [unsupported] this device cannot join a fleet' }
+      try {
+        await pairing.join(code)
+        return { text: 'Invite queued. Restart DSH on this device; the plugin will enroll on the next load and then be able to reach the Fleet.' }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_create(args, exec) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const room = await rooms.upgradeHost({ agent: exec?.agent, policy: args?.policy ?? {} })
+        return {
+          text: [
+            `room created: ${room.roomId}`,
+            `host: ${room.members.find((member) => member.role === 'host')?.memberId ?? '?'}`,
+            'Add participants with room_add_local (simulation) or the remote invite flow later, then room_send.',
+          ].join('\n'),
+        }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_add_local({ roomId, name, agentPreset, cwd }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const member = await rooms.addLocalParticipant({ roomId, name, agentPreset, cwd })
+        return { text: `participant added: ${member.memberId} (${member.name}) session=${member.sessionId}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_remove_member({ roomId, memberId, reason }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const result = await rooms.removeMember({ roomId, memberId, reason })
+        return { text: `member removed: ${result.memberId}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_send({ roomId, to, text }, exec) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const from = { sessionId: exec?.agent?.session?.id }
+        const result = await rooms.send({ roomId, from, to, text })
+        const woken = result.woken.length > 0 ? `, woke ${result.woken.join(', ')}` : ''
+        return { text: `message ${result.messageId} sent to ${result.to.join(', ')}${woken}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_messages({ roomId, limit }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const items = rooms.messages({ roomId, limit })
+        if (items.length === 0) return { text: '(no messages)' }
+        const lines = items.map(
+          (message) => `- [${new Date(message.createdAt).toISOString()}] ${message.fromLabel} → ${message.to.join(', ')}: ${message.text}`,
+        )
+        return { text: lines.join('\n') }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_status({ roomId }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        return { text: JSON.stringify(rooms.status(roomId), null, 2) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_task_add({ roomId, title, owner, dependsOn, description }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const task = await rooms.addTask({ roomId, title, owner, dependsOn: dependsOn ?? [], description: description ?? '' })
+        return { text: `task ${task.id} added for ${task.owner}: ${task.title}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_task_update({ roomId, id, status, note }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const result = await rooms.updateTask({ roomId, id, status, note })
+        const handed = result.handedOff.length > 0 ? `; handed off to ${result.handedOff.map((item) => item.owner).join(', ')}` : ''
+        return { text: `task ${result.task.id} updated (${result.task.status})${handed}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_task_list({ roomId }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const tasks = rooms.listTasks(roomId)
+        if (tasks.length === 0) return { text: '(no tasks)' }
+        return {
+          text: tasks
+            .map((task) => `- [${task.status}] ${task.title} (${task.id}) owner=${task.owner}${task.dependsOn.length ? ` deps=${task.dependsOn.join(',')}` : ''}`)
+            .join('\n'),
+        }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_close({ roomId, reason }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        await rooms.close({ roomId, reason: reason ?? 'closed by host' })
+        return { text: `room closed: ${roomId}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_list() {
+      const lines = []
+      lines.push(`this device: ${node.identity.deviceId} (${node.name})`)
+      const seen = new Set([node.identity.deviceId])
+      const online = new Set(node.peerIds())
+      const discovered = new Map([...node.discovered.values()].map((peer) => [peer.deviceId, peer]))
+      for (const entry of node.rosterEntries()) {
+        if (seen.has(entry.deviceId)) continue
+        seen.add(entry.deviceId)
+        lines.push(`- ${entry.deviceId} (${entry.name ?? 'device'}) ${online.has(entry.deviceId) ? 'online' : 'offline'}${online.has(entry.deviceId) ? '' : ' — direct calls fail while offline'}`)
+      }
+      for (const [deviceId, peer] of discovered) {
+        if (seen.has(deviceId)) continue
+        seen.add(deviceId)
+        lines.push(`- ${deviceId} (${peer.name ?? 'device'}) discovered${online.has(deviceId) ? ', online' : ''}`)
+      }
+      if (lines.length === 1) lines.push('(no other devices known yet; pair/enroll one with an invite first)')
+      return { text: lines.join('\n') }
+    },
+
+    async fleet_tools({ device }) {
+      try {
+        const result = await client.listTools(device)
+        const tools = Array.isArray(result?.tools) ? result.tools : []
+        if (tools.length === 0) return { text: `(no tools visible on ${device})` }
+        const lines = tools.map((tool) => `- ${tool.name}${tool.description ? `: ${String(tool.description).slice(0, 160)}` : ''}`)
+        return { text: lines.join('\n') }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_call({ device, tool, parameters }) {
+      try {
+        const result = await client.call(device, { capability: 'tool', tool, args: parameters ?? {} })
+        return { text: client.render(result) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_delegate({ device, task, label, cwd }) {
+      try {
+        const result = await client.delegate(
+          device,
+          { task, ...(label ? { label } : {}), ...(cwd ? { cwd } : {}) },
+          { timeoutMs: 200_000 },
+        )
+        const meta = result?.childId ? `\n[delegated on ${device} · ${String(result.durationMs ?? 0)}ms · child ${String(result.childId)}]` : ''
+        return { text: `${String(result?.text ?? '')}${meta}`.trim() }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_read({ device, path, offset, limit }) {
+      try {
+        const args = { file_path: path }
+        if (offset !== undefined) args.offset = offset
+        if (limit !== undefined) args.limit = limit
+        const result = await client.call(device, { capability: 'read', tool: 'read', args })
+        return { text: client.render(result) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_fetch({ device, path }) {
+      try {
+        const result = await client.call(device, { capability: 'fetch', args: { path } })
+        return { text: client.render(result) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_run({ device, command }) {
+      try {
+        const result = await client.call(device, { capability: 'run', args: { command } })
+        return { text: client.render(result) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+  }
+}
+
+/** Build the model-facing ToolDefinitions once `defineTool` is available. */
+export function createFleetToolDefinitions({ defineTool, handlers }) {
+  const output = textOutput()
+  const commonDevice = { type: 'string', required: true, description: 'Target device id from `fleet_list`.' }
+  return [
+    defineTool({
+      name: 'fleet_status',
+      description:
+        'Show this device\'s Fleet network status for troubleshooting: device id, direct listener address/port, discovery, connected peers, roster and invite/manual address hints. Use it when discovery does not find the other device.',
+      parameters: {},
+      output,
+      execute: () => handlers.fleet_status(),
+    }),
+    defineTool({
+      name: 'fleet_connect',
+      description:
+        'Connect to another device by explicit host and port when LAN discovery is unavailable. Use it with the port printed by that device\'s `fleet_status`; the peer id is learned from the authenticated handshake.',
+      parameters: {
+        host: { type: 'string', required: true, description: 'Target host/IP address on the LAN or VPN.' },
+        port: { type: 'number', required: true, description: 'Target device\'s Fleet direct port (from its fleet_status).' },
+      },
+      output,
+      execute: (args) => handlers.fleet_connect(args),
+    }),
+    defineTool({
+      name: 'fleet_approvals',
+      description:
+        'List pending approval requests waiting on this device (remote direct calls or delegations whose Tool Policy is `ask`). Approve or deny them with `fleet_approve` / `fleet_deny`. Approvals expire after the configured timeout and fail closed.',
+      parameters: {},
+      output,
+      execute: () => handlers.fleet_approvals(),
+    }),
+    defineTool({
+      name: 'fleet_approve',
+      description:
+        'Approve one pending approval request on this device. `scope: "once"` allows one call; `scope: "ttl"` allows that capability for the configured TTL (default 15 minutes). Permanent grants belong in the device settings, not here.',
+      parameters: {
+        id: { type: 'string', required: true, description: 'Approval request id from `fleet_approvals`.' },
+        scope: { type: 'string', enum: ['once', 'ttl'], description: 'Approval scope; defaults to once.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_approve(args),
+    }),
+    defineTool({
+      name: 'fleet_deny',
+      description: 'Deny one pending approval request on this device.',
+      parameters: {
+        id: { type: 'string', required: true, description: 'Approval request id from `fleet_approvals`.' },
+        reason: { type: 'string', description: 'Optional reason returned to the caller.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_deny(args),
+    }),
+    defineTool({
+      name: 'fleet_simulate_request',
+      description:
+        'Development helper (only when approval simulation is enabled): create a fake pending approval request so the inbox flow can be exercised without a second device. It does not execute anything.',
+      parameters: {
+        fromDeviceId: { type: 'string', description: 'Pretend caller device id.' },
+        capability: { type: 'string', description: 'Capability name, e.g. run.' },
+        tool: { type: 'string', description: 'Optional tool name.' },
+        reason: { type: 'string', description: 'Optional reason shown in the request.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_simulate_request(args),
+    }),
+    defineTool({
+      name: 'room_create',
+      description:
+        'Upgrade the current session into a Room Host (local logic layer) so multiple agents can collaborate with shared messages and a shared task board. Add participants with `room_add_local` (simulation) or the future remote invite flow. Only do this when the user explicitly wants multi-agent collaboration, not for a one-off remote tool call.',
+      parameters: {
+        policy: { type: 'object', additionalProperties: true, description: 'Optional room policy overrides (invite/join/maxMembers/boardWrite/remove).' },
+      },
+      output,
+      execute: (args, exec) => handlers.room_create(args, exec),
+    }),
+    defineTool({
+      name: 'room_add_local',
+      description:
+        'Simulation helper: add a real local DSH agent as a Room participant (its own session). Use it to exercise addressing/wake/board logic in one DSH before the remote participant transport exists.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id returned by room_create.' },
+        name: { type: 'string', description: 'Participant display name.' },
+        agentPreset: { type: 'string', description: 'Optional agent preset id for the participant session.' },
+        cwd: { type: 'string', description: 'Optional working directory for the participant session.' },
+      },
+      output,
+      execute: (args) => handlers.room_add_local(args),
+    }),
+    defineTool({
+      name: 'room_remove_member',
+      description: 'Remove a participant from a Room (the host cannot be removed; close the room instead).',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        memberId: { type: 'string', required: true, description: 'Member id from room_status.' },
+        reason: { type: 'string', description: 'Optional reason recorded in the room log.' },
+      },
+      output,
+      execute: (args) => handlers.room_remove_member(args),
+    }),
+    defineTool({
+      name: 'room_send',
+      description:
+        'Send one addressed Room message as the calling agent. The host appends it to the canonical room log and wakes only the addressed participants; unaddressed members do not run. To say different things to different members, send separate messages.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        to: { type: 'array', items: { type: 'string' }, required: true, description: 'Recipient member ids.' },
+        text: { type: 'string', required: true, description: 'Message body.' },
+      },
+      output,
+      execute: (args, exec) => handlers.room_send(args, exec),
+    }),
+    defineTool({
+      name: 'room_messages',
+      description: 'Read the Room transcript (the user-visible complete conversation, including agent-to-agent messages).',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        limit: { type: 'number', description: 'Maximum recent messages to return (default 50).' },
+      },
+      output,
+      execute: (args) => handlers.room_messages(args),
+    }),
+    defineTool({
+      name: 'room_status',
+      description: 'Show one Room\'s members, policy, message count and task count.',
+      parameters: { roomId: { type: 'string', required: true, description: 'Room id.' } },
+      output,
+      execute: (args) => handlers.room_status(args),
+    }),
+    defineTool({
+      name: 'room_task_add',
+      description:
+        'Add one shared Room Board task. Use dependsOn to express serial handoff: when all dependencies are done, the owner is woken with a "ready" message. Parallel tasks have no dependencies and do not block each other.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        title: { type: 'string', required: true, description: 'Task title.' },
+        owner: { type: 'string', required: true, description: 'Owner member id.' },
+        dependsOn: { type: 'array', items: { type: 'string' }, description: 'Task ids that must complete first.' },
+        description: { type: 'string', description: 'Optional task detail.' },
+      },
+      output,
+      execute: (args) => handlers.room_task_add(args),
+    }),
+    defineTool({
+      name: 'room_task_update',
+      description:
+        'Update one Room Board task. Marking it done triggers serial handoff: owners of pending dependent tasks are woken. Keep status/steps current when starting and finishing your block.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        id: { type: 'string', required: true, description: 'Task id.' },
+        status: { type: 'string', enum: ['pending', 'running', 'done', 'blocked'], description: 'New status.' },
+        note: { type: 'string', description: 'Optional progress note.' },
+      },
+      output,
+      execute: (args) => handlers.room_task_update(args),
+    }),
+    defineTool({
+      name: 'room_task_list',
+      description: 'List the shared Room Board tasks with status, owner and dependencies.',
+      parameters: { roomId: { type: 'string', required: true, description: 'Room id.' } },
+      output,
+      execute: (args) => handlers.room_task_list(args),
+    }),
+    defineTool({
+      name: 'room_close',
+      description: 'Close a Room (archives its canonical log); participants are no longer woken afterwards.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        reason: { type: 'string', description: 'Optional close reason.' },
+      },
+      output,
+      execute: (args) => handlers.room_close(args),
+    }),
+    defineTool({
+      name: 'fleet_invite',
+      description:
+        'Create a Fleet invite code for another device. Only do this when the user asks to pair a new device. Treat the returned code as a secret; it carries the fleet key.',
+      parameters: {},
+      output,
+      execute: () => handlers.fleet_invite(),
+    }),
+    defineTool({
+      name: 'fleet_join',
+      description:
+        'Join an existing Fleet with an invite code from `fleet_invite` on another device. The enrollment is queued and takes effect after DSH restarts on this device.',
+      parameters: {
+        code: { type: 'string', required: true, description: 'Invite code produced by fleet_invite on another device.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_join(args),
+    }),
+    defineTool({
+      name: 'fleet_list',
+      description:
+        'List the devices in this Fleet with their online status. Call it before any `fleet_*` call to learn which device id to use. Offline devices are listed too, but direct calls to them fail fast; use a Room/delegation instead of waiting.',
+      parameters: {},
+      output,
+      execute: () => handlers.fleet_list(),
+    }),
+    defineTool({
+      name: 'fleet_tools',
+      description:
+        'List the tools another device exposes to direct calls (name + description). Use it only when you need an untyped tool; the typed shortcuts `fleet_read` / `fleet_fetch` / `fleet_run` cover the common cases.',
+      parameters: { device: commonDevice },
+      output,
+      execute: (args) => handlers.fleet_tools(args),
+    }),
+    defineTool({
+      name: 'fleet_call',
+      description:
+        'Call one tool on another device directly. Direct calls are stateless: no Room, no shared conversation, no remote history. Use `fleet_tools` first to discover names/arguments, or prefer the typed shortcuts. The target device decides whether to allow, ask its user, or reject.',
+      parameters: {
+        device: commonDevice,
+        tool: { type: 'string', required: true, description: 'Tool name on the target device.' },
+        parameters: { type: 'object', additionalProperties: true, description: 'Arguments object for that tool.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_call(args),
+    }),
+    defineTool({
+      name: 'fleet_delegate',
+      description:
+        'Delegate a one-shot task to another device\'s agent and wait for its final answer. Use it when the work needs that device\'s model and tools ("let B build/check this"), not just one tool call. The delegated agent runs on the target device; it does not join a Room and its history is not shared. The target device decides whether delegation is allowed or needs local approval.',
+      parameters: {
+        device: commonDevice,
+        task: { type: 'string', required: true, description: 'Self-contained task instructions for the target agent.' },
+        label: { type: 'string', description: 'Short label shown in the target device\'s subagent list.' },
+        cwd: { type: 'string', description: 'Optional working directory on the target device.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_delegate(args),
+    }),
+    defineTool({
+      name: 'fleet_read',
+      description:
+        'Read a file on another device (shortcut over `fleet_call` with the target `read` tool). Paths must be inside the roots that device allows. Use it to inspect logs/docs on another machine without opening a Room.',
+      parameters: {
+        device: commonDevice,
+        path: { type: 'string', required: true, description: 'Absolute path on the target device.' },
+        offset: { type: 'number', description: 'Line offset, when supported by the target read tool.' },
+        limit: { type: 'number', description: 'Maximum lines to return.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_read(args),
+    }),
+    defineTool({
+      name: 'fleet_fetch',
+      description:
+        'Fetch a file from another device and return its text content. Use it for "look at B\'s file and bring it over"; for large binaries prefer `fleet_run` with a transfer command.',
+      parameters: {
+        device: commonDevice,
+        path: { type: 'string', required: true, description: 'Absolute path on the target device.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_fetch(args),
+    }),
+    defineTool({
+      name: 'fleet_run',
+      description:
+        'Run a shell command on another device (shortcut over `fleet_call` with the target shell tool). The target device\'s Tool Policy decides whether the command is auto-allowed, needs its local approval, or is rejected; an offline or timed-out approval fails. Use it for builds/tests and other work that belongs on that machine.',
+      parameters: {
+        device: commonDevice,
+        command: { type: 'string', required: true, description: 'Shell command to run on the target device.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_run(args),
+    }),
+  ]
+}

package/src/index.js

@@ -0,0 +1,3 @@
+// Placeholder entry for the DSH plugin. The Host/Client halves land in a later
+// step; for now the network layer is exported so it can be tested and reused.
+export * as net from './net/index.js'

package/src/net/direct.js

@@ -0,0 +1,69 @@
+// Plain TCP direct transport: a listening server and an outbound dialer.
+// The secure channel runs on top; this module only owns sockets.
+import net from 'node:net'
+
+/**
+ * Start a direct listener.
+ * @param {{host?: string, port?: number}} [options]
+ * @returns {{server: net.Server, ready: Promise<{host: string, port: number}>, close: () => Promise<void>}}
+ */
+export function createDirectServer({ host = '0.0.0.0', port = 0 } = {}) {
+  const server = net.createServer({ allowHalfOpen: false })
+  const ready = new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening)
+      reject(error)
+    }
+    const onListening = () => {
+      server.off('error', onError)
+      const address = server.address()
+      resolve({ host: typeof address === 'object' && address ? address.address : host, port: address?.port ?? port })
+    }
+    server.once('error', onError)
+    server.once('listening', onListening)
+    server.listen(port, host)
+  })
+  return {
+    server,
+    ready,
+    close: () =>
+      new Promise((resolve) => {
+        if (!server.listening) return resolve()
+        server.close(() => resolve())
+      }),
+  }
+}
+
+/**
+ * Dial a direct endpoint.
+ * @param {{host: string, port: number, timeoutMs?: number}} options
+ * @returns {Promise<import('node:net').Socket>}
+ */
+export function connectDirect({ host, port, timeoutMs = 5_000 }) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect({ host, port })
+    const timer = setTimeout(() => {
+      cleanup()
+      socket.destroy()
+      const error = new Error(`direct connect to ${host}:${String(port)} timed out`)
+      error.code = 'connect-timeout'
+      reject(error)
+    }, timeoutMs)
+    timer.unref?.()
+    const cleanup = () => {
+      clearTimeout(timer)
+      socket.off('connect', onConnect)
+      socket.off('error', onError)
+    }
+    const onConnect = () => {
+      cleanup()
+      resolve(socket)
+    }
+    const onError = (error) => {
+      cleanup()
+      reject(error)
+    }
+    socket.once('connect', onConnect)
+    socket.once('error', onError)
+  })
+}