@zelari/core 2.7.0 → 2.9.0

package/dist/core/AgentHarness.d.ts

@@ -21,6 +21,7 @@ import { EventBus } from '../shared/eventBus.js';
 import { type BrainEvent, type UsageBreakdown } from '../shared/events.js';
 import { ToolRegistry } from './tools/registry.js';
 import { type RoutedRequestSnapshot, type ProviderGenerationOptions } from './requestSnapshot.js';
+import type { MemoryService } from '../memory/types.js';
 export { collapseLoopedAssistantText, detectAssistantTextLoop, detectAssistantTextLoopWindow, normalizeLoopUnit, isStatusTheaterUnit, TEXT_LOOP_RECOVERY_SYSTEM, TEXT_LOOP_RECOVERY_USER_PROMPT, type TextLoopHit, } from './textLoopDetect.js';
 /** Inline image sent to vision-capable providers (raw base64, no data: prefix). */
 export interface AgentImage {
@@ -76,6 +77,26 @@ export interface AgentToolSpec {
     /** JSON Schema for the tool's input arguments. */
     parameters: Record<string, unknown>;
 }
+/** Host-owned progress evidence for mutation-required build turns. */
+export interface BuildProgress {
+    toolCalls: number;
+    mutationsAttempted: number;
+    mutationsSucceeded: number;
+    verificationCalls: number;
+    recoveries: number;
+}
+/**
+ * Provider-neutral build-liveness policy. The host decides whether the task
+ * requires an on-disk mutation; the harness owns progress detection and the
+ * bounded recovery loop. Provider-specific forcing is serialized only by the
+ * provider adapter through generation.toolChoice.
+ */
+export interface BuildLivenessPolicy {
+    mutationRequired: boolean;
+    /** Zero-mutation recovery turns before the run is failed. Default 2. */
+    maxRecoveries?: number;
+}
+export declare const BUILD_LIVENESS_RECOVERY_PROMPT: string;
 export interface AgentHarnessConfig {
     /** Model identifier (e.g. 'grok-4', 'MiniMax-M2.5'). */
     model: string;
@@ -99,6 +120,14 @@ export interface AgentHarnessConfig {
      * tool execution and emit a matching `tool_execution_end` event.
      */
     toolRegistry?: ToolRegistry;
+    /** Enforce successful mutation evidence before a mutate/build task completes. */
+    buildLiveness?: BuildLivenessPolicy;
+    /**
+     * Volatile messages appended only to the routed request. They never enter
+     * `config.messages` or `getMessages()` and are re-read before every call.
+     * Used for current resource status without rewriting persistent history.
+     */
+    requestTail?: () => readonly AgentMessage[];
     /** Optional cwd for tool execution. Defaults to process.cwd(). */
     cwd?: string;
     /**
@@ -180,6 +209,16 @@ export interface AgentHarnessConfig {
     memberId?: string;
     /** Human-readable member label (e.g. "Caronte"). See `memberId`. */
     memberName?: string;
+    /**
+     * Optional native project memory. The harness performs a bounded, fail-open
+     * recall before the first provider call and injects it ephemerally after the
+     * stable system prefix (it never mutates conversation history).
+     */
+    memoryService?: MemoryService;
+    /** Explicit recall objective; defaults to the latest user message. */
+    memoryQuery?: string;
+    /** Hard character budget for the ephemeral memory block. Default 2,000. */
+    memoryContextChars?: number;
 }
 export type ProviderStreamFn = (params: {
     messages: AgentMessage[];
@@ -187,6 +226,8 @@ export type ProviderStreamFn = (params: {
     provider: string;
     tools: AgentToolSpec[];
     signal?: AbortSignal;
+    /** Stable harness/session id for provider-side conversation affinity. */
+    conversationId?: string;
     /**
      * v1.36.0: optional generation knobs (purpose/temperature/maxTokens).
      * Providers that understand them apply them; others ignore them. Used by
@@ -256,6 +297,9 @@ export declare class AgentHarness {
     private textToolReentries;
     /** Fase M: per-run context-growth counters (reset on every run()). */
     private growth;
+    /** Ephemeral per-run context; never appended to `config.messages`. */
+    private activeMemoryContext;
+    private buildProgress;
     constructor(config: AgentHarnessConfig);
     /**
      * Snapshot of the live transcript (`this.config.messages`) as mutated
@@ -275,6 +319,11 @@ export declare class AgentHarness {
      * @since v1.6.0
      */
     getMessages(): readonly AgentMessage[];
+    /** Immutable snapshot of host-observed build progress for this run. */
+    getBuildProgress(): Readonly<BuildProgress>;
+    private toolPermissions;
+    private isMutationTool;
+    private recordSuccessfulTool;
     /**
      * Member identity fields (memberId + memberName) to merge into every
      * event payload. Returns an empty object when the run is a direct
@@ -343,6 +392,9 @@ export declare class AgentHarness {
      * Callers can subscribe via eventBus AND iterate the returned iterable.
      */
     run(): AsyncIterable<BrainEvent>;
+    private prepareMemoryContext;
+    /** Build a provider-only view with memory after the stable system prefix. */
+    private messagesForProvider;
     /**
      * v1.36.0: capture a deterministic snapshot of the routed request just
      * before it goes out. Never throws into the request path.

package/dist/core/AgentHarness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentHarness.d.ts","sourceRoot":"","sources":["../../src/core/AgentHarness.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentHarness.d.ts","sourceRoot":"","sources":["../../src/core/AgentHarness.ts"],"names":[],"mappings":"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"}

package/dist/core/AgentHarness.js

@@ -24,6 +24,10 @@ import { emptyContextGrowthStats, recordRequest, recordToolResult, recordUsage,
 import { createRoutedRequestSnapshot, } from './requestSnapshot.js';
 import { collapseLoopedAssistantText, detectAssistantTextLoopWindow, TEXT_LOOP_RECOVERY_SYSTEM, TEXT_LOOP_RECOVERY_USER_PROMPT, } from './textLoopDetect.js';
 export { collapseLoopedAssistantText, detectAssistantTextLoop, detectAssistantTextLoopWindow, normalizeLoopUnit, isStatusTheaterUnit, TEXT_LOOP_RECOVERY_SYSTEM, TEXT_LOOP_RECOVERY_USER_PROMPT, } from './textLoopDetect.js';
+export const BUILD_LIVENESS_RECOVERY_PROMPT = '[build-liveness] The requested task requires an on-disk implementation, ' +
+    'but no successful project mutation has occurred yet. Continue working. ' +
+    'Inspect only as needed, then make the required change with an available ' +
+    'mutating tool. Do not merely describe a patch or claim completion.';
 // --- Harness ----------------------------------------------------------------
 export class AgentHarness {
     config;
@@ -59,6 +63,15 @@ export class AgentHarness {
     textToolReentries = 0;
     /** Fase M: per-run context-growth counters (reset on every run()). */
     growth = emptyContextGrowthStats();
+    /** Ephemeral per-run context; never appended to `config.messages`. */
+    activeMemoryContext = '';
+    buildProgress = {
+        toolCalls: 0,
+        mutationsAttempted: 0,
+        mutationsSucceeded: 0,
+        verificationCalls: 0,
+        recoveries: 0,
+    };
     constructor(config) {
         this.config = config;
         this.eventBus = config.eventBus;
@@ -99,6 +112,37 @@ export class AgentHarness {
     getMessages() {
         return this.config.messages;
     }
+    /** Immutable snapshot of host-observed build progress for this run. */
+    getBuildProgress() {
+        return { ...this.buildProgress };
+    }
+    toolPermissions(toolName) {
+        return this.config.toolRegistry?.get(toolName)?.permissions ?? [];
+    }
+    isMutationTool(toolName, args) {
+        const permissions = this.toolPermissions(toolName);
+        if (!permissions.includes('write'))
+            return false;
+        // Generic preview contract used by built-in and third-party mutators.
+        if (args.dryRun === true)
+            return false;
+        // Reuse the registry's argument-aware effect classification. In
+        // particular, `task agent=explore|verify` is parallel-safe/read-only even
+        // though the shared task definition advertises the superset of permissions.
+        return classifyToolConcurrency({
+            toolName,
+            args,
+            permissions,
+            registered: Boolean(this.config.toolRegistry?.get(toolName)),
+        }) === 'exclusive';
+    }
+    recordSuccessfulTool(toolName, args) {
+        const permissions = this.toolPermissions(toolName);
+        if (this.isMutationTool(toolName, args))
+            this.buildProgress.mutationsSucceeded += 1;
+        if (permissions.includes('execute'))
+            this.buildProgress.verificationCalls += 1;
+    }
     /**
      * Member identity fields (memberId + memberName) to merge into every
      * event payload. Returns an empty object when the run is a direct
@@ -356,6 +400,14 @@ export class AgentHarness {
         this.toolCallCounts = new Map();
         this.textToolReentries = 0;
         this.growth = emptyContextGrowthStats();
+        this.buildProgress = {
+            toolCalls: 0,
+            mutationsAttempted: 0,
+            mutationsSucceeded: 0,
+            verificationCalls: 0,
+            recoveries: 0,
+        };
+        const memoryWarning = await this.prepareMemoryContext();
         // Emit agent_start
         const startEvent = createBrainEvent('agent_start', this.sessionId, {
             model: this.config.model,
@@ -364,6 +416,15 @@ export class AgentHarness {
         });
         this.emit(startEvent);
         yield startEvent;
+        if (memoryWarning) {
+            const warning = createBrainEvent('error', this.sessionId, {
+                severity: 'recoverable',
+                message: memoryWarning,
+                code: 'memory_recall_failed',
+            });
+            this.emit(warning);
+            yield warning;
+        }
         // === Initial turn (always runs to preserve Phase 12.x behavior) ===
         // The harness processes the messages buffer that was provided in
         // the config. Backward compat: existing callers expect a single
@@ -375,7 +436,11 @@ export class AgentHarness {
         this.emit(initialMsgStart);
         yield initialMsgStart;
         let initialTurnLength = 0;
-        const initialFinishRef = { value: 'stop' };
+        const initialFinishRef = {
+            value: 'stop',
+            clarificationRequested: false,
+            providerError: false,
+        };
         // Task G.4.3 — capture real provider usage for this turn. The ref
         // is read after runSingleTurn returns and attached to message_end.
         const initialUsageRef = { value: null };
@@ -404,7 +469,7 @@ export class AgentHarness {
         });
         this.emit(initialMsgEnd);
         yield initialMsgEnd;
-        // === Agentic tool-call loop ===
+        // === Agentic tool-call + bounded build-liveness recovery loop ===
         // Soft budget (maxToolLoopIterations) can auto-extend up to the hard cap
         // when the model still wants tools — multi-step work finishes instead of
         // dying mid-task with "budget exhausted". Absolute hard cap still bounds
@@ -414,19 +479,56 @@ export class AgentHarness {
         const hardCap = this.maxToolLoopHardCap;
         let extensions = 0;
         const maxExtensions = 8;
+        const maxBuildRecoveries = Math.max(0, Math.min(10, this.config.buildLiveness?.maxRecoveries ?? 2));
+        const planBuildRecovery = (turn) => {
+            if (!this.config.buildLiveness?.mutationRequired)
+                return null;
+            if (this.buildProgress.mutationsSucceeded > 0)
+                return null;
+            if (turn.value !== 'stop' || turn.clarificationRequested || turn.providerError)
+                return null;
+            if (this.buildProgress.recoveries >= maxBuildRecoveries)
+                return null;
+            this.buildProgress.recoveries += 1;
+            this.config.messages.push({ role: 'user', content: BUILD_LIVENESS_RECOVERY_PROMPT });
+            return {
+                purpose: 'build-recovery',
+                toolChoice: 'required',
+                recoveryAttempt: this.buildProgress.recoveries,
+            };
+        };
+        let lastTurnState = initialFinishRef;
+        let recoveryGeneration = planBuildRecovery(initialFinishRef);
         while (!this.cancelled &&
             !hadError &&
-            toolLoopTurns < softCap &&
-            initialFinishRef.value === 'tool_calls') {
+            toolLoopTurns < hardCap &&
+            (toolLoopTurns < softCap || recoveryGeneration !== null) &&
+            (initialFinishRef.value === 'tool_calls' || recoveryGeneration !== null)) {
             toolLoopTurns++;
+            if (recoveryGeneration) {
+                const recoveryEvent = createBrainEvent('error', this.sessionId, {
+                    severity: 'recoverable',
+                    message: `BUILD liveness recovery ${recoveryGeneration.recoveryAttempt}/${maxBuildRecoveries}: ` +
+                        'no successful mutation observed; continuing instead of completing.',
+                    code: 'build_liveness_recovery',
+                });
+                this.emit(recoveryEvent);
+                yield recoveryEvent;
+            }
             const turnMessageId = crypto.randomUUID();
             const msgStart = createBrainEvent('message_start', this.sessionId, { messageId: turnMessageId, role: 'assistant', ...this.memberFields() });
             this.emit(msgStart);
             yield msgStart;
             let turnLength = 0;
-            const turnFinishRef = { value: 'stop' };
+            const turnFinishRef = {
+                value: 'stop',
+                clarificationRequested: false,
+                providerError: false,
+            };
             const turnUsageRef = { value: null };
-            for await (const ev of this.runSingleTurn(turnMessageId, turnFinishRef, turnUsageRef)) {
+            const generation = recoveryGeneration ?? undefined;
+            recoveryGeneration = null;
+            for await (const ev of this.runSingleTurn(turnMessageId, turnFinishRef, turnUsageRef, generation)) {
                 if (ev.type === 'message_delta') {
                     turnLength += ev.delta.length;
                 }
@@ -449,6 +551,10 @@ export class AgentHarness {
             yield msgEnd;
             // Drive the loop: keep going only if this turn again requested tool calls.
             initialFinishRef.value = turnFinishRef.value;
+            initialFinishRef.clarificationRequested = turnFinishRef.clarificationRequested;
+            initialFinishRef.providerError = turnFinishRef.providerError;
+            lastTurnState = turnFinishRef;
+            recoveryGeneration = planBuildRecovery(turnFinishRef);
             if (hadError || this.cancelled)
                 break;
             // Soft-cap hit but model still wants tools → extend until hard cap.
@@ -486,6 +592,27 @@ export class AgentHarness {
             hitHardCap) {
             yield* this.runFinalAnswerTurn();
         }
+        // A mutate/build task may never report successful completion without a
+        // successful write-permission tool result. Recovery is bounded above, so
+        // an uncooperative provider fails explicitly instead of looping forever.
+        if (!this.cancelled &&
+            !hadError &&
+            this.config.buildLiveness?.mutationRequired &&
+            this.buildProgress.mutationsSucceeded === 0 &&
+            !lastTurnState.clarificationRequested) {
+            hadError = true;
+            const providerFailed = lastTurnState.providerError;
+            const stalled = createBrainEvent('error', this.sessionId, {
+                severity: 'fatal',
+                message: providerFailed
+                    ? 'BUILD provider call failed before any successful on-disk mutation was observed.'
+                    : `BUILD stalled after ${this.buildProgress.recoveries} recovery turn(s): ` +
+                        'the task required an on-disk mutation, but no successful mutation was observed.',
+                code: providerFailed ? 'build_liveness_provider_error' : 'build_liveness_stalled',
+            });
+            this.emit(stalled);
+            yield stalled;
+        }
         // === Queue drain (Task 18.1) ===
         // After the initial turn, drain queued user prompts up to
         // maxQueuedIterations. Each iteration appends the next dequeued
@@ -495,6 +622,8 @@ export class AgentHarness {
         while (turns < this.maxQueuedIterations) {
             if (this.cancelled)
                 break;
+            if (hadError)
+                break;
             if (this.queue.length === 0)
                 break;
             const queuedPrompt = this.dequeueNext();
@@ -511,7 +640,11 @@ export class AgentHarness {
             this.emit(msgStart);
             yield msgStart;
             let turnLength = 0;
-            const turnFinishRef = { value: 'stop' };
+            const turnFinishRef = {
+                value: 'stop',
+                clarificationRequested: false,
+                providerError: false,
+            };
             const turnUsageRef = { value: null };
             for await (const ev of this.runSingleTurn(turnMessageId, turnFinishRef, turnUsageRef)) {
                 if (ev.type === 'message_delta') {
@@ -551,17 +684,68 @@ export class AgentHarness {
         this.emit(agentEnd);
         yield agentEnd;
         this.activeController = null;
+        this.activeMemoryContext = '';
+    }
+    async prepareMemoryContext() {
+        this.activeMemoryContext = '';
+        const memory = this.config.memoryService;
+        if (!memory)
+            return null;
+        const latestUser = [...this.config.messages]
+            .reverse()
+            .find((message) => message.role === 'user')?.content;
+        const query = (this.config.memoryQuery ?? latestUser ?? '').trim();
+        if (!query)
+            return null;
+        try {
+            const context = await memory.buildContext({
+                text: query,
+                useGraph: true,
+                maxChars: this.config.memoryContextChars ?? 2_000,
+                maxMemories: 8,
+            });
+            this.activeMemoryContext = context.text;
+            return null;
+        }
+        catch (error) {
+            return `[memory] recall failed; continuing without memory (${error instanceof Error ? error.message : String(error)}).`;
+        }
+    }
+    /** Build a provider-only view with memory after the stable system prefix. */
+    messagesForProvider() {
+        let messages = this.config.messages;
+        let prefixEnd = 0;
+        if (this.activeMemoryContext) {
+            while (prefixEnd < messages.length && messages[prefixEnd]?.role === 'system') {
+                prefixEnd += 1;
+            }
+            messages = [
+                ...messages.slice(0, prefixEnd),
+                { role: 'system', content: this.activeMemoryContext },
+                ...messages.slice(prefixEnd),
+            ];
+        }
+        if (!this.config.requestTail)
+            return messages;
+        try {
+            const tail = this.config.requestTail();
+            return tail.length > 0 ? [...messages, ...tail] : messages;
+        }
+        catch {
+            // Runtime status is advisory — never fail a provider request for it.
+            return messages;
+        }
     }
     /**
      * v1.36.0: capture a deterministic snapshot of the routed request just
      * before it goes out. Never throws into the request path.
      */
-    emitSnapshot(tools, generation) {
+    emitSnapshot(tools, generation, messages = this.messagesForProvider()) {
         if (!this.config.onRequestSnapshot)
             return;
         try {
             this.config.onRequestSnapshot(createRoutedRequestSnapshot({
-                messages: this.config.messages,
+                messages,
                 model: this.config.model,
                 provider: this.config.provider,
                 tools,
@@ -586,16 +770,19 @@ export class AgentHarness {
      * Extracted from the original monolithic `run()` body to enable
      * the queue-draining loop in Task 18.1.
      */
-    async *runSingleTurn(messageId, finishRef, usageRef) {
+    async *runSingleTurn(messageId, finishRef, usageRef, generation) {
         try {
-            this.emitSnapshot(this.config.tools);
-            recordRequest(this.growth, this.config.messages);
+            const requestMessages = this.messagesForProvider();
+            this.emitSnapshot(this.config.tools, generation, requestMessages);
+            recordRequest(this.growth, requestMessages);
             const stream = this.config.providerStream({
-                messages: this.config.messages,
+                messages: requestMessages,
                 model: this.config.model,
                 provider: this.config.provider,
                 tools: this.config.tools,
                 signal: this.activeController?.signal,
+                conversationId: this.sessionId,
+                generation,
             });
             // Per-turn tool call counter (Task G.2). Reset on every turn so
             // queue-drained turns don't accumulate across prompts.
@@ -698,6 +885,10 @@ export class AgentHarness {
                 }
                 else if (delta.kind === 'tool_call') {
                     toolCallsThisTurn++;
+                    this.buildProgress.toolCalls += 1;
+                    if (this.isMutationTool(delta.toolName, delta.args)) {
+                        this.buildProgress.mutationsAttempted += 1;
+                    }
                     // Record this tool call so the assistant message (appended after the
                     // turn) carries the full tool_calls list the model emitted.
                     turnToolCalls.push({ id: delta.toolCallId, name: delta.toolName, args: delta.args });
@@ -762,6 +953,12 @@ export class AgentHarness {
                                 this.toolCallCache.set(item.cacheKey, item.content);
                             }
                         }
+                        for (let i = 0; i < executed.length; i++) {
+                            const item = executed[i];
+                            const pending = pendingNativeTools[i];
+                            if (!item.isError)
+                                this.recordSuccessfulTool(pending.toolName, pending.args);
+                        }
                         pendingNativeTools.length = 0;
                     }
                     // Clarification pause: if the model posed a ---QUESTION--- with choices,
@@ -771,6 +968,7 @@ export class AgentHarness {
                         /"choices"\s*:\s*\[/.test(turnText);
                     if (clarificationPause) {
                         finishRef.value = 'stop';
+                        finishRef.clarificationRequested = true;
                     }
                     // Fallback text-format tools: ---TOOLS--- JSON, MiniMax invoke XML,
                     // and garbled invoke dumps. Run any text tools not already executed
@@ -812,6 +1010,10 @@ export class AgentHarness {
                             if (typeof maxToolCalls === 'number' && toolCallsThisTurn + 1 > maxToolCalls)
                                 break;
                             toolCallsThisTurn++;
+                            this.buildProgress.toolCalls += 1;
+                            if (this.isMutationTool(tt.name, tt.args)) {
+                                this.buildProgress.mutationsAttempted += 1;
+                            }
                             const toolCallId = `text-${crypto.randomUUID().slice(0, 8)}`;
                             turnToolCalls.push({ id: toolCallId, name: tt.name, args: tt.args });
                             const startEv = createBrainEvent('tool_execution_start', this.sessionId, {
@@ -885,6 +1087,8 @@ export class AgentHarness {
                             this.emit(endEv);
                             yield endEv;
                             turnToolResults.push({ toolCallId, content: resultStr });
+                            if (!isError)
+                                this.recordSuccessfulTool(tt.name, tt.args);
                             executedAny = true;
                         }
                         if (executedAny) {
@@ -957,6 +1161,7 @@ export class AgentHarness {
                     break;
                 }
                 else if (delta.kind === 'error') {
+                    finishRef.providerError = true;
                     const errEvent = createBrainEvent('error', this.sessionId, {
                         severity: 'recoverable',
                         message: delta.message,
@@ -977,6 +1182,7 @@ export class AgentHarness {
             }
         }
         catch (err) {
+            finishRef.providerError = true;
             const errorMessage = err instanceof Error ? err.message : String(err);
             const errEvent = createBrainEvent('error', this.sessionId, {
                 severity: 'recoverable',
@@ -1024,21 +1230,27 @@ export class AgentHarness {
             content: '[system] Hard tool-iteration ceiling reached. Stop calling tools and give a clear status: what is DONE, what remains, and the exact next steps. Use what you already gathered. Do not apologize for the tools.',
         });
         let totalLength = 0;
-        const finishRef = { value: 'stop' };
+        const finishRef = {
+            value: 'stop',
+            clarificationRequested: false,
+            providerError: false,
+        };
         const usageRef = { value: null };
         // Temporarily drop tools for this call by building a no-tools provider
         // invocation. We re-enter runSingleTurn but with an empty tools list via
         // a throwaway config override is not possible (config is readonly), so we
         // call the providerStream directly with tools: [].
-        recordRequest(this.growth, this.config.messages);
+        const requestMessages = this.messagesForProvider();
+        recordRequest(this.growth, requestMessages);
         try {
-            this.emitSnapshot([]);
+            this.emitSnapshot([], undefined, requestMessages);
             const stream = this.config.providerStream({
-                messages: this.config.messages,
+                messages: requestMessages,
                 model: this.config.model,
                 provider: this.config.provider,
                 tools: [],
                 signal: this.activeController?.signal,
+                conversationId: this.sessionId,
             });
             for await (const delta of stream) {
                 if (this.cancelled)