@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.
Files changed (52) hide show
  1. package/cli/src/areas.js +49 -0
  2. package/cli/src/common.js +1 -1
  3. package/cli/src/home-migrate.js +168 -0
  4. package/cli/src/main.js +6 -0
  5. package/cli/src/optimize.js +2 -5
  6. package/cli/src/ui.js +1 -1
  7. package/core/src/config/schema.js +1 -0
  8. package/core/src/engine/charged-completion.js +9 -4
  9. package/core/src/engine/errors.js +29 -2
  10. package/core/src/engine/prompts.js +1 -1
  11. package/core/src/engine/run.js +11 -6
  12. package/core/src/index.js +1 -0
  13. package/core/src/learn/areas.js +192 -0
  14. package/core/src/learn/job.js +15 -1
  15. package/core/src/learn/wiki.js +26 -18
  16. package/core/src/optimize/climb.js +0 -2
  17. package/core/src/optimize/optimize.js +2 -5
  18. package/core/src/optimize/scratchpad-wiki.js +7 -3
  19. package/optimize/src/engine.js +1 -22
  20. package/optimize/src/index.js +0 -1
  21. package/optimize/src/report.js +0 -2
  22. package/package.json +1 -1
  23. package/skills/bundled/wiki/SKILL.md +23 -13
  24. package/store/src/eval-cases.js +12 -6
  25. package/store/src/paths.js +2 -2
  26. package/tools/src/home-folders.js +36 -0
  27. package/tools/src/index.js +2 -0
  28. package/tools/src/wiki-page.js +78 -0
  29. package/tui/src/questions.js +31 -0
  30. package/web/public/area.html +23 -0
  31. package/web/public/cost.html +1 -1
  32. package/web/public/home.html +23 -0
  33. package/web/public/index.html +1 -1
  34. package/web/public/judge.html +1 -1
  35. package/web/public/learning.html +1 -1
  36. package/web/public/lib/api-types.ts +0 -2
  37. package/web/public/lib/optim-view.ts +1 -1
  38. package/web/public/lib/wikis-view.ts +3 -1
  39. package/web/public/optim.html +1 -1
  40. package/web/public/page.html +24 -0
  41. package/web/public/pages/area.ts +59 -0
  42. package/web/public/pages/home.ts +66 -0
  43. package/web/public/pages/page.ts +62 -0
  44. package/web/public/pages/wikis.ts +43 -6
  45. package/web/public/run.html +1 -1
  46. package/web/public/sessions.html +1 -1
  47. package/web/public/style.css +58 -0
  48. package/web/public/wikis.html +1 -1
  49. package/web/src/api.js +14 -9
  50. package/web/src/home-api.js +156 -0
  51. package/web/src/server.js +16 -0
  52. 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
+ }
@@ -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) {
@@ -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 markdown wikis.
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 markdown wiki for future reference.
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>.md", "entities/<slug>.md", "sources/<slug>.md", or "analyses/<slug>.md".
27
- - Provide a concise summary and clear markdown content (with [[wikilinks]] where relevant).
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?.wikis;
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.md"), `# ${p.wikiName} index\n\n## Concepts\n\n## Entities\n\n## Sources\n\n## Analyses\n`);
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.md"), `---\nsummary: Overview of ${p.wikiName}\nupdated: ${today}\nsources: []\n---\n\n# ${p.wikiName}\n`);
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 targetFile = resolveConfined(wikiDir, p.path.endsWith(".md") ? p.path : `${p.path}.md`);
105
+ const pagePath = `${p.path.replace(/[.](md|html)$/, "")}.html`;
106
+ const targetFile = resolveConfined(wikiDir, pagePath);
100
107
  mkdirSync(dirname(targetFile), { recursive: true });
101
- const frontmatter = `---\nsummary: ${p.summary.replace(/\n/g, " ")}\nupdated: ${today}\nsources: [run:${run.id}]\n---\n\n`;
102
- writeFileSync(targetFile, frontmatter + p.content.trim() + "\n");
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
  }
@@ -307,8 +307,6 @@ export async function startClimb(baseEnv, options) {
307
307
  spentUsd: ctx.budget.spentUsd,
308
308
  rollouts: ctx.rollouts,
309
309
  iterations: childArtifactId ? 1 : 0,
310
- merges: 0,
311
- mergeNote: null,
312
310
  createdAt: nowIso(),
313
311
  }),
314
312
  climb,
@@ -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: options.merge ?? false,
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?.wikis;
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(resolveConfined(wikisDir, SCRATCHPAD_WIKI), scratchpadPagePath(targetKey));
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 = resolveConfined(wikisDir, SCRATCHPAD_WIKI);
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"])
@@ -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, merges, scratchpad };
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) {
@@ -1,5 +1,4 @@
1
1
  export * from "./engine.js";
2
- export * from "./merge.js";
3
2
  export * from "./novelty.js";
4
3
  export * from "./pareto.js";
5
4
  export * from "./proposer.js";
@@ -100,8 +100,6 @@ export function buildReport(input) {
100
100
  spentUsd: input.spentUsd,
101
101
  rollouts: input.rollouts,
102
102
  iterations: input.iterations,
103
- merges: input.merges,
104
- mergeNote: input.mergeNote,
105
103
  createdAt: input.createdAt,
106
104
  };
107
105
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hexdecimal16/nexo",
3
- "version": "0.4.7",
3
+ "version": "0.4.9",
4
4
  "description": "nexo agent engine",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "repository": {
@@ -1,17 +1,17 @@
1
1
  ---
2
2
  name: wiki
3
- description: Create and maintain a persistent markdown wiki 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.
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 markdown 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.
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 in it, named for its topic in lowercase with hyphens: `<wikis>/<name>/`. 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.
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 directory and pick the one 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).
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.md catalog: one line per page (link, summary, date), grouped by folder
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.md the evolving top-level synthesis
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 starts with a frontmatter block (between two `---` lines) holding `summary:` (one specific line), `updated:` (YYYY-MM-DD) and `sources:` (raw files or URLs).
36
- - Link pages as `[[folder/slug]]`. One topic per page.
37
- - Search before you write (`grep -ril`, then read `index.md`) and update the existing page instead of adding a near-duplicate.
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.md` (a title and an empty section per folder), `log.md` and `overview.md`.
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>.md`.
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.md` if the synthesis changed, and add or refresh the pages' lines in `index.md`.
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.md` 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>.md`. 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.
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