@orchestrator-claude/definitions 3.31.1 → 3.32.0

package/hooks/lib/api-client.ts

@@ -3,32 +3,30 @@
  * Replaces orch-helpers.sh: typed, async/await, zero `node -e` hacks.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 // Resolve paths relative to this file
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = join(__dirname, "..", "..", "..");
-const STATE_DIR = join(PROJECT_ROOT, ".orchestrator", ".state");
-const JWT_CACHE = join(STATE_DIR, "jwt-token");
-const DEBUG_LOG = join(STATE_DIR, "hook-debug.log");
+const PROJECT_ROOT = join(__dirname, '..', '..', '..');
+const STATE_DIR = join(PROJECT_ROOT, '.orchestrator', '.state');
+const JWT_CACHE = join(STATE_DIR, 'jwt-token');
+const DEBUG_LOG = join(STATE_DIR, 'hook-debug.log');
 
 // Ensure state dir exists
 mkdirSync(STATE_DIR, { recursive: true });
 
 // Config from env
-const API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+const API_URL = process.env.ORCHESTRATOR_API_URL || 'http://localhost:3001';
 const AUTH_EMAIL =
   process.env.ORCHESTRATOR_ADMIN_EMAIL ||
   process.env.ORCHESTRATOR_AUTH_EMAIL ||
-  "admin@orchestrator.local";
+  'admin@orchestrator.local';
 const AUTH_PASSWORD =
-  process.env.ORCHESTRATOR_ADMIN_PASSWORD ||
-  process.env.ORCHESTRATOR_AUTH_PASSWORD ||
-  "admin123";
-const PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+  process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || 'admin123';
+const PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || '';
 
 // --- Types ---
 
