@hexdecimal16/nexo 0.4.17 → 0.4.19

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.
@@ -1,12 +1,12 @@
1
1
  import { spawn } from "node:child_process";
2
- import { rmSync } from "node:fs";
2
+ import { existsSync, mkdirSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
3
3
  import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
4
- import { tmpdir } from "node:os";
4
+ import { homedir, tmpdir } from "node:os";
5
5
  import { join } from "node:path";
6
6
  import { createInterface } from "node:readline";
7
7
  import { createAssistantMessageEventStream, createProvider, getCurrentSystemPrompt, getCurrentTools, } from "@earendil-works/pi-ai";
8
8
  import { getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
9
- import { renderTranscriptParts } from "./claude-p.js";
9
+ import { NEXT_TURN_NOTE, renderEntryParts, renderTranscriptParts } from "./claude-p.js";
10
10
  import { parseReply } from "./kiro-p.js";
11
11
  import { ReplyTextExtractor } from "./reply-text.js";
12
12
  /** Provider id: models are referenced as `agy-p/<model>`, e.g. `agy-p/gemini-4-neon` or `agy-p/claude-sonnet-5-5`. */
@@ -97,24 +97,37 @@ function spawnRunner(command) {
97
97
  };
98
98
  };
99
99
  }
100
+ /**
101
+ * Context nexo budgets for agy models (gpt-oss aside). The models take 1M tokens elsewhere, but `agy acp` answers an
102
+ * empty turn somewhere past ~210k tokens (seen working at 210k, failing at 315k), so nexo must compact before that.
103
+ */
104
+ const AGY_CONTEXT = 200_000;
100
105
  /**
101
106
  * Antigravity CLI base model ids (the `model` config option in `agy acp`), paired with display name, context window and
102
- * reasoning support. Effort maps to ACP's `thought_level` option. Antigravity uses account quota rather than API
103
- * billing, so cost stays zero.
107
+ * the highest `thought_level` the model offers (`null`: no `thought_level` option, so no reasoning effort). Antigravity
108
+ * uses account quota rather than API billing, so cost stays zero.
104
109
  */
105
110
  const AGY_MODELS = [
106
- ["gemini-4-neon", "Gemini 4 Neon", 1_048_576, true],
107
- ["gemini-4-carbon", "Gemini 4 Carbon", 1_048_576, true],
108
- ["gemini-4-argon", "Gemini 4 Argon", 1_048_576, true],
109
- ["gemini-4-hydrogen", "Gemini 4 Hydrogen", 1_048_576, true],
110
- ["gemini-3.8-flash", "Gemini 3.8 Flash", 1_048_576, true],
111
- ["gemini-pro-orchestrator-neon", "Orchestrator (Neon)", 1_048_576, false],
112
- ["gemini-pro-orchestrator", "Orchestrator (Carbon)", 1_048_576, false],
113
- ["gemini-pro-orchestrator-argon", "Orchestrator (Argon)", 1_048_576, false],
114
- ["claude-opus-5-5", "Claude Opus 5.5", 1_000_000, true],
115
- ["claude-sonnet-5-5", "Claude Sonnet 5.5", 1_000_000, true],
116
- ["gpt-oss-120b-medium", "GPT-OSS 120B (Medium)", 128_000, false],
111
+ ["gemini-4-neon", "Gemini 4 Neon", AGY_CONTEXT, "xhigh"],
112
+ ["gemini-4-carbon", "Gemini 4 Carbon", AGY_CONTEXT, "high"],
113
+ ["gemini-4-argon", "Gemini 4 Argon", AGY_CONTEXT, "high"],
114
+ ["gemini-4-hydrogen", "Gemini 4 Hydrogen", AGY_CONTEXT, "xhigh"],
115
+ ["gemini-3.8-flash", "Gemini 3.8 Flash", AGY_CONTEXT, "high"],
116
+ ["gemini-pro-orchestrator-neon", "Orchestrator (Neon)", AGY_CONTEXT, null],
117
+ ["gemini-pro-orchestrator", "Orchestrator (Carbon)", AGY_CONTEXT, null],
118
+ ["gemini-pro-orchestrator-argon", "Orchestrator (Argon)", AGY_CONTEXT, null],
119
+ ["claude-opus-5-5", "Claude Opus 5.5", AGY_CONTEXT, "high"],
120
+ ["claude-sonnet-5-5", "Claude Sonnet 5.5", AGY_CONTEXT, "high"],
121
+ ["gpt-oss-120b-medium", "GPT-OSS 120B (Medium)", 128_000, null],
117
122
  ];
