@botbotgo/agent-harness 0.0.139 → 0.0.141

package/README.md

@@ -140,6 +140,9 @@ Boundary documents live in:
 - `docs/tool-execution-policy.md`
 - `docs/feature-checklist.md`
 - `docs/long-term-memory.md`
+- `docs/memory-runtime-design.md`
+- `docs/memory-runtime-usage.md`
+- `docs/memory-policy-reference.md`
 - `docs/app-task-pattern.md`
 - `docs/model-layering.md`
 - `docs/coding-agent-guide.md`

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.138";
+export declare const AGENT_HARNESS_VERSION = "0.0.140";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.138";
+export const AGENT_HARNESS_VERSION = "0.0.140";

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

@@ -0,0 +1,24 @@
+import type { HarnessEvent, HarnessEventProjection } from "../../../contracts/types.js";
+import type { RuntimePersistence } from "../../../persistence/types.js";
+import type { StoreLike } from "./store.js";
+export type ResolvedRuntimeMemorySyncConfig = {
+    enabled: true;
+    writeOnApprovalResolution: boolean;
+    writeOnRunCompletion: boolean;
+    backgroundConsolidation: boolean;
+    maxMessagesPerRun: number;
+};
+export declare function readRuntimeMemorySyncConfig(runtimeMemory: Record<string, unknown> | undefined): ResolvedRuntimeMemorySyncConfig | undefined;
+export declare class RuntimeMemorySync implements HarnessEventProjection {
+    private readonly persistence;
+    readonly store: StoreLike;
+    private readonly config;
+    private readonly pending;
+    private syncChain;
+    readonly name = "runtime-memory-sync";
+    constructor(persistence: RuntimePersistence, store: StoreLike, config: ResolvedRuntimeMemorySyncConfig);
+    shouldHandle(event: HarnessEvent): boolean;
+    handleEvent(event: HarnessEvent): Promise<void>;
+    private syncRun;
+    close(): Promise<void>;
+}

package/dist/runtime/harness/system/runtime-memory-sync.js

