@botbotgo/agent-harness 0.0.154 → 0.0.156

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

@@ -0,0 +1,90 @@
+import type { CompiledAgentBinding, CompiledModel, HarnessEvent, HarnessEventProjection, InternalApprovalRecord, MemoryCandidate, MemoryRecord, MemoryScope, ThreadSummary, TranscriptMessage, WorkspaceBundle } from "../../../contracts/types.js";
+import type { RuntimePersistence } from "../../../persistence/types.js";
+import { type StoreLike } from "./store.js";
+export type ResolvedRuntimeMemoryFormationConfig = {
+    enabled: true;
+    hotPath: {
+        enabled: boolean;
+    };
+    manager: {
+        enabled: boolean;
+        strategy: "rules" | "model";
+        modelRef?: string;
+        maxContextRecords: number;
+    };
+    background: {
+        enabled: boolean;
+        maxMessagesPerRun: number;
+        scopes: MemoryScope[];
+        stateStorePath: string;
+        writeOnApprovalResolution: boolean;
+        writeOnRunCompletion: boolean;
+    };
+};
+type RuntimeMemoryFormationWriter = (input: {
+    candidates: MemoryCandidate[];
+    threadId: string;
+    runId: string;
+    agentId: string;
+    userId?: string;
+    projectId?: string;
+    recordedAt: string;
+}) => Promise<void>;
+type RuntimeMemoryFormationOptions = {
+    userId?: string;
+    projectId?: string;
+};
+type RuntimeMemoryManagerLike = {
+    transform(input: {
+        candidates: MemoryCandidate[];
+        binding: CompiledAgentBinding;
+        threadId: string;
+        runId: string;
+        recordedAt: string;
+        existingRecords: MemoryRecord[];
+    }): Promise<MemoryCandidate[]>;
+};
+export declare function readRuntimeMemoryFormationConfig(runtimeMemory: Record<string, unknown> | undefined, workspaceRoot: string): ResolvedRuntimeMemoryFormationConfig | undefined;
+export declare function createBackgroundMemoryCandidates(input: {
+    thread: ThreadSummary;
+    runId: string;
+    agentId: string;
+    trigger: "approval.resolved" | "run.completed";
+    recordedAt: string;
+    messages: TranscriptMessage[];
+    approvals: InternalApprovalRecord[];
+    scopes: MemoryScope[];
+}): MemoryCandidate[];
+export declare function runModelMemoryManager(input: {
+    workspace: WorkspaceBundle;
+    binding: CompiledAgentBinding;
+    model: CompiledModel;
+    candidates: MemoryCandidate[];
+    threadId: string;
+    runId: string;
+    recordedAt: string;
+    existingRecords: MemoryRecord[];
+    modelResolver?: (modelId: string) => unknown;
+}): Promise<MemoryCandidate[]>;
+export declare function createRuntimeMemoryManager(input: {
+    workspace: WorkspaceBundle;
+    binding: CompiledAgentBinding;
+    config: ResolvedRuntimeMemoryFormationConfig;
+    modelResolver?: (modelId: string) => unknown;
+}): RuntimeMemoryManagerLike;
+export declare class RuntimeMemoryFormationSync implements HarnessEventProjection {
+    private readonly persistence;
+    private readonly config;
+    private readonly writer;
+    private readonly stateStore;
+    private readonly options;
+    private readonly pending;
+    private syncChain;
+    readonly name = "runtime-memory-formation-sync";
+    constructor(persistence: RuntimePersistence, config: ResolvedRuntimeMemoryFormationConfig, writer: RuntimeMemoryFormationWriter, runRoot: string, stateStore?: StoreLike, options?: RuntimeMemoryFormationOptions);
+    shouldHandle(event: HarnessEvent): boolean;
+    handleEvent(event: HarnessEvent): Promise<void>;
+    private reflectRun;
+    close(): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,371 @@
+import path from "node:path";
+import { extractMessageText } from "../../../utils/message-content.js";
+import { createResolvedModel } from "../../adapter/model/model-providers.js";
+import { FileBackedStore } from "./store.js";
+import { compileModel } from "../../../workspace/resource-compilers.js";
+import { resolveRefId } from "../../../workspace/support/workspace-ref-utils.js";
+const FORMATION_EVENT_TYPES = new Set(["run.state.changed", "approval.resolved"]);
+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 asNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function asMemoryScopes(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const scopes = value
+        .filter((item) => typeof item === "string")
+        .filter((item) => ["thread", "agent", "workspace", "user", "project"].includes(item));
+    return scopes.length > 0 ? Array.from(new Set(scopes)) : undefined;
+}
+function normalizeScopeList(scopes) {
+    return Array.from(new Set(scopes));
+}
+function asStrategy(value) {
+    return value === "rules" || value === "model" ? value : undefined;
+}
+export function readRuntimeMemoryFormationConfig(runtimeMemory, workspaceRoot) {
+    if (runtimeMemory?.enabled !== true) {
+        return undefined;
+    }
+    const formation = asRecord(runtimeMemory.formation);
+    const hotPath = asRecord(formation?.hotPath);
+    const manager = asRecord(formation?.manager);
+    const background = asRecord(formation?.background);
+    const ingestion = asRecord(runtimeMemory.ingestion);
+    const workspaceBaseName = path.basename(workspaceRoot) || "agent-harness";
+    const resolved = {
+        enabled: true,
+        hotPath: {
+            enabled: asBoolean(hotPath?.enabled) ?? true,
+        },
+        manager: {
+            enabled: asBoolean(manager?.enabled) ?? true,
+            strategy: asStrategy(manager?.strategy) ?? "rules",
+            modelRef: asNonEmptyString(manager?.modelRef),
+            maxContextRecords: asPositiveInteger(manager?.maxContextRecords) ?? 12,
+        },
+        background: {
+            enabled: asBoolean(background?.enabled) ?? true,
+            maxMessagesPerRun: asPositiveInteger(background?.maxMessagesPerRun) ?? asPositiveInteger(ingestion?.maxMessagesPerRun) ?? 40,
+            scopes: normalizeScopeList(asMemoryScopes(background?.scopes) ?? ["thread"]),
+            stateStorePath: asNonEmptyString(background?.stateStorePath) ?? `${workspaceBaseName}-memory-formation-state.json`,
+            writeOnApprovalResolution: asBoolean(background?.writeOnApprovalResolution) ?? asBoolean(ingestion?.writeOnApprovalResolution) ?? true,
+            writeOnRunCompletion: asBoolean(background?.writeOnRunCompletion) ?? asBoolean(ingestion?.writeOnRunCompletion) ?? true,
+        },
+    };
+    if (!resolved.hotPath.enabled && !resolved.background.enabled) {
+        return undefined;
+    }
+    return resolved;
+}
+function excerpt(message) {
+    if (!message?.content) {
+        return undefined;
+    }
+    const normalized = extractMessageText(message.content).replace(/\s+/g, " ").trim();
+    if (!normalized) {
+        return undefined;
+    }
+    return normalized.length > 240 ? `${normalized.slice(0, 237)}...` : normalized;
+}
+function summarizeApprovals(approvals) {
+    if (approvals.length === 0) {
+        return "No approvals were recorded in this run.";
+    }
+    return approvals
+        .map((approval) => `${approval.toolName} (${approval.status})`)
+        .join(", ");
+}
+export function createBackgroundMemoryCandidates(input) {
+    const latestUser = excerpt(input.messages.filter((message) => message.role === "user").at(-1));
+    const latestAssistant = excerpt(input.messages.filter((message) => message.role === "assistant").at(-1));
+    const userContext = latestUser ?? "No durable user context captured.";
+    const assistantContext = latestAssistant ?? "No durable assistant response captured.";
+    const approvals = summarizeApprovals(input.approvals);
+    const summarySeed = latestUser ?? latestAssistant ?? `Run ${input.runId}`;
+    const baseSummary = summarySeed.length > 120 ? `${summarySeed.slice(0, 117)}...` : summarySeed;
+    const sourceRefBase = `runtime://threads/${input.thread.threadId}/runs/${input.runId}/background-reflection`;
+    return input.scopes.map((scope) => ({
+        kind: "episodic",
+        scope,
+        sourceType: "runtime-reflection",
+        sourceRef: `${sourceRefBase}#${scope}`,
+        summary: `${baseSummary} (${scope})`,
+        content: [
+            `Run ${input.runId} completed for thread ${input.thread.threadId}.`,
+            `Trigger: ${input.trigger}.`,
+            `Latest user context: ${userContext}`,
+            `Latest assistant context: ${assistantContext}`,
+            `Approvals: ${approvals}`,
+        ].join("\n"),
+        confidence: 0.72,
+        observedAt: input.recordedAt,
+        tags: ["background-reflection", "langmem-aligned", scope, input.trigger],
+    }));
+}
+function normalizeKind(value, fallback) {
+    if (value === "semantic" || value === "episodic" || value === "procedural") {
+        return value;
+    }
+    return fallback;
+}
+function normalizeScope(value, fallback) {
+    if (value === "thread" || value === "agent" || value === "workspace" || value === "user" || value === "project") {
+        return value;
+    }
+    return fallback;
+}
+function normalizeTags(value, fallback) {
+    if (!Array.isArray(value)) {
+        return fallback;
+    }
+    const tags = value.filter((item) => typeof item === "string" && item.trim().length > 0);
+    return tags.length > 0 ? tags : fallback;
+}
+function normalizeConfidence(value, fallback) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        return fallback;
+    }
+    return Math.min(1, Math.max(0, value));
+}
+function extractText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "object" && value !== null && "content" in value && typeof value.content === "string") {
+        return String(value.content);
+    }
+    return undefined;
+}
+function tryParseJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        const match = text.match(/\{[\s\S]*\}/);
+        if (!match) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(match[0]);
+            return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function renderManagerPrompt(input) {
+    const existing = input.existingRecords.length === 0
+        ? "(none)"
+        : input.existingRecords
+            .map((record) => `- scope=${record.scope}; kind=${record.kind}; summary=${record.summary}; status=${record.status}; content=${record.content.replace(/\s+/g, " ").slice(0, 220)}`)
+            .join("\n");
+    return [
+        "You are the runtime memory manager.",
+        "Decide whether a candidate should be stored as durable memory and refine it if appropriate.",
+        "Return JSON only.",
+        "",
+        "Rules:",
+        '- Store only durable reusable knowledge. Reject transient chatter, scratchpad, or duplication without added value.',
+        '- Prefer semantic/episodic/procedural kinds only.',
+        '- Prefer scopes thread/agent/workspace/user/project only.',
+        '- If the candidate should not be stored, return {"store": false, "reason": "..."}',
+        '- If it should be stored, return {"store": true, "content": "...", "summary": "...", "kind": "...", "scope": "...", "tags": ["..."], "confidence": 0.0}',
+        "",
+        `threadId=${input.threadId}`,
+        `runId=${input.runId}`,
+        "",
+        "Candidate:",
+        JSON.stringify(input.candidate, null, 2),
+        "",
+        "Existing relevant records:",
+        existing,
+    ].join("\n");
+}
+export async function runModelMemoryManager(input) {
+    const resolvedModel = await createResolvedModel(input.model, input.modelResolver);
+    const invoker = resolvedModel;
+    if (typeof invoker.invoke !== "function") {
+        return input.candidates;
+    }
+    const transformed = [];
+    for (const candidate of input.candidates) {
+        const prompt = renderManagerPrompt({
+            candidate,
+            threadId: input.threadId,
+            runId: input.runId,
+            existingRecords: input.existingRecords,
+        });
+        const response = await invoker.invoke(prompt, {});
+        const parsed = tryParseJsonObject(extractText(response) ?? "");
+        if (!parsed) {
+            transformed.push(candidate);
+            continue;
+        }
+        if (parsed.store === false) {
+            continue;
+        }
+        transformed.push({
+            ...candidate,
+            content: typeof parsed.content === "string" && parsed.content.trim().length > 0 ? parsed.content.trim() : candidate.content,
+            summary: typeof parsed.summary === "string" && parsed.summary.trim().length > 0 ? parsed.summary.trim() : candidate.summary,
+            kind: normalizeKind(parsed.kind, normalizeKind(candidate.kind, undefined)),
+            scope: normalizeScope(parsed.scope, normalizeScope(candidate.scope, undefined)),
+            tags: normalizeTags(parsed.tags, candidate.tags),
+            confidence: normalizeConfidence(parsed.confidence, candidate.confidence),
+            observedAt: candidate.observedAt ?? input.recordedAt,
+        });
+    }
+    return transformed;
+}
+export function createRuntimeMemoryManager(input) {
+    return {
+        async transform({ candidates, binding, threadId, runId, recordedAt, existingRecords }) {
+            if (input.config.manager.enabled !== true || candidates.length === 0) {
+                return candidates;
+            }
+            const contextRecords = existingRecords
+                .filter((record) => record.status === "active")
+                .slice(-input.config.manager.maxContextRecords);
+            if (input.config.manager.strategy !== "model") {
+                return candidates;
+            }
+            if (!binding.langchainAgentParams?.model) {
+                return candidates;
+            }
+            const primaryModel = (() => {
+                if (!input.config.manager.modelRef) {
+                    return binding.langchainAgentParams.model;
+                }
+                const configured = input.workspace.models.get(resolveRefId(input.config.manager.modelRef));
+                return configured ? compileModel(configured) : binding.langchainAgentParams.model;
+            })();
+            return runModelMemoryManager({
+                workspace: input.workspace,
+                binding,
+                model: primaryModel,
+                candidates,
+                threadId,
+                runId,
+                recordedAt,
+                existingRecords: contextRecords,
+                modelResolver: input.modelResolver,
+            });
+        },
+    };
+}
+function fingerprintMessages(messages, scopes) {
+    const serialized = messages
+        .map((message) => `${message.role}\n${message.createdAt}\n${extractMessageText(message.content)}`)
+        .join("\n---\n");
+    return `${scopes.join(",")}::${serialized}`;
+}
+export class RuntimeMemoryFormationSync {
+    persistence;
+    config;
+    writer;
+    stateStore;
+    options;
+    pending = new Set();
+    syncChain = Promise.resolve();
+    name = "runtime-memory-formation-sync";
+    constructor(persistence, config, writer, runRoot, stateStore = new FileBackedStore(path.join(runRoot, config.background.stateStorePath)), options = {}) {
+        this.persistence = persistence;
+        this.config = config;
+        this.writer = writer;
+        this.stateStore = stateStore;
+        this.options = options;
+    }
+    shouldHandle(event) {
+        if (!this.config.background.enabled || !FORMATION_EVENT_TYPES.has(event.eventType)) {
+            return false;
+        }
+        if (event.eventType === "approval.resolved") {
+            return this.config.background.writeOnApprovalResolution;
+        }
+        return this.config.background.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.reflectRun(event.threadId, event.runId, trigger, event.timestamp))
+            .catch(() => {
+            // Fail open: reflection should not block runtime progress.
+        });
+        this.syncChain = task
+            .catch(() => {
+            // Fail open: reflection should not block runtime progress.
+        })
+            .finally(() => {
+            this.pending.delete(task);
+        });
+        this.pending.add(task);
+    }
+    async reflectRun(threadId, runId, trigger, recordedAt) {
+        const [thread, run, allMessages, approvals] = await Promise.all([
+            this.persistence.getSession(threadId),
+            this.persistence.getRun(runId),
+            this.persistence.listThreadMessages(threadId, this.config.background.maxMessagesPerRun),
+            this.persistence.getRunApprovals(threadId, runId),
+        ]);
+        if (!thread || !run) {
+            return;
+        }
+        const messages = allMessages.filter((message) => message.runId === runId);
+        if (messages.length === 0) {
+            return;
+        }
+        const fingerprint = fingerprintMessages(messages, this.config.background.scopes);
+        const namespace = ["memories", "formation", "threads", threadId, "runs"];
+        const cursor = await this.stateStore.get(namespace, runId);
+        const existing = cursor?.value;
+        if (existing?.fingerprint === fingerprint && existing.trigger === trigger) {
+            return;
+        }
+        const candidates = createBackgroundMemoryCandidates({
+            thread,
+            runId,
+            agentId: run.agentId ?? thread.agentId,
+            trigger,
+            recordedAt,
+            messages,
+            approvals,
+            scopes: this.config.background.scopes,
+        });
+        if (candidates.length === 0) {
+            return;
+        }
+        await this.writer({
+            candidates,
+            threadId,
+            runId,
+            agentId: run.agentId ?? thread.agentId,
+            userId: this.options.userId,
+            projectId: this.options.projectId,
+            recordedAt,
+        });
+        await this.stateStore.put(namespace, runId, {
+            fingerprint,
+            candidateCount: candidates.length,
+            syncedAt: new Date().toISOString(),
+            trigger,
+        });
+    }
+    async close() {
+        await Promise.allSettled(Array.from(this.pending));
+    }
+}

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

