Skip to content
This repository was archived by the owner on Jul 15, 2026. It is now read-only.

Add term-mesh integration: telemetry bridge & execution backend - #5

Open
JINWOO-J wants to merge 5 commits into
mainfrom
claude/xkit-term-mesh-integration-rie8ws
Open

Add term-mesh integration: telemetry bridge & execution backend#5
JINWOO-J wants to merge 5 commits into
mainfrom
claude/xkit-term-mesh-integration-rie8ws

Conversation

@JINWOO-J

@JINWOO-J JINWOO-J commented Jul 8, 2026

Copy link
Copy Markdown
Member

Summary

Adds opt-in term-mesh integration to x-kit, enabling x-build/x-op/x-agent/x-trace to publish telemetry and task state to a term-mesh daemon when running inside a term-mesh pane session. The integration is fire-and-forget, auto-detects term-mesh availability, and degrades gracefully to a no-op when absent — maintaining the invariant that x-kit works with Claude Code alone.

Key Changes

Core telemetry bridge (tm-bridge.mjs)

  • New module synced across x-trace, x-build, x-kit (source of truth: x-trace/lib/x-trace/tm-bridge.mjs)
  • Socket discovery: detects per-pane app socket (TERMMESH_SOCKET) and daemon socket (/tmp/term-meshd.sock)
  • Pane telemetry: paneSetStatus(), paneSetProgress(), paneClearProgress() (line-text protocol)
  • Daemon events: publishDaemonEvent() (JSON-RPC 2.0, newline-framed)
  • Trace mirroring: mirrorTraceEntry(), mirrorTaskBoard() (called from trace-writer, tasks.mjs)
  • Fire-and-forget invariant: 100ms socket timeout, one-time warnings on stderr, never throws or blocks

Execution backend resolution

  • New getExecutionBackend() and isTermMeshSession() in shared-config.mjs
  • Precedence: XK_BACKEND env → execution_backend config → auto-detect
  • Values: 'auto' (term-mesh if detected, else native), 'native' (force Claude Code), 'term-mesh' (force tm-agent)
  • Added execution_backend: "auto" to default config

