@meego-harness/worker-sdk

worker-sdk owns the worker control plane: websocket server/client transport, login, optional device authorization, challenge-response identity reuse, heartbeats, worker availability, task delivery, task updates, cancellation, and reconnect behavior.

Use this package when you are implementing a custom worker server or custom worker bridge. Use @meego-harness/gateway when you want a complete process that already embeds a worker server.

Install

pnpm add @meego-harness/worker-sdk

Server

import { WorkerServerSDK } from '@meego-harness/worker-sdk'

const server = new WorkerServerSDK({
  path: '/workers',
  loginAuthorization: {
    mode: 'manual',
    signingSecret: process.env.WORKER_LOGIN_SIGNING_SECRET!,
  },
})

server.onWorkerEvent((event) => {
  console.log(event.type, event.worker.workerId)
})

server.onTaskUpdate((event) => {
  console.log(event.taskId, event.status)
})

await server.listen(3000)

Use listen(0) in tests or local harnesses that need an OS-assigned port; read the actual port from getListeningAddress().

Client

import { WorkerClientSDK } from '@meego-harness/worker-sdk'

const client = new WorkerClientSDK({
  serverUrl: 'ws://127.0.0.1:3000/workers',
})

client.onMessage(async (context) => {
  await context.controller.working()
  await context.controller.complete({
    parts: [{ type: 'text', text: `received ${context.message.parts.length} part(s)` }],
  })
})

await client.connect()
await client.login({
  workerId: 'example-worker',
  email: '[email protected]',
  capabilitySummary: 'Handles example tasks',
  managerPromotionEnabled: true,
  credentialDeliveryEnabled: true,
  expectedCredentialKinds: ['lark-cli'],
})

expectedCredentialKinds is an optional hint. A server-side credential provider can use it to attach matching task-level leases. Gateway uses this hint to auto-bind at most one matching owner-only credential for the worker email before task delivery; if no credential matches, task dispatch continues without a credential lease.

Concepts

| Concept | Meaning | | --- | --- | | workerId + email | Stable worker identity. | | contextId | Conversation/execution context shared across related tasks and messages. | | taskId | One worker task instance under a context. | | WorkerEvent | Runtime worker lifecycle event such as login, logout, disconnect, or availability change. | | TaskUpdateEvent | Task status or artifact update emitted by workers. | | Device identity | Local keypair used for challenge-response login after first authorization. | | Outbox | Optional client-side persisted retry buffer for status/artifact updates. |

Boundaries

• This package does not know Meego project or work item semantics.
• This package does not render gateway dashboard views.
• This package does not create HITL records by itself; callers decide how to handle login authorization and task failures.