---
title: "0.20.1"
description: "Patch release: agent-trace observability lands, the bunx smithers-orchestrator init agent"
---

Patch release: agent-trace observability lands, the `bunx smithers-orchestrator init` agent
flow gets sharper, and `pnpm release` now opens a GitHub release.

---

## Observability

- **Canonical agent traces.** Every node attempt that invokes an agent now
  emits canonical `AgentTraceEvent` / `AgentTraceSummary` /
  `AgentSessionEvent` records, OTEL log records with stable Loki query
  attributes (`run.id`, `workflow.path`, `node.id`, `node.attempt`,
  `agent.family`, `agent.capture_mode`, `trace.completeness`,
  `event.kind`), and, when `logDir` is set, a durable NDJSON artifact
  at `.smithers/executions/<runId>/logs/agent-trace/<node>-<iter>-<attempt>.ndjson`.
  See `packages/engine/src/AgentTraceCollector.js` and the new
  `apps/observability/src/agentTrace.ts` surface.

- **Local OTEL stack adds Loki 3.3.2.** `observability/docker-compose.otel.yml`
  pins `otel-collector` to `0.148.0`, adds a Loki service with a
  persistent `/loki` volume, wires the otel-collector logs pipeline to
  Loki via `otlp_http`, and adds healthchecks + `service_healthy`
  `depends_on` across the stack. Grafana ships with a Loki datasource
  and Tempo `tracesToLogs` config out of the box. New helper scripts:
  `scripts/obs-reset.sh`, `scripts/obs-wait-healthy.sh`,
  `scripts/verify-observability.sh`.

- **Run annotations.** `RunOptions.annotations` is a flat
  `Record<string, string | number | boolean>` plumbed through every run
  for stable Loki/OTEL query attributes.

- **Demo workflow.** `workflows/agent-trace-otel-demo.tsx` shows the
  end-to-end trace surface against the live OTEL stack.

## Agents

- **Token-usage normalization.** New
  `packages/agents/src/BaseCliAgent/normalizeTokenUsage.js` collapses
  provider-specific token-usage fields into a single
  `NormalizedTokenUsage` shape regardless of source naming.

- **Better JSON text extraction.** `BaseCliAgent.extractTextFromJsonValue`
  now handles array roots, OpenAI-style `output_text`, and recursive
  `item` fields, relevant for Codex/Responses-API outputs.

## CLI

- **`bunx smithers-orchestrator init` agent detection.** Reworked
  `apps/cli/src/agent-detection.js` so the init flow detects installed
  agents correctly across more environments; covered by new tests in
  `apps/cli/tests/cli-agent-detection.test.js` and
  `apps/cli/tests/init-agents.e2e.test.js`.

- **Better `.gitignore` templates.** `bunx smithers-orchestrator init` now writes
  `*.db-shm`, `*.db-wal`, `*.log`, and `logs/` into
  `.smithers/.gitignore`, and adds a new
  `.smithers/workflows/.gitignore` for `*.log` / `run-*.log`. Keeps
  ephemeral SQLite WAL files and run logs out of git by default. (#137)

## Gateway

- **Hardened HTTP boundaries.** `packages/server/src/gateway.js`
  tightens request/response handling at the gateway boundary; covered
  by the rewritten `gateway-http-boundaries.test.js`. (#134)

## Internal

- **GitHub releases on `pnpm release`.** `scripts/publish.mjs` now
  pushes the version tag to `origin` if missing and runs
  `gh release create v<version> --notes-file docs/changelogs/<version>.mdx --latest`
  after a successful npm publish. Pass `--skip-gh-release` to opt out.
  Fills the gap that left releases on GitHub stuck at v0.12.0 while
  npm advanced to v0.20.0; all intermediate tags were backfilled in
  the same pass.

- **Engine `index.d.ts` cleanup.** `tsup --dts-only` regen of the
  engine type bundle drops orphaned
  `ComponentDefinition` / `ComponentDefinitionBuilder` /
  `WorkflowDefinitionBuilder` aliases left over from the Effect API
  rebuild. No public-surface change.
