@botbotgo/agent-harness 0.0.297 → 0.0.299

package/dist/runtime/harness/run/stream-run.js

@@ -1,9 +1,162 @@
 import { AGENT_INTERRUPT_SENTINEL_PREFIX, RuntimeOperationTimeoutError } from "../../agent-runtime-adapter.js";
+import { buildRequestPlanState, summarizeBuiltinWriteTodosArgs } from "../../adapter/runtime-adapter-support.js";
 import { renderRuntimeFailure, renderToolFailure } from "../../support/harness-support.js";
 import { getBindingPrimaryModel } from "../../support/compiled-binding.js";
 import { createContentBlocksItem, createToolResultKey, } from "../events/streaming.js";
 import { projectRuntimeSurfaceFromSingleUpstreamEvent } from "./inspection.js";
 import { formatAgentName } from "../../../utils/agent-display.js";
+function createInitialPlanState(sessionId, requestId, updatedAt) {
+    return {
+        sessionId,
+        requestId,
+        version: 0,
+        updatedAt,
+        items: [],
+        summary: {
+            total: 0,
+            pending: 0,
+            inProgress: 0,
+            completed: 0,
+            failed: 0,
+            cancelled: 0,
+            blocked: 0,
+        },
+    };
+}
+function getPlanStateFromToolResult(input) {
+    if (typeof input.output !== "object" || input.output === null) {
+        return null;
+    }
+    const summary = input.output.summary;
+    if (summary && typeof summary === "object" && Array.isArray(summary.items)) {
+        const typedSummary = summary;
+        if (typedSummary.summary && typeof typedSummary.summary === "object") {
+            return {
+                sessionId: input.sessionId,
+                requestId: input.requestId,
+                version: input.version,
+                updatedAt: input.updatedAt,
+                items: typedSummary.items,
+                summary: typedSummary.summary,
+            };
+        }
+    }
+    const snapshot = summarizeBuiltinWriteTodosArgs(input.output);
+    return buildRequestPlanState({
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        updatedAt: input.updatedAt,
+        version: input.version,
+        snapshot,
+    });
+}
+function getStructuredPlanStateFromToolResult(input) {
+    if (typeof input.output !== "object" || input.output === null) {
+        return null;
+    }
+    const summary = input.output.summary;
+    if (!summary || typeof summary !== "object" || !Array.isArray(summary.items)) {
+        return null;
+    }
+    const typedSummary = summary;
+    if (!typedSummary.summary || typeof typedSummary.summary !== "object") {
+        return null;
+    }
+    return {
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        version: input.version,
+        updatedAt: input.updatedAt,
+        items: typedSummary.items,
+        summary: typedSummary.summary,
+    };
+}
+function buildPlanStateSignature(planState) {
+    return JSON.stringify({
+        items: planState.items,
+        summary: planState.summary,
+    });
+}
+function countStructuredTodoIds(items) {
+    return items.filter((item) => typeof item.id === "string" && item.id.length > 0).length;
+}
+function shouldEmitPlanState(currentPlanState, nextPlanState) {
+    if (!currentPlanState || currentPlanState.items.length === 0) {
+        return true;
+    }
+    if (nextPlanState.items.length === 0) {
+        return false;
+    }
+    const currentStructuredIds = countStructuredTodoIds(currentPlanState.items);
+    const nextStructuredIds = countStructuredTodoIds(nextPlanState.items);
+    if (currentStructuredIds > 0
+        && nextStructuredIds === 0
+        && nextPlanState.items.length < currentPlanState.items.length) {
+        return false;
+    }
+    return true;
+}
+function extractTodosArray(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const record = value;
+    if (Array.isArray(record.todos)) {
+        return record.todos;
+    }
+    if (typeof record.output === "object" && record.output !== null) {
+        const nested = record.output.todos;
+        if (Array.isArray(nested)) {
+            return nested;
+        }
+    }
+    return null;
+}
+function getPlanStateFromUpstreamEvent(input) {
+    if (typeof input.event !== "object" || input.event === null) {
+        return null;
+    }
+    const typed = input.event;
+    const todos = extractTodosArray(typed.data?.output)
+        ?? extractTodosArray(typed.data?.chunk);
+    if (!todos) {
+        return null;
+    }
+    return buildRequestPlanState({
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        updatedAt: input.updatedAt,
+        version: input.version,
+        snapshot: summarizeBuiltinWriteTodosArgs({ todos }),
+    });
+}
+function getLatestPlanStateFromExecutedToolResults(input) {
+    const executedToolResults = Array.isArray(input.metadata?.executedToolResults)
+        ? input.metadata.executedToolResults
+        : [];
+    for (const latest of [...executedToolResults].reverse()) {
+        const structured = getStructuredPlanStateFromToolResult({
+            sessionId: input.sessionId,
+            requestId: input.requestId,
+            output: latest.output,
+            version: input.version,
+            updatedAt: input.updatedAt,
+        });
+        if (structured) {
+            return structured;
+        }
+        if (latest.toolName === "write_todos") {
+            return getPlanStateFromToolResult({
+                sessionId: input.sessionId,
+                requestId: input.requestId,
+                output: latest.output,
+                version: input.version,
+                updatedAt: input.updatedAt,
+            });
+        }
+    }
+    return null;
+}
 function normalizeStreamChunk(chunk) {
     if (typeof chunk === "string") {
         if (chunk.startsWith(AGENT_INTERRUPT_SENTINEL_PREFIX)) {
@@ -11,6 +164,9 @@ function normalizeStreamChunk(chunk) {
         }
         return { kind: "content", content: chunk };
     }
+    if (chunk.kind === "commentary") {
+        return { kind: "commentary", content: chunk.content ?? "" };
+    }
     if (chunk.kind === "upstream-event") {
         return { kind: "upstream-event", event: (chunk.event ?? {}) };
     }
@@ -28,8 +184,117 @@ function normalizeStreamChunk(chunk) {
             isError: chunk.isError,
         };
     }
+    if (chunk.kind === "profile") {
+        return {
+            kind: "profile",
+            step: chunk.step,
+        };
+    }
     return { kind: "content", content: chunk.content ?? "" };
 }
