@stackwright-pro/telemetry

Producer-owned telemetry schema and best-effort NDJSON emit for Stackwright Pro pipeline events.

What this is

This package owns the ProEmittedEvent Zod discriminated union and an emit() function that appends events to .stackwright/pipeline-events.ndjson during raft runs. It implements the Pro-producer side of ADR-002.

• Producer: @stackwright-pro/mcp handlers (tool_call, file_write, pipeline_state_change, …)
• Consumer: otter-viz bridge, future OTel adapter, future repair loop
• Sink: .stackwright/pipeline-events.ndjson (append-only NDJSON, one event per line)

Event types (v1 Pro-emitted subset)

| type | emitter | | ----------------------- | ------------------------------------------ | | phase_start | foreman (via stackwright_pro_emit_event) | | phase_complete | foreman | | agent_invoke_start | foreman | | agent_invoke_complete | foreman | | tool_call | MCP handler entry | | tool_complete | MCP handler exit | | file_read | MCP handler (future) | | file_write | MCP handler after successful write | | pipeline_state_change | phase-state transition handler |

Not in this package (raft-puppy responsibility): reasoning_dump, thinking, agent_response, token_update, shell_command, raw_log.

Usage

import { emit } from '@stackwright-pro/telemetry';

// Best-effort — never throws, returns false on failure
const ok = emit({
  type: 'tool_call',
  toolName: 'stackwright_pro_validate_artifact',
  args: { phase: 'designer' },
  phase: 'designer',
});

emit() options

emit(input, { cwd: '/path/to/project' });

cwd is optional. If omitted, resolution order:

1. STACKWRIGHT_PROJECT_ROOT env var
2. process.cwd()

Environment variables

| Variable | Effect | | ---------------------------------- | ------------------------------------------------------------------ | | STACKWRIGHT_TELEMETRY_DISABLED=1 | Disable all emit calls — emit() returns false, no file written | | STACKWRIGHT_PROJECT_ROOT=/path | Override sink root (primarily for tests) | | STACKWRIGHT_TELEMETRY_DEBUG=1 | Log validation failures and I/O errors to stderr |

Sink path

.stackwright/pipeline-events.ndjson relative to project root.

Created automatically if missing. Never written through symlinks (matches safeWriteSync convention in pipeline.ts).

Architecture

• swp-im3c — this bead (Pro-side emit infrastructure)
• swp-hzz9 — follow-up: mcp_binding_warning event variant
• code_puppy-vbt — raft-puppy side: TelemetryRenderer emitting cognitive events
• swp-hpfa — CI contract test for cross-repo schema drift
• ADR-002 — ../otter-viz/docs/schema-ownership-decision.md