Dashboard & server integration

  • Term-mesh daemon HTTP proxy in x-dashboard-server.mjs (whitelist: /health, /team/*, /usage, etc.)
  • New renderTermMesh() UI panel showing live pane teams, tasks, usage, metrics
  • Graceful degradation: shows "OFFLINE" with helpful message when daemon unavailable

Task board mirroring

  • tasks.mjs calls mirrorTaskBoard() after list/add/update/remove operations
  • phase.mjs calls tasksMirror() to sync board state during phase transitions

Documentation

  • docs/term-mesh-integration.md: repo-neutral contract (socket discovery, transport map, fan-out rules)
  • x-agent/skills/agent/references/term-mesh-backend.md: runtime rules for primitive substitution
  • Updated SKILL.md files (agent, build, eval, humble, op) with term-mesh notes and backend resolution guidance
  • Updated autonomous research/solve docs with board.jsonl interop notes

Tests

  • test/tm-bridge.test.mjs: socket wire format, sanitization, fire-and-forget invariant
  • test/execution-backend.test.mjs: backend resolution precedence (env → config → auto-detect)

Implementation Details

  • Sync strategy: scripts/sync-bundle.sh maintains tm-bridge copies across x-trace, x-build, x-kit (source of truth marked in header)
  • Wire protocols: app socket uses line-text commands; daemon socket uses JSON-RPC 2.0 with newline framing
  • Error handling: warns once per process on stderr when a socket fails, then stays silent (x-humble L6 compromise)
  • Socket timeout: 100ms per send to prevent blocking the main flow
  • Backward compatibility: all functions are no-ops when sockets absent; no changes to native Agent tool path

https://claude.ai/code/session_01SQvKGq5h3ECwwSvP7Kjk7Y

claude added 5 commits July 7, 2026 03:07
@claude
feat: Phase 0 of term-mesh integration — backend config reservation +…
f83b6ef 
… contract doc

- Reserve execution_backend config key (auto|native|term-mesh) in
  default-config.json and shared-config DEFAULT_CONFIG; document in CLAUDE.md.
  No behavior change yet — resolution logic lands with getExecutionBackend().
- Add docs/term-mesh-integration.md: repo-neutral single source for the
  fan-out substitution contract (ported from term-mesh CLAUDE.md), backend
  detection/precedence, transport map, and the XK_TASK/XK_CORR reply-header
  contract that later phases implement.
- x-dashboard SKILL.md: 'Inside term-mesh' section — open the dashboard in a
  term-mesh browser split when a term-mesh session is detected.
- sync-bundle.sh: sync dashboard SKILL.md (its skill dir breaks the x-<p>/skills/<p>
  pattern) + verify block.
- block-marketplace-copy hook: fix protected-set names (were x-prefixed while the
  match key is the un-prefixed bundle dir, so the skills guard never fired) and
  add the dashboard mapping.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQvKGq5h3ECwwSvP7Kjk7Y
@claude
feat: Phase 1 — formalize term-mesh execution backend
e32cec1 
- shared-config.mjs: getExecutionBackend() (XK_BACKEND env → execution_backend
  config → auto-detect) + isTermMeshSession(); 9 precedence tests in
  test/execution-backend.test.mjs.
- New x-agent references/term-mesh-backend.md: runtime substitution rules
  shipped with the plugin — primitive→tm-agent mapping, 15-preset role map,
  team ensure, XK_TASK/XK_CORR reply-header contract, collect/synthesis rules,
  worktree lifecycle, bypass.
- x-agent SKILL.md: Execution Backend section before the primitives (resolve
  once, substitute per reference on term-mesh, unchanged on native).
- x-op SKILL.md: backend resolution folded into the Pre-Execution Confidence
  Gate; 'no term-mesh required' contract reworded to opt-in backend.
- Bundle synced via scripts/sync-bundle.sh.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQvKGq5h3ECwwSvP7Kjk7Y
@claude
feat: Phase 2 — real-time inbound bridge: x-kit → term-mesh panes/kanban
cbf911c 
- New tm-bridge.mjs (source: x-trace/lib/x-trace/): fire-and-forget telemetry
  into term-mesh. paneSetStatus/paneSetProgress over the per-pane app socket
  (TERMMESH_SOCKET, line protocol, --tab targeting), publishDaemonEvent over
  term-meshd events.publish (JSON-RPC), mirrorTaskBoard shelling to
  'tm-agent task create --deps'. All functions no-op without sockets,
  ≤100ms socket timeout, warn-once-then-silent on failure.
- trace-writer.traceAppend() mirrors every trace entry (session_start/fan_out/
  agent_step/synthesize/checkpoint/session_end) to the pane status pill and the
  daemon event bus — every tracing plugin gets live pane telemetry for free.
- x-build: 'tasks mirror' subcommand + automatic mirror on plan-exit gate pass
  (02-plan) — the task DAG lands on the term-mesh kanban/auto-claim pool with
  dependencies, idempotent via tm_task_id backrefs in tasks.json.
- sync-bundle.sh: tm-bridge synced x-trace → x-build same-dir copy → bundle;
  verify block extended. Hook protected set updated in lockstep (incl. missing
  release.mjs entry).
- Tests: test/tm-bridge.test.mjs — no-op invariant, app/daemon wire formats
  against fake unix-socket servers, task-mirror idempotency.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQvKGq5h3ECwwSvP7Kjk7Y
@claude
feat: Phase 4 — deep agent utilization inside term-mesh
ff4dd7e 
- term-mesh-backend.md reference: shared stigmergy board rules (one board per
  run, flock-append for multi-writer, unique agent names across pools) enabling
  MIXED swarms of native subagents + pane agents; scoring & budget governance
  section (model downgrade on warning/exceeded, daemon auto-stop kill-switch).
- x-agent autonomous research/solve: term-mesh interop note — tm-agent uses the
  same .xm/<behavior>/<run-id>/board.jsonl convention and entry schemas.
- x-eval: score term-mesh pane replies via their durable FULL_REPORT files
  (~/.term-mesh/results/<team>/), record quality_score as a task_complete
  metric — enables native-vs-pane A/B of the same strategy.
- x-humble: mirror applied lessons into .agent-runbooks/_common.md when the
  term-mesh runbook source dir exists, so 'tm-agent runbook digest' boots every
  pane agent with the project's confirmed STOP/START rules.
- Budget guard: checkBudget() level 'exceeded' now fires
  postBudgetAutoStop(true) → POST /api/budget/auto-stop on term-meshd
  (TERM_MESH_HTTP_ADDR, default 127.0.0.1:9876); fire-and-forget, no-op
  outside term-mesh. Tested against a local HTTP server.
- sync-bundle.sh: x-build lib mirror is now wholesale *.mjs glob (lesson L8) —
  cost-engine/root/config-loader are covered without per-file lists; hook
  treats all x-kit/lib/x-build/*.mjs as copies accordingly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQvKGq5h3ECwwSvP7Kjk7Y
@claude
feat: Phase 5 — term-mesh panel in x-dashboard
a993b65 
- Server: whitelist read-only proxy /api/term-mesh/* → term-meshd HTTP API
  (health/version/sessions/team*/usage/agents on TERM_MESH_HTTP_ADDR, default
  127.0.0.1:9876; forwards TERM_MESH_HTTP_PASSWORD as Bearer). Daemon down is
  a normal state: 200 {available:false, message} so the SPA degrades gracefully
  without CORS or error swallowing. Non-whitelisted paths → 404.
- SPA: new 'term-mesh' nav route — live pane teams/agents, task board, usage,
  plus an 'x-kit tasks executed on term-mesh' table joining
  .xm/build/metrics/sessions.jsonl task_complete records (backend:'term-mesh',
  correlation_id) written by tm-agent xk-bridge.
- Fix metrics path in docs/x-eval: the cost engine writes
  .xm/build/metrics/sessions.jsonl (ROOT=.xm/build), not .xm/metrics/.
- Verified live: proxy offline fallback, whitelist 404, and proxied responses
  against a scripted daemon HTTP server.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQvKGq5h3ECwwSvP7Kjk7Y
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@JINWOO-J @claude