+function normalizeCommentaryText(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function ensureCommentarySentence(value) {
+    const normalized = normalizeCommentaryText(value);
+    if (!normalized) {
+        return normalized;
+    }
+    return /[.!?]$/.test(normalized) ? normalized : `${normalized}.`;
+}
+function summarizePlanState(planState) {
+    if (planState.summary.total <= 0) {
+        return null;
+    }
+    const counts = [
+        planState.summary.inProgress > 0 ? `${planState.summary.inProgress} in progress` : "",
+        planState.summary.pending > 0 ? `${planState.summary.pending} pending` : "",
+        planState.summary.completed > 0 ? `${planState.summary.completed} completed` : "",
+        planState.summary.blocked > 0 ? `${planState.summary.blocked} blocked` : "",
+        planState.summary.failed > 0 ? `${planState.summary.failed} failed` : "",
+    ].filter((value) => value.length > 0);
+    if (counts.length === 0) {
+        counts.push(`${planState.summary.total} total`);
+    }
+    return `Plan updated: ${counts.join(", ")}.`;
+}
+function createSurfaceCommentary(surfaceItem) {
+    const name = normalizeCommentaryText(surfaceItem.name);
+    if (!name) {
+        return null;
+    }
+    if (surfaceItem.kind === "tool") {
+        if (surfaceItem.status === "started") {
+            return `Running tool ${name}.`;
+        }
+        if (surfaceItem.status === "completed") {
+            return `Tool ${name} completed.`;
+        }
+        if (surfaceItem.status === "failed") {
+            return `Tool ${name} failed.`;
+        }
+        return null;
+    }
+    if (surfaceItem.kind === "skill") {
+        if (surfaceItem.status === "started") {
+            return `Applying skill ${name}.`;
+        }
+        if (surfaceItem.status === "completed") {
+            return `Skill ${name} applied.`;
+        }
+        if (surfaceItem.status === "failed") {
+            return `Skill ${name} failed.`;
+        }
+        return null;
+    }
+    if (surfaceItem.kind === "agent") {
+        if (surfaceItem.status === "started") {
+            return `Delegating work to ${name}.`;
+        }
+        if (surfaceItem.status === "completed") {
+            return `Delegation to ${name} completed.`;
+        }
+        if (surfaceItem.status === "failed") {
+            return `Delegation to ${name} failed.`;
+        }
+        return null;
+    }
+    if (surfaceItem.kind === "llm") {
+        if (surfaceItem.status === "started") {
+            return `Running model ${name}.`;
+        }
+        if (surfaceItem.status === "completed") {
+            return `Model ${name} completed.`;
+        }
+        if (surfaceItem.status === "failed") {
+            return `Model ${name} failed.`;
+        }
+        return null;
+    }
+    if (surfaceItem.kind === "memory") {
+        if (surfaceItem.status === "started") {
+            return `Checking memory ${name}.`;
+        }
+        if (surfaceItem.status === "completed") {
+            return ensureCommentarySentence(`Finished checking memory ${name}`);
+        }
+        if (surfaceItem.status === "failed") {
+            return `Memory ${name} failed.`;
+        }
+        return null;
+    }
+    return null;
+}
+function createProfileStepCommentary(step) {
+    const name = normalizeCommentaryText(step.name);
+    if (!name || step.status !== "started") {
+        return null;
+    }
+    if (step.kind === "memory") {
+        return `Checking memory ${name}.`;
+    }
+    return null;
+}
 function isOpenAICompatibleStreamingCompatibilityError(binding, error) {
     const primaryModel = getBindingPrimaryModel(binding);
     if (primaryModel?.provider !== "openai-compatible") {
@@ -38,33 +303,107 @@ function isOpenAICompatibleStreamingCompatibilityError(binding, error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.toLowerCase().includes("received empty response from chat model call");
 }
+function createRuntimeMemoryRecallSteps(sessionId, requestId, items) {
+    if (items.length === 0) {
+        return [];
+    }
+    const timestamp = new Date().toISOString();
+    const scopes = Array.from(new Set(items.map((item) => item.scope)));
+    const primaryScope = scopes.length === 1 ? scopes[0] : "mixed";
+    const primarySummary = items[0]?.summary;
+    const name = scopes.length === 1 ? `durable ${primaryScope} memory` : "durable memory";
+    const detail = {
+        source: "runtime-durable-memory",
+        scope: primaryScope,
+        scopes,
+        count: items.length,
+        summaries: items.map((item) => item.summary).slice(0, 5),
+        ...(primarySummary ? { summary: primarySummary } : {}),
+    };
+    const startedStep = {
+        id: `runtime-memory-recall:${requestId}:started`,
+        kind: "memory",
+        name,
+        action: "recall",
+        status: "started",
+        occurredAt: timestamp,
+        detail,
+    };
+    const completedStep = {
+        ...startedStep,
+        id: `runtime-memory-recall:${requestId}:completed`,
+        status: "completed",
+    };
+    return [
+        {
+            type: "profile-step",
+            sessionId,
+            requestId,
+            step: startedStep,
+        },
+        {
+            type: "profile-step",
+            sessionId,
+            requestId,
+            step: completedStep,
+        },
+    ];
+}
 export async function* streamHarnessRun(options) {
     const priorHistoryPromise = Promise.resolve(options.isNewSession ? [] : undefined).then((historyHint) => historyHint ?? options.loadPriorHistory(options.sessionId, options.requestId));
     yield { type: "event", event: await options.requestCreatedEventPromise };
+    let planStateVersion = 0;
+    let lastPlanStateSignature;
+    let currentPlanState = null;
     let releaseRunSlot = async () => undefined;
     let emitted = false;
     let streamActivityObserved = false;
     let nonUpstreamStreamActivityObserved = false;
+    let assistantOutput = "";
     let currentAgentId = options.selectedAgentId;
     let currentAgentName = formatAgentName(options.selectedAgentId);
     let delegationChain = [options.selectedAgentId];
     let upstreamEventOrdinal = 0;
     let syntheticFallback;
+    const emittedCommentary = new Set();
+    const emitCommentary = function* (content) {
+        const normalized = normalizeCommentaryText(content);
+        if (!normalized || emittedCommentary.has(normalized)) {
+            return;
+        }
+        emittedCommentary.add(normalized);
+        yield {
+            type: "commentary",
+            sessionId: options.sessionId,
+            requestId: options.requestId,
+            agentId: currentAgentId,
+            content: normalized,
+        };
+    };
     try {
         const [priorHistory, acquiredReleaseRunSlot] = await Promise.all([
             priorHistoryPromise,
             options.releaseRequestSlotPromise,
         ]).then(([loadedPriorHistory, resolvedReleaseRunSlot]) => [loadedPriorHistory, resolvedReleaseRunSlot]);
         releaseRunSlot = acquiredReleaseRunSlot;
-        let assistantOutput = "";
         const toolErrors = [];
         let lastToolResultKey = null;
+        const recalledMemories = options.invocation.memoryRecall?.items ?? [];
+        for (const item of createRuntimeMemoryRecallSteps(options.sessionId, options.requestId, recalledMemories)) {
+            yield item;
+            if (item.type === "profile-step") {
+                const commentary = createProfileStepCommentary(item.step);
+                if (commentary) {
+                    yield* emitCommentary(commentary);
+                }
+            }
+        }
         for await (const rawChunk of options.stream(options.binding, options.input, options.sessionId, priorHistory, {
             context: options.invocation.context,
             state: options.invocation.state,
             files: options.invocation.files,
             requestId: options.requestId,
-            memoryContext: options.invocation.memoryContext,
+            memoryContext: options.invocation.memoryRecall?.prompt,
         })) {
             if (!rawChunk) {
                 continue;
@@ -72,6 +411,32 @@ export async function* streamHarnessRun(options) {
             streamActivityObserved = true;
             const normalizedChunk = normalizeStreamChunk(rawChunk);
             if (normalizedChunk.kind === "upstream-event") {
+                const upstreamPlanState = getPlanStateFromUpstreamEvent({
+                    sessionId: options.sessionId,
+                    requestId: options.requestId,
+                    event: normalizedChunk.event,
+                    version: planStateVersion + 1,
+                    updatedAt: new Date().toISOString(),
+                });
+                if (upstreamPlanState) {
+                    const signature = buildPlanStateSignature(upstreamPlanState);
+                    if (signature !== lastPlanStateSignature && shouldEmitPlanState(currentPlanState, upstreamPlanState)) {
+                        planStateVersion = upstreamPlanState.version;
+                        lastPlanStateSignature = signature;
+                        currentPlanState = upstreamPlanState;
+                        yield {
+                            type: "plan-state",
+                            sessionId: options.sessionId,
+                            requestId: options.requestId,
+                            agentId: currentAgentId,
+                            planState: upstreamPlanState,
+                        };
+                        const commentary = summarizePlanState(upstreamPlanState);
+                        if (commentary) {
+                            yield* emitCommentary(commentary);
+                        }
+                    }
+                }
                 upstreamEventOrdinal += 1;
                 const projectionBinding = options.getBinding(currentAgentId) ?? options.binding;
                 const surfaceProjection = projectRuntimeSurfaceFromSingleUpstreamEvent({
@@ -121,6 +486,10 @@ export async function* streamHarnessRun(options) {
                         surfaceItem,
                         event: normalizedChunk.event,
                     };
+                    const commentary = createSurfaceCommentary(surfaceItem);
+                    if (commentary) {
+                        yield* emitCommentary(commentary);
+                    }
                 }
                 continue;
             }
@@ -150,9 +519,26 @@ export async function* streamHarnessRun(options) {
                 };
                 return;
             }
+            if (normalizedChunk.kind === "commentary") {
+                yield* emitCommentary(normalizedChunk.content);
+                continue;
+            }
             if (normalizedChunk.kind === "reasoning") {
                 continue;
             }
+            if (normalizedChunk.kind === "profile") {
+                yield {
+                    type: "profile-step",
+                    sessionId: options.sessionId,
+                    requestId: options.requestId,
+                    step: normalizedChunk.step,
+                };
+                const commentary = createProfileStepCommentary(normalizedChunk.step);
+                if (commentary) {
+                    yield* emitCommentary(commentary);
+                }
+                continue;
+            }
             if (normalizedChunk.kind === "tool-result") {
                 const toolResultKey = createToolResultKey(normalizedChunk.toolName, normalizedChunk.output, normalizedChunk.isError);
                 if (toolResultKey === lastToolResultKey) {
@@ -171,6 +557,39 @@ export async function* streamHarnessRun(options) {
                     output: normalizedChunk.output,
                     isError: normalizedChunk.isError,
                 };
+                const planState = normalizedChunk.toolName === "write_todos"
+                    ? getPlanStateFromToolResult({
+                        sessionId: options.sessionId,
+                        requestId: options.requestId,
+                        output: normalizedChunk.output,
+                        version: ++planStateVersion,
+                        updatedAt: new Date().toISOString(),
+                    })
+                    : getStructuredPlanStateFromToolResult({
+                        sessionId: options.sessionId,
+                        requestId: options.requestId,
+                        output: normalizedChunk.output,
+                        version: ++planStateVersion,
+                        updatedAt: new Date().toISOString(),
+                    });
+                if (planState) {
+                    const signature = buildPlanStateSignature(planState);
+                    if (signature !== lastPlanStateSignature && shouldEmitPlanState(currentPlanState, planState)) {
+                        lastPlanStateSignature = signature;
+                        currentPlanState = planState;
+                        yield {
+                            type: "plan-state",
+                            sessionId: options.sessionId,
+                            requestId: options.requestId,
+                            agentId: currentAgentId,
+                            planState,
+                        };
+                        const commentary = summarizePlanState(planState);
+                        if (commentary) {
+                            yield* emitCommentary(commentary);
+                        }
+                    }
+                }
                 continue;
             }
             emitted = true;
@@ -200,6 +619,32 @@ export async function* streamHarnessRun(options) {
                 assistantOutput = actual.output;
                 emitted = true;
             }
+            const finalPlanState = getLatestPlanStateFromExecutedToolResults({
+                sessionId: options.sessionId,
+                requestId: options.requestId,
+                metadata: actual.metadata,
+                version: planStateVersion + 1,
+                updatedAt: new Date().toISOString(),
+            });
+            if (finalPlanState) {
+                const signature = buildPlanStateSignature(finalPlanState);
+                if (signature !== lastPlanStateSignature && shouldEmitPlanState(currentPlanState, finalPlanState)) {
+                    planStateVersion = finalPlanState.version;
+                    lastPlanStateSignature = signature;
+                    currentPlanState = finalPlanState;
+                    yield {
+                        type: "plan-state",
+                        sessionId: options.sessionId,
+                        requestId: options.requestId,
+                        agentId: currentAgentId,
+                        planState: finalPlanState,
+                    };
+                    const commentary = summarizePlanState(finalPlanState);
+                    if (commentary) {
+                        yield* emitCommentary(commentary);
+                    }
+                }
+            }
         }
         await options.appendAssistantMessage(options.sessionId, options.requestId, assistantOutput);
         const completedEvent = await options.setRequestStateAndEmit(options.sessionId, options.requestId, 6, "completed", {
@@ -222,8 +667,7 @@ export async function* streamHarnessRun(options) {
         };
     }
     catch (error) {
-        const shouldRetryAfterStreamingCompatibilityError = streamActivityObserved &&
-            !nonUpstreamStreamActivityObserved &&
+        const shouldRetryAfterStreamingCompatibilityError = !assistantOutput &&
             isOpenAICompatibleStreamingCompatibilityError(options.binding, error);
         if ((emitted || streamActivityObserved) && !shouldRetryAfterStreamingCompatibilityError) {
             const runtimeFailure = renderRuntimeFailure(error);

package/dist/runtime/harness/run/surface-semantics.js

@@ -34,24 +34,18 @@ export function stripStepPrefix(label) {
         .replace(/^Accessing memory\s+/i, "")
         .replace(/^Completed memory\s+/i, "");
 }
-function isGenericMemoryMiddlewareName(value) {
-    return /^(memorymiddleware\.before[_\s]?agent|memory middleware before agent)$/i.test(normalizeLabel(value));
-}
 function canonicalMemoryName(memorySource) {
     const normalized = normalizeLabel(memorySource.replace(/^memory\//i, ""));
     const segments = normalized.split(/[\\/]/).filter(Boolean);
     return (segments.at(-1) ?? normalized).toLowerCase() || "memory";
 }
-function isGenericSkillMiddlewareName(value) {
-    return /^(skillsmiddleware\.before[_\s]?agent|skills middleware before agent)$/i.test(normalizeLabel(value));
-}
 export function resolveSurfaceDisplayName(input) {
     const baseName = stripStepPrefix(input.step) || formatAgentName(input.kind);
-    if (input.kind === "memory" && input.binding && isGenericMemoryMiddlewareName(baseName)) {
+    if (input.kind === "memory" && input.binding && baseName.length === 0) {
         const memorySources = getBindingMemorySources(input.binding).filter((name) => name.trim().length > 0);
         return memorySources.length === 1 ? canonicalMemoryName(memorySources[0]) : baseName;
     }
-    if (input.kind !== "skill" || !input.binding || !isGenericSkillMiddlewareName(baseName)) {
+    if (input.kind !== "skill" || !input.binding || baseName.length > 0) {
         return baseName;
     }
     const skillNames = getBindingSkills(input.binding)
@@ -59,32 +53,11 @@ export function resolveSurfaceDisplayName(input) {
         .filter((name) => typeof name === "string" && name.trim().length > 0);
     return skillNames.length === 1 ? skillNames[0] : baseName;
 }
-function normalizeActionHint(value) {
-    return value
-        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-        .replace(/[.:/]+/g, " ")
-        .replace(/[_-]+/g, " ")
-        .replace(/\s+/g, " ")
-        .trim()
-        .toLowerCase();
-}
-function resolveMemoryAction(event, step) {
+function resolveMemoryAction(event) {
     const typed = asObject(event);
-    const hints = [
-        typeof typed?.event === "string" ? typed.event : "",
-        typeof typed?.name === "string" ? typed.name : "",
-        typeof typed?.run_type === "string" ? typed.run_type : "",
-        ...readStringArray(typed?.tags),
-        ...readStringArray(typed?.ns),
-        step,
-    ].map(normalizeActionHint);
-    if (hints.some((value) => /\b(store|memorize|sync|formation|ingestion|archive|write)\b/.test(value))) {
-        return "memorize";
-    }
-    if (hints.some((value) => /\b(recall|retrieve|memorymiddleware|before agent|checkpoint|context)\b/.test(value)
-        || value.includes("accessing memory")
-        || value.includes("access memory"))) {
-        return "recall";
+    const runType = typeof typed?.run_type === "string" ? typed.run_type.trim().toLowerCase() : "";
+    if (runType === "memory") {
+        return "access";
     }
     return "access";
 }
@@ -99,7 +72,7 @@ export function resolveSurfaceAction(input) {
         case "skill":
             return "apply";
         case "memory":
-            return resolveMemoryAction(input.event, input.step ?? "");
+            return resolveMemoryAction(input.event);
         default:
             return "run";
     }

package/dist/runtime/harness/system/runtime-memory-manager.d.ts

@@ -10,6 +10,7 @@ export type ResolvedRuntimeMemoryFormationConfig = {
         enabled: boolean;
         strategy: "rules" | "model";
         modelRef?: string;
+        prompt?: string;
         maxContextRecords: number;
     };
     background: {
@@ -64,6 +65,8 @@ export declare function runModelMemoryManager(input: {
     requestId: string;
     recordedAt: string;
     existingRecords: MemoryRecord[];
+    maxContextRecords?: number;
+    promptTemplate?: string;
     modelResolver?: (modelId: string) => unknown;
 }): Promise<MemoryCandidate[]>;
 export declare function createRuntimeMemoryManager(input: {