@addai/node 0.4.0

package/scripts/precompact-capture.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+// +Ai Memory Phase 4, T7 — PreCompact capture hook (claude agent only).
+//
+// Invoked by Claude Code as a PreCompact command hook — see
+// src/precompact-hook.ts for how/when the daemon writes this into a
+// session's <cwd>/.claude/settings.json (memory_v2-flagged entities only).
+// Runs as a plain child process of claude, so it inherits claude's (and
+// therefore the daemon's PTY spawn's) environment: ENTITY_STUDIO_ENTITY_ID
+// and RUNTIME_REQUEST_ID are threaded in by claude-spawn.ts's extraEnv for
+// exactly this purpose; SUPABASE_URL/SUPABASE_ANON_KEY are NOT threaded as
+// env vars — they're read straight from dist/config.js (the same
+// build-time-public constants session-runner.ts itself uses), which lives
+// one directory up from this script in every install shape (package.json
+// "files": ["dist","scripts", ...]).
+//
+// Best-effort, fire-and-forget, NEVER blocks or fails compaction: every
+// error path here logs to stderr and exits 0 regardless, so Claude Code's
+// own compaction proceeds unaffected whether the capture succeeds, fails,
+// or never had anything to send.
+//
+// Idempotency: this does NOT invent its own turn-hash dedup. It posts the
+// same shape entity-memory-capture already accepts from the normal
+// completed-turn path (surface differs: 'precompact' vs 'chat'/issued_via),
+// and relies on entity-memory-capture's existing episode/turn-hash dedup
+// (T3, sha256(entity_id|user_text|assistant_text)) to make a later
+// completed-turn capture of the SAME exchange a safe no-op.
+//
+// For that to actually hold, this hook's assistantText must match — byte
+// for byte — what the completed-turn path will eventually read back from
+// entity_runtime_requests.assistant_text. That column is populated by the
+// live DB trigger _entity_studio_aggregate_assistant_text (see
+// supabase/migrations/20260720130000_entity_guardrails.sql in the studio
+// repo for the current body), which on the request's terminal transition
+// runs:
+//
+//   select string_agg((e.payload ->> 'delta'), '' order by e.id)
+//     from public.entity_runtime_request_events e
+//    where e.request_id = new.id and e.type = 'assistant_text'
+//
+// i.e. every assistant_text delta event emitted for the WHOLE request row,
+// concatenated in emission order with NO separator, tool_use/tool_result/
+// thinking events excluded entirely. lastTurnFromTranscript below mirrors
+// that by walking back to the last genuine user turn (a role:'user' entry
+// that carries real text — NOT a tool_result-only "user" message, which
+// Claude Code also stamps role:'user') and concatenating every subsequent
+// top-level assistant entry's text blocks, in order, with '' — matching
+// string_agg's join exactly.
+//
+// Sidechain (subagent/Task-tool) entries are skipped (the `entry.isSidechain`
+// check below) as a defensive belt-and-braces measure, but on this daemon's
+// current Claude Code transcript layout they never fire in practice: a
+// subagent's own turns are written to a SEPARATE file tree
+// (`<project>/<session>/subagents/agent-<id>.jsonl`), never interleaved into
+// the top-level `<session>.jsonl` this hook's `transcript_path` and this
+// daemon's own live-turn tailer (jsonl-tail.ts's startJsonlTail, fed the
+// identical spawn.jsonlPath — see session-runner.ts) both read. The DB side
+// (entity_runtime_request_events) is built from that SAME top-level-only
+// tail via events.ts's normalizeJsonlLine, which has no isSidechain check of
+// its own — it doesn't need one, because the file it reads structurally
+// never contains sidechain lines. (Corrected 2026-07-21: this comment
+// previously cited claude-print.ts, the separate --print-mode adapter,
+// which this PreCompact-hooked TUI code path never runs through at all.)
+//
+// assistantText.trim() below (T8 ship-gate fix) matches the completed-turn
+// capture path's own normalization — notifyCaptureIfEnabled in
+// session-runner.ts computes `(row.assistant_text ?? '').trim()` before
+// calling buildCapturePayload — so a genuinely-identical exchange hashes to
+// the SAME turn_hash (sha256(entity_id|user_text|assistant_text), computed
+// server-side in entity-memory-capture/index.ts over exactly the strings
+// this payload sends, no server-side trim) on both paths. Before this fix, a
+// transcript-derived assistantText with incidental leading/trailing
+// whitespace (a trailing newline from the JSONL's own text-block boundary,
+// for instance) would hash differently from the SAME text read back post-
+// trim by the completed-turn path, defeating the dedup this whole mechanism
+// exists to rely on — not just for the documented mid-turn-prefix case
+// below, but for a full, complete, otherwise-identical turn too.
+//
+// Residual (honest, not fixed): PreCompact can still fire MID-turn, before
+// the agent has emitted its final assistant message(s) for this request.
+// When that happens this hook captures a PREFIX of the eventual full
+// assistant_text — same userText, shorter assistantText — which hashes to
+// a DIFFERENT dedup key than the later completed-turn capture. That is a
+// genuine possible duplicate (a "prefix episode" alongside the full one),
+// bounded to at most one extra episode per PreCompact-interrupted turn. We
+// deliberately do NOT special-case this by weakening the dedup key (e.g.
+// hashing on entity_id|user_text alone) — that would blind the general
+// dedup to legitimately different answers to a repeated question.
+//
+// Residual class 2 — user_text normalization: userText here is read
+// straight off the transcript's last real user-turn content block(s)
+// (extractText, '\n'-joined if Claude Code ever splits one turn's content
+// into multiple 'text' blocks) and is NOT trimmed, matching the completed-
+// turn path's own `row.prompt ?? ''` (also untrimmed, read back from the
+// DB's stored prompt column, a plain string with no aggregation step of its
+// own — unlike assistant_text there is no DB trigger to mirror here). Both
+// paths are internally consistent in NOT trimming user_text, so this is not
+// currently a known dedup-breaking mismatch — but it is an unverified
+// assumption: nothing here proves the transcript's literal user-message
+// text is always byte-identical to the stored prompt column (a future
+// prompt-construction change, or a Claude Code content-block split, could
+// silently diverge them). Documented rather than asserted-safe.
+//
+// Residual class 3 — guardrail retry turns (guardrail_meta.final_text):
+// when a guardrail check fails, runGuardrailRetryTurn (session-runner.ts)
+// feeds the violation back as a NEW real user-role message on the SAME
+// claude session/transcript, then accumulates the revised reply. The DB's
+// assistant_text trigger aggregates every assistant_text event emitted for
+// the whole request_id regardless of which sub-turn produced it — original
+// attempt AND revision both — and guardrail_meta.final_text is what
+// actually gets pinned as canonical. If PreCompact fires during or after a
+// guardrail retry, lastTurnFromTranscript walks back to that INTERNAL
+// feedback message as "the last genuine user turn" (it has real text and no
+// way to be distinguished from a genuine human prompt at this layer) — so
+// BOTH userText (the guardrail feedback prompt, not the original caller's
+// text) and assistantText (only the revision, not original+revision) can
+// diverge from what the completed-turn path eventually captures. Unlike the
+// mid-turn-prefix residual above, this is not a strict prefix relationship
+// and not bounded to a whitespace/length difference — it is a different
+// exchange shape entirely. Same posture as the other two residuals: honest,
+// documented, not papered over with a weakened dedup key.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function extractText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+      .map((b) => b.text)
+      .join('\n');
+  }
+  return '';
+}
+
+// Same block-filtering as extractText, but joined with '' — the DB's
+// string_agg(delta, '') separator — for the assistant-side aggregation
+// specifically. In practice a single assistant message content array never
+// carries two adjacent 'text' blocks (the API always merges them), so this
+// only differs from extractText's '\n' join in that hypothetical case; kept
+// separate anyway so the assistant path is exactly, not approximately,
+// faithful to the trigger it's mirroring.
+function extractAssistantText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+      .map((b) => b.text)
+      .join('');
+  }
+  return '';
+}
+
+// A "real" user turn: role:'user' carrying actual typed text. Claude Code
+// also stamps role:'user' on tool_result submissions (content is an array
+// of tool_result blocks only) — extractText() already filters those out to
+// '' since it only pulls type:'text' blocks, so they never look like a
+// turn boundary here.
+function isRealUserTurn(msg) {
+  return !!msg && msg.role === 'user' && extractText(msg.content).trim() !== '';
+}
+
+// Walks the transcript JSONL backwards to find the last genuine user turn
+// (the prompt that started the CURRENT request), then walks forward from
+// there aggregating every top-level assistant entry's text in order — the
+// full "turn" for this request, matching how the DB's
+// _entity_studio_aggregate_assistant_text trigger aggregates
+// entity_runtime_request_events for the same request_id (concatenation in
+// emission order, no separator, tool_use/tool_result/thinking excluded).
+// Multi-assistant-message turns (text → tool_use → tool_result → text →
+// ... → final text) are the norm for agentic sessions — PreCompact can
+// fire mid-turn — so aggregating only the single most recent assistant
+// entry (the old behavior) systematically under-captured relative to what
+// the completed-turn path later reads back, producing a different dedup
+// hash for the same exchange. See the Idempotency comment above for the
+// residual this fix does NOT (and should not) paper over.
+function lastTurnFromTranscript(transcriptPath) {
+  try {
+    const raw = fs.readFileSync(transcriptPath, 'utf-8');
+    const lines = raw.split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try {
+        entries.push(JSON.parse(line));
+      } catch {
+        continue;
+      }
+    }
+
+    let turnStart = -1;
+    let userText = '';
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i];
+      if (entry && entry.isSidechain) continue; // subagent/Task-tool chatter — DB side never sees it either
+      const msg = entry && entry.message;
+      if (isRealUserTurn(msg)) {
+        turnStart = i;
+        userText = extractText(msg.content);
+        break;
+      }
+    }
+    if (turnStart === -1) {
+      return { userText: '', assistantText: '' };
+    }
+
+    let assistantText = '';
+    for (let i = turnStart + 1; i < entries.length; i++) {
+      const entry = entries[i];
+      if (entry && entry.isSidechain) continue;
+      const msg = entry && entry.message;
+      if (!msg || msg.role !== 'assistant') continue;
+      assistantText += extractAssistantText(msg.content); // '' separator — matches string_agg(delta, '')
+    }
+    return { userText, assistantText };
+  } catch (err) {
+    process.stderr.write(`[precompact-capture] transcript read failed: ${err.message}\n`);
+    return { userText: '', assistantText: '' };
+  }
+}
+
+async function main() {
+  const entityId = process.env.ENTITY_STUDIO_ENTITY_ID || '';
+  const requestId = process.env.RUNTIME_REQUEST_ID || '';
+  if (!entityId || !requestId) {
+    // Not a daemon-spawned, entity-attributed session (or the daemon
+    // didn't thread identity through) — nothing to attribute a capture
+    // to. Exit clean, never block compaction.
+    process.exit(0);
+    return;
+  }
+
+  const stdin = readStdinSync();
+  let hookInput = {};
+  try {
+    hookInput = JSON.parse(stdin || '{}');
+  } catch {
+    /* malformed/empty stdin — fall through with {} */
+  }
+  const transcriptPath = hookInput.transcript_path;
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    process.exit(0);
+    return;
+  }
+
+  const { userText, assistantText: rawAssistantText } = lastTurnFromTranscript(transcriptPath);
+  // T8 ship-gate fix: trim to match notifyCaptureIfEnabled's own
+  // `(row.assistant_text ?? '').trim()` — see the module-header comment's
+  // trim-alignment note for why an untrimmed value here would silently
+  // defeat the turn_hash dedup this hook depends on, not just for the
+  // documented mid-turn-prefix residual but for complete matching turns too.
+  const assistantText = rawAssistantText.trim();
+  if (!assistantText) {
+    process.exit(0); // nothing produced yet this turn
+    return;
+  }
+
+  try {
+    const { SUPABASE_URL, SUPABASE_ANON_KEY } = require(path.join(__dirname, '..', 'dist', 'config.js'));
+    const { buildCapturePayload, postCapture } = require(path.join(__dirname, '..', 'dist', 'memory-capture.js'));
+    const payload = buildCapturePayload(
+      { entityId, requestId, surface: 'precompact' },
+      userText,
+      assistantText,
+      { kind: 'jsonl_ref', path: transcriptPath, host: os.hostname() },
+    );
+    await postCapture(SUPABASE_URL, SUPABASE_ANON_KEY, payload);
+  } catch (err) {
+    process.stderr.write(`[precompact-capture] capture failed (non-fatal): ${err.message}\n`);
+  }
+  process.exit(0);
+}
+
+// Guarded so `require()`ing this file for unit tests (of extractText /
+// extractAssistantText / lastTurnFromTranscript) doesn't also run main()
+// — main() reads real stdin/env and makes a real network call.
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`[precompact-capture] fatal (swallowed): ${err && err.message}\n`);
+    process.exit(0);
+  });
+}
+
+module.exports = { extractText, extractAssistantText, lastTurnFromTranscript, isRealUserTurn };

