zelari-code 1.45.0 → 1.47.1

package/dist/cli/hooks/sessionSurface.js

@@ -0,0 +1,171 @@
+import { envNumber } from '../utils/envNumber.js';
+/** Marker prefix — also used by retrieve_observation to refuse rematerializing a stub. */
+export const OBSERVATION_STUB_PREFIX = 'OBSERVATION ref=#';
+export const DEFAULT_HOT_TAIL = 4;
+export const DEFAULT_MAX_BODY_CHARS = 4_000;
+/** Kill switch: ZELARI_SESSION_SURFACE=0 restores the pre-Fase-2 pruner. */
+export function sessionSurfaceEnabled() {
+    return process.env.ZELARI_SESSION_SURFACE !== '0';
+}
+/** True when a tool-result body is already a Fase-2 stub (never un-prune). */
+export function isObservationStub(content) {
+    return content.startsWith(OBSERVATION_STUB_PREFIX);
+}
+/**
+ * Parse `OBSERVATION ref=#N …` into fields. Returns null if the body is not a stub.
+ * Extra key=value pairs after the known ones are preserved as `extra`.
+ */
+export function parseObservationStub(content) {
+    if (!isObservationStub(content))
+        return null;
+    const first = content.split('\n', 1)[0] ?? content;
+    const seqMatch = first.match(/^OBSERVATION ref=#(\d+)\b/);
+    if (!seqMatch)
+        return null;
+    const fields = { seq: Number(seqMatch[1]) };
+    const tool = first.match(/\btool=([A-Za-z0-9._-]+)/);
+    if (tool)
+        fields.tool = tool[1];
+    const status = first.match(/\bstatus=([A-Za-z0-9._-]+)/);
+    if (status)
+        fields.status = status[1];
+    const bytes = first.match(/\bbytes=(\d+)/);
+    if (bytes)
+        fields.bytes = Number(bytes[1]);
+    const known = /^(ref|#\d+|tool|status|bytes)$/;
+    const extras = [];
+    for (const m of first.matchAll(/\b([A-Za-z_][A-Za-z0-9._-]*)=([^\s]+)/g)) {
+        if (!known.test(m[1]))
+            extras.push(`${m[1]}=${m[2]}`);
+    }
+    if (extras.length)
+        fields.extra = extras.join(' ');
+    return fields;
+}
+/**
+ * Deterministic stub. Same fields → byte-identical string (cache-safe).
+ * `seq` is the 1-based index of this tool_execution_end in the session log.
+ */
+export function formatObservationStub(fields) {
+    const parts = [`${OBSERVATION_STUB_PREFIX}${fields.seq}`];
+    if (fields.tool)
+        parts.push(`tool=${fields.tool}`);
+    if (fields.status)
+        parts.push(`status=${fields.status}`);
+    if (fields.bytes !== undefined)
+        parts.push(`bytes=${fields.bytes}`);
+    if (fields.extra)
+        parts.push(fields.extra);
+    return `${parts.join(' ')}\n[retrieve_observation #${fields.seq}]`;
+}
+/**
+ * Extract Ground-Truth status from a tool-result body (Fase 0 footer), if any.
+ * Footer shape: `\n[observation status=complete filesWalked=12 …]`
+ */
+export function statusFromToolBody(body) {
+    const m = body.match(/\[observation\s+([^\]]+)\]\s*$/);
+    if (!m)
+        return undefined;
+    const status = m[1].match(/\bstatus=([A-Za-z0-9._-]+)/);
+    return status?.[1];
+}
+function resolveSurfaceLimits(opts) {
+    return {
+        hotTail: opts?.hotTail ??
+            envNumber(process.env.ZELARI_SURFACE_HOT_TAIL, { default: DEFAULT_HOT_TAIL, min: 0 }),
+        maxBodyChars: opts?.maxBodyChars ??
+            envNumber(process.env.ZELARI_SURFACE_MAX_BODY_CHARS, {
+                default: DEFAULT_MAX_BODY_CHARS,
+                min: 64,
+            }),
+    };
+}
+/**
+ * Resolve the stable observation seq for a tool message.
+ *
+ * Preference order (all deterministic):
+ *  1. already a stub → keep its seq (monotone — never rewrite the number)
+ *  2. `lookup(toolCallId)` from the session log
+ *  3. 1-based index among role:'tool' messages in THIS history (offline / tests)
+ */
+export function resolveObservationSeq(message, indexAmongTools, lookup) {
+    const existing = parseObservationStub(message.content ?? '');
+    if (existing)
+        return existing.seq;
+    const id = message.toolCallId;
+    if (id && lookup) {
+        const fromLog = lookup(id);
+        if (typeof fromLog === 'number' && fromLog > 0)
+            return fromLog;
+    }
+    return indexAmongTools + 1;
+}
+/**
+ * Infer a tool name from the preceding assistant(tool_calls) that declared
+ * this toolCallId. Deterministic walk — no side tables.
+ */
+export function inferToolName(messages, toolIndex, toolCallId) {
+    if (!toolCallId)
+        return undefined;
+    for (let i = toolIndex - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role !== 'assistant' || !m.toolCalls)
+            continue;
+        const hit = m.toolCalls.find((c) => c.id === toolCallId);
+        if (hit)
+            return hit.name;
+    }
+    return undefined;
+}
+/**
+ * Project oversized / cold tool-result bodies onto addressable stubs.
+ *
+ * Invariants:
+ *  - never mutates the input array or its messages
+ *  - already-stubbed bodies are left byte-identical
+ *  - same (messages, opts, lookup) → byte-identical output (cache-safe)
+ *  - returns the SAME array reference when nothing changed
+ */
+export function projectSessionSurface(messages, opts, lookup) {
+    const { hotTail, maxBodyChars } = resolveSurfaceLimits(opts);
+    const stats = { projected: 0, charsOmitted: 0, alreadyStubbed: 0 };
+    const toolPositions = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i].role === 'tool')
+            toolPositions.push(i);
+    }
+    if (toolPositions.length === 0) {
+        return { messages: messages, stats };
+    }
+    const hotStart = Math.max(0, toolPositions.length - hotTail);
+    const protect = new Set(toolPositions.slice(hotStart));
+    let changed = false;
+    const out = messages.map((m, i) => {
+        if (m.role !== 'tool')
+            return m;
+        const body = m.content ?? '';
+        if (isObservationStub(body)) {
+            stats.alreadyStubbed += 1;
+            return m;
+        }
+        if (protect.has(i) || body.length <= maxBodyChars)
+            return m;
+        const toolOrdinal = toolPositions.indexOf(i);
+        const seq = resolveObservationSeq(m, toolOrdinal, lookup);
+        const stub = formatObservationStub({
+            seq,
+            tool: inferToolName(messages, i, m.toolCallId),
+            status: statusFromToolBody(body),
+            bytes: body.length,
+        });
+        changed = true;
+        stats.projected += 1;
+        stats.charsOmitted += Math.max(0, body.length - stub.length);
+        return { ...m, content: stub };
+    });
+    return {
+        messages: changed ? out : messages,
+        stats,
+    };
+}
+//# sourceMappingURL=sessionSurface.js.map

