Skip to main content

Documentation Index

Fetch the complete documentation index at: https://smithers.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
0.20.1

Patch release: agent-trace observability lands, the smithers 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

  • smithers 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. smithers 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.