@tangle-network/agent-runtime 0.92.0 → 0.93.0

package/README.md

@@ -69,22 +69,32 @@ const result = await supervise(
 ### Improve an agent
 
 `improve` optimizes one part of an agent and **only ships a change if it beats the current agent on tasks it never practiced on**.
-It accepts prompt, skill document, tool, MCP, hook, subagent, workflow, rollout-policy, whole-profile, and code surfaces through one call.
-Prompt and skill-document optimization have built-in generators; structured surfaces take an explicit generator, and code runs from isolated incumbent and candidate checkouts.
+It accepts prompt, skill document, curated memory, tool, MCP, hook, subagent, workflow, rollout-policy, whole-profile, and code surfaces through one call.
+Prompt, skill-document, memory, and rollout-policy optimization have built-in generators; structured surfaces take an explicit generator, and code runs from isolated incumbent and candidate checkouts.
 
 ```ts
 import { improve } from '@tangle-network/agent-runtime'
 
 const { profile, shipped, lift } = await improve(baseProfile, findings, {
-  surface: 'prompt',        // or skills/tools/mcp/hooks/subagents/workflow/agent-profile/code
+  surface: 'prompt',        // or skills/memory/tools/mcp/hooks/subagents/workflow/agent-profile/rollout-policy/code
   gate: 'holdout',          // certified on a held-back exam, never the practice set
   scenarios, judge, agent,  // how to measure a candidate
 })
 ```
 
+Curated memory is an external lesson document, not a knowledge store. Supply its current text and persist only the promoted winner:
+
+```ts
+await improve(baseProfile, findings, {
+  surface: 'memory',
+  memory: { document: currentLessons, writeBack: saveLessons },
+  scenarios, judge, agent,
+})
+```
+
 ### Improve a knowledge base
 
-`runKnowledgeImprovementJob` is the runtime-owned front door for KB, wiki, memory-backed, and RAG improvement jobs. It creates a candidate copy, runs supervised agents against it, checks readiness through `@tangle-network/agent-knowledge`, measures spend and timing, and promotes only when the candidate passes.
+`runKnowledgeImprovementJob` is the runtime-owned front door for KB, wiki, memory-backed, and RAG improvement jobs. It creates a candidate copy, runs supervised agents against it, checks readiness through `@tangle-network/agent-knowledge`, measures spend and timing, and promotes only when the candidate passes. Use `improve(..., { surface: 'memory' })` for the agent's curated lesson document; use this job for source, retrieval, and knowledge-store changes.
 
 ```ts
 import { runKnowledgeImprovementJob } from '@tangle-network/agent-runtime/knowledge'

package/dist/agent.js

@@ -1,10 +1,10 @@
-import "./chunk-I7WVPJBZ.js";
-import "./chunk-3BE7KTMU.js";
+import "./chunk-BVVRQ4YC.js";
+import "./chunk-FDJ7AHXG.js";
 import {
   createSandboxForSpec
-} from "./chunk-6O5USWVH.js";
+} from "./chunk-UO2L5VTP.js";
 import "./chunk-DPEUKJRO.js";
-import "./chunk-APVPRF4Y.js";
+import "./chunk-J2K6WIG6.js";
 import "./chunk-3D2RHC4K.js";
 import "./chunk-VSWBYWFK.js";
 import "./chunk-3MDZX7YU.js";
@@ -21,7 +21,7 @@ import {
 
 // src/agent/surfaces.ts
 import { existsSync, statSync } from "fs";
-import { isAbsolute, join } from "path";
+import { isAbsolute, join, relative, resolve, sep } from "path";
 function resolveSubjectPath(subject, surfaces, repoRoot) {
   const candidates = candidatePathsForSubject(subject, surfaces);
   if (candidates.length === 0) return null;
@@ -44,62 +44,62 @@ function candidatePathsForSubject(subject, surfaces) {
   switch (subject.kind) {
     case "knowledge.wiki":
     case "knowledge.stale":
-      return [join(surfaces.knowledge, `${subject.slug}.md`)];
+      return optionalPath(safeJoin(surfaces.knowledge, `${subject.slug}.md`));
     case "knowledge.claim":
-      return [join(surfaces.knowledge, "claims", `${slugify(subject.topic)}.md`)];
+      return optionalPath(safeJoin(surfaces.knowledge, "claims", `${slugify(subject.topic)}.md`));
     case "knowledge.raw":
-      return optionalPath(safeJoin(join(surfaces.knowledge, "raw"), `${subject.sourceId}.md`));
+      return optionalPath(safeJoin(surfaces.knowledge, "raw", `${subject.sourceId}.md`));
     case "system-prompt": {
       const slug = slugify(subject.section);
       return [
-        join(surfaces.systemPrompt, `${slug}.md`),
-        join(surfaces.systemPrompt, slug, "SKILL.md"),
-        join(surfaces.systemPrompt, slug, "index.md")
-      ];
+        safeJoin(surfaces.systemPrompt, `${slug}.md`),
+        safeJoin(surfaces.systemPrompt, slug, "SKILL.md"),
+        safeJoin(surfaces.systemPrompt, slug, "index.md")
+      ].filter((path) => path !== null);
     }
     case "skill": {
       if (!surfaces.skills) return [];
       return [
-        join(surfaces.skills, subject.name, "SKILL.md"),
-        join(surfaces.skills, `${subject.name}.md`)
-      ];
+        safeJoin(surfaces.skills, subject.name, "SKILL.md"),
+        safeJoin(surfaces.skills, `${subject.name}.md`)
+      ].filter((path) => path !== null);
     }
     case "tool-doc":
       if (subject.aspect) {
-        return [join(surfaces.tools, subject.tool, `${slugify(subject.aspect)}.md`)];
+        return optionalPath(safeJoin(surfaces.tools, subject.tool, `${slugify(subject.aspect)}.md`));
       }
       return [
-        join(surfaces.tools, subject.tool, "README.md"),
-        join(surfaces.tools, `${subject.tool}.md`)
-      ];
+        safeJoin(surfaces.tools, subject.tool, "README.md"),
+        safeJoin(surfaces.tools, `${subject.tool}.md`)
+      ].filter((path) => path !== null);
     case "new-tool":
-      return [join(surfaces.tools, subject.name, "README.md")];
+      return optionalPath(safeJoin(surfaces.tools, subject.name, "README.md"));
     case "mcp":
       if (!surfaces.mcp) return [];
-      return subject.tool ? [join(surfaces.mcp, subject.server, `${subject.tool}.md`)] : [
-        join(surfaces.mcp, `${subject.server}.json`),
-        join(surfaces.mcp, subject.server, "README.md")
-      ];
+      return subject.tool ? optionalPath(safeJoin(surfaces.mcp, subject.server, `${subject.tool}.md`)) : [
+        safeJoin(surfaces.mcp, `${subject.server}.json`),
+        safeJoin(surfaces.mcp, subject.server, "README.md")
+      ].filter((path) => path !== null);
     case "hook":
       if (!surfaces.hooks) return [];
       return [
-        join(surfaces.hooks, `${subject.name}.md`),
-        join(surfaces.hooks, `${subject.name}.json`)
-      ];
+        safeJoin(surfaces.hooks, `${subject.name}.md`),
+        safeJoin(surfaces.hooks, `${subject.name}.json`)
+      ].filter((path) => path !== null);
     case "subagent":
       if (!surfaces.subagents) return [];
       return [
-        join(surfaces.subagents, `${subject.name}.md`),
-        join(surfaces.subagents, `${subject.name}.yaml`),
-        join(surfaces.subagents, `${subject.name}.json`)
-      ];
+        safeJoin(surfaces.subagents, `${subject.name}.md`),
+        safeJoin(surfaces.subagents, `${subject.name}.yaml`),
+        safeJoin(surfaces.subagents, `${subject.name}.json`)
+      ].filter((path) => path !== null);
     case "workflow":
       if (!surfaces.workflows) return [];
       return [
-        join(surfaces.workflows, `${subject.name}.md`),
-        join(surfaces.workflows, `${subject.name}.yaml`),
-        join(surfaces.workflows, `${subject.name}.json`)
-      ];
+        safeJoin(surfaces.workflows, `${subject.name}.md`),
+        safeJoin(surfaces.workflows, `${subject.name}.yaml`),
+        safeJoin(surfaces.workflows, `${subject.name}.json`)
+      ].filter((path) => path !== null);
     case "rollout-policy":
       return surfaces.rolloutPolicy ? [surfaces.rolloutPolicy] : [];
     case "agent-profile":
@@ -111,13 +111,13 @@ function candidatePathsForSubject(subject, surfaces) {
     }
     case "rag":
       if (!surfaces.rag) return [];
-      return optionalPath(safeJoin(join(surfaces.rag, subject.corpus), `${subject.docId}.md`));
+      return optionalPath(safeJoin(surfaces.rag, subject.corpus, `${subject.docId}.md`));
     case "memory":
       if (!surfaces.memory) return [];
-      return [join(surfaces.memory, `${slugify(subject.key)}.json`)];
+      return optionalPath(safeJoin(surfaces.memory, `${slugify(subject.key)}.json`));
     case "scaffolding":
       if (!surfaces.scaffolding) return [];
-      return [join(surfaces.scaffolding, `${slugify(subject.concern)}.md`)];
+      return optionalPath(safeJoin(surfaces.scaffolding, `${slugify(subject.concern)}.md`));
     case "output-schema":
       if (!surfaces.outputSchema) return [];
       return [surfaces.outputSchema];
@@ -128,11 +128,13 @@ function candidatePathsForSubject(subject, surfaces) {
       return [];
   }
 }
-function safeJoin(root, child) {
-  if (child.includes("\0") || isAbsolute(child)) return null;
-  const segments = child.replace(/\\/g, "/").split("/");
-  if (segments.some((segment) => segment === "..")) return null;
-  return join(root, ...segments);
+function safeJoin(root, ...children) {
+  if (children.some((child) => child.includes("\0") || isAbsolute(child))) return null;
+  const rootAbsolute = resolve(root);
+  const targetAbsolute = resolve(rootAbsolute, ...children);
+  const escaped = relative(rootAbsolute, targetAbsolute);
+  if (escaped === ".." || escaped.startsWith(`..${sep}`) || isAbsolute(escaped)) return null;
+  return join(root, ...children);
 }
 function optionalPath(path) {
   return path ? [path] : [];
@@ -748,8 +750,8 @@ function createSandboxAct(options) {
     const raw = [];
     let settle;
     let fail;
-    const output = new Promise((resolve, reject) => {
-      settle = resolve;
+    const output = new Promise((resolve2, reject) => {
+      settle = resolve2;
       fail = reject;
     });
     output.catch(() => {