@meego-harness/sdk

Harness SDK for full-lifecycle Meego integrations.

What it does

• builds on top of @meego-harness/event-sdk
• composes @meego-harness/worker-sdk by default
• records four event streams: meego, openapi, harness, worker
• supports HITL storage in memory or sqlite
• exposes a Node-only audited meegoClient

Install

pnpm add @meego-harness/sdk hono

Example

import { MeegoHarnessSDK } from '@meego-harness/sdk'

const sdk = new MeegoHarnessSDK({
  meego: {
    pluginId: process.env.MEEGO_PLUGIN_ID,
    token: process.env.MEEGO_WEBHOOK_TOKEN,
    pluginSecret: process.env.MEEGO_PLUGIN_SECRET,
  },
  openapi: {
    baseURL: process.env.MEEGO_BASE_URL,
  },
})

sdk.on('project-init', async (event) => {
  console.log(event.payload.id)
  console.log(event.payload.project_name)
})

console.log(sdk.listProjects())

await sdk.meegoClient.workItem.query({
  work_item_ids: [123456],
})

HITL sync to Meego work items

Use hitlSyncRules when a new HITL record should also create a Meego approval work item.

import { MeegoHarnessSDK } from '@meego-harness/sdk'

const sdk = new MeegoHarnessSDK({
  meego: {
    pluginId: process.env.MEEGO_PLUGIN_ID,
    token: process.env.MEEGO_WEBHOOK_TOKEN,
    pluginSecret: process.env.MEEGO_PLUGIN_SECRET,
  },
  projectInitRules: [
    {
      projectKey: 'meego-space-1',
      workItemTypeKey: 'story',
      templateId: '481329',
    },
  ],
  hitlSyncRules: [
    {
      projectKey: 'approval-space',
      workItemTypeKey: 'approval',
      templateId: '900001',
      type: 'worker-dispatch-blocked',
    },
    {
      projectKey: 'approval-space',
      workItemTypeKey: 'approval',
      type: 'worker-input-required',
    },
  ],
})

await sdk.createHitl({
  projectId: 7105803003,
  kind: {
    category: 'progression',
    type: 'worker-dispatch-blocked',
    reasonCode: 'manual-review-required',
  },
  title: 'Need release approval',
  summary: 'A human needs to confirm the release plan',
  operator: 'ou_xxx',
  context: {
    releaseId: 'release-42',
  },
  responseSpec: {
    required: false,
    allowedPartTypes: ['text'],
  },
})

Notes:

• projectId is the harness project ID, not the Meego projectKey.
• projectKey inside hitlSyncRules is the target Meego space key for the approval work item.
• createHitl() should prefer explicit kind over legacy sourceType.
• When operator is present, the SDK uses it as the audited OpenAPI user. To also write role_owners, configure hitlSyncRules[].roleOwnerRole with the target Meego role ID.
• When operator is missing but the HITL has worker email context, the SDK searches Meego users by email and uses the exactly matched user_key.

OpenAPI client

• accessor: sdk.meegoClient
• base URL priority:
  • openapi.baseURL
  • process.env.MEEGO_BASE_URL
  • meeglesdk default
• every outgoing Meego operation is recorded into the openapi stream

Manager-agent internal API

The remote manager WebSocket control plane has been removed. The gateway-owned manager-agent now runs in-process and calls MeegoHarnessSDK.executeManagerCommand and MeegoHarnessSDK.subscribeManagerEvent through a local control port. The worker server no longer accepts manager command or subscription frames.

OpenAPI whitelist env

• env name: MEEGO_HARNESS_MANAGER_OPENAPI_WHITELIST
• format: JSON array of action IDs
• unset or []: manager can still use harness admin commands, but cannot invoke remote OpenAPI actions
• invalid JSON, non-array values, or unknown action IDs fail fast during MeegoHarnessSDK initialization

Action IDs are derived from the actual sdk.meegoClient surface with kebab-case paths, for example:

• openapi.get-base-url
• openapi.work-item.query
• openapi.work-item.comment.create