@@ -38,6 +36,10 @@ export interface WorkflowStatus {
   status: string;
   currentPhase: string;
   mode?: string;
+  /** ADR-017 Phase 3: execution mode for direct execution governance */
+  executionMode?: string;
+  /** PME variant tag (e.g. "consultoria-externa", "enterprise") — optional, fail-open */
+  variant?: string;
 }
 
 export interface PendingAction {
@@ -58,10 +60,10 @@ export interface DetectResult {
 // --- Logging ---
 
 export function log(prefix: string, msg: string): void {
-  const ts = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+  const ts = new Date().toISOString().replace(/\.\d+Z$/, 'Z');
   try {
     const line = `[${ts}] ${prefix}: ${msg}\n`;
-    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+    writeFileSync(DEBUG_LOG, line, { flag: 'a' });
   } catch {
     // fail silently
   }
@@ -75,7 +77,7 @@ function getCachedToken(): string | null {
     const ageMs = Date.now() - stat.mtimeMs;
     if (ageMs < 3_500_000) {
       // ~58 min
-      return readFileSync(JWT_CACHE, "utf-8").trim();
+      return readFileSync(JWT_CACHE, 'utf-8').trim();
     }
   } catch {
     // no cache
@@ -88,10 +90,10 @@ async function login(): Promise<string | null> {
 
   try {
     const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
-      method: "POST",
+      method: 'POST',
       headers: {
-        "Content-Type": "application/json",
-        "X-Project-ID": PROJECT_ID,
+        'Content-Type': 'application/json',
+        'X-Project-ID': PROJECT_ID,
       },
       body: JSON.stringify({ email: AUTH_EMAIL, password: AUTH_PASSWORD }),
       signal: AbortSignal.timeout(5000),
@@ -102,7 +104,7 @@ async function login(): Promise<string | null> {
     const token =
       (data.accessToken as string) ||
       ((data.data as Record<string, unknown>)?.accessToken as string) ||
-      "";
+      '';
     if (token) {
       writeFileSync(JWT_CACHE, token);
     }
@@ -123,7 +125,7 @@ async function apiGet<T>(path: string, token: string, timeoutMs = 5000): Promise
     const resp = await fetch(`${API_URL}${path}`, {
       headers: {
         Authorization: `Bearer ${token}`,
-        "X-Project-ID": PROJECT_ID,
+        'X-Project-ID': PROJECT_ID,
       },
       signal: AbortSignal.timeout(timeoutMs),
     });
@@ -142,11 +144,11 @@ async function apiPost<T>(
 ): Promise<T | null> {
   try {
     const resp = await fetch(`${API_URL}${path}`, {
-      method: "POST",
+      method: 'POST',
       headers: {
-        "Content-Type": "application/json",
+        'Content-Type': 'application/json',
         Authorization: `Bearer ${token}`,
-        "X-Project-ID": PROJECT_ID,
+        'X-Project-ID': PROJECT_ID,
       },
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(timeoutMs),
@@ -164,7 +166,7 @@ export async function getActiveWorkflow(): Promise<WorkflowStatus | null> {
   const token = await getToken();
   if (!token) return null;
 
-  for (const status of ["in_progress", "awaiting_agent", "awaiting_approval"]) {
+  for (const status of ['in_progress', 'awaiting_agent', 'awaiting_approval']) {
     const resp = await apiGet<{ data?: WorkflowStatus[] }>(
       `/api/v1/workflows?status=${status}&limit=1`,
       token,
@@ -185,7 +187,9 @@ export async function getWorkflowStatus(workflowId: string): Promise<WorkflowSta
 
 export async function getWorkflowMode(workflowId: string): Promise<string | null> {
   const status = await getWorkflowStatus(workflowId);
-  return status?.mode || null;
+  if (!status) return null;
+  // ADR-017 Phase 3: prefer executionMode (direct governance) over mode when present
+  return status.executionMode ?? status.mode ?? null;
 }
 
 export async function getNextAction(workflowId: string): Promise<PendingAction | null> {
@@ -200,21 +204,288 @@ export async function detectWorkflow(prompt: string): Promise<DetectResult | nul
   return apiPost(`/api/v1/workflows/detect`, token, { prompt }, 3000);
 }
 
+// --- Last-Completed Workflow State (B4 FinOps timing race fix) ---
+
+/**
+ * Payload written to .orchestrator/.state/last-completed-workflow.json
+ * after a successful completeWorkflow MCP call. Used by dangling-guard.ts
+ * as a fallback when getActiveWorkflow() returns null (timing race).
+ */
+export interface LastCompletedWorkflow {
+  workflowId: string;
+  completedAt: string; // ISO 8601
+}
+
+const LAST_COMPLETED_FILE = join(STATE_DIR, 'last-completed-workflow.json');
+const LAST_COMPLETED_TTL_MS = 60 * 60 * 1000; // 60 minutes
+
+/**
+ * Returns the last completed workflow from the state file if it exists
+ * and its completedAt timestamp is within the 60-minute TTL.
+ * Returns null on any failure (missing file, malformed JSON, expired).
+ */
+export function getLastCompletedWorkflow(): LastCompletedWorkflow | null {
+  try {
+    const raw = readFileSync(LAST_COMPLETED_FILE, 'utf-8');
+    const data = JSON.parse(raw) as Record<string, unknown>;
+    if (typeof data.workflowId !== 'string' || typeof data.completedAt !== 'string') {
+      return null;
+    }
+    const completedAtMs = new Date(data.completedAt).getTime();
+    if (isNaN(completedAtMs)) return null;
+    if (Date.now() - completedAtMs > LAST_COMPLETED_TTL_MS) return null;
+    return { workflowId: data.workflowId, completedAt: data.completedAt };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes the last-completed workflow state file.
+ * Called by the completeWorkflow MCP handler after successful completion.
+ */
+export function writeLastCompletedWorkflow(workflowId: string): void {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(
+      LAST_COMPLETED_FILE,
+      JSON.stringify({ workflowId, completedAt: new Date().toISOString() }),
+      'utf-8'
+    );
+  } catch {
+    // fail silently — FinOps fallback is best-effort
+  }
+}
+
+/**
+ * Deletes the last-completed workflow state file after it has been consumed
+ * by the dangling-guard Stop hook. Prevents double-posting telemetry on
+ * subsequent Stop invocations (idempotency guard).
+ * Returns true if file was deleted, false if already gone.
+ */
+export function consumeLastCompletedWorkflow(): boolean {
+  try {
+    readFileSync(LAST_COMPLETED_FILE); // throws if missing
+    unlinkSync(LAST_COMPLETED_FILE);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // --- Invocation Tracking ---
 
+/** Response shape from POST /api/v1/invocations/start */
+interface StartInvocationApiResponse {
+  invocationId: string;
+  status: string;
+  startedAt: string;
+  agentName: string;
+  phase: string;
+  workflowId?: string;
+}
+
+/** Payload written to the per-key invocation state file. */
+export interface InvocationStatePayload {
+  invocationId: string;
+  startedAt: string;
+  agentType: string;
+  workflowId: string;
+}
+
+const INVOCATIONS_DIR = join(STATE_DIR, 'invocations');
+
+/**
+ * Returns the per-key state file path for an invocation.
+ * Pattern: <stateDir>/invocations/<workflowId>-<agentType>.json
+ * Ensures concurrent sprint-pane agents with same workflowId but different
+ * agentType get separate files (no collision). Same agentType → same file
+ * (last-writer-wins; acceptable trade-off per ADR-W3-B5).
+ */
+export function buildInvocationStatePath(
+  stateDir: string,
+  workflowId: string,
+  agentType: string
+): string {
+  return join(stateDir, 'invocations', `${workflowId}-${agentType}.json`);
+}
+
+/**
+ * Writes invocation state to the per-key state file.
+ * Called by subagent-start.ts after a successful startInvocation POST.
+ * Fail-open: silently returns false on any filesystem error.
+ */
+export function writeInvocationState(
+  workflowId: string,
+  agentType: string,
+  invocationId: string
+): boolean {
+  try {
+    mkdirSync(INVOCATIONS_DIR, { recursive: true });
+    const path = buildInvocationStatePath(STATE_DIR, workflowId, agentType);
+    const payload: InvocationStatePayload = {
+      invocationId,
+      startedAt: new Date().toISOString(),
+      agentType,
+      workflowId,
+    };
+    writeFileSync(path, JSON.stringify(payload), 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads invocation state from the per-key state file.
+ * Called by subagent-stop.ts to obtain the invocationId for completeAgentInvocation.
+ * Returns null if file is missing, malformed, or any read error occurs (fail-open).
+ */
+export function readInvocationState(
+  workflowId: string,
+  agentType: string
+): InvocationStatePayload | null {
+  try {
+    const path = buildInvocationStatePath(STATE_DIR, workflowId, agentType);
+    const raw = readFileSync(path, 'utf-8');
+    const data = JSON.parse(raw) as Record<string, unknown>;
+    if (
+      typeof data.invocationId !== 'string' ||
+      typeof data.startedAt !== 'string' ||
+      typeof data.agentType !== 'string' ||
+      typeof data.workflowId !== 'string'
+    ) {
+      return null;
+    }
+    return {
+      invocationId: data.invocationId,
+      startedAt: data.startedAt,
+      agentType: data.agentType,
+      workflowId: data.workflowId,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** TTL for invocation state files: 4 hours. Files older than this are stale. */
+const INVOCATION_STATE_TTL_MS = 4 * 60 * 60 * 1000;
+
+/**
+ * Returns true if an invocation state payload is stale (older than TTL_MS).
+ * Stale files are skipped by subagent-stop.ts to avoid zombie completions
+ * for agents that crashed before the stop hook ran.
+ * Malformed startedAt timestamps are treated as stale (fail-safe).
+ */
+export function isInvocationStateStale(
+  payload: InvocationStatePayload,
+  nowMs: number = Date.now(),
+  ttlMs: number = INVOCATION_STATE_TTL_MS
+): boolean {
+  const startedAtMs = new Date(payload.startedAt).getTime();
+  if (isNaN(startedAtMs)) return true;
+  return nowMs - startedAtMs > ttlMs;
+}
+
+/**
+ * Deletes the per-key invocation state file after it has been consumed by
+ * subagent-stop.ts. Returns true if deleted, false if already gone.
+ */
+export function consumeInvocationState(workflowId: string, agentType: string): boolean {
+  try {
+    const path = buildInvocationStatePath(STATE_DIR, workflowId, agentType);
+    readFileSync(path); // throws if missing — fast existence check
+    unlinkSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Start tracking an agent invocation.
+ * Returns the invocationId string on success, or null on any failure (fail-open).
+ * Structured log on POST failure so failures are surfaced (not silent).
+ */
 export async function startInvocation(
   agentType: string,
   workflowId: string,
   phase: string
-): Promise<void> {
+): Promise<string | null> {
   const token = await getToken();
-  if (!token) return;
-  await apiPost(`/api/v1/invocations/start`, token, {
-    agentType,
+  if (!token) {
+    log(
+      'API-CLIENT',
+      `startInvocation: no token — skipping (agent=${agentType} workflow=${workflowId})`
+    );
+    return null;
+  }
+  const resp = await apiPost<StartInvocationApiResponse>(`/api/v1/invocations/start`, token, {
+    agentName: agentType,
     workflowId,
     phase,
-    startedAt: new Date().toISOString(),
   });
+  if (!resp) {
+    log(
+      'API-CLIENT',
+      `startInvocation: POST failed — agent=${agentType} workflow=${workflowId} phase=${phase}`
+    );
+    return null;
+  }
+  const invocationId =
+    typeof resp.invocationId === 'string' && resp.invocationId.length > 0
+      ? resp.invocationId
+      : null;
+  if (!invocationId) {
+    log(
+      'API-CLIENT',
+      `startInvocation: response missing invocationId — agent=${agentType} workflow=${workflowId}`
+    );
+  }
+  return invocationId;
+}
+
+/**
+ * Complete an agent invocation via the safety-net fallback path.
+ * Called by subagent-stop.ts after reading the per-key state file, in case
+ * the agent did not self-report via MCP tool.
+ *
+ * Follows the same fail-open pattern as startInvocation:
+ * - Returns true on success (HTTP 2xx from POST /invocations/:id/complete)
+ * - Returns false on any failure (no token, network error, non-2xx)
+ * - Structured log on failure so it is surfaced, not silent
+ */
+export async function completeAgentInvocation(
+  invocationId: string,
+  status: string,
+  summary?: string,
+  error?: string
+): Promise<boolean> {
+  const token = await getToken();
+  if (!token) {
+    log(
+      'API-CLIENT',
+      `completeAgentInvocation: no token — skipping (invocationId=${invocationId})`
+    );
+    return false;
+  }
+  const body: Record<string, unknown> = { status };
+  if (summary !== undefined) body.summary = summary;
+  if (error !== undefined) body.error = error;
+
+  const resp = await apiPost<Record<string, unknown>>(
+    `/api/v1/invocations/${invocationId}/complete`,
+    token,
+    body
+  );
+  if (!resp) {
+    log(
+      'API-CLIENT',
+      `completeAgentInvocation: POST failed — invocationId=${invocationId} status=${status}`
+    );
+    return false;
+  }
+  return true;
 }
 
 export async function registerCheckpoint(
@@ -231,6 +502,116 @@ export async function registerCheckpoint(
   });
 }
 
+// --- Telemetry ---
+
+/**
+ * Flat snake_case FinOps payload sent directly to POST /workflows/:id/telemetry.
+ * All fields are optional — callers may report a subset of metrics.
+ */
+export interface TelemetryPayload {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_read_tokens?: number;
+  total_tokens?: number;
+  total_turns?: number;
+  cache_hit_rate?: number;
+  estimated_cost_usd?: number;
+  model_used?: string;
+  session_id?: string;
+  orchestrator_session_id?: string;
+  variant?: string;
+}
+
+/**
+ * Post session telemetry data for a workflow.
+ * Sends the flat snake_case payload directly to the API endpoint.
+ * Returns true on success, false on any failure (fail-open).
+ */
+export async function postTelemetry(
+  workflowId: string,
+  payload: TelemetryPayload
+): Promise<boolean> {
+  const token = await getToken();
+  if (!token) return false;
+
+  const result = await apiPost<Record<string, unknown>>(
+    `/api/v1/workflows/${workflowId}/telemetry`,
+    token,
+    payload as unknown as Record<string, unknown>
+  );
+  return result !== null;
+}
+
+// --- PME Adversarial Gate Helpers (S188 / RFC-031 §4.4) ---
+
+/**
+ * Extracts the workflow type and variant from the workflow status endpoint.
+ * Returns null on any error (fail-open). Reuses getWorkflowStatus internally.
+ */
+export async function getWorkflowTypeAndVariant(
+  workflowId: string,
+  token: string
+): Promise<{ type: string; variant: string } | null> {
+  try {
+    const resp = await apiGet<WorkflowStatus>(`/api/v1/workflows/${workflowId}/status`, token);
+    if (!resp) return null;
+    const { type, variant } = resp;
+    if (!type || !variant) return null;
+    return { type, variant };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns the GateCell mode ('REQ' | 'OPT' | 'SKIP') for a given
+ * workflow type + variant + gate key, by calling the F1 endpoint.
+ * Returns null on 404, missing field, or any infra error (fail-open).
+ */
+export async function getGateCellMode(
+  typeId: string,
+  variant: string,
+  gateKey: string,
+  token: string
+): Promise<'REQ' | 'OPT' | 'SKIP' | null> {
+  try {
+    const resp = await apiGet<{
+      typeId: string;
+      modes: Record<string, { gates?: Record<string, string> }>;
+    }>(`/api/v1/workflow-definitions/${typeId}`, token);
+    if (!resp) return null;
+    const cell = resp.modes?.[variant]?.gates?.[gateKey];
+    if (cell === 'REQ' || cell === 'OPT' || cell === 'SKIP') return cell;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Retrieves the adversarial review verdict and iteration for a workflow.
+ * Calls GET /api/v1/artifact-content/:workflowId/adversarial_review.
+ * Returns null when artifact is absent (404), on 5xx, timeout, or missing
+ * metadata fields (fail-open — gate is not enforced when artifact is absent).
+ */
+export async function getAdversarialVerdict(
+  workflowId: string,
+  token: string
+): Promise<{ verdict: string; iteration: number } | null> {
+  try {
+    const resp = await apiGet<{
+      content?: string;
+      metadata?: { verdict?: string; iteration?: number };
+    }>(`/api/v1/artifact-content/${workflowId}/adversarial_review`, token);
+    if (!resp) return null;
+    const { verdict, iteration } = resp.metadata ?? {};
+    if (typeof verdict !== 'string' || typeof iteration !== 'number') return null;
+    return { verdict, iteration };
+  } catch {
+    return null;
+  }
+}
+
 // --- Stdin Helper ---
 
 export async function readStdin(): Promise<Record<string, unknown>> {
@@ -238,7 +619,7 @@ export async function readStdin(): Promise<Record<string, unknown>> {
   for await (const chunk of process.stdin) {
     chunks.push(chunk as Buffer);
   }
-  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  const raw = Buffer.concat(chunks).toString('utf-8').trim();
   if (!raw) return {};
   try {
     return JSON.parse(raw) as Record<string, unknown>;
@@ -250,25 +631,25 @@ export async function readStdin(): Promise<Record<string, unknown>> {
 // --- JSON Field Access ---
 
 export function getField(obj: Record<string, unknown>, path: string): string {
-  const parts = path.split(".");
+  const parts = path.split('.');
   let current: unknown = obj;
   for (const part of parts) {
-    if (current == null || typeof current !== "object") return "";
+    if (current == null || typeof current !== 'object') return '';
     current = (current as Record<string, unknown>)[part];
   }
-  return current != null ? String(current) : "";
+  return current != null ? String(current) : '';
 }
 
 // --- Output Helpers ---
 
 export function outputPreToolUse(opts: {
-  decision: "allow" | "deny";
+  decision: 'allow' | 'deny';
   reason?: string;
   context?: string;
 }): void {
   const output: Record<string, unknown> = {
     hookSpecificOutput: {
-      hookEventName: "PreToolUse",
+      hookEventName: 'PreToolUse',
       permissionDecision: opts.decision,
       ...(opts.reason && { permissionDecisionReason: opts.reason }),
       ...(opts.context && { additionalContext: opts.context }),
@@ -289,5 +670,5 @@ export function outputContext(hookEvent: string, context: string): void {
 }
 
 export function outputBlock(reason: string): void {
-  console.log(JSON.stringify({ decision: "block", reason }));
+  console.log(JSON.stringify({ decision: 'block', reason }));
 }