Skip to main content
Builtins catalog / nika:inspect

Introspection

Tool family from the canonical registry.

invoke

Call this builtin through the invoke verb.

​
Read this contract

This reference preserves the specification at the revision linked below. Source examples are fragments: their surrounding tasks, inputs and permissions are not supplied here. Consult engine status and nika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.

​
Usage and behavior

illustration
Workflow introspection · 1 builtin · 4 view: enum modes (Rams collapse per ADR-088 · 2026-05-27) ·
  • view: cost → { total_usd, by_task, by_provider }. Running workflow cost.
  • view: records → { tasks: [{ id, status, duration_ms, ... }] }. Full execution record. (Per-task status is also read directly via the ${{ tasks.X.status }} namespace, same shape.)
  • view: dag_info → { nodes, edges, waves }. DAG topology.
  • view: threads → { active, queued, completed }. Engine task-pool state · advisory · counts reflect the engine’s concurrency model (impl-dependent · use for coarse adaptive-throttling · not a portable contract-precise number).
Replaces · 4 legacy introspection builtins (nika:cost · nika:records · nika:dag_info · nika:threads) collapsed per « less but better » Rams sweep · same trust class (PURE) · same query-own-workflow-state semantic family · the split into 4 separate builtins was historical (one-per-shape) not structural · the unified view: discriminator + per-shape args: is the canonical « one super-powerful builtin · multi-mode args » pattern (matches fetch+extract · jq · convert · wait). Throws · NIKA-BUILTIN-INSPECT-001 if view: value not in the canonical enum. The reference engine injects a live cell at composition and writes it as tasks settle. available: true once the DAG is seeded at run start. The teaching shape is examples/16-inspect-self.nika.yaml. Probe any new builtin with mock/echo before wiring it after a paid infer.

Arguments

Pass the values required by the tool contract.

Permissions

Understand authority before granting effects.

Errors and recovery

Read diagnostics and choose a recovery policy.

Workflow templates

Put the fragment inside a complete workflow.

​
Contract provenance

Read the pinned specification · Canonical registry. Tool identity: nika:inspect. Specification revision: f8c5df2127c7. The Lab language identity is language:tool:inspect; the registry view is ecosystem:tool/nika:inspect. They refer to this contract without merging their graph identities.