@lardexx/arenacode 2.10.0 → 2.11.0

package/README.md

@@ -271,6 +271,41 @@ Every file path is resolved **inside the open folder**; paths that escape it are
 the folder itself. Local operations run with your user's permissions — `--confirm-writes` adds a confirmation for
 mutating file operations, `--yes` skips confirmations for terminal commands.
 
+### Project context
+
+Every folder gets its own log, `context_<project>.md`, next to the files you are working on. It is the desktop
+client's file, with the desktop's own template (mined from `ArenaCode-x64.exe`):
+
+```markdown
+# Contesto del progetto progetto-web
+
+Sessione: 2026-11-02 21:45 (nome-del-bridge.tunnl.gg)
+_Nessun task ancora._
+<!-- agente:inizio -->
+<!-- agente:fine -->
+
+Aggiornato automaticamente da ArenaCode a fine di ogni job. La API key non è scritta qui.
+```
+
+The title, the session label, the placeholder and the footer follow the interface language (`it`, `en`, `es`).
+What happens when:
+
+* **The folder opens or a session starts** → the client creates the file if it is missing, and adds a `Sessione:`
+  line for the new session. An existing file is **never overwritten**: the agent's block lives inside it.
+* **At the end of every task** the agent rewrites the block between `<!-- agente:inizio -->` and
+  `<!-- agente:fine -->` (date, task id, files changed, commits, decisions, what is still open, how it was checked —
+  at most 40 lines). The client saves it **at once, without Accept or Reject**: the card only shows what changed.
+* **The first task of a new bridge session** carries the whole file as `project_context`, so the bridge writes it
+  to `runtime/project_context.txt` and tells the agent to read it in parts (`agentctl.py context --part N`). Later
+  tasks do not repeat it — a new bridge (`/health` → `started_at`) or a different folder makes it travel again.
+  The file is never summarised or truncated.
+* **Commits** never include it: `git add -A` runs, then the sheet is unstaged — `git add -A, never
+  context_<project>.md`, as the desktop puts it.
+
+`test/context.js` checks the template verbatim in the three languages, the "create once, never overwrite" rule,
+the send-once-per-session rule and the git exclusion; the integration test checks that a real task creates the
+sheet and that the bridge receives it.
+
 ### Shells
 
 Terminal cards run in a real shell, and which one is not fixed:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lardexx/arenacode",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Terminal client for ArenaCode: talks to an arena-bridge, streams the Agent Mode timeline, and runs local commands, file operations and computer automation on your PC (windows-use.dll on Windows, Xlib/XTest on Linux, osascript on macOS). Node port of the ArenaCode desktop client.",
   "license": "MIT",
   "type": "commonjs",