123
+ /**
124
+ * The efforts nexo may pick for a model, as pi's clamp reads them: `thought_level` runs low..high (plus xhigh on some
125
+ * models), and has no "off" or "minimal", which clamp up to low rather than leave the model on its own default (high).
126
+ * pi counts xhigh and max as supported only when mapped, so without this map they would clamp down to high.
127
+ */
128
+ function agyThinkingLevels(topLevel) {
129
+ return { off: null, minimal: null, low: "low", medium: "medium", high: "high", xhigh: topLevel === "xhigh" ? "xhigh" : null, max: null };
130
+ }
118
131
  /** Antigravity's base models, borrowing `maxTokens` from pi-ai's Google/Anthropic catalog where an entry matches. */
119
132
  function agyPModels() {
120
133
  const builtin = new Map();
@@ -122,7 +135,7 @@ function agyPModels() {
122
135
  for (const m of getBuiltinModels(provider))
123
136
  builtin.set(m.id, m);
124
137
  }
125
- return AGY_MODELS.map(([id, displayName, contextWindow, reasoning]) => {
138
+ return AGY_MODELS.map(([id, displayName, contextWindow, topLevel]) => {
126
139
  const base = builtin.get(id);
127
140
  return {
128
141
  ...(base ?? { maxTokens: id.startsWith("gemini-") ? 65_536 : 32_000 }),
@@ -131,7 +144,8 @@ function agyPModels() {
131
144
  api: AGY_P_API,
132
145
  provider: AGY_P_PROVIDER,
133
146
  baseUrl: "",
134
- reasoning,
147
+ reasoning: topLevel !== null,
148
+ thinkingLevelMap: topLevel === null ? undefined : agyThinkingLevels(topLevel),
135
149
  input: ["text", "image"],
136
150
  contextWindow,
137
151
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@@ -153,11 +167,122 @@ export function agyToolsSection(tools) {
153
167
  'Every reply must be exactly one JSON object and nothing else (no prose around it, no code fence): {"text": string, "tool_calls": [{"name": string, "arguments": object}]}.',
154
168
  "`text` is what you say to the user (may be empty). `tool_calls` lists actions for the caller to run now, with arguments matching the action's parameters.",
155
169
  "The actions below are not tools you can invoke: never call them directly and never invoke any native or built-in tool (`call_mcp_tool`, `list_resources`, `read_resource`, `manage_task`, etc.). These actions are NOT MCP tools — only list them in the JSON `tool_calls` array. The caller runs them and sends the results back in the next turn as <tool_result> entries. When you are finished, leave `tool_calls` empty and put the final answer in `text`.",
170
+ "When you list `tool_calls`, use `text` for one short sentence: what the earlier results showed and what these calls will check.",
171
+ "Earlier <assistant> entries may open with <notes>: your own reasoning from that turn, carried over because each turn starts fresh. Build on it, never write <notes> yourself, and do not repeat a command or read whose <tool_result> already answers the question.",
156
172
  "",
157
173
  "Available actions, one JSON definition per line:",
158
174
  defs,
159
175
  ].join("\n");
160
176
  }
177
+ /** How many of the latest assistant turns carry their reasoning forward, and how much of each (its end, where conclusions are). */
178
+ const NOTES_TURNS = 20;
179
+ const NOTES_CHARS = 1_500;
180
+ const NEW_MESSAGE_NOTE = "The last <user> entry is the user's newest message: follow it, even where it changes or stops the earlier work.";
181
+ function withNotes(message) {
182
+ if (message.role !== "assistant")
183
+ return message;
184
+ const reasoning = message.content
185
+ .map((b) => (b.type === "thinking" && !b.redacted ? b.thinking.trim() : ""))
186
+ .filter((t) => t.length > 0)
187
+ .join("\n");
188
+ if (!reasoning)
189
+ return message;
190
+ const kept = reasoning.length > NOTES_CHARS ? `…${reasoning.slice(-NOTES_CHARS)}` : reasoning;
191
+ return { ...message, content: [{ type: "text", text: `<notes>\n${kept}\n</notes>` }, ...message.content] };
192
+ }
193
+ /**
194
+ * The conversation as `agy acp` sees it. Each turn is a fresh session, so the model's reasoning from earlier turns
195
+ * would otherwise be lost: Gemini thinks in thinking blocks and leaves `text` empty on tool turns, then re-derives (and
196
+ * re-runs) what it already found. The latest turns' reasoning goes back in as <notes>, and a new user message that
197
+ * ends the transcript is called out so it is not mistaken for context.
198
+ */
199
+ export function agyTranscriptParts(messages) {
200
+ const turns = messages.filter((m) => m.role !== "system");
201
+ if (turns.length === 1 && turns[0]?.role === "user")
202
+ return renderTranscriptParts(turns);
203
+ const assistants = turns.flatMap((m, i) => (m.role === "assistant" ? [i] : []));
204
+ const noted = new Set(assistants.slice(-NOTES_TURNS));
205
+ const parts = renderEntryParts(turns.map((m, i) => (noted.has(i) ? withNotes(m) : m)));
206
+ const note = turns.at(-1)?.role === "user" ? `${NEXT_TURN_NOTE} ${NEW_MESSAGE_NOTE}` : NEXT_TURN_NOTE;
207
+ parts.push({ type: "text", text: `\n\n${note}` });
208
+ return parts;
209
+ }
210
+ /**
211
+ * `agy acp` silently cuts a prompt message at about 68k tokens and keeps its beginning, so on a long conversation the
212
+ * model never saw the newest tool results or user message and kept redoing its last step. The system prompt is not
213
+ * cut, so past `PROMPT_CHARS` of text the start of the transcript moves there and the message keeps its last
214
+ * `TAIL_CHARS` (at ~2.5 characters a token for code and JSON, both stay well under the cap).
215
+ */
216
+ const PROMPT_CHARS = 100_000;
217
+ const TAIL_CHARS = 40_000;
218
+ const CONTINUED_NOTE = "(The conversation so far is in your instructions under \"Conversation so far\"; it continues here.)\n\n";
219
+ /** Splits a long transcript into the part that goes in the system prompt (`history`) and the message to send. */
220
+ export function splitAgyPrompt(parts) {
221
+ const textChars = parts.reduce((n, p) => n + (p.type === "text" ? p.text.length : 0), 0);
222
+ if (textChars <= PROMPT_CHARS)
223
+ return { prompt: [...parts] };
224
+ const tail = [];
225
+ let budget = TAIL_CHARS;
226
+ let i = parts.length - 1;
227
+ let headEnd = "";
228
+ for (; i >= 0; i--) {
229
+ const part = parts[i];
230
+ if (part.type !== "text") {
231
+ tail.unshift(part);
232
+ continue;
233
+ }
234
+ if (part.text.length <= budget) {
235
+ tail.unshift(part);
236
+ budget -= part.text.length;
237
+ continue;
238
+ }
239
+ const cut = part.text.length - budget;
240
+ if (budget > 0)
241
+ tail.unshift({ type: "text", text: part.text.slice(cut) });
242
+ headEnd = part.text.slice(0, cut);
243
+ break;
244
+ }
245
+ // Images before the split cannot go in the system prompt; they stay as a marker where they were.
246
+ const history = parts
247
+ .slice(0, Math.max(0, i))
248
+ .map((p) => (p.type === "text" ? p.text : "[image]"))
249
+ .join("") + headEnd;
250
+ return { history, prompt: [{ type: "text", text: CONTINUED_NOTE }, ...tail] };
251
+ }
252
+ function historySection(history) {
253
+ return `# Conversation so far\n\nThe transcript below is cut where the user message continues it.\n\n${history}`;
254
+ }
255
+ /** MCP config agy reads from `<gemini dir>/config/`: the mirror swaps in an empty one. */
256
+ const MCP_CONFIG = "mcp_config.json";
257
+ /**
258
+ * Builds a copy of the Antigravity data directory under `workspace` whose entries are symlinks to the real ones (login,
259
+ * settings and projects included), except `config/mcp_config.json`, which lists no servers. `agy acp` offers the model
260
+ * every configured MCP server regardless of the agent's `tools: []` and the session's `mcpServers: []`, and those tools
261
+ * are what the model reaches for instead of the JSON reply. Returns undefined when there is nothing to mirror or the
262
+ * mirror cannot be made; the server then runs against the real directory.
263
+ */
264
+ export function mirrorGeminiDir(source, workspace) {
265
+ try {
266
+ if (!statSync(source).isDirectory())
267
+ return undefined;
268
+ const target = join(workspace, ".gemini-home");
269
+ mkdirSync(join(target, "config"), { recursive: true });
270
+ for (const name of readdirSync(source))
271
+ if (name !== "config")
272
+ symlinkSync(join(source, name), join(target, name));
273
+ const config = join(source, "config");
274
+ if (existsSync(config)) {
275
+ for (const name of readdirSync(config))
276
+ if (name !== MCP_CONFIG)
277
+ symlinkSync(join(config, name), join(target, "config", name));
278
+ }
279
+ writeFileSync(join(target, "config", MCP_CONFIG), '{"mcpServers":{}}\n', "utf8");
280
+ return target;
281
+ }
282
+ catch {
283
+ return undefined;
284
+ }
285
+ }
161
286
  let callSeq = 0;
162
287
  function toolCallId() {
163
288
  callSeq = (callSeq + 1) % 1_000_000;
@@ -322,14 +447,17 @@ class AcpConnection {
322
447
  this.onClose = onClose;
323
448
  }
324
449
  /** Starts the server and completes the `initialize` handshake. */
325
- static async open(run, onClose) {
450
+ static async open(run, onClose, geminiDir) {
326
451
  registerExitHandler();
327
452
  // Throwaway workspace holding the no-tools custom agent under ./.agents/agents, with no project files in reach.
328
453
  const dir = await mkdtemp(join(tmpdir(), "nexo-agy-p-"));
329
454
  liveDirs.add(dir);
330
455
  await mkdir(join(dir, ".agents", "agents"), { recursive: true });
331
456
  await writeFile(join(dir, ".agents", "agents", `${AGENT_NAME}.md`), AGENT_FILE, "utf8");
332
- const proc = run({ args: ["acp", "--agent", AGENT_NAME, "--include-default-customizations=false"], cwd: dir });
457
+ // Removing the workspace later unlinks the mirror's symlinks without touching what they point at.
458
+ const mirror = geminiDir === null ? undefined : mirrorGeminiDir(geminiDir, dir);
459
+ const args = ["acp", "--agent", AGENT_NAME, "--include-default-customizations=false", ...(mirror ? ["--gemini-dir", mirror] : [])];
460
+ const proc = run({ args, cwd: dir });
333
461
  const conn = new AcpConnection(proc, dir, onClose);
334
462
  void conn.pump();
335
463
  void proc.exit.then((exit) => conn.shutdown(new Error(exit.stderr.trim().split("\n").at(-1) || `agy exited with code ${exit.code ?? "null"}`)));
@@ -450,6 +578,8 @@ class AcpConnection {
450
578
  void rm(this.dir, { recursive: true, force: true }).catch(() => { });
451
579
  }
452
580
  }
581
+ /** Why a turn failed when agy answered nothing at all. */
582
+ export const AGY_P_EMPTY_REPLY = "agy returned an empty reply with no token usage (the conversation may exceed what agy accepts; compact it or start a new session)";
453
583
  /** Why a tools turn ended without a usable reply; the engine retries it a few times (see `isFormatFailure`). */
454
584
  export const AGY_P_BAD_REPLY = "reply was not a JSON object in the required format";
455
585
  /** True when a reply that did not parse was an attempt at the JSON format rather than a plain-prose answer. */
@@ -457,6 +587,9 @@ function looksLikeReplyAttempt(text) {
457
587
  return /"tool_calls"\s*:/.test(text) || /^\s*(```|\{)/.test(text);
458
588
  }
459
589
  const RETRY_NOTE = "Your previous reply was not a single valid JSON object in the required format. Reply again with only that JSON object.";
590
+ function nativeRetryNote(call) {
591
+ return `The tool "${call}" is not available: you have no native, built-in or MCP tools. Reply again with only the JSON object, listing actions in its \`tool_calls\` array.`;
592
+ }
460
593
  function raceAbort(promise, signal) {
461
594
  if (!signal)
462
595
  return promise;
@@ -504,7 +637,10 @@ function streamAgyP(getConn, model, context, options) {
504
637
  const tools = getCurrentTools(context.messages);
505
638
  const useTools = tools.length > 0 && options?.toolChoice !== "none";
506
639
  const knownTools = useTools ? new Set(tools.map((t) => t.name)) : new Set();
507
- const systemPrompt = [getCurrentSystemPrompt(context.messages), useTools ? agyToolsSection(tools) : ""].filter((s) => s.length > 0).join("\n\n");
640
+ const { history, prompt } = splitAgyPrompt(agyTranscriptParts(context.messages));
641
+ const systemPrompt = [getCurrentSystemPrompt(context.messages), useTools ? agyToolsSection(tools) : "", history ? historySection(history) : ""]
642
+ .filter((s) => s.length > 0)
643
+ .join("\n\n");
508
644
  const idleMs = parseIdleMs(process.env[AGY_P_IDLE_ENV]);
509
645
  const closeSession = (session) => {
510
646
  if (!session || session.conn.closed)
@@ -672,8 +808,10 @@ function streamAgyP(getConn, model, context, options) {
672
808
  outcome.aborted = true;
673
809
  else if (stalled)
674
810
  outcome.error = `no output for ${Math.round(idleMs / 1000)}s`;
675
- else if (nativeCall)
811
+ else if (nativeCall) {
812
+ outcome.nativeCall = nativeCall;
676
813
  outcome.error = `stopped: native tool call "${nativeCall}" (the nexo agent offers no tools)`;
814
+ }
677
815
  else if (outcome.recoveredCalls.length > 0) {
678
816
  if (!("e" in settled))
679
817
  outcome.usage = toUsage(settled.r?.usage);
@@ -700,7 +838,6 @@ function streamAgyP(getConn, model, context, options) {
700
838
  let session;
701
839
  try {
702
840
  stream.push({ type: "start", partial: snapshot() });
703
- const prompt = renderTranscriptParts(context.messages);
704
841
  const opened = await startSession();
705
842
  if (opened === "aborted" || signal?.aborted)
706
843
  return fail("aborted", "Request was aborted");
@@ -717,8 +854,19 @@ function streamAgyP(getConn, model, context, options) {
717
854
  let usage = outcome.usage;
718
855
  if (outcome.aborted || signal?.aborted)
719
856
  return fail("aborted", "Request was aborted", usage);
857
+ // A native tool call: correct it once in the same session (it keeps the transcript and its cache) rather
858
+ // than failing back to the engine, which would resend the whole transcript to a fresh session.
859
+ if (useTools && outcome.nativeCall) {
860
+ outcome = await runOnce(session, nativeRetryNote(outcome.nativeCall), !partial.content.some((b) => b.type === "text"));
861
+ usage = addUsage(usage, outcome.usage);
862
+ if (outcome.aborted || signal?.aborted)
863
+ return fail("aborted", "Request was aborted", usage);
864
+ }
720
865
  if (outcome.error)
721
866
  return fail("error", `agy failed: ${outcome.error}`, usage);
867
+ // No text, no calls and no usage: agy declined the prompt without saying why, as it does past its context limit.
868
+ if (!outcome.text.trim() && outcome.recoveredCalls.length === 0 && usage.totalTokens === 0)
869
+ return fail("error", `agy failed: ${AGY_P_EMPTY_REPLY}`, usage);
722
870
  let stopReason = outcome.stopReason === "max_tokens" ? "length" : "stop";
723
871
  if (useTools) {
724
872
  const fromOutcome = (o) => o.recoveredCalls.length > 0
@@ -782,14 +930,17 @@ function streamAgyP(getConn, model, context, options) {
782
930
  /**
783
931
  * Runs models through one long-lived Antigravity CLI ACP server (`agy acp`), authenticated by the CLI's own login.
784
932
  * The server starts on the first call and is shared by every call after it, avoiding per-call language-server start-up.
785
- * It runs a minimal custom agent with `tools: []` in a throwaway workspace; each turn opens a fresh session carrying
933
+ * It runs a minimal custom agent with `tools: []` in a throwaway workspace, against a mirror of the Antigravity data
934
+ * directory with no MCP servers (`mirrorGeminiDir`); each turn opens a fresh session carrying
786
935
  * nexo's system prompt via `_meta.antigravity.systemPrompt.append`, sets the base model and `thought_level` from
787
- * reasoning effort, and closes the session afterwards. Any native tool call cancels the turn. Nexo tools are described
936
+ * reasoning effort, and closes the session afterwards. The transcript carries the latest turns' reasoning as <notes>
937
+ * (`agyTranscriptParts`). Any native tool call cancels the turn and is corrected once in the same session. Nexo tools are described
788
938
  * in the prompt and parsed as `{ text, tool_calls }` (one correction retry when it does not parse); `text` streams as
789
939
  * it is written. Token counts are reported from ACP usage while cost stays $0.
790
940
  */
791
941
  export function agyPProvider(options = {}) {
792
942
  const run = options.run ?? spawnRunner(options.command ?? process.env[AGY_P_COMMAND_ENV] ?? "agy");
943
+ const geminiDir = options.geminiDir === undefined ? join(homedir(), ".gemini") : options.geminiDir;
793
944
  let current;
794
945
  const getConn = () => {
795
946
  if (current)
@@ -797,7 +948,7 @@ export function agyPProvider(options = {}) {
797
948
  const opened = AcpConnection.open(run, () => {
798
949
  if (current === opened)
799
950
  current = undefined;
800
- });
951
+ }, geminiDir);
801
952
  current = opened;
802
953
  opened.catch(() => {
803
954
  if (current === opened)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hexdecimal16/nexo",
3
- "version": "0.4.17",
3
+ "version": "0.4.19",
4
4
  "description": "nexo agent engine",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "repository": {