@hexdecimal16/nexo 0.4.7 → 0.4.8

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 (45) hide show
  1. package/cli/src/areas.js +49 -0
  2. package/cli/src/common.js +1 -1
  3. package/cli/src/main.js +3 -0
  4. package/cli/src/optimize.js +2 -5
  5. package/core/src/config/schema.js +1 -0
  6. package/core/src/engine/charged-completion.js +9 -4
  7. package/core/src/engine/errors.js +29 -2
  8. package/core/src/engine/prompts.js +1 -1
  9. package/core/src/engine/run.js +9 -4
  10. package/core/src/index.js +1 -0
  11. package/core/src/learn/areas.js +179 -0
  12. package/core/src/learn/job.js +13 -0
  13. package/core/src/learn/wiki.js +15 -10
  14. package/core/src/optimize/climb.js +0 -2
  15. package/core/src/optimize/optimize.js +1 -4
  16. package/optimize/src/engine.js +1 -22
  17. package/optimize/src/index.js +0 -1
  18. package/optimize/src/report.js +0 -2
  19. package/package.json +1 -1
  20. package/skills/bundled/wiki/SKILL.md +21 -11
  21. package/store/src/eval-cases.js +12 -6
  22. package/tools/src/index.js +1 -0
  23. package/tools/src/wiki-page.js +78 -0
  24. package/tui/src/questions.js +31 -0
  25. package/web/public/area.html +23 -0
  26. package/web/public/cost.html +1 -1
  27. package/web/public/home.html +23 -0
  28. package/web/public/index.html +1 -1
  29. package/web/public/judge.html +1 -1
  30. package/web/public/learning.html +1 -1
  31. package/web/public/lib/api-types.ts +0 -2
  32. package/web/public/lib/optim-view.ts +1 -1
  33. package/web/public/lib/wikis-view.ts +3 -1
  34. package/web/public/optim.html +1 -1
  35. package/web/public/pages/area.ts +49 -0
  36. package/web/public/pages/home.ts +60 -0
  37. package/web/public/pages/wikis.ts +43 -6
  38. package/web/public/run.html +1 -1
  39. package/web/public/sessions.html +1 -1
  40. package/web/public/style.css +31 -0
  41. package/web/public/wikis.html +1 -1
  42. package/web/src/api.js +11 -6
  43. package/web/src/home-api.js +99 -0
  44. package/web/src/server.js +6 -0
  45. package/optimize/src/merge.js +0 -73
