@botbotgo/agent-harness 0.0.306 → 0.0.308

package/README.md

@@ -469,9 +469,9 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-`createAgentHarness(...)` loads the workspace, resolves `resources/`, initializes persistence under `runtimeRoot`, and starts runtime maintenance.
+`createAgentHarness(...)` loads the workspace, resolves workspace sources, initializes persistence under `runtimeRoot`, and starts runtime maintenance.
 
-`runtime.spec.resources` may attach multiple extra resource packages. Each entry may point either to a package root that contains `resources/`, or directly to a resource folder that contains its own `package.json`.
+`runtime.spec.sources` is the primary public discovery surface for local tools, package tools, and skill packages.
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -479,11 +479,29 @@ kind: Runtime
 metadata:
   name: default
 spec:
-  resources:
-    - ../shared-tools
-    - file:../shared-skills
+  sources:
+    tools:
+      - file://./resources/tools
+      - file://../shared-tools
+      - npm://@acme/agent-tools
+    skills:
+      - file://./resources/skills
+      - https://example.com/skills/review/SKILL.md
 ```
 
+Tool-source rules:
+
+- `file://...` scans only the configured folder
+- `npm://...` resolves one package, auto-installs it when missing, and discovers exported `tool({...})` definitions from the package entry
+- tool discovery never traverses `node_modules/**`
+
+Skill-source rules:
+
+- `file://...` accepts a skill collection folder, a single skill root, or a direct `SKILL.md` path
+- `http://...` and `https://...` currently accept a single remote `SKILL.md`
+
+`runtime.spec.resources` remains supported as a compatibility path for attached resource packages.
+
 `createAgentHarness(..., { load })` accepts workspace loading controls.
 
 Merge order is deterministic:
@@ -739,8 +757,10 @@ Discovery rules:
 
 - every YAML document under `config/**` is discovered recursively; filenames and subfolders are organizational only
 - YAML object semantics come from `kind`, `metadata.name` or `id`, and object content rather than the file path
-- local tools are auto-discovered from `resources/tools/**/*.js|*.mjs|*.cjs` when they export `tool({...})`
-- skills are auto-discovered from `resources/skills/**/SKILL.md`
+- `Runtime.spec.sources.tools` defaults to `file://./resources/tools`
+- `Runtime.spec.sources.skills` defaults to `file://./resources/skills`
+- local file-based tools are auto-discovered from each configured tool folder when modules export `tool({...})`
+- file-based skills are auto-discovered from each configured skill source
 - a minimal workspace can start with only `config/models.yaml`; the repository defaults provide the `Runtime`, the default `orchestra` host, and runtime-managed durable memory with `enabled: true`
 - when you do not override runtime placement, harness-owned generated state is written under `./.botbotgo/`
 
@@ -768,7 +788,9 @@ For DeepAgents-backed agents, the runtime still keeps an internal compatibility
 
 Default wiring guidance:
 
-- let workspace startup scan local and attached `resources` packages into one registry
+- let `Runtime.spec.sources` declare the tool and skill roots the workspace owns
+- let workspace startup scan only those declared sources into one registry
+- let workspace startup scan local and attached `resources` packages into one registry when compatibility paths are still in use
 - let agents whitelist tools and skills by name
 - keep `config/catalogs/tools.yaml` for reusable shared tools
 - keep `config/catalogs/mcp.yaml` for shared MCP server definitions
@@ -810,6 +832,8 @@ Important fields:
 
 - `runtimeRoot`
 - `concurrency.maxConcurrentRequests`
+- `sources.tools`
+- `sources.skills`
 - `routing.defaultAgentId`
 - `routing.rules`
 - `toolModuleDiscovery.scope`
@@ -826,7 +850,17 @@ Important fields:
 - `maintenance.checkpoints` trims backend checkpoint state used for resume/recovery
 - `maintenance.records` trims harness-owned terminal session/request records stored in `runtime.sqlite`
 
-`toolModuleDiscovery.scope` controls how local `resources/tools/`-style module discovery walks tool directories:
+`sources.tools` controls which tool roots or packages participate in workspace discovery:
+
+- `file://...` for folder scanning
+- `npm://...` for package-entry discovery and auto-install when missing
+
+`sources.skills` controls which skill folders or skill documents participate in workspace discovery:
+
+- `file://...` for local folders, skill roots, or direct `SKILL.md`
+- `http://...` / `https://...` for one remote `SKILL.md`
+
+`toolModuleDiscovery.scope` controls how local `resources/tools/`-style file discovery walks tool directories:
 
 - `recursive` is the default and keeps scanning nested folders
 - `top-level` limits module discovery to files directly under each tool root while leaving YAML catalogs recursive