@@ -20,7 +20,7 @@
     "vendor/"
   ],
   "scripts": {
-    "test": "node test/shell.js && node test/integration.js && node test/parity.js && node test/automation.js && node test/native.js"
+    "test": "node test/shell.js && node test/context.js && node test/integration.js && node test/parity.js && node test/automation.js && node test/native.js"
   },
   "keywords": [
     "arenacode",

package/src/cli.js

@@ -14,6 +14,7 @@ const { attachRefs, decorate } = require('./attach');
 const { decide, dangerText, normaliseApproval } = require('./approval');
 const session = require('./session');
 const { buildMeta, readProjectContext } = require('./meta');
+const { ensureContextFile, shouldSend: shouldSendContext, markSent: markContextSent } = require('./context');
 const { followTask } = require('./turn');
 const { c, write, ask, banner, truncate, indentLines } = require('./ui');
 
@@ -286,16 +287,42 @@ function agentPrompt() {
 }
 
 /** POST /task exactly like the desktop client does. */
+/**
+ * The bridge says it itself: `started_at` in /health changes every time the bridge
+ * starts. That is how the client knows a session is new and the sheet has to be sent.
+ */
+const bridgeStarts = new Map();
+async function bridgeStartedAt(bridge, url) {
+  if (bridgeStarts.has(url)) return bridgeStarts.get(url);
+  let startedAt = null;
+  try {
+    const res = await bridge.health();
+    if (res.status === 200 && res.json) startedAt = res.json.started_at ?? null;
+  } catch {
+    startedAt = null;
+  }
+  bridgeStarts.set(url, startedAt);
+  return startedAt;
+}
+
 async function createTask(ctx, instruction, { extraInstructions = '' } = {}) {
   const meta = buildMeta(ctx.folder, { lang: ctx.lang, pcAccess: ctx.pcAccess, activeFile: '' });
-  const projectContext = readProjectContext(ctx.folder);
+  // the sheet exists from the moment the folder is used: the agent fills the block
+  // between the markers at the end of every task, the client only writes the frame
+  ensureContextFile(ctx.folder, { lang: ctx.lang, bridgeUrl: ctx.url });
+  const startedAt = await bridgeStartedAt(ctx.bridge, ctx.url);
+  const sendContext = shouldSendContext({ folder: ctx.folder, url: ctx.url, startedAt });
+  const projectContext = sendContext ? readProjectContext(ctx.folder) : '';
   const body = {
     instruction,
     wait: 0,
     meta,
     agent_prompt: agentPrompt(),
   };
-  if (projectContext) body.project_context = projectContext;
+  if (projectContext) {
+    body.project_context = projectContext;
+    markContextSent({ folder: ctx.folder, url: ctx.url, startedAt });
+  }
   if (extraInstructions) body.instruction = `${instruction}\n\n${extraInstructions}`;
 
   const res = await ctx.bridge.createTask(body);

package/src/context.js

@@ -0,0 +1,234 @@
+'use strict';
+
+// The project context sheet: `context_<project>.md` in the open folder.
+//
+// Mined from ArenaCode-x64.exe (the literals are the desktop client's own, UTF-16 in
+// .rdata, built by the function at 0x14002f7f0):
+//
+//   '# Contesto del progetto ' + name + '\n\n'
+//   'Sessione: ' + … + ' (' + … + ')\n'
+//   '_Nessun task ancora._\n'
+//   '<!-- agente:inizio -->\n'
+//   '<!-- agente:fine -->\n\n'
+//   'Aggiornato automaticamente da ArenaCode a fine di ogni job. La API key non è scritta qui.\n\n'
+//
+// The client creates the file when the folder opens or a session starts, sends the whole
+// file to the bridge with the first task of a new bridge session (bridge_server.py:
+// "arriva con il primo task di un bridge nuovo"), and never summarises it. The agent
+// rewrites the block between the two HTML comments at the end of every task — the client
+// only writes the frame, never the block.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const MARK_START = '<!-- agente:inizio -->';
+const MARK_END = '<!-- agente:fine -->';
+
+const TEXT = {
+  it: {
+    title: '# Contesto del progetto ',
+    session: 'Sessione: ',
+    noTask: '_Nessun task ancora._',
+    footer: 'Aggiornato automaticamente da ArenaCode a fine di ogni job. La API key non è scritta qui.',
+  },
+  en: {
+    title: '# Project context ',
+    session: 'Session: ',
+    noTask: '_No task yet._',
+    footer: 'Updated automatically by ArenaCode at the end of each job. The API key is not written here.',
+  },
+  es: {
+    title: '# Contexto del proyecto ',
+    session: 'Sesión: ',
+    noTask: '_Ningún trabajo todavía._',
+    footer: 'Actualizado automáticamente por ArenaCode al final de cada trabajo. La clave API no se escribe aquí.',
+  },
+};
+
+function pack(lang) {
+  return TEXT[lang] || TEXT.it;
+}
+
+/** `Progetto web` → `Progetto-web`; keeps the name readable, drops what a filesystem hates. */
+function projectName(folder) {
+  const base = path.basename(path.resolve(String(folder || '.'))) || 'progetto';
+  const clean = base
+    .replace(/[\\/:*?"<>|]/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/^[.-]+/, '')
+    .slice(0, 60);
+  return clean || 'progetto';
+}
+
+function contextFileName(folder) {
+  return `context_${projectName(folder)}.md`;
+}
+
+function contextFilePath(folder) {
+  return path.join(path.resolve(String(folder || '.')), contextFileName(folder));
+}
+
+function stamp(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+/** Where the session line's parenthetical comes from: the bridge, or the machine. */
+function sessionHost(bridgeUrl) {
+  const raw = String(bridgeUrl || '').trim();
+  if (raw) {
+    try {
+      return new URL(raw.includes('://') ? raw : `https://${raw}`).host;
+    } catch {
+      return raw;
+    }
+  }
+  return os.hostname();
+}
+
+/** The frame the client writes, byte for byte in the desktop's order. */
+function buildTemplate({ folder, lang = 'it', bridgeUrl = '', now = new Date() } = {}) {
+  const t = pack(lang);
+  return (
+    `${t.title}${projectName(folder)}\n` +
+    '\n' +
+    `${t.session}${stamp(now)} (${sessionHost(bridgeUrl)})\n` +
+    `${t.noTask}\n` +
+    `${MARK_START}\n` +
+    `${MARK_END}\n` +
+    '\n' +
+    `${t.footer}\n`
+  );
+}
+
+/**
+ * Creates the file if the folder does not have one yet. An existing file is never
+ * touched: it is the project's log and the agent's block lives inside it.
+ */
+function ensureContextFile(folder, { lang = 'it', bridgeUrl = '', now = new Date() } = {}) {
+  const root = path.resolve(String(folder || '.'));
+  const file = contextFilePath(root);
+  try {
+    const stat = fs.statSync(file);
+    if (stat.isFile()) return { ok: true, file, created: false, name: contextFileName(root) };
+  } catch {
+    /* not there yet */
+  }
+  try {
+    fs.mkdirSync(root, { recursive: true });
+    fs.writeFileSync(file, buildTemplate({ folder: root, lang, bridgeUrl, now }), { encoding: 'utf8', flag: 'wx' });
+    return { ok: true, file, created: true, name: contextFileName(root) };
+  } catch (err) {
+    // EEXIST: another window created it first — fine, nothing to do
+    if (err.code === 'EEXIST') return { ok: true, file, created: false, name: contextFileName(root) };
+    return { ok: false, file, created: false, error: err.message };
+  }
+}
+
+/** Reads the sheet the way the desktop sends it: whole, untouched. */
+function readContext(folder, { maxBytes = 200_000 } = {}) {
+  const root = path.resolve(String(folder || '.'));
+  let names = [];
+  try {
+    names = fs.readdirSync(root).filter((name) => /^context_.*\.md$/i.test(name));
+  } catch {
+    return '';
+  }
+  if (!names.length) return '';
+  // the one for this folder first, then any other context sheet
+  const file = names.find((name) => name === contextFileName(root)) || names[0];
+  try {
+    const full = path.join(root, file);
+    if (fs.statSync(full).size > maxBytes) return '';
+    return fs.readFileSync(full, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+// ------------------------------------------------------------------ sending it --
+// The bridge writes what it receives to runtime/project_context.txt and tells the agent
+// to read it in parts; it expects it once per bridge session, not on every task.
+
+const STATE_FILE = () => path.join(path.dirname(configDir()), 'context-state.json');
+
+function configDir() {
+  if (process.platform === 'win32') {
+    const base = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+    return path.join(base, 'ArenaCode', 'config.json');
+  }
+  return path.join(os.homedir(), '.arenacode', 'config.json');
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeState(state) {
+  try {
+    fs.mkdirSync(path.dirname(STATE_FILE()), { recursive: true });
+    fs.writeFileSync(STATE_FILE(), JSON.stringify(state, null, 2), 'utf8');
+  } catch {
+    /* a read-only HOME only costs one extra send */
+  }
+}
+
+/**
+ * Should this task carry the project context? Yes on the first task of a bridge
+ * session and whenever the folder changes, no for the following tasks.
+ */
+function shouldSend({ folder, url = '', startedAt = null } = {}) {
+  const state = readState();
+  const project = path.resolve(String(folder || '.'));
+  if (state.folder !== project) return true;
+  if (!startedAt) return false; // same folder, bridge identity unknown: it already got it
+  return state.url !== String(url) || Number(state.startedAt) !== Number(startedAt);
+}
+
+function markSent({ folder, url = '', startedAt = null } = {}) {
+  writeState({ folder: path.resolve(String(folder || '.')), url: String(url), startedAt: startedAt ? Number(startedAt) : null });
+}
+
+/** Appends a session line to the sheet when the client opens it again later. */
+function touchSession(folder, { lang = 'it', bridgeUrl = '', now = new Date() } = {}) {
+  const file = contextFilePath(folder);
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { ok: false, error: 'context file missing' };
+  }
+  const t = pack(lang);
+  const line = `${t.session}${stamp(now)} (${sessionHost(bridgeUrl)})\n`;
+  if (text.includes(line)) return { ok: true, file, added: false };
+  const at = text.indexOf('\n\n');
+  const updated = at >= 0 ? `${text.slice(0, at + 2)}${line}${text.slice(at + 2)}` : `${text}${line}`;
+  try {
+    fs.writeFileSync(file, updated, 'utf8');
+    return { ok: true, file, added: true };
+  } catch (err) {
+    return { ok: false, file, error: err.message };
+  }
+}
+
+module.exports = {
+  MARK_START,
+  MARK_END,
+  TEXT,
+  projectName,
+  contextFileName,
+  contextFilePath,
+  buildTemplate,
+  ensureContextFile,
+  readContext,
+  shouldSend,
+  markSent,
+  touchSession,
+  sessionHost,
+  stamp,
+};

package/src/local.js

@@ -39,6 +39,15 @@ function resolveInRoot(root, rel) {
   return abs;
 }
 
+/** `context_<project>.md` — the project log, never committed and never asked about. */
+function contextFiles(root) {
+  try {
+    return fs.readdirSync(root).filter((name) => /^context_.*\.md$/i.test(name));
+  } catch {
+    return [];
+  }
+}
+
 function relativize(root, abs) {
   const rel = path.relative(root, abs).replace(/\\/g, '/');
   return rel === '' ? '.' : rel;
@@ -426,6 +435,8 @@ function runFsOp(op, body, root) {
     case 'git_commit': {
       const add = git(['add', '-A'], root);
       if (!add.ok) return { ok: false, error: add.output };
+      // the project log stays out of the history, exactly like the desktop client does
+      for (const name of contextFiles(root)) git(['reset', '-q', '--', name], root);
       const commit = git(['commit', '-m', String(body.content || 'ArenaCode')], root);
       return { ok: commit.ok, output: commit.output };
     }
@@ -475,7 +486,9 @@ async function handleLocalFs(bridge, taskId, request, opts) {
   write(`  ${c.bold(c.yellow('▤ files'))} ${c.dim('·')} ${c.cyan(op)} ${c.gray(request.path || '.')}${request.to ? c.gray(` → ${request.to}`) : ''}`);
 
   const mutating = ['write', 'replace', 'rm', 'mv', 'mkdir'].includes(op);
-  const verdict = mutating
+  // the project log is saved at once: the card only shows what changed, like the desktop
+  const isProjectLog = /^context_.*\.md$/i.test(path.basename(String(request.path || '')));
+  const verdict = mutating && !isProjectLog
     ? decide({
         approval: opts.approval,
         mode: session.modeOf(taskId),
@@ -485,7 +498,7 @@ async function handleLocalFs(bridge, taskId, request, opts) {
       })
     : 'auto';
   // --confirm-writes keeps asking even when the client runs in Proceed
-  const mustAsk = mutating && (verdict === 'ask' || opts.confirmWrites);
+  const mustAsk = mutating && !isProjectLog && (verdict === 'ask' || opts.confirmWrites);
   if (mustAsk) {
     const key = await askKey(`  ${t(lang, 'Applico? [s] sì  [n] no', 'Apply? [y] yes  [n] no', '¿Aplico? [s] sí  [n] no')} `, ['s', 'y', 'n']);
     if (key === 'n') {

package/src/meta.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { readContext } = require('./context');
 const { execFileSync } = require('node:child_process');
 
 const { CLIENT_NAME, VERSION } = require('./config');
@@ -118,26 +119,12 @@ function buildMeta(folder, { lang = 'it', pcAccess = true, activeFile = '', open
 }
 
 /**
- * Project context: the client sends the content of `context_<project>.md` from the
- * open folder when a bridge session starts, so the agent can resume the project.
+ * Project context: the content of `context_<project>.md` from the open folder, sent to
+ * the bridge with the first task of a new session (see src/context.js for the sheet and
+ * for the gating).
  */
 function readProjectContext(folder) {
-  const root = path.resolve(folder);
-  let names = [];
-  try {
-    names = fs.readdirSync(root).filter((n) => /^context_.*\.md$/i.test(n));
-  } catch {
-    return '';
-  }
-  if (!names.length) return '';
-  const file = path.join(root, names[0]);
-  try {
-    const stat = fs.statSync(file);
-    if (stat.size > MAX_CONTEXT_BYTES) return '';
-    return fs.readFileSync(file, 'utf8');
-  } catch {
-    return '';
-  }
+  return readContext(folder, { maxBytes: MAX_CONTEXT_BYTES });
 }
 
 module.exports = { POLICY, VERSION, buildMeta, workspaceMeta, readProjectContext, detectTools, which };

package/src/tui/app.js

@@ -16,6 +16,7 @@ const { Bridge } = require('../bridge');
 const { buildMeta, readProjectContext } = require('../meta');
 const { runShell, runFsOp, resolveInRoot, detectShell, availableShells, shellCommand } = require('../local');
 const { readConfig, patchConfig, deviceId, resolveUrl, resolveKey, openFolder, VERSION } = require('../config');
+const { ensureContextFile, touchSession } = require('../context');
 
 const { MODE_LINES, modeLabel, nextMode, normaliseMode } = require('../modes');
 const { attachRefs, attachImage, decorate, strings } = require('../attach');
@@ -90,6 +91,14 @@ class App {
 
   // ---------------------------------------------------------------- lifecycle
   async start() {
+    // the sheet belongs to the folder, not to the task: it is there as soon as the
+    // folder is open, and it records this session next to the previous ones
+    try {
+      const made = ensureContextFile(this.folder, { lang: this.lang, bridgeUrl: this.url });
+      if (!made.created) touchSession(this.folder, { lang: this.lang, bridgeUrl: this.url });
+    } catch {
+      /* a read-only folder must not stop the client */
+    }
     this.term.enter();
     this.term.on('key', (chunk) => {
       this.parser.feed(chunk);