@caupulican/pi-adaptative 0.81.8 → 0.81.12

package/dist/core/agent-session.js

@@ -2,7 +2,8 @@ import { readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { classifyFailure, compactToolResultDetailsForRetention, computeRetryDelayMs, createCustomMessage, DEFAULT_RETRY_POLICY, RetryController, sleepAbortable, withStreamIdleWatchdog, } from "@caupulican/pi-agent-core";
 import { calculateContextTokens, compact, createDeterministicCompaction, estimateContextTokens, getLatestCompactionEntry, prepareCompaction, runCompactionLoop, shouldCompact, } from "@caupulican/pi-agent-core/node";
-import { cleanupSessionResources, isContextOverflow, streamSimple } from "@caupulican/pi-ai";
+import { cleanupSessionResources, formatToolRepairStandingRule, generateTextToolProtocolPrimer, isContextOverflow, parseTextToolCalls, streamSimple, } from "@caupulican/pi-ai";
+import { Type } from "typebox";
 import { getAgentDir } from "../config.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
@@ -28,6 +29,7 @@ import { MemoryController } from "./memory-controller.js";
 import { deriveModelCapabilityProfile, filterToolNamesForCapability, } from "./model-capability.js";
 import { formatModelRouterModel, ModelRouterController } from "./model-router-controller.js";
 import { ModelSelectionController } from "./model-selection-controller.js";
+import { ModelAdaptationStore } from "./models/adaptation-store.js";
 import { ProfileFilterController } from "./profile-filter-controller.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { ReflectionController } from "./reflection-controller.js";
@@ -39,6 +41,8 @@ import { SessionAnalytics } from "./session-analytics.js";
 import { SessionTreeNavigator } from "./session-tree-navigator.js";
 import { SystemPromptBuilder } from "./system-prompt-builder.js";
 import { ToolGateController } from "./tool-gate-controller.js";
+import { formatToolRepairHealthReport } from "./tool-repair-health.js";
+import { resolveCurrentToolRepairSettings } from "./tool-repair-settings.js";
 // ============================================================================
 // Stream-idle watchdog wiring
 // ============================================================================
@@ -52,6 +56,15 @@ import { ToolGateController } from "./tool-gate-controller.js";
  * key stable regardless of how many times this module is evaluated.
  */
 const RAW_STREAM_MARKER = Symbol.for("pi.rawStreamSimple");
+const MODEL_ADAPTATION_REPAIR_THRESHOLD = 3;
+const TEXT_TOOL_PROTOCOL_VERSION = 1;
+const TEXT_TOOL_PROTOCOL_TRIALS_PER_VARIANT = 2;
+const TEXT_TOOL_PROTOCOL_VARIANTS = ["tool-tag", "tool-call", "fenced-json"];
+const TEXT_TOOL_PROTOCOL_ECHO_TOOL = {
+    name: "echo",
+    description: "Echo calibration data",
+    parameters: Type.Object({ data: Type.String() }),
+};
 /** Test-only override of the stream-idle bounds. Read per-request by the wiring's resolver. */
 let streamIdleOptionsOverride;
 /**
@@ -133,6 +146,8 @@ export class AgentSession {
     _agentDir;
     _collectWorkspaceSources;
     _localRuntimeController;
+    _modelAdaptationStore;
+    _repairModeSessionCounts = new Map();
     /** Assembles the session's base system prompt from live session state (see
      * system-prompt-builder.ts); owns the paired _baseSystemPromptOptions. */
     _systemPromptBuilder;
@@ -242,6 +257,8 @@ export class AgentSession {
         this._customTools = config.customTools ?? [];
         this._cwd = config.cwd;
         this._agentDir = config.agentDir ?? getAgentDir();
+        this._modelAdaptationStore = ModelAdaptationStore.forAgentDir(this._agentDir);
+        this._applyToolRepairLayerSettings();
         this._collectWorkspaceSources = config.collectWorkspaceSources ?? collectWorkspaceSources;
         this._localRuntimeController = new LocalRuntimeController({
             agentDir: this._agentDir,
@@ -260,6 +277,7 @@ export class AgentSession {
             hasTool: (name) => this._runtimeBuilder.hasTool(name),
             getToolPromptSnippet: (name) => this._runtimeBuilder.getToolPromptSnippet(name),
             getToolPromptGuidelines: (name) => this._runtimeBuilder.getToolPromptGuidelines(name),
+            getModelAdaptationRules: () => this._getModelAdaptationRulesForPrompt(),
             getActiveExtensions: () => this._extensionRunner.activeExtensions,
         });
         this._autonomyTelemetry = new AutonomyTelemetry({
@@ -479,6 +497,14 @@ export class AgentSession {
             getSettingsManager: () => this.settingsManager,
             getToolDefinition: (name) => this.getToolDefinition(name),
         });
+        const previousToolArgumentValidation = this.agent.onToolArgumentValidation;
+        this.agent.onToolArgumentValidation = (event) => {
+            const taggedEvent = this._tagModelAdaptationRuleTeaching(event);
+            previousToolArgumentValidation?.(taggedEvent);
+            this._analytics.recordToolArgumentValidation(taggedEvent);
+            this._recordToolValidationBounce(taggedEvent);
+            this._handleModelAdaptationTelemetry(taggedEvent);
+        };
         this._treeNavigator = new SessionTreeNavigator({
             getSessionManager: () => this.sessionManager,
             getModel: () => this.model,
@@ -757,6 +783,169 @@ export class AgentSession {
             tools: this.agent.state.tools.slice(),
         };
     }
+    _modelAdaptationKeyFor(model) {
+        return model ? formatModelRouterModel(model) : undefined;
+    }
+    _toolRepairSettings() {
+        return resolveCurrentToolRepairSettings(this.settingsManager.settings);
+    }
+    _applyToolRepairLayerSettings() {
+        const settings = this._toolRepairSettings();
+        this.agent.toolArgumentRepairEnabled = settings.repair;
+        this.agent.toolArgumentTeachEnabled = settings.teach;
+    }
+    _getModelAdaptationRulesForPrompt() {
+        if (!this._toolRepairSettings().teach)
+            return [];
+        const modelKey = this._modelAdaptationKeyFor(this.agent.state.model);
+        return modelKey ? this._modelAdaptationStore.get(modelKey).rules : [];
+    }
+    _textProtocolFlag(model) {
+        const override = this._toolRepairSettings().textProtocol;
+        return override ?? model?.textToolCallProtocol === true;
+    }
+    _textProtocolCalibrationContext(variant, token) {
+        const primer = generateTextToolProtocolPrimer([TEXT_TOOL_PROTOCOL_ECHO_TOOL], { variant });
+        const instruction = `Text tool protocol calibration trial. Using the protocol above, call echo with data exactly "${token}". Output only the tool-call envelope.`;
+        return {
+            systemPrompt: `${primer}\n\n${instruction}`,
+            messages: [{ role: "user", content: [{ type: "text", text: instruction }], timestamp: Date.now() }],
+            tools: [TEXT_TOOL_PROTOCOL_ECHO_TOOL],
+        };
+    }
+    async _runTextProtocolTrial(model, variant, token) {
+        const stream = await this.agent.streamFn(model, this._textProtocolCalibrationContext(variant, token), {
+            textToolCallProtocol: false,
+            maxRetries: 0,
+        });
+        const message = await stream.result();
+        if (message.content.some((block) => block.type === "toolCall" && block.name === "echo" && block.arguments.data === token)) {
+            return true;
+        }
+        const text = message.content
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("\n")
+            .trim();
+        if (!text)
+            return false;
+        const parsed = parseTextToolCalls(text, [TEXT_TOOL_PROTOCOL_ECHO_TOOL]);
+        return parsed.calls.some((call) => call.name === "echo" && call.arguments.data === token);
+    }
+    async _ensureTextToolProtocolForActiveModel() {
+        const model = this.agent.state.model;
+        if (!this._textProtocolFlag(model)) {
+            this.agent.textToolCallProtocol = undefined;
+            return;
+        }
+        const modelKey = this._modelAdaptationKeyFor(model);
+        if (!modelKey) {
+            this.agent.textToolCallProtocol = true;
+            return;
+        }
+        const profile = this._modelAdaptationStore.get(modelKey);
+        if (profile.protocol?.version === TEXT_TOOL_PROTOCOL_VERSION) {
+            this.agent.textToolCallProtocol = { variant: profile.protocol.variant };
+            return;
+        }
+        for (const variant of TEXT_TOOL_PROTOCOL_VARIANTS) {
+            let passed = true;
+            for (let trial = 0; trial < TEXT_TOOL_PROTOCOL_TRIALS_PER_VARIANT; trial++) {
+                const ok = await this._runTextProtocolTrial(model, variant, `pi-calibration-${trial + 1}`);
+                if (!ok) {
+                    passed = false;
+                    break;
+                }
+            }
+            if (passed) {
+                const calibratedAt = new Date().toISOString();
+                this._modelAdaptationStore.setProtocol(modelKey, { version: TEXT_TOOL_PROTOCOL_VERSION, variant, calibratedAt }, calibratedAt);
+                this.agent.textToolCallProtocol = { variant };
+                return;
+            }
+        }
+        this.agent.textToolCallProtocol = undefined;
+        throw new Error(`Model ${modelKey} cannot follow the text tool protocol after calibration.`);
+    }
+    _recordToolValidationBounce(event) {
+        if (event.outcome !== "bounced" || !event.failureShape || event.failureShape.length === 0)
+            return;
+        this._failureCorpus.recordToolValidation({
+            provider: event.provider ?? this.agent.state.model?.provider,
+            modelId: event.model ?? this.agent.state.model?.id,
+            tool: event.tool,
+            failureModes: event.failureModes,
+            shape: event.failureShape,
+            errorKeywords: event.errorKeywords,
+        });
+    }
+    _tagModelAdaptationRuleTeaching(event) {
+        if (!this._toolRepairSettings().teach || event.taught !== "none")
+            return event;
+        const modelKey = event.provider && event.model
+            ? `${event.provider}/${event.model}`
+            : this._modelAdaptationKeyFor(this.agent.state.model);
+        if (!modelKey)
+            return event;
+        try {
+            const rules = this._modelAdaptationStore.get(modelKey).rules;
+            const modes = new Set([...event.failureModes, ...event.repairsApplied]);
+            if (rules.some((rule) => modes.has(rule.mode))) {
+                return { ...event, taught: "rule" };
+            }
+        }
+        catch {
+            // Adaptation telemetry tagging is best-effort; leave the original event unchanged.
+        }
+        return event;
+    }
+    _repairSessionCount(modelKey, mode) {
+        const key = `${modelKey}\0${mode}`;
+        const count = (this._repairModeSessionCounts.get(key) ?? 0) + 1;
+        this._repairModeSessionCounts.set(key, count);
+        return count;
+    }
+    _handleModelAdaptationTelemetry(event) {
+        if (!this._toolRepairSettings().teach || event.outcome !== "repaired" || event.repairsApplied.length === 0)
+            return;
+        const modelKey = event.provider && event.model
+            ? `${event.provider}/${event.model}`
+            : this._modelAdaptationKeyFor(this.agent.state.model);
+        if (!modelKey)
+            return;
+        try {
+            for (const mode of [...new Set(event.repairsApplied)]) {
+                const profile = this._modelAdaptationStore.get(modelKey);
+                const stats = profile.teachStats[mode] ?? { taught: 0, recurrenceBefore: 0, recurrenceAfter: 0 };
+                if (profile.rules.some((rule) => rule.mode === mode)) {
+                    this._modelAdaptationStore.markRuleFired(modelKey, mode);
+                    this._modelAdaptationStore.setTeachStats(modelKey, mode, {
+                        ...stats,
+                        recurrenceAfter: stats.recurrenceAfter + 1,
+                    });
+                    continue;
+                }
+                const recurrenceBefore = stats.recurrenceBefore + 1;
+                this._modelAdaptationStore.setTeachStats(modelKey, mode, { ...stats, recurrenceBefore });
+                const sessionCount = this._repairSessionCount(modelKey, mode);
+                if (sessionCount >= MODEL_ADAPTATION_REPAIR_THRESHOLD ||
+                    recurrenceBefore >= MODEL_ADAPTATION_REPAIR_THRESHOLD) {
+                    this._modelAdaptationStore.addRule(modelKey, {
+                        mode,
+                        text: formatToolRepairStandingRule(mode),
+                    });
+                    this._modelAdaptationStore.setTeachStats(modelKey, mode, {
+                        ...stats,
+                        taught: stats.taught + 1,
+                        recurrenceBefore,
+                    });
+                }
+            }
+        }
+        catch {
+            // Model adaptation is best-effort; failed telemetry persistence must not affect the turn.
+        }
+    }
     /** Tool-build call-site delegation to {@link ContextPipeline.getToolArtifactStore}. */
     _getToolArtifactStore() {
         return this._pipeline.getToolArtifactStore();
@@ -896,6 +1085,12 @@ export class AgentSession {
     formatContextCompositionDashboard() {
         return formatContextCompositionDashboard(this.getContextCompositionReport());
     }
+    formatToolRepairHealthReport() {
+        return formatToolRepairHealthReport(this._modelAdaptationStore);
+    }
+    removeToolRepairRule(model, mode) {
+        return this._modelAdaptationStore.removeRule(model, mode);
+    }
     /** Curation status for diagnostics/dashboard: settings, live telemetry, last refusal reason. */
     /** Curation status for diagnostics/dashboard (delegates to {@link ContextPipeline.getContextCurationStatus}). */
     getContextCurationStatus() {
@@ -1492,6 +1687,7 @@ export class AgentSession {
         try {
             const maxGoalLoopRounds = this.settingsManager.getAutonomySettings().maxStallTurns;
             this.agent.maxStallTurns = maxGoalLoopRounds;
+            await this._ensureTextToolProtocolForActiveModel();
             let goalLoopRounds = 1;
             await this.agent.prompt(messages);
             while ((maxGoalLoopRounds === 0 || goalLoopRounds < maxGoalLoopRounds) && (await this._handlePostAgentRun())) {
@@ -1587,6 +1783,7 @@ export class AgentSession {
         return this._promptUnserialized(text, options);
     }
     async _promptUnserialized(text, options) {
+        this._applyToolRepairLayerSettings();
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const processSlashCommands = options?.processSlashCommands ?? expandPromptTemplates;
         const preflightResult = options?.preflightResult;