add-agenttrace

name	add-agenttrace
description	Add live agent activity traces (tools, tasks, reasoning summaries, silence keepalives) via nanoclaw-agenttrace and nanoclaw-hosthooks.

/add-agenttrace — Live Agent Activity Trace

Surfaces what the agent is doing during long turns — tools, task progress, optional reasoning summaries, and silence keepalives — without polluting chat history on rich channels.

Addresses nanocoai/nanoclaw#1440. Does not implement deep-session mode (#1686).

See also: QUICKSTART.md in the npm package.

Prerequisites

• Working NanoClaw v2 install with pnpm
• Node.js ≥ 20 (22 recommended)
• nanoclaw-hosthooks API v1 installed in the host and runner
• Container rebuilt after installing hosthooks

Architecture

Claude SDK → agenttrace observe (container)
                ↓
         messages_out system action
                ↓
         host delivery action → channel (timeline | edit status | typing)

Recipe order

/add-webchat       # optional — richest timeline UI
/add-agenttrace    # this skill

Install

Pre-flight (idempotent)

Skip to Enable if all of these are already in place:

• src/agenttrace-boot.ts exists
• container/agent-runner/src/agenttrace/observe.ts exists
• src/index.ts contains await startAgentTrace()
• src/hosthooks.ts and container/agent-runner/src/hosthooks.ts expose API v1
• nanoclaw-agenttrace is listed in package.json

Otherwise continue. Every step is safe to re-run.

0. Sync this skill (first time only)

pnpm exec nanoclaw-agenttrace sync-skill

1. Install npm package

pnpm add nanoclaw-agenttrace@0.1.0

Local peer monorepo:

pnpm add file:../nanoclaw-agenttrace

2. Run the installer

pnpm exec nanoclaw-agenttrace install

This will:

1. Copy host adapter sources into src/agenttrace-*.ts
2. Copy runner modules into container/agent-runner/src/agenttrace/
3. Insert the host startAgentTrace() boot block and runner registration import
4. Register Claude observation, partial/summarized-thinking options, inbound turn boundaries, and container environment forwarding through hosthooks
5. Scaffold .env keys (AGENTTRACE_ENABLED=false by default)
6. Sync this skill to .claude/skills/add-agenttrace/

The installer fails clearly when hosthooks API v1 or its call sites are missing. Install nanoclaw-hosthooks first and rebuild the container.

3. Enable

In .env:

AGENTTRACE_ENABLED=true
AGENTTRACE_DEFAULT_VISIBILITY=trace
AGENTTRACE_SILENCE_KEEPALIVE=true

4. Build, rebuild container, verify

pnpm run build
./container/build.sh
pnpm exec nanoclaw-agenttrace verify
# restart host

Run host wiring test when present:

pnpm exec vitest run src/agenttrace-wiring.test.ts src/agenttrace-config.test.ts src/agenttrace-dispatch.test.ts

5. Webchat companion (optional)

If nanoclaw-webchat is installed, upgrade it to ≥ 0.3.1 (implements publishActivity + activity WebSocket events) for the collapsible timeline:

pnpm webchat:local   # or: pnpm add nanoclaw-webchat@0.3.1 && pnpm exec nanoclaw-webchat install

Typing continues to work as a floor signal even without the timeline.

Uninstall

See REMOVE.md.

Visibility levels

Value	Shows
off	Nothing
status	Tools / tasks / keepalives (no reasoning or partial text)
trace (default)	Status + partial text + Anthropic summarized reasoning
trace_reasoning	Alias of trace (compat; no raw CoT mode — API does not expose raw CoT)
trace_full	Everything in trace plus secret-scanned tool inputs/results and subagent transcripts

trace_full payloads are secret-scanned (@sanity-labs/secret-scan, pattern-based) — credential-shaped strings are stripped, but PII, internal URLs, file paths, and proprietary content pass through truncated. Enable only where that content is acceptable on the timeline.

Host default: AGENTTRACE_DEFAULT_VISIBILITY. Per-group override (container env / config blob): activity_visibility or AGENTTRACE_VISIBILITY at spawn — no trunk CRUD change required if you set it in the group's container config JSON.

Retention

Bounded per session: max 200 events/turn (500 under trace_full), ~4 KiB/event summary, prune oldest activity rows beyond 50 turns. Activity never replaces the final chat reply.