Relay Observe Instrument: TypeScript

This repository provides the canonical TypeScript/Node.js SDK for emitting constitutionally-valid Relay signals as structured OTLP logs. It powers the Vitest E2E harness in relay/observe/deploy/compose to simulate and verify the Relay handover lifecycle.

What it is (high-level)

• Simple client: InstrumentClient for Node.js actors (human/agent/services).
• Contracts-first: Uses protobuf-ts generated types and packs payloads into google.protobuf.Any.
• OpenTelemetry logs: Minimal, stable provider/processor/exporter setup that plays nicely with test seams.
• API Surface:
  • task.start({ taskId, taskType, causeTaskId? })
  • task.complete({ taskId, reviewRoundsCount? })
  • task.handover({ taskId, recipient }) → returns { handoverId }
  • work.start({ taskId, handoverId })
  • experiment.start({ experimentId, hypothesis })
  • experiment.conclude({ experimentId, outcome })
  • experiment.graduate({ experimentId, newTaskId })

Why it exists

To keep instrumentation ergonomic, type-safe, and production-grade, while making tests predictable and verifiable across OpenTelemetry minor/patch evolutions.

Quickstart

The following example demonstrates how to simulate a task handover between two actors.

import {
  InstrumentClient,
  ExperimentConcludedEvent_Outcome
} from '@deposition/relay-observe-instrument-ts'

// Actor 1 (e.g., a developer)
const alex = {
  actorId: 'alex-uuid',
  actorType: 'human',
  organizationId: 'org-1'
}
const clientForAlex = new InstrumentClient({
  endpoint: 'http://localhost:4318',
  actor: alex,
  context: { contextId: 'ctx-1' },
  serviceName: 'relay-instrument-ts-dev'
})

// Actor 2 (e.g., a QA agent)
const barbara = {
  actorId: 'barbara-uuid',
  actorType: 'agent',
  organizationId: 'org-1'
}
const clientForBarbara = new InstrumentClient({
  endpoint: 'http://localhost:4318',
  actor: barbara,
  context: { contextId: 'ctx-1' },
  serviceName: 'relay-instrument-ts-dev'
})

// --- Simulate the workflow ---
console.log('Alex starts a task...')
clientForAlex.task.start({ taskId: 'PROJ-123', taskType: 'feature' })

console.log('Alex hands the task over to Barbara...')
const { handoverId } = clientForAlex.task.handover({
  taskId: 'PROJ-123',
  recipient: barbara
})
console.log(`Handover initiated with ID: ${handoverId}`)

console.log('Barbara accepts and starts the work...')
clientForBarbara.work.start({ taskId: 'PROJ-123', handoverId })

console.log('Barbara completes the task with no reviews needed.')
clientForBarbara.task.complete({ taskId: 'PROJ-123', reviewRoundsCount: 0 })

// --- Shutdown clients ---
await clientForAlex.shutdown()
await clientForBarbara.shutdown()

Debugging

Set INSTRUMENT_DEBUG=1 (or pass { logLevel: DiagLogLevel.DEBUG }) to enable detailed diag.* traces:

INSTRUMENT_DEBUG=1 pnpm test

You’ll see lifecycle events like exporter creation, provider wiring, and per-event emission traces.

Roadmap (phases)

• Phase 1 (Completed): Core client with full KPI signal coverage and a comprehensive test suite.
• Phase 2 (Current Focus): Evolve into a full-featured SDK with metrics, auto-instrumentation, and robust error handling.
• Phase 3: Isomorphic browser support.