package/scripts/smoke-test.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Daemon smoke test — verifies the running daemon's health + each agent's
+# binary + auth state. Run AFTER upgrading the daemon to 0.2.14+.
+#
+# Usage: bash scripts/smoke-test.sh
+
+set -uo pipefail
+LOCKFILE="${HOME}/.entities-runtime/runtime.json"
+
+if [ ! -f "$LOCKFILE" ]; then
+  echo "✗ No daemon lockfile at $LOCKFILE — daemon not running"
+  exit 1
+fi
+
+PORT=$(python3 -c "import json; print(json.load(open('${LOCKFILE}'))['port'])")
+echo "Daemon lockfile port: $PORT"
+
+probe() {
+  local ep="$1"
+  local expect_field="$2"
+  local body
+  body=$(curl -s --max-time 3 "http://127.0.0.1:${PORT}${ep}")
+  if [ -z "$body" ]; then
+    echo "  ✗ $ep — no response"
+    return 1
+  fi
+  if [ -n "$expect_field" ]; then
+    if echo "$body" | python3 -c "import json,sys; d=json.load(sys.stdin); assert '$expect_field' in d or any('$expect_field' in str(v) for v in d.values())" 2>/dev/null; then
+      echo "  ✓ $ep — $(echo "$body" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin), separators=(',',':'))[:120])")"
+    else
+      echo "  ⚠ $ep — missing field '$expect_field': $body" | head -c 200
+      echo
+    fi
+  else
+    echo "  ✓ $ep — $(echo "$body" | head -c 100)"
+  fi
+}
+
+echo
+echo "=== Daemon control-server endpoints ==="
+probe /status "version"
+probe /self "runtime"
+probe /stats "inflight"   # inflight field added in 0.2.11
+probe /requests "requests"
+probe /projects "projects"
+
+echo
+echo "=== Agent binary + auth checks ==="
+check_agent() {
+  local name="$1" bin="$2" auth_file="$3" env_var="$4"
+  printf "  %s: " "$name"
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    echo "✗ binary missing"
+    return
+  fi
+  local ver
+  ver=$("$bin" --version 2>&1 | head -1 | tr -d '\n')
+  if [ -n "$env_var" ] && [ -n "${!env_var:-}" ]; then
+    echo "✓ $ver — authed via \$$env_var"
+    return
+  fi
+  if [ -f "$HOME/$auth_file" ] && [ "$(stat -f %z "$HOME/$auth_file" 2>/dev/null || stat -c %s "$HOME/$auth_file" 2>/dev/null)" -gt 16 ]; then
+    echo "✓ $ver — authed via ~/$auth_file"
+  else
+    echo "⚠ $ver — NO AUTH (set $env_var or login)"
+  fi
+}
+check_agent "claude" claude .claude/.credentials.json ANTHROPIC_API_KEY
+check_agent "codex"  codex  .codex/auth.json OPENAI_API_KEY
+check_agent "kimi"   kimi   .kimi/auth.toml KIMI_API_KEY
+check_agent "gemini" gemini .gemini/oauth_creds.json GEMINI_API_KEY
+
+echo
+echo "=== Done ==="