@@ -0,0 +1,193 @@
+import { extractMessageText } from "../../../utils/message-content.js";
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function asPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function excerpt(message) {
+    if (!message?.content) {
+        return "(none)";
+    }
+    const normalized = extractMessageText(message.content).replace(/\s+/g, " ").trim();
+    return normalized.length > 240 ? `${normalized.slice(0, 237)}...` : normalized;
+}
+function formatMessageSection(title, messages) {
+    const lines = [`## ${title}`, ""];
+    if (messages.length === 0) {
+        lines.push("(none)", "");
+        return lines;
+    }
+    for (const message of messages) {
+        lines.push(`- ${excerpt(message)}`);
+    }
+    lines.push("");
+    return lines;
+}
+function formatApprovalSection(approvals) {
+    const lines = ["## Approval Snapshot", ""];
+    if (approvals.length === 0) {
+        lines.push("(none)", "");
+        return lines;
+    }
+    for (const approval of approvals) {
+        lines.push(`- ${approval.approvalId}: ${approval.toolName} (${approval.status})`);
+    }
+    lines.push("");
+    return lines;
+}
+function renderRunSummaryMarkdown(input) {
+    const userMessages = input.messages.filter((message) => message.role === "user").slice(-3);
+    const assistantMessages = input.messages.filter((message) => message.role === "assistant").slice(-3);
+    return [
+        "# Run Memory Summary",
+        "",
+        `- thread_id: ${input.thread.threadId}`,
+        `- run_id: ${input.runId}`,
+        `- agent_id: ${input.agentId}`,
+        `- status: ${input.thread.status}`,
+        `- trigger: ${input.trigger}`,
+        `- captured_at: ${input.capturedAt}`,
+        "",
+        ...formatMessageSection("Recent User Messages", userMessages),
+        ...formatMessageSection("Recent Assistant Messages", assistantMessages),
+        ...formatApprovalSection(input.approvals),
+    ].join("\n");
+}
+function renderThreadDigestMarkdown(input) {
+    const latestUser = input.messages.filter((message) => message.role === "user").at(-1);
+    const latestAssistant = input.messages.filter((message) => message.role === "assistant").at(-1);
+    return [
+        "# Durable Thread Digest",
+        "",
+        `- thread_id: ${input.thread.threadId}`,
+        `- latest_run_id: ${input.runId}`,
+        `- status: ${input.thread.status}`,
+        `- last_memory_trigger: ${input.trigger}`,
+        `- updated_at: ${input.capturedAt}`,
+        "",
+        "## Latest Durable User Context",
+        excerpt(latestUser),
+        "",
+        "## Latest Durable Assistant Context",
+        excerpt(latestAssistant),
+        "",
+    ].join("\n");
+}
+const RUNTIME_MEMORY_EVENT_TYPES = new Set(["run.state.changed", "approval.resolved"]);
+export function readRuntimeMemorySyncConfig(runtimeMemory) {
+    if (runtimeMemory?.enabled !== true) {
+        return undefined;
+    }
+    const ingestion = asRecord(runtimeMemory.ingestion);
+    const writeOnApprovalResolution = asBoolean(ingestion?.writeOnApprovalResolution) ?? true;
+    const writeOnRunCompletion = asBoolean(ingestion?.writeOnRunCompletion) ?? true;
+    if (!writeOnApprovalResolution && !writeOnRunCompletion) {
+        return undefined;
+    }
+    return {
+        enabled: true,
+        writeOnApprovalResolution,
+        writeOnRunCompletion,
+        backgroundConsolidation: asBoolean(ingestion?.backgroundConsolidation) ?? true,
+        maxMessagesPerRun: asPositiveInteger(ingestion?.maxMessagesPerRun) ?? 40,
+    };
+}
+export class RuntimeMemorySync {
+    persistence;
+    store;
+    config;
+    pending = new Set();
+    syncChain = Promise.resolve();
+    name = "runtime-memory-sync";
+    constructor(persistence, store, config) {
+        this.persistence = persistence;
+        this.store = store;
+        this.config = config;
+    }
+    shouldHandle(event) {
+        if (!RUNTIME_MEMORY_EVENT_TYPES.has(event.eventType)) {
+            return false;
+        }
+        if (event.eventType === "approval.resolved") {
+            return this.config.writeOnApprovalResolution;
+        }
+        return this.config.writeOnRunCompletion && event.payload.state === "completed";
+    }
+    async handleEvent(event) {
+        if (!this.shouldHandle(event)) {
+            return;
+        }
+        const trigger = event.eventType === "approval.resolved" ? "approval.resolved" : "run.completed";
+        const task = this.syncChain
+            .then(() => this.syncRun(event.threadId, event.runId, trigger, event.timestamp))
+            .catch(() => {
+            // Fail open: runtime memory sync must not break the hot path.
+        });
+        this.syncChain = task
+            .catch(() => {
+            // Fail open: runtime memory sync must not break the hot path.
+        })
+            .finally(() => {
+            this.pending.delete(task);
+        });
+        this.pending.add(task);
+    }
+    async syncRun(threadId, runId, trigger, capturedAt) {
+        const [thread, run, allMessages, approvals] = await Promise.all([
+            this.persistence.getSession(threadId),
+            this.persistence.getRun(runId),
+            this.persistence.listThreadMessages(threadId, this.config.maxMessagesPerRun),
+            this.persistence.getRunApprovals(threadId, runId),
+        ]);
+        if (!thread || !run) {
+            return;
+        }
+        const messages = allMessages.filter((message) => message.runId === runId);
+        if (messages.length === 0) {
+            return;
+        }
+        const agentId = run.agentId ?? thread.agentId;
+        const summaryMarkdown = renderRunSummaryMarkdown({
+            thread,
+            runId,
+            agentId,
+            trigger,
+            capturedAt,
+            messages,
+            approvals,
+        });
+        await Promise.all([
+            this.store.put(["memories", "runs", threadId], `${runId}.summary.md`, { content: `${summaryMarkdown}\n` }),
+            this.store.put(["memories", "runs", threadId], `${runId}.record.json`, {
+                kind: "summary",
+                scope: "thread",
+                threadId,
+                runId,
+                agentId,
+                trigger,
+                capturedAt,
+                status: thread.status,
+                messageCount: messages.length,
+                approvalCount: approvals.length,
+            }),
+        ]);
+        if (!this.config.backgroundConsolidation) {
+            return;
+        }
+        const digestMarkdown = renderThreadDigestMarkdown({
+            thread,
+            runId,
+            trigger,
+            capturedAt,
+            messages,
+        });
+        await this.store.put(["memories", "threads", threadId], "durable-summary.md", { content: `${digestMarkdown}\n` });
+    }
+    async close() {
+        await Promise.allSettled(Array.from(this.pending));
+    }
+}

