@hexdecimal16/nexo 0.4.7 → 0.4.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/cli/src/areas.js +49 -0
- package/cli/src/common.js +1 -1
- package/cli/src/home-migrate.js +168 -0
- package/cli/src/main.js +6 -0
- package/cli/src/optimize.js +2 -5
- package/cli/src/ui.js +1 -1
- package/core/src/config/schema.js +1 -0
- package/core/src/engine/charged-completion.js +9 -4
- package/core/src/engine/errors.js +29 -2
- package/core/src/engine/prompts.js +1 -1
- package/core/src/engine/run.js +11 -6
- package/core/src/index.js +1 -0
- package/core/src/learn/areas.js +192 -0
- package/core/src/learn/job.js +15 -1
- package/core/src/learn/wiki.js +26 -18
- package/core/src/optimize/climb.js +0 -2
- package/core/src/optimize/optimize.js +2 -5
- package/core/src/optimize/scratchpad-wiki.js +7 -3
- package/optimize/src/engine.js +1 -22
- package/optimize/src/index.js +0 -1
- package/optimize/src/report.js +0 -2
- package/package.json +1 -1
- package/skills/bundled/wiki/SKILL.md +23 -13
- package/store/src/eval-cases.js +12 -6
- package/store/src/paths.js +2 -2
- package/tools/src/home-folders.js +36 -0
- package/tools/src/index.js +2 -0
- package/tools/src/wiki-page.js +78 -0
- package/tui/src/questions.js +31 -0
- package/web/public/area.html +23 -0
- package/web/public/cost.html +1 -1
- package/web/public/home.html +23 -0
- package/web/public/index.html +1 -1
- package/web/public/judge.html +1 -1
- package/web/public/learning.html +1 -1
- package/web/public/lib/api-types.ts +0 -2
- package/web/public/lib/optim-view.ts +1 -1
- package/web/public/lib/wikis-view.ts +3 -1
- package/web/public/optim.html +1 -1
- package/web/public/page.html +24 -0
- package/web/public/pages/area.ts +59 -0
- package/web/public/pages/home.ts +66 -0
- package/web/public/pages/page.ts +62 -0
- package/web/public/pages/wikis.ts +43 -6
- package/web/public/run.html +1 -1
- package/web/public/sessions.html +1 -1
- package/web/public/style.css +58 -0
- package/web/public/wikis.html +1 -1
- package/web/src/api.js +14 -9
- package/web/src/home-api.js +156 -0
- package/web/src/server.js +16 -0
- package/optimize/src/merge.js +0 -73
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { isAbsolute, join, relative, sep } from "node:path";
|
|
3
|
+
import { dataBlock } from "../../../scorers/src/index.js";
|
|
4
|
+
import { NexoError } from "../../../telemetry/src/index.js";
|
|
5
|
+
import { listHomeFolders } from "../../../tools/src/index.js";
|
|
6
|
+
import { Type } from "typebox";
|
|
7
|
+
import { structuredLearnCall } from "./caller.js";
|
|
8
|
+
/** Life areas live in the wikis directory as data. Code never names an area; the user approves every new one. */
|
|
9
|
+
export const AREAS_FILE = "areas.json";
|
|
10
|
+
export const FEED_FILE = "feed.jsonl";
|
|
11
|
+
export const DECISIONS_FILE = "decisions.jsonl";
|
|
12
|
+
/** Unsorted tasks sharing a label before that label is proposed as a new area. */
|
|
13
|
+
export const PROPOSAL_THRESHOLD = 3;
|
|
14
|
+
/** Runs scoring below this get an unverified feed line and no filed decisions. */
|
|
15
|
+
export const FILE_SCORE_FLOOR = 0.6;
|
|
16
|
+
const MAX_UNSORTED = 200;
|
|
17
|
+
export function emptyRegistry() {
|
|
18
|
+
return { version: 1, areas: [], unsorted: [] };
|
|
19
|
+
}
|
|
20
|
+
export function normalizeLabel(label) {
|
|
21
|
+
return label.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
|
|
22
|
+
}
|
|
23
|
+
function slug(label) {
|
|
24
|
+
return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "area";
|
|
25
|
+
}
|
|
26
|
+
/** Reads the registry; a missing file is an empty registry. An unreadable file throws so it is never overwritten. */
|
|
27
|
+
export function readRegistry(wikisDir) {
|
|
28
|
+
const file = join(wikisDir, AREAS_FILE);
|
|
29
|
+
if (!existsSync(file))
|
|
30
|
+
return emptyRegistry();
|
|
31
|
+
const parsed = JSON.parse(readFileSync(file, "utf8"));
|
|
32
|
+
return { version: 1, areas: Array.isArray(parsed.areas) ? parsed.areas : [], unsorted: Array.isArray(parsed.unsorted) ? parsed.unsorted : [] };
|
|
33
|
+
}
|
|
34
|
+
/** Writes the registry atomically (temp file, then rename). */
|
|
35
|
+
export function writeRegistry(wikisDir, registry) {
|
|
36
|
+
mkdirSync(wikisDir, { recursive: true });
|
|
37
|
+
const file = join(wikisDir, AREAS_FILE);
|
|
38
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
39
|
+
writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`);
|
|
40
|
+
renameSync(tmp, file);
|
|
41
|
+
}
|
|
42
|
+
export function areaMatches(area, label) {
|
|
43
|
+
const n = normalizeLabel(label);
|
|
44
|
+
return n !== "" && [area.id, area.name, ...area.aliases].some((x) => normalizeLabel(x) === n);
|
|
45
|
+
}
|
|
46
|
+
/** Queues an unsorted task. Once PROPOSAL_THRESHOLD queued tasks share a label no area covers, that label becomes a proposed area. */
|
|
47
|
+
export function recordUnsorted(registry, item) {
|
|
48
|
+
const unsorted = [...registry.unsorted, item].slice(-MAX_UNSORTED);
|
|
49
|
+
const n = normalizeLabel(item.label);
|
|
50
|
+
if (n === "" || registry.areas.some((a) => areaMatches(a, item.label)))
|
|
51
|
+
return { registry: { ...registry, unsorted }, proposed: null };
|
|
52
|
+
const same = unsorted.filter((u) => normalizeLabel(u.label) === n);
|
|
53
|
+
if (same.length < PROPOSAL_THRESHOLD)
|
|
54
|
+
return { registry: { ...registry, unsorted }, proposed: null };
|
|
55
|
+
let id = slug(item.label);
|
|
56
|
+
for (let i = 2; registry.areas.some((a) => a.id === id); i++)
|
|
57
|
+
id = `${slug(item.label)}-${i}`;
|
|
58
|
+
const proposed = {
|
|
59
|
+
id,
|
|
60
|
+
name: item.label.trim(),
|
|
61
|
+
scope: `Proposed from ${same.length} unsorted tasks. Write a scope note before approving.`,
|
|
62
|
+
examples: same.slice(-3).map((u) => u.reason),
|
|
63
|
+
aliases: [],
|
|
64
|
+
wikis: [],
|
|
65
|
+
status: "proposed",
|
|
66
|
+
createdAt: item.at,
|
|
67
|
+
};
|
|
68
|
+
return { registry: { ...registry, unsorted, areas: [...registry.areas, proposed] }, proposed };
|
|
69
|
+
}
|
|
70
|
+
/** Makes a proposed area active. Only a user action should call this. */
|
|
71
|
+
export function approveArea(registry, id) {
|
|
72
|
+
const area = registry.areas.find((a) => a.id === id);
|
|
73
|
+
if (!area)
|
|
74
|
+
throw new NexoError({ code: "NOT_FOUND", message: `No area "${id}"`, context: { id } });
|
|
75
|
+
if (area.status === "active")
|
|
76
|
+
throw new NexoError({ code: "CONFLICT", message: `Area "${id}" is already active`, context: { id } });
|
|
77
|
+
return { ...registry, areas: registry.areas.map((a) => (a.id === id ? { ...a, status: "active" } : a)) };
|
|
78
|
+
}
|
|
79
|
+
/** Mean value of the latest scoring round, or null when the run has no valued scores. */
|
|
80
|
+
export function runScoreMean(scores) {
|
|
81
|
+
if (scores.length === 0)
|
|
82
|
+
return null;
|
|
83
|
+
const last = Math.max(...scores.map((s) => s.round));
|
|
84
|
+
const values = scores.filter((s) => s.round === last && typeof s.value === "number").map((s) => s.value);
|
|
85
|
+
return values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : null;
|
|
86
|
+
}
|
|
87
|
+
/** The run's ask_user questions and answers, the most reliable record of the user's decisions. */
|
|
88
|
+
export function askUserAnswers(spans) {
|
|
89
|
+
return spans
|
|
90
|
+
.filter((s) => s.kind === "tool_call" && s.name === "ask_user" && s.status === "ok")
|
|
91
|
+
.map((s) => {
|
|
92
|
+
const attrs = (s.attrs ?? {});
|
|
93
|
+
const args = (attrs.args ?? {});
|
|
94
|
+
return JSON.stringify({ questions: args.questions, answer: attrs.result ?? attrs.output ?? attrs.text }).slice(0, 1500);
|
|
95
|
+
})
|
|
96
|
+
.slice(-5);
|
|
97
|
+
}
|
|
98
|
+
/** HTML wiki pages (relative to the wikis dir) that the run's write and edit tool calls changed. */
|
|
99
|
+
export function wikiPagesTouched(spans, wikisDir) {
|
|
100
|
+
const out = [];
|
|
101
|
+
for (const s of spans) {
|
|
102
|
+
if (s.kind !== "tool_call" || s.status !== "ok" || (s.name !== "write" && s.name !== "edit"))
|
|
103
|
+
continue;
|
|
104
|
+
const path = (s.attrs ?? {}).args?.path;
|
|
105
|
+
if (typeof path !== "string" || !isAbsolute(path))
|
|
106
|
+
continue;
|
|
107
|
+
const rel = relative(wikisDir, path);
|
|
108
|
+
if (!rel || rel.startsWith("..") || isAbsolute(rel) || !rel.endsWith(".html"))
|
|
109
|
+
continue;
|
|
110
|
+
out.push(rel.split(sep).join("/"));
|
|
111
|
+
}
|
|
112
|
+
return out;
|
|
113
|
+
}
|
|
114
|
+
function listWikis(wikisDir) {
|
|
115
|
+
return listHomeFolders(wikisDir).map((f) => f.name);
|
|
116
|
+
}
|
|
117
|
+
export const AssignmentSchema = Type.Object({
|
|
118
|
+
areaId: Type.String({ minLength: 1, maxLength: 64 }),
|
|
119
|
+
unsortedLabel: Type.Optional(Type.String({ maxLength: 60 })),
|
|
120
|
+
wiki: Type.Optional(Type.String({ maxLength: 64 })),
|
|
121
|
+
feed: Type.String({ maxLength: 240 }),
|
|
122
|
+
decisions: Type.Array(Type.Object({ choice: Type.String({ minLength: 1, maxLength: 300 }), reason: Type.String({ maxLength: 300 }) }, { additionalProperties: false }), { maxItems: 5 }),
|
|
123
|
+
}, { additionalProperties: false });
|
|
124
|
+
export const ASSIGN_SYSTEM = `You file a finished task into the user's life areas.
|
|
125
|
+
The areas are a fixed list the user approved. Pick the one area whose scope fits the task and answer with its id. Never invent an area id.
|
|
126
|
+
If no area fits, set areaId to "unsorted" and give unsortedLabel: a short, broad name (one or two words) for the area the task would need. Prefer broad names such as "travel" over narrow ones such as "goa trip", and reuse a label from the queued list when it fits.
|
|
127
|
+
wiki: the existing wiki this task belongs to, from the wiki list, or omit it.
|
|
128
|
+
feed: one past-tense line for the user's home feed saying what happened, under 160 characters. Use "" for trivial tasks (small talk, a one-off lookup worth no record).
|
|
129
|
+
decisions: choices the user made in this task (answers to questions, or an option they picked or stated), each with the choice and the reason they gave. Only the user's choices, never the agent's own. Use [] when there are none.`;
|
|
130
|
+
export function assignPrompt(input) {
|
|
131
|
+
const areas = input.registry.areas.filter((a) => a.status === "active").map((a) => ({ id: a.id, name: a.name, scope: a.scope, examples: a.examples, aliases: a.aliases, wikis: a.wikis }));
|
|
132
|
+
const queued = [...new Set(input.registry.unsorted.map((u) => normalizeLabel(u.label)).filter(Boolean))].slice(-30);
|
|
133
|
+
return [
|
|
134
|
+
`# Areas\n${JSON.stringify(areas, null, 1)}`,
|
|
135
|
+
`# Queued unsorted labels\n${queued.join(", ") || "(none)"}`,
|
|
136
|
+
`# Wikis\n${input.wikis.join(", ") || "(none)"}`,
|
|
137
|
+
`# Working folder\n${input.cwd ?? "(unknown)"}`,
|
|
138
|
+
`# User instruction\n${dataBlock("instruction", input.instruction)}`,
|
|
139
|
+
`# Questions the user answered\n${dataBlock("answers", input.answers.join("\n") || "(none)")}`,
|
|
140
|
+
`# Final output\n${dataBlock("output", input.output.slice(0, 4000))}`,
|
|
141
|
+
].join("\n\n");
|
|
142
|
+
}
|
|
143
|
+
/** After a scored run: files it into an approved area (or the unsorted queue), appends a feed line and, for verified runs, the user's decisions. Does nothing until an area is active. */
|
|
144
|
+
export async function assignRun(deps, input) {
|
|
145
|
+
const none = { areaId: null, feed: false, decisions: 0, proposed: null, verified: false };
|
|
146
|
+
const wikisDir = deps.env.deps.paths?.homeRoot;
|
|
147
|
+
if (!wikisDir || !existsSync(wikisDir))
|
|
148
|
+
return none;
|
|
149
|
+
if (!input.output || input.output.trim().length < 50)
|
|
150
|
+
return none;
|
|
151
|
+
const registry = readRegistry(wikisDir);
|
|
152
|
+
const active = registry.areas.filter((a) => a.status === "active");
|
|
153
|
+
if (active.length === 0)
|
|
154
|
+
return none;
|
|
155
|
+
const wikis = listWikis(wikisDir);
|
|
156
|
+
const reply = await structuredLearnCall(deps, AssignmentSchema, {
|
|
157
|
+
system: ASSIGN_SYSTEM,
|
|
158
|
+
user: assignPrompt({ registry, wikis, cwd: input.cwd, instruction: input.run.instruction, answers: askUserAnswers(input.spans), output: input.output }),
|
|
159
|
+
tier: "curator",
|
|
160
|
+
});
|
|
161
|
+
const now = deps.env.now().toISOString();
|
|
162
|
+
const redact = deps.env.deps.redact;
|
|
163
|
+
const mean = runScoreMean(input.scores);
|
|
164
|
+
const verified = mean !== null && mean >= FILE_SCORE_FLOOR;
|
|
165
|
+
const known = active.find((a) => a.id === reply.areaId);
|
|
166
|
+
const wiki = reply.wiki && wikis.includes(reply.wiki) ? reply.wiki : null;
|
|
167
|
+
let proposed = null;
|
|
168
|
+
if (!known) {
|
|
169
|
+
const label = (reply.unsortedLabel ?? (reply.areaId === "unsorted" ? "" : reply.areaId)).trim();
|
|
170
|
+
if (label) {
|
|
171
|
+
const next = recordUnsorted(registry, { runId: input.run.id, label, reason: redact((reply.feed.trim() || input.run.instruction).slice(0, 200)), at: now });
|
|
172
|
+
writeRegistry(wikisDir, next.registry);
|
|
173
|
+
proposed = next.proposed?.id ?? null;
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
const areaId = known?.id ?? null;
|
|
177
|
+
const pages = [...new Set([...wikiPagesTouched(input.spans, wikisDir), ...(input.extraPages ?? [])])].filter((x) => x.endsWith(".html")).slice(0, 5);
|
|
178
|
+
const base = { at: now, runId: input.run.id, sessionId: input.run.sessionId ?? null, areaId, wiki, pages };
|
|
179
|
+
let fed = false;
|
|
180
|
+
if (reply.feed.trim()) {
|
|
181
|
+
appendFileSync(join(wikisDir, FEED_FILE), `${JSON.stringify({ ...base, text: redact(reply.feed.trim()), verified })}\n`);
|
|
182
|
+
fed = true;
|
|
183
|
+
}
|
|
184
|
+
let decisions = 0;
|
|
185
|
+
if (verified) {
|
|
186
|
+
for (const d of reply.decisions) {
|
|
187
|
+
appendFileSync(join(wikisDir, DECISIONS_FILE), `${JSON.stringify({ ...base, choice: redact(d.choice), reason: redact(d.reason) })}\n`);
|
|
188
|
+
decisions++;
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
return { areaId, feed: fed, decisions, proposed, verified };
|
|
192
|
+
}
|
package/core/src/learn/job.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { curateWikiKnowledge } from "./wiki.js";
|
|
2
|
+
import { assignRun } from "./areas.js";
|
|
2
3
|
import { existsSync } from "node:fs";
|
|
3
4
|
import { applyCuratorDelta, CURATOR_SYSTEM, CuratorDeltaSchema, curatorPrompt, REFLECTOR_SYSTEM, ReflectionSchema, reflectorPrompt, relevanceScores, } from "../../../memory/src/index.js";
|
|
4
5
|
import { renderTrajectory } from "../../../scorers/src/index.js";
|
|
@@ -89,6 +90,16 @@ export async function runLearnJob(env, job, options) {
|
|
|
89
90
|
output = "";
|
|
90
91
|
}
|
|
91
92
|
const feedback = latestFeedback(db, run.id);
|
|
93
|
+
const assignAreas = async (extraPages = []) => {
|
|
94
|
+
try {
|
|
95
|
+
await assignRun(deps, { run, output, spans, scores, extraPages, cwd: run.sessionId ? getSessionRow(db, run.sessionId)?.cwd : undefined });
|
|
96
|
+
}
|
|
97
|
+
catch (err) {
|
|
98
|
+
if (options.signal.aborted)
|
|
99
|
+
throw err;
|
|
100
|
+
logger.warn("area assignment failed; continuing without it", { run_id: run.id, error: err });
|
|
101
|
+
}
|
|
102
|
+
};
|
|
92
103
|
const reflectorUser = reflectorPrompt({
|
|
93
104
|
instruction: run.instruction,
|
|
94
105
|
status: run.status,
|
|
@@ -121,6 +132,7 @@ export async function runLearnJob(env, job, options) {
|
|
|
121
132
|
}
|
|
122
133
|
const reflection = await structuredLearnCall(deps, ReflectionSchema, { system: REFLECTOR_SYSTEM, user: reflectorUser, tier: "reflector" });
|
|
123
134
|
if (reflection.lessons.length === 0 && reflection.playbookTags.length === 0) {
|
|
135
|
+
await assignAreas();
|
|
124
136
|
markSucceeded();
|
|
125
137
|
return { lessons: 0, curation: null, costUsd, costUnknown };
|
|
126
138
|
}
|
|
@@ -182,12 +194,14 @@ export async function runLearnJob(env, job, options) {
|
|
|
182
194
|
throw error;
|
|
183
195
|
}
|
|
184
196
|
recorder.finish(writeSpan, { status: "ok", attrs: { result: curation } });
|
|
197
|
+
let curated = [];
|
|
185
198
|
try {
|
|
186
|
-
await curateWikiKnowledge(deps, run, output, spans);
|
|
199
|
+
curated = (await curateWikiKnowledge(deps, run, output, spans)).pages;
|
|
187
200
|
}
|
|
188
201
|
catch (err) {
|
|
189
202
|
logger.warn("wiki curation pass failed; continuing without it", { run_id: run.id, error: err });
|
|
190
203
|
}
|
|
204
|
+
await assignAreas(curated);
|
|
191
205
|
return { lessons: reflection.lessons.length, curation, costUsd, costUnknown };
|
|
192
206
|
}
|
|
193
207
|
catch (error) {
|
package/core/src/learn/wiki.js
CHANGED
|
@@ -1,9 +1,13 @@
|
|
|
1
1
|
import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
|
|
2
|
-
import { dirname, join } from "node:path";
|
|
2
|
+
import { dirname, join, relative, sep } from "node:path";
|
|
3
3
|
import { dataBlock } from "../../../scorers/src/index.js";
|
|
4
|
-
import { resolveConfined } from "../../../tools/src/index.js";
|
|
4
|
+
import { findHomeFolder, listHomeFolders, resolveConfined, UNSORTED_AREA, wrapWikiHtml } from "../../../tools/src/index.js";
|
|
5
5
|
import { Type } from "typebox";
|
|
6
6
|
import { structuredLearnCall } from "./caller.js";
|
|
7
|
+
function titleFromPath(path) {
|
|
8
|
+
const base = path.split("/").pop() ?? path;
|
|
9
|
+
return base.replace(/[.]html$/, "").replace(/-/g, " ");
|
|
10
|
+
}
|
|
7
11
|
export const WikiPageProposalSchema = Type.Object({
|
|
8
12
|
wikiName: Type.String({ minLength: 1, maxLength: 64, pattern: "^[a-z0-9]+(-[a-z0-9]+)*$" }),
|
|
9
13
|
path: Type.String({ minLength: 1, maxLength: 128 }),
|
|
@@ -13,8 +17,8 @@ export const WikiPageProposalSchema = Type.Object({
|
|
|
13
17
|
export const WikiCurationSchema = Type.Object({
|
|
14
18
|
pages: Type.Array(WikiPageProposalSchema, { maxItems: 4 }),
|
|
15
19
|
}, { additionalProperties: false });
|
|
16
|
-
export const WIKI_CURATOR_SYSTEM = `You are a knowledge curator for an AI agent's persistent
|
|
17
|
-
Review the finished task and its output. Determine if the task produced substantive, durable subject knowledge (research results, domain concepts, entity profiles, method syntheses, technical facts) that should be recorded into a
|
|
20
|
+
export const WIKI_CURATOR_SYSTEM = `You are a knowledge curator for an AI agent's persistent wikis of HTML pages.
|
|
21
|
+
Review the finished task and its output. Determine if the task produced substantive, durable subject knowledge (research results, domain concepts, entity profiles, method syntheses, technical facts) that should be recorded into a wiki for future reference.
|
|
18
22
|
|
|
19
23
|
Do NOT create wiki pages for:
|
|
20
24
|
- Routine code modifications, git operations or minor debugging
|
|
@@ -23,8 +27,8 @@ Do NOT create wiki pages for:
|
|
|
23
27
|
|
|
24
28
|
If durable subject knowledge is present:
|
|
25
29
|
- Select an appropriate wiki topic name in lowercase-with-hyphens (e.g. "ai", "finance", "distributed-systems").
|
|
26
|
-
- Propose pages using appropriate subfolders: "concepts/<slug>.
|
|
27
|
-
- Provide a concise summary and
|
|
30
|
+
- Propose pages using appropriate subfolders: "concepts/<slug>.html", "entities/<slug>.html", "sources/<slug>.html", or "analyses/<slug>.html".
|
|
31
|
+
- Provide a concise summary and the page content as an HTML body fragment for a human reader: no html, head, body or script elements. Start with <div class="tldr"> giving the answer in two or three sentences, then h2 sections, tables, <details> for side detail, and inline SVG for diagrams where they help. Link other pages with relative hrefs such as <a href="../concepts/slug.html">. Escape text as HTML.
|
|
28
32
|
If no substantive subject knowledge is worth saving, reply with {"pages": []}.`;
|
|
29
33
|
export function wikiCuratorPrompt(input) {
|
|
30
34
|
const wikisList = input.existingWikis.length > 0 ? input.existingWikis.join(", ") : "(no existing wikis)";
|
|
@@ -38,18 +42,18 @@ export function wikiCuratorPrompt(input) {
|
|
|
38
42
|
* Curates durable subject knowledge into persistent markdown wikis after a run.
|
|
39
43
|
*/
|
|
40
44
|
export async function curateWikiKnowledge(deps, run, output, spans) {
|
|
41
|
-
const wikisDir = deps.env.deps.paths?.
|
|
45
|
+
const wikisDir = deps.env.deps.paths?.homeRoot;
|
|
42
46
|
if (!wikisDir)
|
|
43
|
-
return { pagesCreated: 0, wikisTouched: [] };
|
|
47
|
+
return { pagesCreated: 0, wikisTouched: [], pages: [] };
|
|
44
48
|
if (!existsSync(wikisDir))
|
|
45
49
|
mkdirSync(wikisDir, { recursive: true });
|
|
46
50
|
// Skip if the run itself explicitly loaded the wiki skill (it managed its own wiki edits)
|
|
47
51
|
const usedWikiSkill = spans.some((s) => s.kind === "skill_load" && s.status === "ok" && s.attrs.args?.name === "wiki");
|
|
48
52
|
if (usedWikiSkill)
|
|
49
|
-
return { pagesCreated: 0, wikisTouched: [] };
|
|
53
|
+
return { pagesCreated: 0, wikisTouched: [], pages: [] };
|
|
50
54
|
// Only evaluate runs that have non-trivial instruction/output
|
|
51
55
|
if (!output || output.trim().length < 50)
|
|
52
|
-
return { pagesCreated: 0, wikisTouched: [] };
|
|
56
|
+
return { pagesCreated: 0, wikisTouched: [], pages: [] };
|
|
53
57
|
let existingWikis = [];
|
|
54
58
|
try {
|
|
55
59
|
existingWikis = readdirSync(wikisDir).filter((f) => {
|
|
@@ -66,6 +70,7 @@ export async function curateWikiKnowledge(deps, run, output, spans) {
|
|
|
66
70
|
catch {
|
|
67
71
|
existingWikis = [];
|
|
68
72
|
}
|
|
73
|
+
existingWikis = listHomeFolders(wikisDir).map((f) => f.name);
|
|
69
74
|
const prompt = wikiCuratorPrompt({
|
|
70
75
|
instruction: run.instruction,
|
|
71
76
|
output,
|
|
@@ -77,13 +82,14 @@ export async function curateWikiKnowledge(deps, run, output, spans) {
|
|
|
77
82
|
tier: "curator",
|
|
78
83
|
});
|
|
79
84
|
if (curation.pages.length === 0)
|
|
80
|
-
return { pagesCreated: 0, wikisTouched: [] };
|
|
85
|
+
return { pagesCreated: 0, wikisTouched: [], pages: [] };
|
|
81
86
|
let pagesCreated = 0;
|
|
87
|
+
const createdPages = [];
|
|
82
88
|
const wikisTouched = new Set();
|
|
83
89
|
const today = deps.env.now().toISOString().slice(0, 10);
|
|
84
90
|
for (const p of curation.pages) {
|
|
85
91
|
try {
|
|
86
|
-
const wikiDir = resolveConfined(wikisDir, p.wikiName);
|
|
92
|
+
const wikiDir = findHomeFolder(wikisDir, p.wikiName)?.dir ?? resolveConfined(wikisDir, `${UNSORTED_AREA}/${p.wikiName}`);
|
|
87
93
|
if (!existsSync(wikiDir)) {
|
|
88
94
|
mkdirSync(wikiDir, { recursive: true });
|
|
89
95
|
mkdirSync(join(wikiDir, "concepts"), { recursive: true });
|
|
@@ -92,15 +98,17 @@ export async function curateWikiKnowledge(deps, run, output, spans) {
|
|
|
92
98
|
mkdirSync(join(wikiDir, "analyses"), { recursive: true });
|
|
93
99
|
mkdirSync(join(wikiDir, "raw"), { recursive: true });
|
|
94
100
|
writeFileSync(join(wikiDir, "AGENTS.md"), `# ${p.wikiName} wiki\n\nKnowledge base for ${p.wikiName}.\n`);
|
|
95
|
-
writeFileSync(join(wikiDir, "index.
|
|
101
|
+
writeFileSync(join(wikiDir, "index.html"), wrapWikiHtml({ title: `${p.wikiName} index`, summary: `Index of the ${p.wikiName} wiki`, updated: today, sources: [], body: "<p>No pages yet.</p>" }));
|
|
96
102
|
writeFileSync(join(wikiDir, "log.md"), `# Log\n\n## [${today}] create | Initialized wiki\n`);
|
|
97
|
-
writeFileSync(join(wikiDir, "overview.
|
|
103
|
+
writeFileSync(join(wikiDir, "overview.html"), wrapWikiHtml({ title: `${p.wikiName} overview`, summary: `Overview of the ${p.wikiName} wiki`, updated: today, sources: [], body: "<p>No synthesis yet.</p>" }));
|
|
98
104
|
}
|
|
99
|
-
const
|
|
105
|
+
const pagePath = `${p.path.replace(/[.](md|html)$/, "")}.html`;
|
|
106
|
+
const targetFile = resolveConfined(wikiDir, pagePath);
|
|
100
107
|
mkdirSync(dirname(targetFile), { recursive: true });
|
|
101
|
-
const
|
|
102
|
-
writeFileSync(targetFile,
|
|
108
|
+
const pageHtml = wrapWikiHtml({ title: titleFromPath(pagePath), summary: p.summary, updated: today, sources: [`run:${run.id}`], body: p.content });
|
|
109
|
+
writeFileSync(targetFile, pageHtml);
|
|
103
110
|
pagesCreated++;
|
|
111
|
+
createdPages.push(relative(wikisDir, targetFile).split(sep).join("/"));
|
|
104
112
|
wikisTouched.add(p.wikiName);
|
|
105
113
|
const logFile = join(wikiDir, "log.md");
|
|
106
114
|
if (existsSync(logFile)) {
|
|
@@ -112,5 +120,5 @@ export async function curateWikiKnowledge(deps, run, output, spans) {
|
|
|
112
120
|
deps.env.deps.logger.warn("failed to write curated wiki page", { wiki: p.wikiName, path: p.path, error: err });
|
|
113
121
|
}
|
|
114
122
|
}
|
|
115
|
-
return { pagesCreated, wikisTouched: [...wikisTouched] };
|
|
123
|
+
return { pagesCreated, wikisTouched: [...wikisTouched], pages: createdPages };
|
|
116
124
|
}
|
|
@@ -164,7 +164,7 @@ export async function startOptimization(baseEnv, options) {
|
|
|
164
164
|
budgetRollouts: options.maxRollouts ?? null,
|
|
165
165
|
spentUsd: 0,
|
|
166
166
|
rollouts: 0,
|
|
167
|
-
merge:
|
|
167
|
+
merge: false,
|
|
168
168
|
seed,
|
|
169
169
|
baseArtifactId: base.id,
|
|
170
170
|
bestArtifactId: null,
|
|
@@ -244,7 +244,7 @@ export async function startOptimization(baseEnv, options) {
|
|
|
244
244
|
ctx.reserveUsd = cases.holdout.length * Math.min(config.budgets.perRunUsd, 2 * dearest);
|
|
245
245
|
ctx.phase = "loop";
|
|
246
246
|
options.onEvent?.({ type: "phase", phase: "loop" });
|
|
247
|
-
const wikisDir = env.deps.paths?.
|
|
247
|
+
const wikisDir = env.deps.paths?.homeRoot;
|
|
248
248
|
const seededPad = wikisDir ? readScratchpad(wikisDir, target.key) : undefined;
|
|
249
249
|
const result = await runGepa({
|
|
250
250
|
adapter,
|
|
@@ -257,7 +257,6 @@ export async function startOptimization(baseEnv, options) {
|
|
|
257
257
|
noveltySimilarity: config.optimize.noveltySimilarity,
|
|
258
258
|
...(seededPad ? { scratchpad: seededPad } : {}),
|
|
259
259
|
offspringAlpha: config.optimize.offspringAlpha,
|
|
260
|
-
merge: options.merge ?? false,
|
|
261
260
|
rng: mulberry32(seed),
|
|
262
261
|
signal,
|
|
263
262
|
callbacks: {
|
|
@@ -350,8 +349,6 @@ export async function startOptimization(baseEnv, options) {
|
|
|
350
349
|
spentUsd: ctx.budget.spentUsd,
|
|
351
350
|
rollouts: ctx.rollouts,
|
|
352
351
|
iterations: result.iterations,
|
|
353
|
-
merges: result.merges,
|
|
354
|
-
mergeNote: options.merge && result.merges === 0 && components.length === 1 ? `${target.key} has one component, so no merge is possible` : null,
|
|
355
352
|
createdAt: nowIso(),
|
|
356
353
|
});
|
|
357
354
|
writeFileSync(join(optimizer.runDir.root, "report.json"), `${JSON.stringify(redact(report), null, 2)}\n`);
|
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
2
2
|
import { dirname, join } from "node:path";
|
|
3
3
|
import { emptyScratchpad, SCRATCHPAD_ENTRIES, scratchpadEntry } from "../../../optimize/src/index.js";
|
|
4
|
-
import { resolveConfined } from "../../../tools/src/index.js";
|
|
4
|
+
import { findHomeFolder, resolveConfined, UNSORTED_AREA } from "../../../tools/src/index.js";
|
|
5
|
+
/** The scratchpad wiki folder: wherever it already lives under an area, else <root>/unsorted/optimization. */
|
|
6
|
+
function scratchpadDir(root) {
|
|
7
|
+
return findHomeFolder(root, SCRATCHPAD_WIKI)?.dir ?? resolveConfined(root, `${UNSORTED_AREA}/${SCRATCHPAD_WIKI}`);
|
|
8
|
+
}
|
|
5
9
|
/** The wiki that holds what optimizations learned: one page per target, readable and editable in the Wikis UI. */
|
|
6
10
|
export const SCRATCHPAD_WIKI = "optimization";
|
|
7
11
|
/** The page of `targetKey` inside the wiki, e.g. `analyses/optim-skill-web-research.md`. */
|
|
@@ -28,7 +32,7 @@ export function parseScratchpad(markdown) {
|
|
|
28
32
|
/** The saved scratchpad of a target, or undefined when there is no page, it has no entries or it cannot be read. */
|
|
29
33
|
export function readScratchpad(wikisDir, targetKey) {
|
|
30
34
|
try {
|
|
31
|
-
const file = resolveConfined(
|
|
35
|
+
const file = resolveConfined(scratchpadDir(wikisDir), scratchpadPagePath(targetKey));
|
|
32
36
|
if (!existsSync(file))
|
|
33
37
|
return undefined;
|
|
34
38
|
const pad = parseScratchpad(readFileSync(file, "utf8"));
|
|
@@ -40,7 +44,7 @@ export function readScratchpad(wikisDir, targetKey) {
|
|
|
40
44
|
}
|
|
41
45
|
/** Writes the target's scratchpad page (creating the wiki on first use) and logs it; returns the page file. */
|
|
42
46
|
export function writeScratchpad(wikisDir, targetKey, pad, info) {
|
|
43
|
-
const wikiDir =
|
|
47
|
+
const wikiDir = scratchpadDir(wikisDir);
|
|
44
48
|
const { today } = info;
|
|
45
49
|
if (!existsSync(wikiDir)) {
|
|
46
50
|
for (const d of ["concepts", "entities", "sources", "analyses", "raw"])
|
package/optimize/src/engine.js
CHANGED
|
@@ -1,12 +1,9 @@
|
|
|
1
|
-
import { findMerge } from "./merge.js";
|
|
2
1
|
import { bestCandidate, meanOf, paretoMembers, selectCandidate } from "./pareto.js";
|
|
3
2
|
import { NOVELTY_MAX_JACCARD, NOVELTY_MAX_SIMILARITY, textCosine, wordJaccard } from "./novelty.js";
|
|
4
3
|
import { checkPrediction, emptyScratchpad, SCRATCHPAD_ENTRIES, scratchpadEntry } from "./proposer.js";
|
|
5
4
|
import { sampleWithoutReplacement } from "./rng.js";
|
|
6
5
|
/** Feedback cases per minibatch (spec §8.2.2.3). */
|
|
7
6
|
export const MINIBATCH_SIZE = 3;
|
|
8
|
-
/** Most system-aware merges per optimization (spec §8.2.2.6). */
|
|
9
|
-
export const MAX_MERGES = 5;
|
|
10
7
|
/** Thrown by an adapter or a callback when the optimization's budget cannot pay for the next rollout or call. */
|
|
11
8
|
export class BudgetStop extends Error {
|
|
12
9
|
reason;
|
|
@@ -40,12 +37,10 @@ export async function runGepa(options) {
|
|
|
40
37
|
const refs = new Map([[options.seed.id, options.seed]]);
|
|
41
38
|
const nodes = new Map([[options.seed.id, { id: options.seed.id, parentIds: [] }]]);
|
|
42
39
|
const texts = new Map([[options.seed.id, options.seed.texts]]);
|
|
43
|
-
const tried = new Set();
|
|
44
40
|
const memberIds = () => new Set(paretoMembers(table, caseIds).map((m) => m.id));
|
|
45
41
|
const emit = (event) => callbacks.onEvent?.(event);
|
|
46
42
|
let iterations = 0;
|
|
47
43
|
let stale = 0;
|
|
48
|
-
let merges = 0;
|
|
49
44
|
let componentIndex = 0;
|
|
50
45
|
const scratchpad = emptyScratchpad();
|
|
51
46
|
if (options.scratchpad) {
|
|
@@ -160,22 +155,6 @@ export async function runGepa(options) {
|
|
|
160
155
|
stale = newMember ? 0 : stale + 1;
|
|
161
156
|
const mean = meanOf(perCase, caseIds);
|
|
162
157
|
emit({ type: "pareto", candidateId: child.id, meanQuality: mean.quality, meanCostUsd: mean.costUsd, newMember });
|
|
163
|
-
if (!options.merge || merges >= MAX_MERGES)
|
|
164
|
-
continue;
|
|
165
|
-
const plan = findMerge([...after], nodes, texts, tried);
|
|
166
|
-
if (!plan)
|
|
167
|
-
continue;
|
|
168
|
-
tried.add(`${plan.a}|${plan.b}`);
|
|
169
|
-
const merged = callbacks.createCandidate({ parentIds: [plan.a, plan.b], texts: plan.texts, iteration: iterations, origin: "merge", component: null });
|
|
170
|
-
remember(merged, [plan.a, plan.b]);
|
|
171
|
-
merges++;
|
|
172
|
-
const mergedCases = await evaluatePareto(merged);
|
|
173
|
-
table.set(merged.id, mergedCases);
|
|
174
|
-
const kept = memberIds().has(merged.id);
|
|
175
|
-
if (!kept)
|
|
176
|
-
table.delete(merged.id);
|
|
177
|
-
callbacks.recordPareto(merged.id, mergedCases, kept);
|
|
178
|
-
emit({ type: "merge", candidateId: merged.id, parents: [plan.a, plan.b], accepted: kept });
|
|
179
158
|
}
|
|
180
159
|
}
|
|
181
160
|
catch (error) {
|
|
@@ -186,7 +165,7 @@ export async function runGepa(options) {
|
|
|
186
165
|
else
|
|
187
166
|
throw error;
|
|
188
167
|
}
|
|
189
|
-
return { table, bestId: bestCandidate(table, caseIds), stopReason: stopReason ?? "patience", iterations,
|
|
168
|
+
return { table, bestId: bestCandidate(table, caseIds), stopReason: stopReason ?? "patience", iterations, scratchpad };
|
|
190
169
|
}
|
|
191
170
|
/** Children per candidate, counted from the lineage (rejected children count too). */
|
|
192
171
|
function offspringCounts(nodes) {
|
package/optimize/src/index.js
CHANGED
package/optimize/src/report.js
CHANGED
package/package.json
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: wiki
|
|
3
|
-
description: Create and maintain a persistent
|
|
3
|
+
description: Create and maintain a persistent wiki of HTML pages on one topic in the user's wikis directory (Karpathy's LLM-wiki pattern). Use it to start a wiki, ingest a source (article, paper, notes, research results) into it, answer a question from it, or health-check it. Load it before reading or writing any wiki.
|
|
4
4
|
metadata:
|
|
5
5
|
nexo-parallel-safe: "false"
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Wiki
|
|
9
9
|
|
|
10
|
-
A wiki is a folder of interlinked
|
|
10
|
+
A wiki is a folder of interlinked HTML pages that you build and keep current for the user. Knowledge is compiled once, when a source arrives, instead of being rediscovered on every question. You write and maintain the pages. The user brings sources and asks questions.
|
|
11
11
|
|
|
12
|
-
The wikis directory is named in your system prompt. Each wiki is one folder
|
|
12
|
+
The wikis directory is named in your system prompt. Each wiki is one folder one level under its area, named for its topic in lowercase with hyphens: `<wikis>/<area>/<name>/` (for example `<wikis>/builds/nexo/`). Reach it with absolute paths in `read`, `write`, `edit` and `bash`. Never put wiki pages in the run workspace and never touch other nexo files.
|
|
13
13
|
|
|
14
|
-
If the user does not name a wiki, list the wikis
|
|
14
|
+
If the user does not name a wiki, list the area folders (`ls <wikis>/*/`) and pick the wiki that fits the topic. If none fits and the task produced durable subject knowledge worth keeping, create a new wiki without asking and tell the user its name and why. Do not create a wiki for a one-off question or for knowledge about how you should behave (that belongs to memories and playbooks).
|
|
15
15
|
|
|
16
16
|
The wiki holds knowledge about a subject. Lessons about how you should behave next time belong to nexo's memories and playbooks, which you do not edit. Do not copy the same fact into both.
|
|
17
17
|
|
|
@@ -20,21 +20,31 @@ The wiki holds knowledge about a subject. Lessons about how you should behave ne
|
|
|
20
20
|
```
|
|
21
21
|
<name>/
|
|
22
22
|
AGENTS.md this wiki's schema: purpose, conventions, extra folders
|
|
23
|
-
index.
|
|
23
|
+
index.html catalog: one line per page (link, summary, date), grouped by folder
|
|
24
24
|
log.md append-only record of operations
|
|
25
25
|
raw/ immutable sources; read them, never edit them (raw/assets/ for images)
|
|
26
26
|
sources/ one summary page per raw source
|
|
27
27
|
entities/ people, organisations, tools, places
|
|
28
28
|
concepts/ ideas, methods, themes
|
|
29
29
|
analyses/ answers and comparisons worth keeping
|
|
30
|
-
overview.
|
|
30
|
+
overview.html the evolving top-level synthesis
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
+
## Areas
|
|
34
|
+
|
|
35
|
+
`<wikis>/areas.json` lists the user's life areas (for example work, builds, research). Each area has a scope note, aliases and the wikis it holds. The user approves every area.
|
|
36
|
+
|
|
37
|
+
- Before creating a wiki, read `areas.json` and pick the area whose scope fits. Create the wiki at `<wikis>/<area>/<name>/` and put its name in that area's `wikis` list. If no area fits, use `<wikis>/unsorted/<name>/`.
|
|
38
|
+
- Never add, rename, merge or approve an area. If nothing fits, say so in your answer; the post-run step queues it and proposes a new area once three tasks need it.
|
|
39
|
+
- Do not write `feed.jsonl` or `decisions.jsonl`; the post-run step writes them after the run is scored.
|
|
40
|
+
|
|
33
41
|
## Page rules
|
|
34
42
|
|
|
35
|
-
- Each page
|
|
36
|
-
-
|
|
37
|
-
-
|
|
43
|
+
- Each page is one self-contained HTML file: inline CSS, no external files, no script elements unless the user asks for interactivity. The head holds <meta name="summary" content="...">, <meta name="updated" content="YYYY-MM-DD"> and <meta name="sources" content="...">.
|
|
44
|
+
- Write for a human who reads the page once: open with a <div class="tldr"> that answers in two or three sentences, then h2 sections, tables for comparisons, <details> for side detail, and inline SVG for flows.
|
|
45
|
+
- Pages written earlier as .md stay valid and are still read. When you edit one, convert it to .html and delete the .md in the same commit.
|
|
46
|
+
- Link pages with relative hrefs such as <a href="../concepts/slug.html">. One topic per page.
|
|
47
|
+
- Search before you write (`grep -ril`, then read `index.html`) and update the existing page instead of adding a near-duplicate.
|
|
38
48
|
- When a fact changes, replace it and note what changed. Do not leave two claims that contradict each other.
|
|
39
49
|
- Date facts and say where they came from.
|
|
40
50
|
- Split a page that grows past about 150 lines.
|
|
@@ -42,21 +52,21 @@ The wiki holds knowledge about a subject. Lessons about how you should behave ne
|
|
|
42
52
|
## Create a wiki
|
|
43
53
|
|
|
44
54
|
1. Create the wiki directory and initial files (`write` creates parent folders automatically, or use `mkdir -p` and `git -C <wiki> init`).
|
|
45
|
-
2. Write `AGENTS.md` (topic, one-line purpose, the layout and page rules above, any extra folders), `index.
|
|
55
|
+
2. Write `AGENTS.md` (topic, one-line purpose, the layout and page rules above, any extra folders), `index.html` (a title and an empty section per folder), `log.md` and `overview.html`.
|
|
46
56
|
3. Log and commit (below).
|
|
47
57
|
|
|
48
58
|
## Ingest a source
|
|
49
59
|
|
|
50
60
|
1. Put the source in `raw/` (copy a file, or save the fetched text). Do not edit it afterwards.
|
|
51
61
|
2. Read it. Tell the user the key takeaways in a few lines and what you plan to emphasise.
|
|
52
|
-
3. Write `sources/<slug>.
|
|
62
|
+
3. Write `sources/<slug>.html`.
|
|
53
63
|
4. Update the entity and concept pages it touches, creating the ones that are missing. A single source often touches several pages. Flag where it contradicts an existing claim.
|
|
54
|
-
5. Update `overview.
|
|
64
|
+
5. Update `overview.html` if the synthesis changed, and add or refresh the pages' lines in `index.html`.
|
|
55
65
|
6. Log and commit.
|
|
56
66
|
|
|
57
67
|
## Answer a question
|
|
58
68
|
|
|
59
|
-
Read `index.
|
|
69
|
+
Read `index.html` first, open the pages it points to, and answer with citations to those pages. If the answer is worth keeping (a comparison, an analysis, a connection), offer to file it as `analyses/<slug>.html`. Once the user agrees, write it, update the index, then log and commit. If the wiki cannot answer, say what is missing instead of guessing.
|
|
60
70
|
|
|
61
71
|
## Lint
|
|
62
72
|
|