@@ -942,6 +976,8 @@ The default repository shape uses:
 - `KnowledgeRuntime`: hot path + background formation + long-term maintenance
 - `ProceduralMemoryRuntime`: background formation + scheduled or idle maintenance
 
+In the shipped runtime, explicit durable facts such as “remember I moved to the United States” still go to `KnowledgeRuntime` and land in `knowledge/knowledge.sqlite`. Background procedural learning writes its own store and state files under the same data root, such as `knowledge/procedural-memory.sqlite` and `knowledge/procedural-memory-state.json`.
+
 For DeepAgents-backed workspaces, keep upstream context compaction upstream-owned and use procedural memory only as a background learning layer.
 
 ### `config/catalogs/backends.yaml`

package/README.zh.md

@@ -464,9 +464,9 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-`createAgentHarness(...)` 会加载工作区、解析 `resources/`、在 `runtimeRoot` 下初始化持久化，并启动运行时维护任务。
+`createAgentHarness(...)` 会加载工作区、解析工作区 source、在 `runtimeRoot` 下初始化持久化，并启动运行时维护任务。
 
-`runtime.spec.resources` 可以挂载多个额外资源包。每个条目既可以指向“包根目录下带有 `resources/` 的目录”，也可以直接指向“自身带有 `package.json` 的资源目录”。
+`runtime.spec.sources` 现在是本地工具、npm 工具包与 skill package 的主公开发现入口。
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -474,11 +474,29 @@ kind: Runtime
 metadata:
   name: default
 spec:
-  resources:
-    - ../shared-tools
-    - file:../shared-skills
+  sources:
+    tools:
+      - file://./resources/tools
+      - file://../shared-tools
+      - npm://@acme/agent-tools
+    skills:
+      - file://./resources/skills
+      - https://example.com/skills/review/SKILL.md
 ```
 
+tool source 规则：
+
+- `file://...` 只扫描显式配置的目录
+- `npm://...` 只解析单个包；本地缺失时会自动安装，再从包入口发现导出的 `tool({...})`
+- tool 发现永远不会遍历 `node_modules/**`
+
+skill source 规则：
+
+- `file://...` 可以指向 skill 集合目录、单个 skill root，或直接指向 `SKILL.md`
+- `http://...` 与 `https://...` 当前只支持一个远程 `SKILL.md`
+
+`runtime.spec.resources` 仍保留为兼容旧 attached resource package 的路径。
+
 `createAgentHarness(..., { load })` 支持工作区加载控制。
 
 合并顺序是确定性的：
@@ -710,8 +728,10 @@ await stop(runtime);
 
 - `config/**` 下的所有 YAML 文档都会被递归发现；文件名与子目录只用于组织，不参与语义
 - YAML 对象语义由 `kind`、`metadata.name` 或 `id` 以及对象内容决定，而不是由文件路径决定
-- 本地工具会从 `resources/tools/**/*.js|*.mjs|*.cjs` 中自动发现，前提是模块导出 `tool({...})`
-- skills 会从 `resources/skills/**/SKILL.md` 自动发现
+- `Runtime.spec.sources.tools` 默认值是 `file://./resources/tools`
+- `Runtime.spec.sources.skills` 默认值是 `file://./resources/skills`
+- file-based 工具会从每个声明的 tool source 自动发现，前提是模块导出 `tool({...})`
+- file-based skills 会从每个声明的 skill source 自动发现
 - 一个最小工作区只放 `config/models.yaml` 也可以启动；仓库默认值会补上 `Runtime`、默认 `orchestra` host，以及默认开启的 runtime-managed durable memory
 - 如果不显式覆盖 runtime 放置位置，harness 生成的数据默认写到 `./.botbotgo/`
 
@@ -740,7 +760,9 @@ await stop(runtime);
 
 配置大致分这几层（由下至上叠加）：
 
-- workspace 启动时扫描本地与附加的 `resources` 包，建立统一 registry
+- 先由 `Runtime.spec.sources` 声明工作区实际拥有的 tool / skill 来源
+- workspace 启动时只扫描这些显式声明的 source，并建立统一 registry
+- workspace 启动时扫描本地与附加的 `resources` 包，建立统一 registry；这条兼容路径仍可继续工作
 - 各 agent 再按名称白名单选用 tools 与 skills
 - `config/runtime/workspace.yaml` 承载运行时策略
 - `config/catalogs/*.yaml` 承载可复用对象目录
