fraim-framework 2.0.124 → 2.0.127

package/dist/src/ai-hub/hosts.js

@@ -1,12 +1,209 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createHubEvent = exports.createHubMessage = exports.FakeHostRuntime = exports.CliHostRuntime = void 0;
+exports.createHubEvent = exports.createHubMessage = exports.ScriptedHostRuntime = exports.FakeHostRuntime = exports.CliHostRuntime = void 0;
+exports.parseSeekMentoringSignal = parseSeekMentoringSignal;
+exports.parseUsageSignal = parseUsageSignal;
+exports.parseAgentIdentitySignal = parseAgentIdentitySignal;
 exports.detectEmployees = detectEmployees;
 exports.buildStartPlan = buildStartPlan;
 exports.buildContinuePlan = buildContinuePlan;
 exports.parseHostLine = parseHostLine;
 const crypto_1 = require("crypto");
 const child_process_1 = require("child_process");
+// Parse a single line of host stdout looking for a seekMentoring tool-use
+// signal. Returns null if the line does not contain one. Supports both
+// hosts FRAIM ships against today:
+//   - Claude Code: tool_use blocks inside message.content with name
+//     'mcp__fraim__seekMentoring' (MCP names are prefixed in Claude's
+//     stream-json output).
+//   - Codex: top-level events of type 'item.started' / 'item.completed'
+//     whose item.type === 'mcp_tool_call' and item.tool === 'seekMentoring'
+//     (Codex separates the MCP server name from the tool name).
+function parseSeekMentoringSignal(line) {
+    if (!line.includes('seekMentoring'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const obj = parsed;
+    // Codex shape: { type: 'item.started' | 'item.completed', item: { type: 'mcp_tool_call', tool: 'seekMentoring', arguments: {...} } }.
+    // Match both started + completed; the call carries the same arguments
+    // either way, so applying the signal at the earliest is fine.
+    if ((obj.type === 'item.started' || obj.type === 'item.completed') &&
+        typeof obj.item === 'object' && obj.item !== null) {
+        const item = obj.item;
+        const itemType = item.type;
+        const tool = typeof item.tool === 'string' ? item.tool : null;
+        if (itemType === 'mcp_tool_call' &&
+            (tool === 'seekMentoring' || tool === 'mcp__fraim__seekMentoring')) {
+            const args = item.arguments;
+            const sig = extractSignalFromArgs(args);
+            if (sig)
+                return sig;
+        }
+    }
+    // Claude Code shape: tool_use blocks live inside parsed.message.content.
+    // The name is MCP-prefixed (e.g. 'mcp__fraim__seekMentoring').
+    const candidates = [obj];
+    if (Array.isArray(obj.content))
+        candidates.push(...obj.content);
+    if (typeof obj.message === 'object' && obj.message !== null) {
+        const msg = obj.message;
+        if (Array.isArray(msg.content))
+            candidates.push(...msg.content);
+    }
+    for (const candidate of candidates) {
+        if (typeof candidate !== 'object' || candidate === null)
+            continue;
+        const c = candidate;
+        const isToolUse = c.type === 'tool_use' || c.type === 'function_call';
+        const nameField = typeof c.name === 'string' ? c.name : (typeof c.tool_name === 'string' ? c.tool_name : '');
+        const isSeekMentoring = nameField === 'seekMentoring' ||
+            nameField === 'mcp__fraim__seekMentoring' ||
+            nameField.endsWith('seekMentoring');
+        if (!isToolUse || !isSeekMentoring)
+            continue;
+        const input = (c.input || c.arguments || c.parameters);
+        const sig = extractSignalFromArgs(input);
+        if (sig)
+            return sig;
+    }
+    return null;
+}
+// Issue #347 — extract per-turn usage from the host's JSON stream.
+// Codex: `{"type":"turn.completed","usage":{input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens}}`.
+// Claude Code: `{"type":"result", ..., "usage":{input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens}, "total_cost_usd": ...}`.
+function parseUsageSignal(line) {
+    if (!line.includes('usage'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const obj = parsed;
+    // Codex turn.completed shape. Codex's `input_tokens` is cumulative
+    // and INCLUDES the cached portion, so normalize by subtracting.
+    if (obj.type === 'turn.completed' && typeof obj.usage === 'object' && obj.usage !== null) {
+        const u = obj.usage;
+        const totalInput = numberOrNull(u.input_tokens);
+        const cachedInput = numberOrNull(u.cached_input_tokens) ?? 0;
+        const outputTokens = numberOrNull(u.output_tokens);
+        if (totalInput === null && outputTokens === null)
+            return null;
+        const nonCached = Math.max(0, (totalInput ?? 0) - cachedInput);
+        return {
+            nonCachedInputTokens: nonCached,
+            cachedInputTokens: cachedInput,
+            cacheCreationTokens: 0, // Codex does not bill cache creation separately
+            outputTokens: outputTokens ?? 0,
+            reasoningTokens: numberOrNull(u.reasoning_output_tokens) ?? undefined,
+        };
+    }
+    // Claude Code result shape. Anthropic semantics: input_tokens,
+    // cache_read_input_tokens, and cache_creation_input_tokens are
+    // mutually exclusive — pass each through to its own bucket.
+    if (obj.type === 'result' && typeof obj.usage === 'object' && obj.usage !== null) {
+        const u = obj.usage;
+        const inputTokens = numberOrNull(u.input_tokens);
+        const outputTokens = numberOrNull(u.output_tokens);
+        if (inputTokens === null && outputTokens === null)
+            return null;
+        const costUsd = numberOrNull(obj.total_cost_usd);
+        return {
+            nonCachedInputTokens: inputTokens ?? 0,
+            cachedInputTokens: numberOrNull(u.cache_read_input_tokens) ?? 0,
+            cacheCreationTokens: numberOrNull(u.cache_creation_input_tokens) ?? 0,
+            outputTokens: outputTokens ?? 0,
+            costUsd: costUsd ?? undefined,
+        };
+    }
+    return null;
+}
+// Issue #347 — extract agent identity from the fraim_connect tool call.
+// Both hosts pass `agent: { name, model }` in the call's arguments.
+function parseAgentIdentitySignal(line) {
+    if (!line.includes('fraim_connect'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const obj = parsed;
+    // Codex shape.
+    if ((obj.type === 'item.started' || obj.type === 'item.completed') && typeof obj.item === 'object' && obj.item !== null) {
+        const item = obj.item;
+        if (item.type === 'mcp_tool_call' && item.tool === 'fraim_connect') {
+            return readAgentFromArgs(item.arguments);
+        }
+    }
+    // Claude Code shape.
+    const candidates = [obj];
+    if (typeof obj.message === 'object' && obj.message !== null) {
+        const msg = obj.message;
+        if (Array.isArray(msg.content))
+            candidates.push(...msg.content);
+    }
+    for (const candidate of candidates) {
+        if (typeof candidate !== 'object' || candidate === null)
+            continue;
+        const c = candidate;
+        if (c.type !== 'tool_use' && c.type !== 'function_call')
+            continue;
+        const name = typeof c.name === 'string' ? c.name : '';
+        if (!name.endsWith('fraim_connect'))
+            continue;
+        const sig = readAgentFromArgs((c.input || c.arguments));
+        if (sig)
+            return sig;
+    }
+    return null;
+}
+function readAgentFromArgs(args) {
+    if (!args || typeof args.agent !== 'object' || args.agent === null)
+        return null;
+    const agent = args.agent;
+    const agentName = typeof agent.name === 'string' ? agent.name : null;
+    const agentModel = typeof agent.model === 'string' ? agent.model : null;
+    if (!agentName || !agentModel)
+        return null;
+    return { agentName, agentModel };
+}
+function numberOrNull(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+function extractSignalFromArgs(args) {
+    if (!args)
+        return null;
+    const phaseId = typeof args.currentPhase === 'string' ? args.currentPhase : null;
+    const rawStatus = typeof args.status === 'string' ? args.status : null;
+    if (!phaseId || !rawStatus)
+        return null;
+    const phaseStatus = ['starting', 'complete', 'incomplete', 'failure'].includes(rawStatus)
+        ? rawStatus
+        : 'starting';
+    const findings = args.findings;
+    const findingsText = findings && typeof findings.summary === 'string' ? findings.summary : undefined;
+    const discriminant = typeof args.runDiscriminant === 'string' ? args.runDiscriminant : undefined;
+    const jobName = typeof args.jobName === 'string' ? args.jobName : undefined;
+    const jobId = typeof args.jobId === 'string' ? args.jobId : undefined;
+    return { phaseId, phaseStatus, findingsText, discriminant, jobName, jobId };
+}
 const EMPLOYEE_LABELS = {
     codex: 'Codex',
     claude: 'Claude Code',
@@ -83,39 +280,51 @@ function parseHostLine(hostId, line) {
     const trimmed = line.trim();
     if (!trimmed)
         return {};
+    // Issue #347: scan every line for the three signals the Hub UI cares
+    // about — seekMentoring (drives the tracker), turn-level usage
+    // (drives the totals tokens/cost), and the agent identity from
+    // fraim_connect (used to look up cost when the host doesn't emit it).
+    const seekMentoring = parseSeekMentoringSignal(trimmed);
+    const usage = parseUsageSignal(trimmed);
+    const agentIdentity = parseAgentIdentitySignal(trimmed);
+    const withSignal = (event) => {
+        if (!seekMentoring && !usage && !agentIdentity)
+            return event;
+        return { ...event, ...(seekMentoring ? { seekMentoring } : {}), ...(usage ? { usage } : {}), ...(agentIdentity ? { agentIdentity } : {}) };
+    };
     if (hostId === 'codex') {
         try {
             const parsed = JSON.parse(trimmed);
             if (parsed.type === 'thread.started' && parsed.thread_id) {
-                return { sessionId: parsed.thread_id, raw: trimmed };
+                return withSignal({ sessionId: parsed.thread_id, raw: trimmed });
             }
             if (parsed.type === 'item.completed' && parsed.item?.type === 'agent_message' && parsed.item.text) {
-                return { message: parsed.item.text, raw: trimmed };
+                return withSignal({ message: parsed.item.text, raw: trimmed });
             }
-            return { raw: trimmed };
+            return withSignal({ raw: trimmed });
         }
         catch {
-            return { raw: trimmed };
+            return withSignal({ raw: trimmed });
         }
     }
     try {
         const parsed = JSON.parse(trimmed);
         if (parsed.type === 'system' && parsed.session_id) {
-            return { sessionId: parsed.session_id, raw: trimmed };
+            return withSignal({ sessionId: parsed.session_id, raw: trimmed });
         }
         if (parsed.type === 'assistant') {
             const text = parsed.message?.content?.find((entry) => entry.type === 'text')?.text;
             if (text) {
-                return { message: text, sessionId: parsed.session_id, raw: trimmed };
+                return withSignal({ message: text, sessionId: parsed.session_id, raw: trimmed });
             }
         }
         if (parsed.type === 'result' && parsed.result) {
-            return { message: parsed.result, sessionId: parsed.session_id, raw: trimmed };
+            return withSignal({ message: parsed.result, sessionId: parsed.session_id, raw: trimmed });
         }
-        return { raw: trimmed };
+        return withSignal({ raw: trimmed });
     }
     catch {
-        return { raw: trimmed };
+        return withSignal({ raw: trimmed });
     }
 }
 function wireHostProcess(hostId, child, handlers) {
@@ -225,6 +434,171 @@ class FakeHostRuntime {
     }
 }
 exports.FakeHostRuntime = FakeHostRuntime;
+// Issue #347 — test-only host that lets a test inject seekMentoring
+// signals on a runId-by-runId basis. The Hub server treats it like any
+// HostRuntime; the test holds a reference and calls emitPhase() to
+// drive deterministic phase transitions. Outside tests, prefer
+// FakeHostRuntime (smaller surface, no seekMentoring).
+class ScriptedHostRuntime {
+    constructor() {
+        this.employees = [
+            { id: 'codex', label: 'Codex', available: true, detail: 'Scripted test double.' },
+            { id: 'claude', label: 'Claude Code', available: true, detail: 'Scripted test double.' },
+        ];
+        // Track each active run so the test can emit signals at it. Key is the
+        // sessionId we hand back on startRun; mapping sessionId → handlers
+        // lets emitPhase() reach the right run's onEvent callback.
+        this.handlersBySession = new Map();
+        // Tracks runDiscriminant per sessionId so consecutive emitPhase calls
+        // can resolve onSuccess routing without each test having to repeat it.
+        this.discriminantBySession = new Map();
+    }
+    detectEmployees() {
+        return this.employees;
+    }
+    startRun(_hostId, _projectPath, _message, handlers) {
+        const sessionId = (0, crypto_1.randomUUID)();
+        handlers.onEvent({ sessionId, raw: 'scripted-session-start' }, 'system');
+        this.handlersBySession.set(sessionId, handlers);
+        return this.spawnDouble();
+    }
+    continueRun(_hostId, _projectPath, sessionId, _message, handlers) {
+        this.handlersBySession.set(sessionId, handlers);
+        handlers.onEvent({ sessionId, raw: 'scripted-session-resume' }, 'system');
+        return this.spawnDouble();
+    }
+    // Test API — fire a seekMentoring tool-use event for the most recent
+    // active run. The phaseId is the raw FSM phase id (e.g.,
+    // 'implement-validate'); the parser will turn it into a friendly
+    // tracker label downstream.
+    emitPhase(runId, phaseId, status, findingsText) {
+        const target = this.resolveSession(runId);
+        if (!target)
+            return;
+        target.handlers.onEvent({
+            sessionId: target.sessionId,
+            raw: `scripted-seekMentoring:${phaseId}:${status}`,
+            seekMentoring: { phaseId, phaseStatus: status, findingsText },
+        }, 'stdout');
+    }
+    // Test API — set the runDiscriminant for a run so onSuccess routing
+    // resolves correctly (e.g., 'feature' vs 'bug' for feature-implementation).
+    emitDiscriminant(runId, discriminant) {
+        const target = this.resolveSession(runId);
+        if (!target)
+            return;
+        this.discriminantBySession.set(target.sessionId, discriminant);
+        target.handlers.onEvent({
+            sessionId: target.sessionId,
+            raw: `scripted-discriminant:${discriminant}`,
+            seekMentoring: {
+                phaseId: '__discriminant__',
+                phaseStatus: 'starting',
+                discriminant,
+            },
+        }, 'system');
+    }
+    // Test API — emit a seekMentoring signal for a job *other* than the
+    // one this run is tracking. Used to verify the cross-job pollution
+    // filter in applySeekMentoringSignal.
+    emitForeignPhase(runId, foreignJobId, phaseId, status) {
+        const target = this.resolveSession(runId);
+        if (!target)
+            return;
+        target.handlers.onEvent({
+            sessionId: target.sessionId,
+            raw: `scripted-foreign-seekMentoring:${foreignJobId}:${phaseId}`,
+            seekMentoring: {
+                phaseId,
+                phaseStatus: status,
+                jobId: foreignJobId,
+                jobName: foreignJobId,
+            },
+        }, 'stdout');
+    }
+    // Test API — emit a per-turn usage signal in the normalized shape
+    // the server expects. Mirrors what parseUsageSignal would produce
+    // from a real host's stream.
+    emitUsage(runId, usage) {
+        const target = this.resolveSession(runId);
+        if (!target)
+            return;
+        target.handlers.onEvent({
+            sessionId: target.sessionId,
+            raw: `scripted-usage:${JSON.stringify(usage)}`,
+            usage: {
+                nonCachedInputTokens: usage.nonCachedInputTokens ?? 0,
+                cachedInputTokens: usage.cachedInputTokens ?? 0,
+                cacheCreationTokens: usage.cacheCreationTokens ?? 0,
+                outputTokens: usage.outputTokens ?? 0,
+                costUsd: usage.costUsd,
+            },
+        }, 'stdout');
+    }
+    // Test API — emit the agent-identity signal that fraim_connect would
+    // produce, so applyUsageSignal's price-table lookup has identity to
+    // work with.
+    emitAgentIdentity(runId, agentName, agentModel) {
+        const target = this.resolveSession(runId);
+        if (!target)
+            return;
+        target.handlers.onEvent({
+            sessionId: target.sessionId,
+            raw: `scripted-agent-identity:${agentName}:${agentModel}`,
+            agentIdentity: { agentName, agentModel },
+        }, 'stdout');
+    }
+    // Reset between tests (called from beforeEach).
+    reset() {
+        this.handlersBySession.clear();
+        this.discriminantBySession.clear();
+    }
+    // The Hub server keeps its own sessionId map keyed off run.sessionId —
+    // but at the time the test calls emitPhase(runId), we may only have
+    // one handler registered (the latest start). Resolve by sessionId
+    // first, fall back to the most recent registered handler.
+    resolveSession(_runId) {
+        if (this.handlersBySession.size === 0)
+            return null;
+        const entries = [...this.handlersBySession.entries()];
+        const [sessionId, handlers] = entries[entries.length - 1];
+        return { sessionId, handlers };
+    }
+    spawnDouble() {
+        return {
+            stdout: process.stdout,
+            stderr: process.stderr,
+            stdin: process.stdin,
+            kill: () => true,
+            on: () => ({}),
+            once: () => ({}),
+            emit: () => true,
+            addListener: () => ({}),
+            removeListener: () => ({}),
+            removeAllListeners: () => ({}),
+            setMaxListeners: () => ({}),
+            getMaxListeners: () => 0,
+            listeners: () => [],
+            rawListeners: () => [],
+            listenerCount: () => 0,
+            prependListener: () => ({}),
+            prependOnceListener: () => ({}),
+            eventNames: () => [],
+            pid: 0,
+            connected: false,
+            disconnect: () => undefined,
+            exitCode: 0,
+            killed: false,
+            signalCode: null,
+            spawnargs: [],
+            spawnfile: '',
+            stdio: [],
+            unref: () => undefined,
+            ref: () => undefined,
+        };
+    }
+}
+exports.ScriptedHostRuntime = ScriptedHostRuntime;
 const createHubMessage = (role, text) => ({
     id: (0, crypto_1.randomUUID)(),
     role,