@@ -0,0 +1,49 @@
1
+ import { approveArea, readRegistry, writeRegistry } from "../../core/src/index.js";
2
+ import { ensureNexoDirs, resolveNexoPaths } from "../../store/src/index.js";
3
+ import { NexoError } from "../../telemetry/src/index.js";
4
+ import { usageError } from "./common.js";
5
+ const AREAS_USAGE = "Usage: nexo areas [list] | nexo areas approve <id> | nexo areas reject <id>";
6
+ /** `nexo areas`: lists life areas and the unsorted queue; approve activates a proposed area, reject removes one. */
7
+ export function areasCommand(args, io, options) {
8
+ const [sub = "list", id, ...extra] = args;
9
+ if (extra.length > 0)
10
+ throw usageError(AREAS_USAGE);
11
+ const paths = resolveNexoPaths(options.env ?? process.env);
12
+ ensureNexoDirs(paths);
13
+ const registry = readRegistry(paths.wikis);
14
+ if (sub === "list") {
15
+ if (registry.areas.length === 0) {
16
+ io.stdout.write("No areas yet.\n");
17
+ return 0;
18
+ }
19
+ for (const status of ["active", "proposed"]) {
20
+ const areas = registry.areas.filter((a) => a.status === status);
21
+ if (areas.length === 0)
22
+ continue;
23
+ io.stdout.write(status === "active" ? "Active:\n" : "Proposed (approve with: nexo areas approve <id>):\n");
24
+ for (const a of areas)
25
+ io.stdout.write(` ${a.id.padEnd(10)} ${a.name}: ${a.scope}${a.wikis.length > 0 ? ` [wikis: ${a.wikis.join(", ")}]` : ""}\n`);
26
+ }
27
+ const labels = new Map();
28
+ for (const u of registry.unsorted)
29
+ labels.set(u.label, (labels.get(u.label) ?? 0) + 1);
30
+ if (labels.size > 0)
31
+ io.stdout.write(`Unsorted: ${[...labels].map(([l, n]) => `${l} (${n})`).join(", ")}\n`);
32
+ return 0;
33
+ }
34
+ if ((sub !== "approve" && sub !== "reject") || !id)
35
+ throw usageError(AREAS_USAGE);
36
+ if (sub === "approve") {
37
+ writeRegistry(paths.wikis, approveArea(registry, id));
38
+ io.stdout.write(`Approved area ${id}\n`);
39
+ return 0;
40
+ }
41
+ const area = registry.areas.find((a) => a.id === id);
42
+ if (!area)
43
+ throw new NexoError({ code: "NOT_FOUND", message: `No area "${id}"`, context: { id } });
44
+ if (area.status !== "proposed")
45
+ throw new NexoError({ code: "CONFLICT", message: `Area "${id}" is active; only proposed areas can be rejected`, context: { id } });
46
+ writeRegistry(paths.wikis, { ...registry, areas: registry.areas.filter((a) => a.id !== id) });
47
+ io.stdout.write(`Rejected area ${id}\n`);
48
+ return 0;
49
+ }
package/cli/src/common.js CHANGED
@@ -30,7 +30,7 @@ export const USAGE = `Usage:
30
30
  nexo eval accept <case-id> [--expected <text>]
31
31
  nexo eval dismiss <case-id>
32
32
  nexo eval golden revert <case-id>
33
- nexo optimize --target skill:<name>|tool:<name>|system_prompt|planner_prompt|judge_rubric [--budget-usd <n>] [--max-rollouts <n>] [--merge] [--seed <n>]
33
+ nexo optimize --target skill:<name>|tool:<name>|system_prompt|planner_prompt|judge_rubric [--budget-usd <n>] [--max-rollouts <n>] [--seed <n>]
34
34
  nexo optimize climb --target skill:<name>|tool:<name>|system_prompt|planner_prompt [--case <id>] [--guards <0-10>] [--budget-usd <n>] [--seed <n>]
35
35
  nexo optimize list
36
36
  nexo optimize show <id> [--diff]
package/cli/src/main.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { areasCommand } from "./areas.js";
1
2
  import { parseArgs } from "node:util";
2
3
  import { judgeFamilyWarnings } from "../../core/src/index.js";
3
4
  import { EFFORTS } from "../../router/src/index.js";
@@ -257,6 +258,8 @@ export async function runCli(argv, io, options = {}) {
257
258
  return await initCommand(rest, io, options, stdio);
258
259
  case "update":
259
260
  return await updateCommand(io, options);
261
+ case "areas":
262
+ return areasCommand(rest, io, options);
260
263
  case "sessions":
261
264
  return sessionsCommand(rest, io, options);
262
265
  // Read-only listing of the same file the TUI's Up key uses.
@@ -46,7 +46,7 @@ export function reportLines(db, run, report, minJudgeKappa, options = {}) {
46
46
  for (const c of h.cases)
47
47
  lines.push(` ${c.outcome.padEnd(4)} ${q(c.before.quality)} → ${q(c.after.quality)} ${escapeControl(c.input.replace(/\s+/g, " ").slice(0, 80))}`);
48
48
  if (!report.climb)
49
- lines.push(` ${report.iterations} iterations, ${report.lineage.length - 1} candidates, ${report.merges} merges${report.mergeNote ? ` (${escapeControl(report.mergeNote)})` : ""}`);
49
+ lines.push(` ${report.iterations} iterations, ${report.lineage.length - 1} candidates`);
50
50
  const e = report.evidence;
51
51
  lines.push(e.humanScored
52
52
  ? " evidence: human verdicts"
@@ -96,8 +96,6 @@ export function optimizeEventLine(event) {
96
96
  return ` minibatch ${q(event.parentQuality)} → ${q(event.childQuality)} ${event.accepted ? "✓ accepted" : "✗ not better"}${event.prediction ? ` · predicted fixes ${event.prediction.fixesHit}/${event.prediction.fixesPredicted}, risks ${event.prediction.atRiskHit}/${event.prediction.atRiskPredicted}${event.prediction.unpredictedRegressions > 0 ? `, ${event.prediction.unpredictedRegressions} unpredicted` : ""}` : ""}`;
97
97
  case "pareto":
98
98
  return ` pareto mean ${q(event.meanQuality)} at ${usd(event.meanCostUsd)}${event.newMember ? " · new Pareto member" : ""}`;
99
- case "merge":
100
- return ` merge of ${event.parents.join(" and ")} ${event.accepted ? "kept" : "dropped"}`;
101
99
  case "reflection":
102
100
  return event.problem ? ` reflection unusable: ${escapeControl(event.problem)}` : null;
103
101
  default:
@@ -125,7 +123,7 @@ function rolloutNotice(config) {
125
123
  async function runOptimize(args, io, options) {
126
124
  const { values } = parseArgs({
127
125
  args,
128
- options: { target: { type: "string" }, "budget-usd": { type: "string" }, "max-rollouts": { type: "string" }, merge: { type: "boolean" }, seed: { type: "string" } },
126
+ options: { target: { type: "string" }, "budget-usd": { type: "string" }, "max-rollouts": { type: "string" }, seed: { type: "string" } },
129
127
  });
130
128
  if (!values.target)
131
129
  throw usageError("nexo optimize needs --target skill:<name>|tool:<name>|system_prompt|planner_prompt|judge_rubric");
@@ -141,7 +139,6 @@ async function runOptimize(args, io, options) {
141
139
  target: values.target,
142
140
  budgetUsd: positiveNumber("--budget-usd", values["budget-usd"], false),
143
141
  maxRollouts: positiveNumber("--max-rollouts", values["max-rollouts"], true),
144
- merge: values.merge ?? false,
145
142
  ...(seed !== undefined ? { seed } : {}),
146
143
  signal: options.signal,
147
144
  onEvent: (event) => {
@@ -44,6 +44,7 @@ export const ConfigSchema = Type.Object({
44
44
  maxConcurrent: Type.Optional(Type.Integer({ minimum: 1 })),
45
45
  maxRetries: Type.Optional(Type.Integer({ minimum: 0, maximum: 10 })),
46
46
  retryBaseDelayMs: Type.Optional(Type.Integer({ minimum: 0 })),
47
+ retryWindowMs: Type.Optional(Type.Integer({ minimum: 0 })),
47
48
  rateLimitBaseDelayMs: Type.Optional(Type.Integer({ minimum: 0 })),
48
49
  }, { additionalProperties: false })),
49
50
  router: Type.Object({ policy: ArtifactSource("router_policy"), maxEscalations: Type.Integer({ minimum: 0 }) }, { additionalProperties: false }),
@@ -1,7 +1,7 @@
1
1
  import { normalizeContext } from "@earendil-works/pi-ai";
2
2
  import { NexoError, toErrorPayload } from "../../../telemetry/src/index.js";
3
3
  import { estimateCallCostUsd } from "../cost/pricing.js";
4
- import { classifyProviderError, providerRetryDelayMs } from "./errors.js";
4
+ import { classifyProviderError, providerRetryDelayMs, withinRetryLimits } from "./errors.js";
5
5
  import { assistantText } from "./messages.js";
6
6
  /**
7
7
  * One LLM completion outside the agent loop (judge, self-check, reflector, curator). Each attempt reserves its estimate
@@ -15,7 +15,8 @@ export async function runChargedCompletion(payer, request, signal) {
15
15
  const { config, redact } = env.deps;
16
16
  const { model, span } = request;
17
17
  const providerCfg = config.providers[model.provider] ?? {};
18
- const maxRetries = request.maxRetries ?? providerCfg.maxRetries ?? 3;
18
+ const retryCfg = request.maxRetries !== undefined ? { ...providerCfg, maxRetries: request.maxRetries } : providerCfg;
19
+ let waitedMs = 0;
19
20
  // The reply is capped at the output tokens the estimate assumes, so a verbose reply cannot cost more than was reserved.
20
21
  const outputTokens = request.outputTokens ?? config.budgets.estimateOutputTokens;
21
22
  const maxTokens = model.maxTokens > 0 ? Math.min(outputTokens, model.maxTokens) : outputTokens;
@@ -72,8 +73,12 @@ export async function runChargedCompletion(payer, request, signal) {
72
73
  if (!failed)
73
74
  return { text, costUsd, costUnknown };
74
75
  const error = classifyProviderError(msg.errorMessage ?? "Provider error");
75
- if (!error.retryable || attempt > maxRetries)
76
+ if (!error.retryable)
76
77
  throw error;
77
- await env.sleep(providerRetryDelayMs(attempt, msg.errorMessage ?? "", providerCfg), signal);
78
+ const delay = providerRetryDelayMs(attempt, msg.errorMessage ?? "", providerCfg);
79
+ if (!withinRetryLimits(attempt, waitedMs + delay, retryCfg))
80
+ throw error;
81
+ waitedMs += delay;
82
+ await env.sleep(delay, signal);
78
83
  }
79
84
  }
@@ -1,3 +1,4 @@
1
+ import { isRetryableAssistantError } from "@earendil-works/pi-ai";
1
2
  import { NexoError } from "../../../telemetry/src/index.js";
2
3
  /** Maps a provider error message (pi encodes failures as text) to a NexoError code and hint. */
3
4
  export function classifyProviderError(message) {
@@ -36,6 +37,32 @@ export function retryAfterMs(errorMessage) {
36
37
  return match?.[1] ? Math.round(Number(match[1]) * 1000) : undefined;
37
38
  }
38
39
  const RATE_LIMIT_MAX_DELAY_MS = 60_000;
40
+ /** The longest single backoff for a non-rate-limit error before jitter. */
41
+ const RETRY_MAX_DELAY_MS = 60_000;
42
+ /** Backoff time a streak of consecutive provider failures may spend before the call gives up, when maxRetries is unset. */
43
+ export const DEFAULT_RETRY_WINDOW_MS = 30 * 60_000;
44
+ /** A hard cap on retries within the window, so zero-delay configs (tests) cannot loop forever. */
45
+ const MAX_RETRY_ATTEMPTS = 200;
46
+ // Transient failures pi's classifier does not know: Kiro's capacity message and the kiro-p idle stall.
47
+ const EXTRA_TRANSIENT = /high traffic|try again|no output for \d+\s*s/i;
48
+ const NOT_TRANSIENT = /quota|billing|usage limit/i;
49
+ /** Whether a failed model call is worth retrying: pi's transient patterns plus the kiro-cli ones above. */
50
+ export function isRetryableProviderMessage(message) {
51
+ if (message.stopReason !== "error" || !message.errorMessage)
52
+ return false;
53
+ if (isRetryableAssistantError(message))
54
+ return true;
55
+ return EXTRA_TRANSIENT.test(message.errorMessage) && !NOT_TRANSIENT.test(message.errorMessage);
56
+ }
57
+ /**
58
+ * Whether retry `attempt` (1-based, per failure streak) may run after `waitedMs` of backoff including its own delay.
59
+ * An explicit `maxRetries` is a plain count; otherwise retries continue until `retryWindowMs` (default 30 min) of backoff.
60
+ */
61
+ export function withinRetryLimits(attempt, waitedMs, cfg) {
62
+ if (cfg.maxRetries !== undefined)
63
+ return attempt <= cfg.maxRetries;
64
+ return attempt <= MAX_RETRY_ATTEMPTS && waitedMs <= (cfg.retryWindowMs ?? DEFAULT_RETRY_WINDOW_MS);
65
+ }
39
66
  /**
40
67
  * Backoff before retry `attempt` (1-based, counted per streak of consecutive failures) of a retryable provider error.
41
68
  * A rate limit waits `rateLimitBaseDelayMs` (default 5 s) doubling per attempt up to a minute, ±20% so parallel callers
@@ -48,9 +75,9 @@ export function providerRetryDelayMs(attempt, errorMessage, cfg, random = Math.r
48
75
  const base = Math.min(RATE_LIMIT_MAX_DELAY_MS, (cfg.rateLimitBaseDelayMs ?? 5000) * 2 ** (attempt - 1));
49
76
  return Math.max(Math.round(base * (0.8 + 0.4 * random())), retryAfterMs(errorMessage) ?? 0);
50
77
  }
51
- /** Backoff before retry `attempt` (1-based) of a retryable provider error: full jitter on an exponential base, at least the provider's retry-after. */
78
+ /** Backoff before retry `attempt` (1-based) of a retryable provider error: full jitter on an exponential base capped at a minute, at least the provider's retry-after. */
52
79
  export function retryDelayMs(attempt, baseDelayMs, errorMessage, random = Math.random) {
53
- return Math.max(random() * baseDelayMs * 2 ** (attempt - 1), retryAfterMs(errorMessage) ?? 0);
80
+ return Math.max(random() * Math.min(RETRY_MAX_DELAY_MS, baseDelayMs * 2 ** (attempt - 1)), retryAfterMs(errorMessage) ?? 0);
54
81
  }
55
82
  /** The text the model sees for a failed tool call: code, retryability, message and hint. */
56
83
  export function toolErrorText(error) {
@@ -17,7 +17,7 @@ export const DEFAULT_PLANNER_PROMPT = `Parallel work:
17
17
  export const WEB_SEARCH_PROMPT = `Web research: your training data has a cutoff, so use web_search for anything that may have changed or that you are not sure of: current versions, APIs and docs, error messages, prices, news and other recent facts. Search with specific terms, read the best one to three hits with web_fetch, and cite the URLs you relied on in your answer. Do not search for things the workspace or a skill already answers.`;
