@orchestrator-claude/definitions 3.31.1 → 3.31.2

package/hooks/lib/finops-parser.ts

@@ -0,0 +1,247 @@
+/**
+ * finops-parser.ts — JSONL session parser + FinOps cost estimator (RFC-027 Sprint 3)
+ *
+ * Parses Claude Code session JSONL files to extract token usage, tool calls,
+ * and duration. Computes API cost estimates and formats telemetry output.
+ *
+ * All public functions are fail-open: they return null/0/empty on any error, never throw.
+ */
+
+import { createReadStream, existsSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+// ─── Types ────────────────────────────────────────────────
+
+export interface SessionMetrics {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  toolCalls: number;
+  durationSeconds: number;
+}
+
+export interface ModelPricing {
+  /** Price per 1M input tokens (USD) */
+  input: number;
+  /** Price per 1M output tokens (USD) */
+  output: number;
+  /** Price per 1M cache-read tokens (USD) */
+  cacheRead: number;
+}
+
+// ─── Constants ────────────────────────────────────────────
+
+export const MODEL_PRICING: Record<string, ModelPricing> = {
+  'claude-sonnet-4-6': { input: 3.0, output: 15.0, cacheRead: 0.3 },
+  'claude-opus-4-6': { input: 15.0, output: 75.0, cacheRead: 1.5 },
+  'claude-haiku-4-6': { input: 0.25, output: 1.25, cacheRead: 0.03 },
+};
+
+export const DEFAULT_MODEL = 'claude-sonnet-4-6';
+
+// ─── JSONL Parsing ────────────────────────────────────────
+
+interface UsageBlock {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_read_input_tokens?: number;
+}
+
+interface ContentBlock {
+  type?: string;
+}
+
+interface JsonlLine {
+  type?: string;
+  usage?: UsageBlock;
+  message?: {
+    usage?: UsageBlock;
+    content?: ContentBlock[];
+  };
+  timestamp?: string;
+}
+
+/**
+ * Parse a Claude Code session JSONL file using streaming readline.
+ * Aggregates token usage, tool call count, and duration from timestamps.
+ *
+ * Returns null on any error (fail-open).
+ */
+export async function parseJsonlSession(filePath: string): Promise<SessionMetrics | null> {
+  try {
+    if (!existsSync(filePath)) return null;
+
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let toolCalls = 0;
+    let firstTimestamp: number | null = null;
+    let lastTimestamp: number | null = null;
+    let hasData = false;
+
+    const rl = createInterface({
+      input: createReadStream(filePath, { encoding: 'utf-8' }),
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      let parsed: JsonlLine;
+      try {
+        parsed = JSON.parse(trimmed) as JsonlLine;
+      } catch {
+        // Skip malformed lines (fail-open)
+        continue;
+      }
+
+      hasData = true;
+
+      // Track timestamps for duration calculation
+      if (parsed.timestamp) {
+        try {
+          const ts = new Date(parsed.timestamp).getTime();
+          if (!Number.isNaN(ts)) {
+            if (firstTimestamp === null) firstTimestamp = ts;
+            lastTimestamp = ts;
+          }
+        } catch {
+          // ignore invalid timestamps
+        }
+      }
+
+      // Count tool_use events — in Claude Code JSONL, tool_use is nested
+      // inside message.content[] blocks, not at the top-level type field.
+      if (parsed.type === 'tool_use') {
+        toolCalls += 1;
+      } else if (parsed.message?.content) {
+        for (const block of parsed.message.content) {
+          if (block.type === 'tool_use') toolCalls += 1;
+        }
+      }
+
+      // Aggregate usage from any line that has a usage block
+      // Claude Code JSONL nests usage under message.usage (assistant type)
+      // or at top-level (older/test format). Check both paths.
+      const usage = parsed.message?.usage ?? parsed.usage;
+      if (usage) {
+        inputTokens += usage.input_tokens ?? 0;
+        outputTokens += usage.output_tokens ?? 0;
+        cacheReadTokens += usage.cache_read_input_tokens ?? 0;
+      }
+    }
+
+    if (!hasData) return null;
+
+    const durationSeconds =
+      firstTimestamp !== null && lastTimestamp !== null
+        ? Math.round((lastTimestamp - firstTimestamp) / 1000)
+        : 0;
+
+    return {
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      toolCalls,
+      durationSeconds,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ─── Path Resolution ──────────────────────────────────────
+
+/**
+ * Find the JSONL file for a given session ID by globbing ~/.claude/projects/.
+ * Uses a 5-second timeout. Returns null if not found or on any error.
+ */
+export async function findJsonlPath(sessionId: string): Promise<string | null> {
+  try {
+    if (!sessionId) return null;
+
+    const { glob } = await import('glob');
+    const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (!homeDir) return null;
+
+    const pattern = `${homeDir}/.claude/projects/**/${sessionId}.jsonl`;
+
+    const matches = await Promise.race([
+      glob(pattern, { nodir: true }),
+      new Promise<null>((resolve) =>
+        setTimeout(() => {
+          resolve(null);
+        }, 5000)
+      ),
+    ]);
+
+    if (!matches || !Array.isArray(matches) || matches.length === 0) return null;
+    return matches[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Cost Estimation ─────────────────────────────────────
+
+/**
+ * Estimate API cost from session metrics using model pricing table.
+ * Falls back to DEFAULT_MODEL pricing for unknown models.
+ * Never throws (fail-open).
+ */
+export function estimateCost(metrics: SessionMetrics, model?: string): number {
+  try {
+    const pricing = MODEL_PRICING[model ?? DEFAULT_MODEL] ?? MODEL_PRICING[DEFAULT_MODEL];
+    if (!pricing) return 0;
+
+    const inputCost = (metrics.inputTokens / 1_000_000) * pricing.input;
+    const outputCost = (metrics.outputTokens / 1_000_000) * pricing.output;
+    const cacheCost = (metrics.cacheReadTokens / 1_000_000) * pricing.cacheRead;
+
+    return inputCost + outputCost + cacheCost;
+  } catch {
+    return 0;
+  }
+}
+
+// ─── Output Formatting ────────────────────────────────────
+
+/**
+ * Format session metrics and cost as a multi-line [FINOPS] telemetry string.
+ * Follows the RFC-027 §5.5 format.
+ * Never throws (fail-open).
+ */
+export function formatFinopsOutput(
+  metrics: SessionMetrics,
+  cost: number,
+  extras?: {
+    commits?: number;
+    filesChanged?: number;
+    sessionLabel?: string;
+  }
+): string {
+  try {
+    const durationMinutes = Math.round(metrics.durationSeconds / 60);
+
+    const lines: string[] = [
+      `[FINOPS] Session telemetry:${extras?.sessionLabel ? ` ${extras.sessionLabel}` : ''}`,
+      `  Input tokens:  ${metrics.inputTokens.toLocaleString('en-US')}`,
+      `  Output tokens: ${metrics.outputTokens.toLocaleString('en-US')}`,
+      `  Cache hits:    ${metrics.cacheReadTokens.toLocaleString('en-US')}`,
+      `  Tool calls:    ${metrics.toolCalls}`,
+      `  Duration:      ${durationMinutes}min`,
+      `  API cost est:  $${cost.toFixed(2)}`,
+    ];
+
+    if (extras?.commits !== undefined || extras?.filesChanged !== undefined) {
+      const commits = extras.commits ?? 0;
+      const files = extras.filesChanged ?? 0;
+      lines.push(`  Deliverables:  ${commits} commits, ${files} files`);
+    }
+
+    return lines.join('\n');
+  } catch {
+    return '[FINOPS] Error formatting telemetry';
+  }
+}

package/hooks/lib/gate-logic.ts

@@ -4,8 +4,8 @@
  * Fully testable without any mocks.
  */
 
-export type RiskLevel = "HIGH" | "LOW";
-export type GateStrategy = "AUTO_APPROVE" | "ASK_HUMAN" | "BLOCK_AND_REQUIRE";
+export type RiskLevel = 'HIGH' | 'LOW';
+export type GateStrategy = 'AUTO_APPROVE' | 'ASK_HUMAN' | 'BLOCK_AND_REQUIRE';
 
 export interface GateContext {
   workflowId: string;
@@ -29,9 +29,9 @@ export interface GateDecision {
  */
 export function classifyRisk(targetPhase: string): RiskLevel {
   if (/implement|deploy|migrate|delete/i.test(targetPhase)) {
-    return "HIGH";
+    return 'HIGH';
   }
-  return "LOW";
+  return 'LOW';
 }
 
 /**
@@ -43,16 +43,16 @@ export function classifyRisk(targetPhase: string): RiskLevel {
  * BLOCK_AND_REQUIRE exists as a type but has no trigger rule yet.
  */
 export function deriveGateStrategy(ctx: GateContext): GateDecision {
-  if (ctx.riskLevel === "HIGH") {
+  if (ctx.riskLevel === 'HIGH') {
     return {
-      strategy: "ASK_HUMAN",
+      strategy: 'ASK_HUMAN',
       reason: `Phase '${ctx.targetPhase}' is high-risk and requires human approval before proceeding.`,
     };
   }
 
   // Default: AUTO_APPROVE
   return {
-    strategy: "AUTO_APPROVE",
+    strategy: 'AUTO_APPROVE',
     reason: `Phase '${ctx.targetPhase}' is low-risk — auto-approved.`,
   };
 }

package/hooks/lib/git-checkpoint.ts

@@ -3,19 +3,19 @@
  * Replaces post-phase-checkpoint.sh git logic.
  */
 
-import { execSync } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { log, registerCheckpoint } from "./api-client.js";
+import { execSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log, registerCheckpoint } from './api-client.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = join(__dirname, "..", "..", "..");
-const STATE_DIR = join(PROJECT_ROOT, ".orchestrator", ".state");
-const LAST_PHASE_FILE = join(STATE_DIR, "last-checkpointed-phase");
+const PROJECT_ROOT = join(__dirname, '..', '..', '..');
+const STATE_DIR = join(PROJECT_ROOT, '.orchestrator', '.state');
+const LAST_PHASE_FILE = join(STATE_DIR, 'last-checkpointed-phase');
 
-const PHASE_ORDER = ["research", "specify", "plan", "tasks", "implement", "validate"];
+const PHASE_ORDER = ['research', 'specify', 'plan', 'tasks', 'implement', 'validate'];
 
 /** Map from current phase to the phase that just completed */
 function getCompletedPhase(currentPhase: string): string | null {
@@ -25,7 +25,7 @@ function getCompletedPhase(currentPhase: string): string | null {
 }
 
 function exec(cmd: string): string {
-  return execSync(cmd, { cwd: PROJECT_ROOT, encoding: "utf-8" }).trim();
+  return execSync(cmd, { cwd: PROJECT_ROOT, encoding: 'utf-8' }).trim();
 }
 
 /**
@@ -38,31 +38,31 @@ export async function createCheckpointIfNeeded(
 ): Promise<string | null> {
   const completedPhase = getCompletedPhase(currentPhase);
   if (!completedPhase) {
-    log("CHECKPOINT", `No completed phase from: ${currentPhase}`);
+    log('CHECKPOINT', `No completed phase from: ${currentPhase}`);
     return null;
   }
 
   // Check if already checkpointed
-  let lastPhase = "";
+  let lastPhase = '';
   try {
-    lastPhase = readFileSync(LAST_PHASE_FILE, "utf-8").trim();
+    lastPhase = readFileSync(LAST_PHASE_FILE, 'utf-8').trim();
   } catch {
     // no file
   }
   if (lastPhase === completedPhase) {
-    log("CHECKPOINT", `Already checkpointed: ${completedPhase}`);
+    log('CHECKPOINT', `Already checkpointed: ${completedPhase}`);
     return null;
   }
 
   try {
     // Stage all changes
-    exec("git add -A");
+    exec('git add -A');
 
     // Check if there are staged changes
     try {
-      exec("git diff --cached --quiet");
+      exec('git diff --cached --quiet');
       // No changes
-      log("CHECKPOINT", `No changes for phase: ${completedPhase}`);
+      log('CHECKPOINT', `No changes for phase: ${completedPhase}`);
       writeFileSync(LAST_PHASE_FILE, completedPhase);
       return null;
     } catch {
@@ -71,9 +71,9 @@ export async function createCheckpointIfNeeded(
 
     const commitMsg = `[orchestrator] ${completedPhase}: Auto-checkpoint after ${completedPhase} phase`;
     exec(`git commit -m "${commitMsg}" --no-verify`);
-    const commitHash = exec("git rev-parse HEAD");
+    const commitHash = exec('git rev-parse HEAD');
 
-    log("CHECKPOINT", `Created: phase=${completedPhase} commit=${commitHash}`);
+    log('CHECKPOINT', `Created: phase=${completedPhase} commit=${commitHash}`);
 
     // Register via API
     await registerCheckpoint(
@@ -85,7 +85,7 @@ export async function createCheckpointIfNeeded(
     writeFileSync(LAST_PHASE_FILE, completedPhase);
     return commitHash;
   } catch (err) {
-    log("CHECKPOINT", `Error: ${err}`);
+    log('CHECKPOINT', `Error: ${err}`);
     return null;
   }
 }

package/hooks/lib/observations-helper.ts

@@ -0,0 +1,104 @@
+/**
+ * observations-helper.ts — Tier B observations for sub-agents (RFC-027 Sprint 3)
+ *
+ * Provides types and helper to write observations.yaml files.
+ * Used by subagent-stop.ts to record what each sub-agent observed.
+ * All functions are fail-open: errors logged to stderr, never thrown.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+// ─── Types ───────────────────────────────────────────────
+
+export interface ObservationEntry {
+  timestamp: string;
+  session_id: string;
+  phase: string;
+  workflow_id?: string;
+  summary: string;
+  tags: string[];
+  promoted: boolean;
+}
+
+export interface ObservationsFile {
+  schema: 'observations/v1';
+  agent: string;
+  entries: ObservationEntry[];
+}
+
+// ─── Constants ───────────────────────────────────────────
+
+const MAX_ENTRIES = 50;
+const MAX_SUMMARY_LENGTH = 200;
+
+// ─── Functions ───────────────────────────────────────────
+
+/**
+ * Append an observation entry to the agent's observations.yaml.
+ * Creates the file and directory if they don't exist.
+ * FIFO rotation: oldest entries removed when >50.
+ * Fail-open: any error → console.warn, return without throwing.
+ */
+export function appendObservation(
+  memoryDir: string,
+  agent: string,
+  entry: Omit<ObservationEntry, 'promoted'>
+): void {
+  try {
+    const agentDir = join(memoryDir, agent);
+    const filePath = join(agentDir, 'observations.yaml');
+
+    // Ensure directory exists
+    if (!existsSync(agentDir)) {
+      mkdirSync(agentDir, { recursive: true });
+    }
+
+    // Truncate summary
+    const summary =
+      entry.summary.length > MAX_SUMMARY_LENGTH
+        ? entry.summary.slice(0, MAX_SUMMARY_LENGTH)
+        : entry.summary;
+
+    const newEntry: ObservationEntry = {
+      ...entry,
+      summary,
+      promoted: false,
+    };
+
+    let data: ObservationsFile;
+
+    if (existsSync(filePath)) {
+      try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const parsed = parseYaml(raw) as ObservationsFile;
+        if (parsed?.entries && Array.isArray(parsed.entries)) {
+          data = {
+            schema: 'observations/v1',
+            agent,
+            entries: [...parsed.entries, newEntry],
+          };
+        } else {
+          data = { schema: 'observations/v1', agent, entries: [newEntry] };
+        }
+      } catch {
+        // Corrupt YAML → start fresh
+        data = { schema: 'observations/v1', agent, entries: [newEntry] };
+      }
+    } else {
+      data = { schema: 'observations/v1', agent, entries: [newEntry] };
+    }
+
+    // FIFO rotation: keep only last MAX_ENTRIES
+    if (data.entries.length > MAX_ENTRIES) {
+      data.entries = data.entries.slice(data.entries.length - MAX_ENTRIES);
+    }
+
+    writeFileSync(filePath, stringifyYaml(data), 'utf-8');
+  } catch (err) {
+    console.warn(
+      `[OBSERVATIONS] Failed to write observation for agent '${agent}': ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}

package/hooks/lib/sprint-context.ts

@@ -0,0 +1,102 @@
+/**
+ * sprint-context.ts — Sprint context persistence helper (RFC-027 Sprint 1)
+ *
+ * Reads and writes sprint context JSON files stored at:
+ *   .claude/sprint-context/{workflowId}.json
+ *
+ * Note: files use .json format internally for zero-dependency operation
+ * (no yaml package required). The directory name uses 'sprint-context'
+ * as specified in RFC-027.
+ *
+ * All operations are fail-open: no function throws. Errors are swallowed
+ * and null / void is returned.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ─────────────────────────────────────────────────────────────
+// Path resolution
+// ─────────────────────────────────────────────────────────────
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Project root: go up from .claude/hooks/lib → .claude/hooks → .claude → project root
+ */
+const PROJECT_ROOT = join(__dirname, '..', '..', '..');
+const SPRINT_CONTEXT_DIR = join(PROJECT_ROOT, '.claude', 'sprint-context');
+
+// ─────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────
+
+export interface SprintContext {
+  /** Schema version for forward compatibility (e.g. "1.0") */
+  schema: string;
+  /** Relative path from project root to the parent RFC/ADR document */
+  parentDocument: string;
+  /** 1-based sprint index within the parent document */
+  sprintIndex: number;
+  /** Short description of what this sprint covers */
+  sprintScope: string;
+  /** Summary of sprints executed before this one */
+  previousSprints: {
+    index: number;
+    status: 'complete' | 'in_progress' | 'skipped';
+    deliverables: string[];
+  }[];
+  /** Workflow ID this sprint context belongs to */
+  workflowId: string;
+  /** ISO-8601 timestamp when the context was first created */
+  createdAt: string;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────
+
+function contextPath(workflowId: string): string {
+  return join(SPRINT_CONTEXT_DIR, `${workflowId}.json`);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Read the sprint context for a given workflow.
+ * Returns null if the file does not exist or contains invalid JSON.
+ * Never throws.
+ */
+export function readSprintContext(workflowId: string): SprintContext | null {
+  try {
+    const filePath = contextPath(workflowId);
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    const raw = readFileSync(filePath, 'utf-8');
+    // No schema validation — caller must tolerate partial/stale data gracefully
+    return JSON.parse(raw) as SprintContext;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a sprint context for a given workflow.
+ * Creates the directory if it does not exist.
+ * Overwrites any existing file for the same workflowId.
+ * Never throws.
+ */
+export function writeSprintContext(workflowId: string, ctx: SprintContext): void {
+  try {
+    mkdirSync(SPRINT_CONTEXT_DIR, { recursive: true });
+    const filePath = contextPath(workflowId);
+    writeFileSync(filePath, JSON.stringify(ctx, null, 2), 'utf-8');
+  } catch {
+    // fail-open: swallow errors silently
+  }
+}