@@ -776,6 +798,8 @@ await stop(runtime);
 
 - `runtimeRoot`
 - `concurrency.maxConcurrentRequests`
+- `sources.tools`
+- `sources.skills`
 - `routing.defaultAgentId`
 - `routing.rules`
 - `routing.systemPrompt`
@@ -793,7 +817,17 @@ await stop(runtime);
 - `maintenance.checkpoints` 清理后端用于 resume/recovery 的 checkpoint 状态
 - `maintenance.records` 清理 harness 自己保存在 `runtime.sqlite` 中、已结束的 session/request 记录
 
-`toolModuleDiscovery.scope` 用来控制本地 `resources/tools/` 这类 tool module 目录的发现范围：
+`sources.tools` 用来声明哪些 tool root 或 package 参与工作区发现：
+
+- `file://...` 用于目录扫描
+- `npm://...` 用于包入口发现；本地缺失时自动安装
+
+`sources.skills` 用来声明哪些 skill 目录或 skill 文档参与工作区发现：
+
+- `file://...` 用于本地目录、skill root 或直接 `SKILL.md`
+- `http://...` / `https://...` 用于单个远程 `SKILL.md`
+
+`toolModuleDiscovery.scope` 用来控制本地 `resources/tools/` 风格 file source 的发现范围：
 
 - `recursive` 是默认值，会继续扫描嵌套目录
 - `top-level` 只发现每个工具根目录下一层文件，同时保留 YAML catalog 的递归发现
@@ -910,6 +944,8 @@ spec:
 - `KnowledgeRuntime`：hot path + 后台形成 + 长期养护
 - `ProceduralMemoryRuntime`：后台形成 + 定时或空闲整理
 
+在当前已发布的 runtime 里，像“请记住我最近搬到了美国”这种显式 durable fact 仍然走 `KnowledgeRuntime`，并写入 `knowledge/knowledge.sqlite`。后台 procedural learning 会在同一个 data root 下单独写自己的 store 与 state 文件，例如 `knowledge/procedural-memory.sqlite` 和 `knowledge/procedural-memory-state.json`。
+
 对于 `backend: deepagent` 的工作区，应继续把 context compaction 留给上游 DeepAgents，只把 procedural memory 当作后台学习层使用。
 
 ### `config/catalogs/backends.yaml`

package/dist/config/runtime/workspace.yaml

@@ -29,6 +29,22 @@ spec:
   # agent-harness feature: stable runtime profile identifier for this data folder.
   profile: default
 
+  # agent-harness feature: explicit tool and skill discovery sources.
+  # The default local workspace contract stays:
+  # - tools from ./resources/tools
+  # - skills from ./resources/skills
+  #
+  # Supported source forms today:
+  # - tools: file://<folder>, npm://<package-or-spec>
+  # - skills: file://<folder-or-SKILL.md>, http(s)://.../SKILL.md
+  #
+  # Discovery never traverses node_modules directories.
+  sources:
+    tools:
+      - file://./resources/tools
+    skills:
+      - file://./resources/skills
+
   # agent-harness feature: runtime-level task queue and maximum number of concurrent requests.
   # Additional requests wait in the harness queue until a slot becomes available.
   concurrency:

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.305";
+export declare const AGENT_HARNESS_VERSION = "0.0.307";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.305";
+export const AGENT_HARNESS_VERSION = "0.0.307";

package/dist/procedural/index.d.ts

@@ -1,2 +1,3 @@
 export { readProceduralMemoryRuntimeConfig } from "./config.js";
+export { createBackgroundProceduralCandidates, createProceduralMemoryManager, ProceduralMemoryFormationSync, } from "./manager.js";
 export type { ProceduralMemoryBackgroundConfig, ProceduralMemoryFormationConfig, ProceduralMemoryMaintenanceConfig, ProceduralMemoryMaintenanceIdleConfig, ProceduralMemoryMaintenanceScheduleConfig, ProceduralMemoryProviderConfig, ProceduralMemoryRetrievalConfig, ProceduralMemoryRuntimeConfig, } from "./config.js";

package/dist/procedural/index.js

@@ -1 +1,2 @@
 export { readProceduralMemoryRuntimeConfig } from "./config.js";
+export { createBackgroundProceduralCandidates, createProceduralMemoryManager, ProceduralMemoryFormationSync, } from "./manager.js";

package/dist/procedural/manager.d.ts