18
18
  /** The line that points the agent at the wikis directory; the wiki skill holds the rules for using it. */
19
19
  export function wikiPrompt(wikisDir) {
20
- return `Wikis: the user keeps persistent knowledge bases as markdown folders under ${wikisDir}. When a task produces durable subject knowledge worth keeping (research findings, a source you read, a topic the user keeps returning to), load the wiki skill with load_skill and file it in the wiki that fits, creating a new wiki when none fits. Do not create or edit wikis for one-off questions, small talk or routine code changes. Load the wiki skill first whenever the task is about a wiki.`;
20
+ return `Wikis: the user keeps persistent knowledge bases as folders of HTML pages under ${wikisDir}. When a task produces durable subject knowledge worth keeping (research findings, a source you read, a topic the user keeps returning to), load the wiki skill with load_skill and file it in the wiki that fits, creating a new wiki when none fits. Do not create or edit wikis for one-off questions, small talk or routine code changes. Load the wiki skill first whenever the task is about a wiki. The user's approved life areas are listed in ${wikisDir}/areas.json; file work in a wiki that belongs to the matching area, and never add or rename an area yourself, because new areas need the user's approval.`;
21
21
  }
22
22
  export function renderSystemPrompt(parts) {
23
23
  const sections = [parts.systemPrompt.replaceAll("{{workspace}}", parts.workspace)];
@@ -1,5 +1,5 @@
1
1
  import { Agent } from "@earendil-works/pi-agent-core";
2
- import { isContextOverflow, isRetryableAssistantError, normalizeContext, } from "@earendil-works/pi-ai";
2
+ import { isContextOverflow, normalizeContext, } from "@earendil-works/pi-ai";
3
3
  import { createModelRegistry, DEFAULT_ROUTER_POLICY, ESCALATION_BLOCK_REASONS, endOfRunSignals, escalationBlock, isModelAllowed, resolveModel, TriggerMonitor, } from "../../../router/src/index.js";
4
4
  import { createLoadSkillTool, formatSkillIndex, parseSkillFile } from "../../../skills/src/index.js";
5
5
  import { createArtifactSet, enqueueLearnJob, getActiveArtifact, insertRun, isPidAlive, listPlaybookItems, listSpans, newId, recoverCrashedRuns, resolveSourcedArtifact, RunDir, sessionRunDirs, updateRun, } from "../../../store/src/index.js";
@@ -12,7 +12,7 @@ import { budgetExhaustedError, checkAdmission, recordSpend, runBudgetLimit } fro
12
12
  import { budgetLine, RunBudget } from "../cost/budget.js";
13
13
  import { estimateCallCostUsd, priceUsage } from "../cost/pricing.js";
14
14
  import { clearOldToolResults } from "./context-trim.js";
15
- import { classifyProviderError, contextOverflowError, providerRetryDelayMs, toolErrorText, withToolErrorCodes } from "./errors.js";
15
+ import { classifyProviderError, contextOverflowError, isRetryableProviderMessage, providerRetryDelayMs, toolErrorText, withToolErrorCodes, withinRetryLimits } from "./errors.js";
16
16
  import { assistantText, contentText, estimatePromptChars, foreignToolCallsAsText, lastAssistant, recordedContent, withBudgetLine } from "./messages.js";
17
17
  import { DEFAULT_PLANNER_PROMPT, DEFAULT_SYSTEM_PROMPT, renderSystemPrompt } from "./prompts.js";
18
18
  import { loadProjectInstructions } from "../session/project-instructions.js";
@@ -992,20 +992,25 @@ export async function executeRun(env, input) {
992
992
  await runAgent.prompt(text);
993
993
  // Retries are counted per streak of consecutive failures: a successful call since the last retry starts over.
994
994
  let attempt = 0;
995
+ let waitedMs = 0;
995
996
  let succeededCalls = completedCalls;
996
997
  for (;;) {
997
998
  const last = lastAssistant(runAgent.state.messages);
998
- if (!last || last.stopReason !== "error" || isContextOverflow(last) || !isRetryableAssistantError(last))
999
+ if (!last || last.stopReason !== "error" || isContextOverflow(last) || !isRetryableProviderMessage(last))
999
1000
  break;
1000
1001
  if (completedCalls !== succeededCalls) {
1001
1002
  attempt = 0;
1003
+ waitedMs = 0;
1002
1004
  succeededCalls = completedCalls;
1003
1005
  }
1004
1006
  attempt++;
1005
1007
  const providerCfg = config.providers[active.model.provider] ?? {};
1006
- if (attempt > (providerCfg.maxRetries ?? 3) || input.signal?.aborted || budgetExceeded)
1008
+ if (input.signal?.aborted || budgetExceeded)
1007
1009
  break;
1008
1010
  const delay = providerRetryDelayMs(attempt, last.errorMessage ?? "", providerCfg);
1011
+ if (!withinRetryLimits(attempt, waitedMs + delay, providerCfg))
1012
+ break;
1013
+ waitedMs += delay;
1009
1014
  logger.warn("retrying provider error", { attempt, delay_ms: Math.round(delay), error_message: last.errorMessage });
1010
1015
  await env.sleep(delay, input.signal);
1011
1016
  runAgent.state.messages = runAgent.state.messages.slice(0, -1);
package/core/src/index.js CHANGED
@@ -34,3 +34,4 @@ export * from "./settings/credentials.js";
34
34
  export * from "./settings/doctor.js";
35
35
  export * from "./settings/settings.js";
36
36
  import "./engine/spawn-tool.js";
37
+ export * from "./learn/areas.js";
@@ -0,0 +1,179 @@
1
+ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { dataBlock } from "../../../scorers/src/index.js";
4
+ import { NexoError } from "../../../telemetry/src/index.js";
5
+ import { Type } from "typebox";
6
+ import { structuredLearnCall } from "./caller.js";
7
+ /** Life areas live in the wikis directory as data. Code never names an area; the user approves every new one. */
8
+ export const AREAS_FILE = "areas.json";
9
+ export const FEED_FILE = "feed.jsonl";
10
+ export const DECISIONS_FILE = "decisions.jsonl";
11
+ /** Unsorted tasks sharing a label before that label is proposed as a new area. */
12
+ export const PROPOSAL_THRESHOLD = 3;
13
+ /** Runs scoring below this get an unverified feed line and no filed decisions. */
14
+ export const FILE_SCORE_FLOOR = 0.6;
15
+ const MAX_UNSORTED = 200;
16
+ export function emptyRegistry() {
17
+ return { version: 1, areas: [], unsorted: [] };
18
+ }
19
+ export function normalizeLabel(label) {
20
+ return label.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
21
+ }
22
+ function slug(label) {
23
+ return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "area";
24
+ }
25
+ /** Reads the registry; a missing file is an empty registry. An unreadable file throws so it is never overwritten. */
26
+ export function readRegistry(wikisDir) {
27
+ const file = join(wikisDir, AREAS_FILE);
28
+ if (!existsSync(file))
29
+ return emptyRegistry();
30
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
31
+ return { version: 1, areas: Array.isArray(parsed.areas) ? parsed.areas : [], unsorted: Array.isArray(parsed.unsorted) ? parsed.unsorted : [] };
32
+ }
33
+ /** Writes the registry atomically (temp file, then rename). */
34
+ export function writeRegistry(wikisDir, registry) {
35
+ mkdirSync(wikisDir, { recursive: true });
36
+ const file = join(wikisDir, AREAS_FILE);
37
+ const tmp = `${file}.${process.pid}.tmp`;
38
+ writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`);
39
+ renameSync(tmp, file);
40
+ }
41
+ export function areaMatches(area, label) {
42
+ const n = normalizeLabel(label);
43
+ return n !== "" && [area.id, area.name, ...area.aliases].some((x) => normalizeLabel(x) === n);
44
+ }
45
+ /** Queues an unsorted task. Once PROPOSAL_THRESHOLD queued tasks share a label no area covers, that label becomes a proposed area. */
46
+ export function recordUnsorted(registry, item) {
47
+ const unsorted = [...registry.unsorted, item].slice(-MAX_UNSORTED);
48
+ const n = normalizeLabel(item.label);
49
+ if (n === "" || registry.areas.some((a) => areaMatches(a, item.label)))
50
+ return { registry: { ...registry, unsorted }, proposed: null };
51
+ const same = unsorted.filter((u) => normalizeLabel(u.label) === n);
52
+ if (same.length < PROPOSAL_THRESHOLD)
53
+ return { registry: { ...registry, unsorted }, proposed: null };
54
+ let id = slug(item.label);
55
+ for (let i = 2; registry.areas.some((a) => a.id === id); i++)
56
+ id = `${slug(item.label)}-${i}`;
57
+ const proposed = {
58
+ id,
59
+ name: item.label.trim(),
60
+ scope: `Proposed from ${same.length} unsorted tasks. Write a scope note before approving.`,
61
+ examples: same.slice(-3).map((u) => u.reason),
62
+ aliases: [],
63
+ wikis: [],
64
+ status: "proposed",
65
+ createdAt: item.at,
66
+ };
67
+ return { registry: { ...registry, unsorted, areas: [...registry.areas, proposed] }, proposed };
68
+ }
69
+ /** Makes a proposed area active. Only a user action should call this. */
70
+ export function approveArea(registry, id) {
71
+ const area = registry.areas.find((a) => a.id === id);
72
+ if (!area)
73
+ throw new NexoError({ code: "NOT_FOUND", message: `No area "${id}"`, context: { id } });
74
+ if (area.status === "active")
75
+ throw new NexoError({ code: "CONFLICT", message: `Area "${id}" is already active`, context: { id } });
76
+ return { ...registry, areas: registry.areas.map((a) => (a.id === id ? { ...a, status: "active" } : a)) };
77
+ }
78
+ /** Mean value of the latest scoring round, or null when the run has no valued scores. */
79
+ export function runScoreMean(scores) {
80
+ if (scores.length === 0)
81
+ return null;
82
+ const last = Math.max(...scores.map((s) => s.round));
83
+ const values = scores.filter((s) => s.round === last && typeof s.value === "number").map((s) => s.value);
84
+ return values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : null;
85
+ }
86
+ /** The run's ask_user questions and answers, the most reliable record of the user's decisions. */
87
+ export function askUserAnswers(spans) {
88
+ return spans
89
+ .filter((s) => s.kind === "tool_call" && s.name === "ask_user" && s.status === "ok")
90
+ .map((s) => {
91
+ const attrs = (s.attrs ?? {});
92
+ const args = (attrs.args ?? {});
93
+ return JSON.stringify({ questions: args.questions, answer: attrs.result ?? attrs.output ?? attrs.text }).slice(0, 1500);
94
+ })
95
+ .slice(-5);
96
+ }
97
+ function listWikis(wikisDir) {
98
+ try {
99
+ return readdirSync(wikisDir).filter((f) => !f.startsWith(".") && statSync(join(wikisDir, f)).isDirectory());
100
+ }
101
+ catch {
102
+ return [];
103
+ }
104
+ }
105
+ export const AssignmentSchema = Type.Object({
106
+ areaId: Type.String({ minLength: 1, maxLength: 64 }),
107
+ unsortedLabel: Type.Optional(Type.String({ maxLength: 60 })),
108
+ wiki: Type.Optional(Type.String({ maxLength: 64 })),
109
+ feed: Type.String({ maxLength: 240 }),
110
+ decisions: Type.Array(Type.Object({ choice: Type.String({ minLength: 1, maxLength: 300 }), reason: Type.String({ maxLength: 300 }) }, { additionalProperties: false }), { maxItems: 5 }),
111
+ }, { additionalProperties: false });
112
+ export const ASSIGN_SYSTEM = `You file a finished task into the user's life areas.
113
+ 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.
114
+ 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.
115
+ wiki: the existing wiki this task belongs to, from the wiki list, or omit it.
116
+ 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).
117
+ 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.`;
118
+ export function assignPrompt(input) {
119
+ 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 }));
120
+ const queued = [...new Set(input.registry.unsorted.map((u) => normalizeLabel(u.label)).filter(Boolean))].slice(-30);
121
+ return [
122
+ `# Areas\n${JSON.stringify(areas, null, 1)}`,
123
+ `# Queued unsorted labels\n${queued.join(", ") || "(none)"}`,
124
+ `# Wikis\n${input.wikis.join(", ") || "(none)"}`,
125
+ `# Working folder\n${input.cwd ?? "(unknown)"}`,
126
+ `# User instruction\n${dataBlock("instruction", input.instruction)}`,
127
+ `# Questions the user answered\n${dataBlock("answers", input.answers.join("\n") || "(none)")}`,
128
+ `# Final output\n${dataBlock("output", input.output.slice(0, 4000))}`,
129
+ ].join("\n\n");
130
+ }
131
+ /** 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. */
132
+ export async function assignRun(deps, input) {
133
+ const none = { areaId: null, feed: false, decisions: 0, proposed: null, verified: false };
134
+ const wikisDir = deps.env.deps.paths?.wikis;
135
+ if (!wikisDir || !existsSync(wikisDir))
136
+ return none;
137
+ if (!input.output || input.output.trim().length < 50)
138
+ return none;
139
+ const registry = readRegistry(wikisDir);
140
+ const active = registry.areas.filter((a) => a.status === "active");
141
+ if (active.length === 0)
142
+ return none;
143
+ const wikis = listWikis(wikisDir);
144
+ const reply = await structuredLearnCall(deps, AssignmentSchema, {
145
+ system: ASSIGN_SYSTEM,
146
+ user: assignPrompt({ registry, wikis, cwd: input.cwd, instruction: input.run.instruction, answers: askUserAnswers(input.spans), output: input.output }),
147
+ tier: "curator",
148
+ });
149
+ const now = deps.env.now().toISOString();
150
+ const redact = deps.env.deps.redact;
151
+ const mean = runScoreMean(input.scores);
152
+ const verified = mean !== null && mean >= FILE_SCORE_FLOOR;
153
+ const known = active.find((a) => a.id === reply.areaId);
154
+ const wiki = reply.wiki && wikis.includes(reply.wiki) ? reply.wiki : null;
155
+ let proposed = null;
156
+ if (!known) {
157
+ const label = (reply.unsortedLabel ?? (reply.areaId === "unsorted" ? "" : reply.areaId)).trim();
158
+ if (label) {
159
+ const next = recordUnsorted(registry, { runId: input.run.id, label, reason: redact((reply.feed.trim() || input.run.instruction).slice(0, 200)), at: now });
160
+ writeRegistry(wikisDir, next.registry);
161
+ proposed = next.proposed?.id ?? null;
162
+ }
163
+ }
164
+ const areaId = known?.id ?? null;
165
+ const base = { at: now, runId: input.run.id, sessionId: input.run.sessionId ?? null, areaId, wiki };
166
+ let fed = false;
167
+ if (reply.feed.trim()) {
168
+ appendFileSync(join(wikisDir, FEED_FILE), `${JSON.stringify({ ...base, text: redact(reply.feed.trim()), verified })}\n`);
169
+ fed = true;
170
+ }
171
+ let decisions = 0;
172
+ if (verified) {
173
+ for (const d of reply.decisions) {
174
+ appendFileSync(join(wikisDir, DECISIONS_FILE), `${JSON.stringify({ ...base, choice: redact(d.choice), reason: redact(d.reason) })}\n`);
175
+ decisions++;
176
+ }
177
+ }
178
+ return { areaId, feed: fed, decisions, proposed, verified };
179
+ }
@@ -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 () => {
94
+ try {
95
+ await assignRun(deps, { run, output, spans, scores, 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
  }
@@ -188,6 +200,7 @@ export async function runLearnJob(env, job, options) {
188
200
  catch (err) {
189
201
  logger.warn("wiki curation pass failed; continuing without it", { run_id: run.id, error: err });
190
202
  }
203
+ await assignAreas();
191
204
  return { lessons: reflection.lessons.length, curation, costUsd, costUnknown };
192
205
  }
193
206
  catch (error) {
@@ -1,9 +1,13 @@
1
1
  import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
2
2
  import { dirname, join } from "node:path";
3
3
  import { dataBlock } from "../../../scorers/src/index.js";
4
- import { resolveConfined } from "../../../tools/src/index.js";
4
+ import { resolveConfined, 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)";
@@ -92,14 +96,15 @@ export async function curateWikiKnowledge(deps, run, output, spans) {
92
96
  mkdirSync(join(wikiDir, "analyses"), { recursive: true });
93
97
  mkdirSync(join(wikiDir, "raw"), { recursive: true });
94
98
  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`);
99
+ 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
100
  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`);
101
+ 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
102
  }
99
- const targetFile = resolveConfined(wikiDir, p.path.endsWith(".md") ? p.path : `${p.path}.md`);
103
+ const pagePath = `${p.path.replace(/[.](md|html)$/, "")}.html`;
104
+ const targetFile = resolveConfined(wikiDir, pagePath);
100
105
  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");
106
+ const pageHtml = wrapWikiHtml({ title: titleFromPath(pagePath), summary: p.summary, updated: today, sources: [`run:${run.id}`], body: p.content });
107
+ writeFileSync(targetFile, pageHtml);
103
108
  pagesCreated++;
104
109
  wikisTouched.add(p.wikiName);
105
110
  const logFile = join(wikiDir, "log.md");
@@ -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,
@@ -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`);