package/dist/cli/hooks/sessionSurface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionSurface.js","sourceRoot":"","sources":["../../../src/cli/hooks/sessionSurface.ts"],"names":[],"mappings":"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"}

package/dist/cli/hooks/sessionSurface.test.js

@@ -0,0 +1,112 @@
+/**
+ * sessionSurface — Fase 2 acceptance: deterministic projection, monotone
+ * stubs, byte-identical replay, no un-pruning.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { formatObservationStub, isObservationStub, parseObservationStub, projectSessionSurface, resolveObservationSeq, statusFromToolBody, } from './sessionSurface.js';
+function tool(id, content) {
+    return { role: 'tool', toolCallId: id, content };
+}
+function assistantCall(id, name) {
+    return { role: 'assistant', content: '', toolCalls: [{ id, name, args: {} }] };
+}
+describe('observation stub codec', () => {
+    it('round-trips fields byte-identically', () => {
+        const stub = formatObservationStub({
+            seq: 12,
+            tool: 'grep_content',
+            status: 'complete',
+            bytes: 4096,
+        });
+        expect(stub).toBe('OBSERVATION ref=#12 tool=grep_content status=complete bytes=4096\n[retrieve_observation #12]');
+        expect(isObservationStub(stub)).toBe(true);
+        expect(parseObservationStub(stub)).toEqual({
+            seq: 12,
+            tool: 'grep_content',
+            status: 'complete',
+            bytes: 4096,
+        });
+        expect(formatObservationStub(parseObservationStub(stub))).toBe(stub);
+    });
+    it('rejects non-stubs', () => {
+        expect(isObservationStub('hello')).toBe(false);
+        expect(parseObservationStub('hello')).toBeNull();
+    });
+    it('reads Fase-0 footer status', () => {
+        expect(statusFromToolBody('body\n[observation status=partial filesWalked=3]')).toBe('partial');
+        expect(statusFromToolBody('plain')).toBeUndefined();
+    });
+});
+describe('projectSessionSurface', () => {
+    afterEach(() => {
+        delete process.env.ZELARI_SURFACE_HOT_TAIL;
+        delete process.env.ZELARI_SURFACE_MAX_BODY_CHARS;
+        delete process.env.ZELARI_SESSION_SURFACE;
+    });
+    it('returns the same reference when nothing needs projecting', () => {
+        const msgs = [
+            { role: 'user', content: 'hi' },
+            tool('c1', 'tiny'),
+        ];
+        const r = projectSessionSurface(msgs, { hotTail: 4, maxBodyChars: 4000 });
+        expect(r.messages).toBe(msgs);
+        expect(r.stats.projected).toBe(0);
+    });
+    it('keeps the hot tail full-fidelity and stubs older oversized bodies', () => {
+        const big = 'B'.repeat(500);
+        const msgs = [];
+        for (let i = 1; i <= 6; i++) {
+            msgs.push(assistantCall(`c${i}`, 'read_file'));
+            msgs.push(tool(`c${i}`, big + `\n[observation status=complete bytes=${big.length}]`));
+        }
+        const r = projectSessionSurface(msgs, { hotTail: 2, maxBodyChars: 100 });
+        expect(r.stats.projected).toBe(4);
+        const tools = r.messages.filter((m) => m.role === 'tool');
+        expect(tools.slice(0, 4).every((m) => isObservationStub(m.content))).toBe(true);
+        expect(tools.slice(4).every((m) => !isObservationStub(m.content))).toBe(true);
+        expect(tools[0].content).toContain('tool=read_file');
+        expect(tools[0].content).toContain('status=complete');
+        expect(tools[0].content).toContain('[retrieve_observation #1]');
+    });
+    it('is deterministic: same input → byte-identical surface', () => {
+        const big = 'X'.repeat(800);
+        const msgs = [
+            assistantCall('a', 'grep_content'),
+            tool('a', big),
+            assistantCall('b', 'grep_content'),
+            tool('b', big),
+            assistantCall('c', 'list_files'),
+            tool('c', big),
+        ];
+        const a = projectSessionSurface(msgs, { hotTail: 1, maxBodyChars: 50 });
+        const b = projectSessionSurface(msgs, { hotTail: 1, maxBodyChars: 50 });
+        expect(JSON.stringify(a.messages)).toBe(JSON.stringify(b.messages));
+        expect(a.stats).toEqual(b.stats);
+    });
+    it('never un-prunes an existing stub (monotone / cache-safe)', () => {
+        const stub = formatObservationStub({ seq: 7, tool: 'read_file', bytes: 9999 });
+        const msgs = [tool('old', stub), tool('hot', 'H'.repeat(50))];
+        const r = projectSessionSurface(msgs, { hotTail: 4, maxBodyChars: 10 });
+        expect(r.messages[0].content).toBe(stub);
+        expect(r.stats.alreadyStubbed).toBe(1);
+        expect(r.stats.projected).toBe(0);
+    });
+    it('uses lookup(toolCallId) for stable seq when provided', () => {
+        const big = 'Z'.repeat(200);
+        const msgs = [
+            assistantCall('call-z', 'bash'),
+            tool('call-z', big),
+            assistantCall('keep', 'bash'),
+            tool('keep', big),
+        ];
+        const lookup = (id) => (id === 'call-z' ? 42 : undefined);
+        const r = projectSessionSurface(msgs, { hotTail: 1, maxBodyChars: 10 }, lookup);
+        expect(r.messages[1].content).toContain('ref=#42');
+        expect(r.messages[1].content).toContain('[retrieve_observation #42]');
+    });
+    it('falls back to 1-based ordinal when lookup misses', () => {
+        const seq = resolveObservationSeq(tool('x', 'body'), 3);
+        expect(seq).toBe(4);
+    });
+});
+//# sourceMappingURL=sessionSurface.test.js.map

package/dist/cli/hooks/sessionSurface.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionSurface.test.js","sourceRoot":"","sources":["../../../src/cli/hooks/sessionSurface.test.ts"],"names":[],"mappings":"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"}

package/dist/cli/hooks/useChatTurn.js

@@ -2,6 +2,7 @@
 // from app.tsx. Runtime is correct; tighten signatures in a follow-up.
 import { useState, useRef, useCallback } from "react";
 import { AgentHarness } from "@zelari/core/harness";
+import { ingestLiveEvent } from "./observationStore.js";
 import { getMetricsLogger } from "../metrics.js";
 import { calculateCost } from "../modelPricing.js";
 import { providerFromEnv, providerConfigFor, resolveActiveProvider, } from "../provider/openai-compatible.js";
@@ -351,6 +352,8 @@ export function useChatTurn(params) {
                     "You are in PLAN mode. Explore and design only.",
                     "- Do NOT implement production code or run destructive shell commands.",
                     "- write_file / edit_file / bash / apply_diff are unavailable.",
+                    "- inspect_command IS available: allowlisted read-only inspector (no shell). Use it for git_status/git_log/git_diff/git_show/git_branch_current/git_ls_files/typecheck/node_version/npm_ls/npm_outdated/npm_view - it turns claims into execution-verified observations.",
+                    "- OBSERVATION INTEGRITY: negative evidence is valid only from a completed observation. Never conclude that code/symbols/files do not exist from degraded results, zero files examined, or unavailable backends (grep_content SEARCH_EMPTY_SCOPE, ast/LSP degraded status, inspect_command unsupported shapes).",
                     "- Produce a clear plan, ask clarifying questions (---QUESTION---), use workspace plan tools when relevant.",
                     "- When the plan is ready, tell the user to run /build to implement.",
                 ].join("\n")
@@ -536,6 +539,8 @@ export function useChatTurn(params) {
             // matching start event (keyed by toolCallId) for metrics.
             const toolNameById = new Map();
             const metrics = getMetricsLogger();
+            // Fase M: last log-only context_metrics event (arrives before agent_end).
+            let lastGrowth = null;
             let realUsage = null;
             try {
                 for await (const event of harness.run()) {
@@ -578,6 +583,11 @@ export function useChatTurn(params) {
                         // to serialize the render loop with mkdir+appendFile per delta.
                         // Turn boundaries below call flush() so the tail is durable.
                         void writerRef.current.append(event);
+                        if (sessionId)
+                            ingestLiveEvent(sessionId, event);
+                    }
+                    if (event.type === "context_metrics") {
+                        lastGrowth = event;
                     }
                     if (event.type === "agent_end") {
                         metrics.record({
@@ -587,6 +597,17 @@ export function useChatTurn(params) {
                             model: envConfig.model,
                             latencyMs: event.durationMs,
                             ok: event.reason === "stop",
+                            // Fase M: context-growth counters (log-only event, folded here).
+                            ...(lastGrowth
+                                ? {
+                                    toolRoundTrips: lastGrowth.toolRoundTrips,
+                                    intermediateToolBytes: lastGrowth.intermediateToolBytes,
+                                    requests: lastGrowth.requests,
+                                    historyBytesAtRequest: lastGrowth.historyBytesLast,
+                                    historyBytesPeak: lastGrowth.historyBytesPeak,
+                                    cacheHitTokens: lastGrowth.cacheHitTokens,
+                                }
+                                : {}),
                             // v1.35: real usage landed on message_end (which precedes
                             // agent_end), so historical spend can be aggregated from
                             // metrics.jsonl — previously these fields were always absent.
@@ -1171,12 +1192,16 @@ async function dispatchCouncilPromptImpl(text, deps, overrides = {}) {
                 // Drain remaining events silently after the abort decision.
                 if (writerRef.current)
                     void writerRef.current.append(event);
+                if (sessionId)
+                    ingestLiveEvent(sessionId, event);
                 continue;
             }
             if (writerRef.current) {
                 // Same batching as the single-agent path: fire-and-forget per event,
                 // flush at the turn boundary in `finally`.
                 void writerRef.current.append(event);
+                if (sessionId)
+                    ingestLiveEvent(sessionId, event);
             }
             if (event.type === "council_mode") {
                 councilRunMode = event.runMode;
@@ -1680,6 +1705,8 @@ async function runZelariMissionInTui(userMessage, deps, emit) {
                         onEvent: async (event) => {
                             if (writerRef.current)
                                 await writerRef.current.append(event);
+                            if (sessionId)
+                                ingestLiveEvent(sessionId, event);
                             if (event.type === "tool_execution_start") {
                                 const name = event.toolName ?? "tool";
                                 appendSystem(setMessages, `[build@kraken] → ${name}`, Date.now());