@@ -0,0 +1,59 @@
+import type { CompiledAgentBinding, HarnessEvent, HarnessEventProjection, InternalApprovalRecord, MemoryCandidate, MemoryRecord, SessionSummary, TranscriptMessage, WorkspaceBundle } from "../contracts/types.js";
+import type { RuntimePersistence } from "../persistence/types.js";
+import { type StoreLike } from "../runtime/harness/system/store.js";
+import type { ProceduralMemoryRuntimeConfig } from "./config.js";
+type ProceduralMemoryWriter = (input: {
+    candidates: MemoryCandidate[];
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    userId?: string;
+    projectId?: string;
+    recordedAt: string;
+}) => Promise<void>;
+type ProceduralMemoryFormationOptions = {
+    userId?: string;
+    projectId?: string;
+};
+type ProceduralMemoryManagerLike = {
+    transform(input: {
+        candidates: MemoryCandidate[];
+        binding: CompiledAgentBinding;
+        sessionId: string;
+        requestId: string;
+        recordedAt: string;
+        existingRecords: MemoryRecord[];
+    }): Promise<MemoryCandidate[]>;
+};
+export declare function createBackgroundProceduralCandidates(input: {
+    session: SessionSummary;
+    requestId: string;
+    agentId: string;
+    trigger: "approval.resolved" | "request.completed";
+    recordedAt: string;
+    messages: TranscriptMessage[];
+    approvals: InternalApprovalRecord[];
+    focus: string[];
+}): MemoryCandidate[];
+export declare function createProceduralMemoryManager(input: {
+    workspace: WorkspaceBundle;
+    binding: CompiledAgentBinding;
+    config: ProceduralMemoryRuntimeConfig;
+    modelResolver?: (modelId: string) => unknown;
+}): ProceduralMemoryManagerLike;
+export declare class ProceduralMemoryFormationSync implements HarnessEventProjection {
+    private readonly persistence;
+    private readonly config;
+    private readonly writer;
+    private readonly stateStore;
+    private readonly options;
+    private readonly pending;
+    private syncChain;
+    readonly name = "procedural-memory-formation-sync";
+    constructor(persistence: RuntimePersistence, config: ProceduralMemoryRuntimeConfig, writer: ProceduralMemoryWriter, runtimeRoot: string, stateStore?: StoreLike, options?: ProceduralMemoryFormationOptions);
+    shouldHandle(event: HarnessEvent): boolean;
+    handleEvent(event: HarnessEvent): Promise<void>;
+    private reflectRun;
+    close(): Promise<void>;
+}
+export {};

package/dist/procedural/manager.js