package/dist/runtime/harness.d.ts

@@ -23,6 +23,8 @@ export declare class AgentHarnessRuntime {
     private readonly routingDefaultAgentId?;
     private readonly threadMemorySync;
     private readonly unregisterThreadMemorySync;
+    private readonly runtimeMemorySync;
+    private readonly unregisterRuntimeMemorySync;
     private readonly mem0IngestionSync;
     private readonly unregisterMem0IngestionSync;
     private readonly resolvedRuntimeAdapterOptions;

package/dist/runtime/harness.js

@@ -7,6 +7,7 @@ import { PolicyEngine } from "./harness/system/policy-engine.js";
 import { getConcurrencyConfig, getRecoveryConfig, getRoutingDefaultAgentId, getRoutingRules, } from "../workspace/support/workspace-ref-utils.js";
 import { createHarnessEvent, inferRoutingBindings, renderRuntimeFailure, } from "./support/harness-support.js";
 import { ThreadMemorySync } from "./harness/system/thread-memory-sync.js";
+import { RuntimeMemorySync, readRuntimeMemorySyncConfig } from "./harness/system/runtime-memory-sync.js";
 import { FileBackedStore } from "./harness/system/store.js";
 import { HealthMonitor, readHealthMonitorConfig, } from "./harness/system/health-monitor.js";
 import { normalizeInvocationEnvelope, normalizeRunPriority, resolveRunListeners, } from "./harness/run/helpers.js";
@@ -58,6 +59,8 @@ export class AgentHarnessRuntime {
     routingDefaultAgentId;
     threadMemorySync;
     unregisterThreadMemorySync;
+    runtimeMemorySync;
+    unregisterRuntimeMemorySync;
     mem0IngestionSync;
     unregisterMem0IngestionSync;
     resolvedRuntimeAdapterOptions;
@@ -143,6 +146,15 @@ export class AgentHarnessRuntime {
             this.threadMemorySync = null;
             this.unregisterThreadMemorySync = () => { };
         }
+        const runtimeMemorySyncConfig = readRuntimeMemorySyncConfig(this.defaultRuntimeEntryBinding?.harnessRuntime.runtimeMemory);
+        if (runtimeMemorySyncConfig) {
+            this.runtimeMemorySync = new RuntimeMemorySync(this.persistence, this.runtimeMemoryStore, runtimeMemorySyncConfig);
+            this.unregisterRuntimeMemorySync = this.eventBus.registerProjection(this.runtimeMemorySync);
+        }
+        else {
+            this.runtimeMemorySync = null;
+            this.unregisterRuntimeMemorySync = () => { };
+        }
         const mem0RuntimeConfig = readMem0RuntimeConfig(this.defaultRuntimeEntryBinding?.harnessRuntime.runtimeMemory, this.workspace.workspaceRoot);
         if (mem0RuntimeConfig) {
             this.mem0IngestionSync = new Mem0IngestionSync(this.persistence, mem0RuntimeConfig, runRoot);
@@ -582,9 +594,11 @@ export class AgentHarnessRuntime {
         this.closed = true;
         await this.healthMonitor?.stop();
         this.unregisterThreadMemorySync();
+        this.unregisterRuntimeMemorySync();
         this.unregisterMem0IngestionSync();
         await Promise.allSettled(Array.from(this.backgroundTasks));
         await this.threadMemorySync?.close();
+        await this.runtimeMemorySync?.close();
         await this.mem0IngestionSync?.close();
         await closeMcpClientsForWorkspace(this.workspace);
         this.initialized = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.139",
+  "version": "0.0.141",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",