@@ -14,6 +14,10 @@ type PersistMemoryRecordsOptions = {
 export declare function renderMemoryRecordsMarkdown(title: string, records: MemoryRecord[]): string;
 export declare function rebuildStructuredMemoryProjections(store: StoreLike, namespace: string[], title: string, scope: MemoryScope, maxEntries: number): Promise<void>;
 export declare function listMemoryRecordsForScopes(store: StoreLike, scopes: MemoryScope[]): Promise<MemoryRecord[]>;
+export declare function getMemoryRecord(store: StoreLike, scope: MemoryScope, recordId: string): Promise<MemoryRecord | null>;
+export declare function findMemoryRecordById(store: StoreLike, recordId: string): Promise<MemoryRecord | null>;
+export declare function updateMemoryRecord(store: StoreLike, record: MemoryRecord, updatedAt: string): Promise<MemoryRecord>;
+export declare function removeMemoryRecord(store: StoreLike, scope: MemoryScope, recordId: string): Promise<MemoryRecord | null>;
 export declare function persistStructuredMemoryRecords(options: PersistMemoryRecordsOptions): Promise<{
     records: MemoryRecord[];
     decisions: MemoryDecision[];

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

@@ -34,6 +34,12 @@ function createCanonicalKey(candidate, kind, scope) {
 function buildScopeNamespace(scope) {
     return ["memories", "records", scope];
 }
+function buildCanonicalIndexNamespace(scope) {
+    return ["memories", "indexes", "canonical", scope];
+}
+function buildSourceRefIndexNamespace(scope) {
+    return ["memories", "indexes", "source-ref", scope];
+}
 function normalizeTextForCompare(value) {
     return value.toLowerCase().replace(/\s+/g, " ").trim();
 }
@@ -312,7 +318,7 @@ function evaluateDecision(existing, incoming, recordedAt) {
 async function putRecordWithIndexes(store, record, updatedAt) {
     const canonicalKeyId = createFingerprint(record.canonicalKey);
     await store.put(buildScopeNamespace(record.scope), `${record.id}.json`, record);
-    await store.put(["memories", "indexes", "canonical", record.scope], `${canonicalKeyId}-${record.id}.json`, {
+    await store.put(buildCanonicalIndexNamespace(record.scope), `${canonicalKeyId}-${record.id}.json`, {
         canonicalKey: record.canonicalKey,
         recordId: record.id,
         scope: record.scope,
@@ -321,7 +327,7 @@ async function putRecordWithIndexes(store, record, updatedAt) {
     });
     await Promise.all(record.sourceRefs.map((sourceRef) => {
         const sourceRefId = createFingerprint(sourceRef);
-        return store.put(["memories", "indexes", "source-ref", record.scope], `${sourceRefId}-${record.id}.json`, {
+        return store.put(buildSourceRefIndexNamespace(record.scope), `${sourceRefId}-${record.id}.json`, {
             sourceRef,
             recordId: record.id,
             scope: record.scope,
@@ -375,6 +381,55 @@ export async function listMemoryRecordsForScopes(store, scopes) {
     const all = await Promise.all(scopes.map((scope) => listStoredRecords(store, scope)));
     return all.flat();
 }
+export async function getMemoryRecord(store, scope, recordId) {
+    const entry = await store.get(buildScopeNamespace(scope), `${recordId}.json`);
+    const record = entry?.value;
+    if (typeof record !== "object" || !record || Array.isArray(record)) {
+        return null;
+    }
+    const candidate = record;
+    return typeof candidate.id === "string" && typeof candidate.content === "string" ? candidate : null;
+}
+export async function findMemoryRecordById(store, recordId) {
+    for (const scope of MEMORY_SCOPES) {
+        const record = await getMemoryRecord(store, scope, recordId);
+        if (record) {
+            return record;
+        }
+    }
+    return null;
+}
+async function deleteRecordIndexes(store, record) {
+    const [canonicalEntries, sourceRefEntries] = await Promise.all([
+        store.search(buildCanonicalIndexNamespace(record.scope)),
+        store.search(buildSourceRefIndexNamespace(record.scope)),
+    ]);
+    await Promise.all([
+        ...canonicalEntries
+            .filter((entry) => entry.value?.recordId === record.id)
+            .map((entry) => store.delete(entry.namespace, entry.key)),
+        ...sourceRefEntries
+            .filter((entry) => entry.value?.recordId === record.id)
+            .map((entry) => store.delete(entry.namespace, entry.key)),
+    ]);
+}
+export async function updateMemoryRecord(store, record, updatedAt) {
+    const existing = await getMemoryRecord(store, record.scope, record.id);
+    if (existing) {
+        await deleteRecordIndexes(store, existing);
+    }
+    await putRecordWithIndexes(store, record, updatedAt);
+    return record;
+}
+export async function removeMemoryRecord(store, scope, recordId) {
+    const existing = await getMemoryRecord(store, scope, recordId);
+    if (!existing) {
+        return null;
+    }
+    await deleteRecordIndexes(store, existing);
+    await store.delete(buildScopeNamespace(scope), `${recordId}.json`);
+    return existing;
+}
 export async function persistStructuredMemoryRecords(options) {
     const existingRecords = await listStoredRecords(options.store);
     const persistedRecords = [];

package/dist/runtime/harness/system/store.d.ts

@@ -49,4 +49,31 @@ export declare class FileBackedStore {
     delete(namespace: string[], key: string): Promise<void>;
     listNamespaces(options?: Parameters<InMemoryStore["listNamespaces"]>[0]): Promise<string[][]>;
 }
+export declare class SqliteBackedStore {
+    readonly filePath: string;
+    private readonly db;
+    constructor(filePath: string);
+    batch(operations: Array<Record<string, unknown>>): Promise<readonly unknown[]>;
+    get(namespace: string[], key: string): Promise<{
+        value: unknown;
+        key: string;
+        namespace: string[];
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    private getSync;
+    search(namespacePrefix: string[]): Promise<Array<{
+        value: unknown;
+        key: string;
+        namespace: string[];
+        createdAt: Date;
+        updatedAt: Date;
+        score?: number;
+    }>>;
+    put(namespace: string[], key: string, value: Record<string, any>, _index?: false | string[]): Promise<void>;
+    private putSync;
+    delete(namespace: string[], key: string): Promise<void>;
+    private deleteSync;
+    listNamespaces(): Promise<string[][]>;
+}
 export declare function createInMemoryStore(): StoreLike;