@@ -0,0 +1,345 @@
+import path from "node:path";
+import { extractMessageText } from "../utils/message-content.js";
+import { createResolvedModel } from "../runtime/adapter/model/model-providers.js";
+import { FileBackedStore } from "../runtime/harness/system/store.js";
+import { compileModel } from "../workspace/resource-compilers.js";
+import { resolveRefId } from "../workspace/support/workspace-ref-utils.js";
+import { renderProceduralMemoryManagerPrompt } from "../runtime/support/runtime-prompts.js";
+const FORMATION_EVENT_TYPES = new Set([
+    "request.state.changed",
+    "approval.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(", ");
+}
+function fingerprintMessages(messages, focus) {
+    const serialized = messages
+        .map((message) => `${message.role}\n${message.createdAt}\n${extractMessageText(message.content)}`)
+        .join("\n---\n");
+    return `${focus.join(",")}::${serialized}`;
+}
+function selectRelatedContextRecords(candidate, existingRecords, maxRecords) {
+    const candidateText = `${candidate.summary ?? ""}\n${candidate.content}`.toLowerCase().trim();
+    if (!candidateText) {
+        return existingRecords.slice(0, maxRecords);
+    }
+    return existingRecords
+        .filter((record) => record.status === "active")
+        .map((record) => {
+        let score = 0;
+        const recordText = `${record.summary}\n${record.content}`.toLowerCase();
+        if (candidate.scope && record.scope === candidate.scope) {
+            score += 2;
+        }
+        if (recordText.includes(candidateText) || candidateText.includes(recordText)) {
+            score += 4;
+        }
+        const candidateTokens = new Set(candidateText.split(/[^a-z0-9_\u4e00-\u9fff]+/iu).filter((token) => token.length > 1));
+        const recordTokens = new Set(recordText.split(/[^a-z0-9_\u4e00-\u9fff]+/iu).filter((token) => token.length > 1));
+        let shared = 0;
+        for (const token of candidateTokens) {
+            if (recordTokens.has(token)) {
+                shared += 1;
+            }
+        }
+        score += shared;
+        return { record, score };
+    })
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || right.record.lastConfirmedAt.localeCompare(left.record.lastConfirmedAt))
+        .slice(0, maxRecords)
+        .map((item) => item.record);
+}
+function extractText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    if ("content" in value && typeof value.content === "string") {
+        return String(value.content);
+    }
+    const kwargs = "kwargs" in value && typeof value.kwargs === "object" && value.kwargs !== null
+        ? value.kwargs
+        : undefined;
+    if (typeof kwargs?.content === "string") {
+        return kwargs.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 asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const items = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    return items.length > 0 ? Array.from(new Set(items)) : undefined;
+}
+function normalizeScope(value) {
+    return value === "session" || value === "agent" || value === "workspace" || value === "user" || value === "project"
+        ? value
+        : undefined;
+}
+function normalizeCandidateOutputs(parsed, candidate) {
+    const rawOutputs = Array.isArray(parsed.mutations)
+        ? parsed.mutations.filter((item) => typeof item === "object" && item !== null && !Array.isArray(item))
+        : [parsed];
+    return rawOutputs.map((output) => ({
+        ...candidate,
+        kind: "procedural",
+        scope: normalizeScope(output.scope) ?? candidate.scope ?? "workspace",
+        summary: asString(output.summary) ?? candidate.summary,
+        content: asString(output.content) ?? candidate.content,
+        confidence: asNumber(output.confidence) ?? candidate.confidence ?? 0.72,
+        tags: asStringArray(output.tags) ?? candidate.tags,
+    })).filter((item) => typeof item.content === "string" && item.content.trim().length > 0);
+}
+export function createBackgroundProceduralCandidates(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 transcriptPreview = input.messages
+        .slice(-6)
+        .map((message) => `${message.role}: ${excerpt(message) ?? "(empty)"}`)
+        .join("\n");
+    const approvals = summarizeApprovals(input.approvals);
+    const sourceRef = `runtime://sessions/${input.session.sessionId}/requests/${input.requestId}/procedural-reflection`;
+    return [{
+            kind: "procedural",
+            scope: "workspace",
+            sourceType: "runtime-transcript",
+            sourceRef,
+            summary: latestUser ?? latestAssistant ?? `Procedural reflection for ${input.requestId}`,
+            content: [
+                "Completed run transcript evidence for procedural memory extraction.",
+                `Trigger: ${input.trigger}`,
+                `Focus: ${input.focus.join(", ")}`,
+                "",
+                "Latest user message:",
+                latestUser ?? "(none)",
+                "",
+                "Latest assistant response:",
+                latestAssistant ?? "(none)",
+                "",
+                "Recent transcript excerpt:",
+                transcriptPreview || "(none)",
+                "",
+                "Approval snapshot:",
+                approvals,
+            ].join("\n"),
+            confidence: 0.64,
+            observedAt: input.recordedAt,
+            tags: ["procedural-background-extraction", input.trigger, ...input.focus],
+        }];
+}
+async function runProceduralMemoryManager(input) {
+    let resolvedModel;
+    try {
+        resolvedModel = await createResolvedModel(input.model, input.modelResolver);
+    }
+    catch {
+        return input.candidates;
+    }
+    const invoker = resolvedModel;
+    if (typeof invoker.invoke !== "function") {
+        return input.candidates;
+    }
+    const transformed = [];
+    for (const candidate of input.candidates) {
+        const prompt = renderProceduralMemoryManagerPrompt({
+            candidate,
+            sessionId: input.sessionId,
+            requestId: input.requestId,
+            focus: input.focus,
+            existingRecords: selectRelatedContextRecords(candidate, input.existingRecords, input.maxContextRecords ?? input.existingRecords.length),
+        });
+        let response;
+        try {
+            response = await invoker.invoke(prompt, {});
+        }
+        catch {
+            continue;
+        }
+        const parsed = tryParseJsonObject(extractText(response) ?? "");
+        if (!parsed || parsed.store === false) {
+            continue;
+        }
+        transformed.push(...normalizeCandidateOutputs(parsed, candidate));
+    }
+    return transformed;
+}
+export function createProceduralMemoryManager(input) {
+    return {
+        async transform({ candidates, binding, sessionId, requestId, recordedAt, existingRecords }) {
+            if (input.config.enabled !== true || candidates.length === 0) {
+                return candidates;
+            }
+            if (!binding.langchainAgentParams?.model) {
+                return candidates;
+            }
+            const providerModelRef = asString(input.config.provider?.options?.modelRef);
+            const primaryModel = (() => {
+                if (!providerModelRef) {
+                    return binding.langchainAgentParams.model;
+                }
+                const configured = input.workspace.models.get(resolveRefId(providerModelRef));
+                return configured ? compileModel(configured) : binding.langchainAgentParams.model;
+            })();
+            return runProceduralMemoryManager({
+                workspace: input.workspace,
+                binding,
+                model: primaryModel,
+                candidates,
+                sessionId,
+                requestId,
+                recordedAt,
+                existingRecords: existingRecords.filter((record) => record.status === "active"),
+                focus: input.config.formation?.background?.scopeHints ?? ["workflow_patterns", "debugging_lessons", "reusable_procedures"],
+                maxContextRecords: 8,
+                modelResolver: input.modelResolver,
+            });
+        },
+    };
+}
+export class ProceduralMemoryFormationSync {
+    persistence;
+    config;
+    writer;
+    stateStore;
+    options;
+    pending = new Set();
+    syncChain = Promise.resolve();
+    name = "procedural-memory-formation-sync";
+    constructor(persistence, config, writer, runtimeRoot, stateStore = new FileBackedStore(path.join(runtimeRoot, config.formation?.background?.stateStorePath ?? "knowledge/procedural-memory-state.json")), options = {}) {
+        this.persistence = persistence;
+        this.config = config;
+        this.writer = writer;
+        this.stateStore = stateStore;
+        this.options = options;
+    }
+    shouldHandle(event) {
+        const background = this.config.formation?.background;
+        if (!background?.enabled || !FORMATION_EVENT_TYPES.has(event.eventType)) {
+            return false;
+        }
+        if (event.eventType === "approval.resolved") {
+            return background.writeOnApprovalResolution;
+        }
+        return background.writeOnRequestCompletion && event.payload.state === "completed";
+    }
+    async handleEvent(event) {
+        if (!this.shouldHandle(event)) {
+            return;
+        }
+        const trigger = event.eventType === "approval.resolved" ? "approval.resolved" : "request.completed";
+        const task = this.syncChain
+            .then(() => this.reflectRun(event.sessionId, event.requestId, trigger, event.timestamp))
+            .catch(() => {
+            // Fail open: procedural reflection should not block runtime progress.
+        });
+        this.syncChain = task
+            .catch(() => {
+            // Fail open: procedural reflection should not block runtime progress.
+        })
+            .finally(() => {
+            this.pending.delete(task);
+        });
+        this.pending.add(task);
+    }
+    async reflectRun(sessionId, requestId, trigger, recordedAt) {
+        const background = this.config.formation?.background;
+        if (!background) {
+            return;
+        }
+        const [session, run, allMessages, approvals] = await Promise.all([
+            this.persistence.getSession(sessionId),
+            this.persistence.getRequest(requestId),
+            this.persistence.listSessionMessages(sessionId, background.maxMessagesPerRequest),
+            this.persistence.getRequestApprovals(sessionId, requestId),
+        ]);
+        if (!session || !run) {
+            return;
+        }
+        const messages = allMessages.filter((message) => message.requestId === requestId);
+        if (messages.length === 0) {
+            return;
+        }
+        const fingerprint = fingerprintMessages(messages, background.scopeHints);
+        const namespace = ["memories", "formation", "sessions", sessionId, "requests"];
+        const cursor = await this.stateStore.get(namespace, requestId);
+        const existing = cursor?.value;
+        if (existing?.fingerprint === fingerprint && existing.trigger === trigger) {
+            return;
+        }
+        const candidates = createBackgroundProceduralCandidates({
+            session,
+            requestId,
+            agentId: run.agentId ?? session.agentId,
+            trigger,
+            recordedAt,
+            messages,
+            approvals,
+            focus: background.scopeHints,
+        });
+        await this.writer({
+            candidates,
+            sessionId,
+            requestId,
+            agentId: run.agentId ?? session.agentId,
+            userId: this.options.userId,
+            projectId: this.options.projectId,
+            recordedAt,
+        });
+        await this.stateStore.put(namespace, requestId, {
+            fingerprint,
+            candidateCount: candidates.length,
+            syncedAt: new Date().toISOString(),
+            trigger,
+        });
+    }
+    async close() {
+        await Promise.allSettled(Array.from(this.pending));
+    }
+}