@joenandez/academy 0.4.0 → 0.5.13

package/scripts/cli/tldr.mjs

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ACADEMY_ROOT, RuntimeUnavailableError } from './core.mjs';
+
+const PRODUCT = 'tldr-agents';
+const ACTIVATION_MANIFEST = path.join('release', 'activation-manifest.json');
+const ORPHAN_MARKER = '.orphaned_at';
+const REGISTRY_PLUGIN_NAME = 'tldr';
+const FALLBACK_RELEASE = path.join('.tldr-agents', 'agent', 'install', 'tldr-agent');
+
+function isAbsoluteExecutable(file) {
+  if (!path.isAbsolute(file)) return false;
+  try {
+    const stat = fs.statSync(file);
+    return stat.isFile() && (stat.mode & 0o111) !== 0;
+  } catch {
+    return false;
+  }
+}
+
+function manifestNamesTldrAgents(release) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(release, ACTIVATION_MANIFEST), 'utf8'));
+    return manifest?.product === PRODUCT;
+  } catch {
+    return false;
+  }
+}
+
+function verifyRelease(release, source) {
+  const bin = path.join(release, 'bin', PRODUCT);
+  if (!isAbsoluteExecutable(bin)) {
+    throw new RuntimeUnavailableError(
+      `Failed to resolve executable "${PRODUCT}" from ${source}: ${bin} is not executable.`,
+      { executable: PRODUCT },
+    );
+  }
+  if (!manifestNamesTldrAgents(release)) {
+    throw new RuntimeUnavailableError(
+      `Failed to resolve executable "${PRODUCT}" from ${source}: ${release} is not a tldr-agents release.`,
+      { executable: PRODUCT },
+    );
+  }
+  return bin;
+}
+
+function verifyOverride(bin) {
+  const binDir = path.dirname(bin);
+  if (!path.isAbsolute(bin) || path.basename(bin) !== PRODUCT || path.basename(binDir) !== 'bin') {
+    throw new RuntimeUnavailableError(
+      `Failed to resolve executable "${PRODUCT}" from SUBSPACE_TLDR_AGENTS_BIN: ${bin} is not an absolute tldr-agents executable.`,
+      { executable: PRODUCT },
+    );
+  }
+  return verifyRelease(path.dirname(binDir), 'SUBSPACE_TLDR_AGENTS_BIN');
+}
+
+function registryInstalls(registryPath) {
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  } catch {
+    return [];
+  }
+  return Object.entries(registry?.plugins ?? {})
+    .filter(
+      ([key, installs]) => key.split('@')[0] === REGISTRY_PLUGIN_NAME && Array.isArray(installs),
+    )
+    .flatMap(([, installs]) => installs)
+    .filter((entry) => typeof entry?.installPath === 'string')
+    .filter((entry) => !fs.existsSync(path.join(entry.installPath, ORPHAN_MARKER)))
+    .map((entry) => ({ release: entry.installPath, lastUpdated: Date.parse(entry.lastUpdated) }));
+}
+
+function newestFirst(left, right) {
+  const a = Number.isNaN(left.lastUpdated) ? -Infinity : left.lastUpdated;
+  const b = Number.isNaN(right.lastUpdated) ? -Infinity : right.lastUpdated;
+  return b - a;
+}
+
+function resolveFromRegistry(homeDir) {
+  const registryPath = path.join(homeDir, '.claude', 'plugins', 'installed_plugins.json');
+  const installs = registryInstalls(registryPath).sort(newestFirst);
+  if (installs.length === 0) return null;
+  let newestRejection = null;
+  for (const install of installs) {
+    try {
+      return verifyRelease(install.release, 'plugin registry');
+    } catch (error) {
+      newestRejection ??= error;
+    }
+  }
+  throw newestRejection;
+}
+
+// The tldr package Academy depends on, for a machine with no plugin install
+// (WSL, Linux). Walks up like Node resolution: npm nests it under Academy, or
+// dedupes it to a sibling global package. Not require.resolve: tldr's empty
+// `exports` map blocks it. Its package root is also its Claude plugin root.
+function bundledTldrRoot(academyRoot) {
+  for (let dir = academyRoot; ; dir = path.dirname(dir)) {
+    try {
+      return fs.realpathSync(path.join(dir, 'node_modules', '@joenandez', 'tldr'));
+    } catch {
+      if (path.dirname(dir) === dir) return null;
+    }
+  }
+}
+
+function resolveTldrAgents(env, academyRoot) {
+  const override = env.SUBSPACE_TLDR_AGENTS_BIN;
+  if (override) return { bin: verifyOverride(override) };
+
+  const homeDir = os.homedir();
+  if (!path.isAbsolute(homeDir)) {
+    throw new RuntimeUnavailableError(`Failed to resolve executable "${PRODUCT}".`, {
+      executable: PRODUCT,
+    });
+  }
+
+  const registryBin = resolveFromRegistry(homeDir);
+  if (registryBin) return { bin: registryBin };
+
+  const fallback = path.join(homeDir, FALLBACK_RELEASE);
+  if (fs.existsSync(path.join(fallback, 'bin', PRODUCT))) {
+    return { bin: verifyRelease(fallback, 'fallback install') };
+  }
+  const bundled = bundledTldrRoot(academyRoot);
+  if (!bundled) {
+    throw new RuntimeUnavailableError(
+      `Failed to resolve executable "${PRODUCT}" from plugin registry, fallback install, or bundled package.`,
+      { executable: PRODUCT },
+    );
+  }
+  return { bin: verifyRelease(bundled, 'bundled package'), root: bundled };
+}
+
+export function resolveTldrAgentsBinary(env = process.env, academyRoot = ACADEMY_ROOT) {
+  return resolveTldrAgents(env, academyRoot).bin;
+}
+
+// The bundled package's plugin root, or null when tldr resolves from anywhere
+// else (or nowhere): only then must a launch load the bundled plugin itself.
+export function bundledTldrPluginRoot(env = process.env, academyRoot = ACADEMY_ROOT) {
+  try {
+    return resolveTldrAgents(env, academyRoot).root ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// A hung tldr must not hold an agent's lifecycle lock (others wait 5 s for it)
+// without bound. Generous because the machine can run at very high load.
+// ACADEMY_TLDR_TIMEOUT_MS is the test override, as ACADEMY_HIRE_TIMEOUT_MS is for hire.
+const DEFAULT_TLDR_TIMEOUT_MS = 60_000;
+
+export function tldrTimeoutMs(env = process.env) {
+  const configured = Number.parseInt(env.ACADEMY_TLDR_TIMEOUT_MS ?? '', 10);
+  return Number.isInteger(configured) && configured > 0 ? configured : DEFAULT_TLDR_TIMEOUT_MS;
+}
+
+// The spawnSync options every tldr-agents call shares, timeout included.
+export const tldrSpawnOptions = (cwd, extra = {}) => ({
+  cwd,
+  encoding: 'utf8',
+  env: process.env,
+  timeout: tldrTimeoutMs(),
+  ...extra,
+});
+
+export function spawnTldrTasksArgs(args) {
+  return ['tasks', ...args];
+}
+
+// tldr starts a job's run with its own context env, built by its executor
+// (`buildHelmContextEnv` for an adapter run, the runtime env for a command
+// job): HELM_JOB_ID, HELM_RUN_ID, HELM_REPORT_CMD, HELM_SCOPE_ID,
+// HELM_SCOPE_CWD. An adapter (`--provider`) run gets no job env: tldr refuses
+// `--env-json` on a provider job, and would not pass it on. The job id is the
+// one fact about the run that always arrives, so `academy run` reads it here.
+export function schedulerJobId(env = process.env) {
+  return env.HELM_JOB_ID || null;
+}

package/scripts/cli/toml-string.mjs

@@ -0,0 +1,76 @@
+// The string forms of a TOML value, as Codex reads a `-c key=value` override.
+// Anything that is not one complete, valid TOML string is the raw text, which
+// is what Codex does with a value that does not parse.
+
+const SIMPLE_ESCAPES = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+const HEX_WIDTH = { u: 4, U: 8 };
+
+function codePointText(hex) {
+  const point = Number.parseInt(hex, 16);
+  const valid =
+    /^[0-9a-fA-F]+$/.test(hex) && point <= 0x10ffff && !(point >= 0xd800 && point <= 0xdfff);
+  return valid ? String.fromCodePoint(point) : undefined;
+}
+
+// Reads the escape that starts at `raw[at]` (the backslash). Returns the text it
+// stands for and where reading resumes, or undefined for an invalid escape.
+function readEscape(raw, at, multiline) {
+  const kind = raw[at + 1];
+  if (kind in SIMPLE_ESCAPES) return { text: SIMPLE_ESCAPES[kind], next: at + 2 };
+  if (kind in HEX_WIDTH) {
+    const end = at + 2 + HEX_WIDTH[kind];
+    const text = codePointText(raw.slice(at + 2, end));
+    return text === undefined ? undefined : { text, next: end };
+  }
+  // A line-ending backslash drops the newline and the whitespace after it.
+  const trimmed = /^[ \t]*\r?\n\s*/.exec(raw.slice(at + 1));
+  return multiline && trimmed ? { text: '', next: at + 1 + trimmed[0].length } : undefined;
+}
+
+// A quote either closes the string (`closed` is the content it adds) or is
+// content itself.
+function readQuote(raw, at, quote, multiline) {
+  let run = 1;
+  while (raw[at + run] === quote) run++;
+  if (!multiline) return at + 1 === raw.length ? { closed: '' } : undefined;
+  if (run < 3) return { text: quote.repeat(run), next: at + run };
+  // At most two quotes may sit against the closing three, as content.
+  return run <= 5 && at + run === raw.length ? { closed: quote.repeat(run - 3) } : undefined;
+}
+
+function readStep(raw, at, quote, multiline) {
+  const ch = raw[at];
+  if (ch === quote) return readQuote(raw, at, quote, multiline);
+  if (ch === '\\' && quote === '"') return readEscape(raw, at, multiline);
+  return ch === '\n' && !multiline ? undefined : { text: ch, next: at + 1 };
+}
+
+function scanString(raw, quote, multiline) {
+  const open = quote.repeat(multiline ? 3 : 1);
+  if (!raw.startsWith(open)) return undefined;
+  let at = open.length;
+  if (multiline) at += /^\r?\n/.exec(raw.slice(at))?.[0].length ?? 0;
+  let out = '';
+  while (at < raw.length) {
+    const step = readStep(raw, at, quote, multiline);
+    if (!step) return undefined;
+    if (step.closed !== undefined) return out + step.closed;
+    out += step.text;
+    at = step.next;
+  }
+  return undefined;
+}
+
+export function decodeTomlString(raw) {
+  const forms = [
+    ['"', true],
+    ['"', false],
+    ["'", true],
+    ["'", false],
+  ];
+  for (const [quote, multiline] of forms) {
+    const text = scanString(raw, quote, multiline);
+    if (text !== undefined) return text;
+  }
+  return raw;
+}

package/scripts/cli/user-work-view.mjs

@@ -0,0 +1,48 @@
+const AGENTS_LINE = /^agents:/;
+
+// A section is `## ` through the line before the next `## `; the preamble is
+// everything before the first. Only the curator writes the `agents:` line, and
+// it never reaches a prompt. `names` are the agent's current name and fixed id:
+// a rename changes only the name, and the curator may still list the id.
+export function filterUserWork(text, ...names) {
+  const [preamble, ...sections] = text.split('\n').reduce(
+    (blocks, line) => {
+      if (line.startsWith('## ')) blocks.push([]);
+      blocks.at(-1).push(line);
+      return blocks;
+    },
+    [[]],
+  );
+  const kept = sections.filter((lines) => {
+    const named = lines.find((line) => AGENTS_LINE.test(line));
+    return (
+      named !== undefined &&
+      named
+        .slice('agents:'.length)
+        .split(',')
+        .some((agent) => names.includes(agent.trim()))
+    );
+  });
+  const view = [preamble, ...kept.map((lines) => lines.filter((line) => !AGENTS_LINE.test(line)))]
+    .flat()
+    .join('\n')
+    .trimEnd();
+  return { view, sections: sections.length, kept: kept.length };
+}
+
+/** The part of the user's user-work.md that names `name`: preamble plus its sections. */
+export function userWorkView(text, name) {
+  return filterUserWork(text, name).view;
+}
+
+export function logUserWorkView(agent, surfaces) {
+  const { sections, kept } = surfaces.find(({ name }) => name === 'user-work');
+  console.error(
+    JSON.stringify({
+      event: 'run.user_work_view',
+      params: { agent },
+      result: { sections, kept },
+      status: 'filtered',
+    }),
+  );
+}

package/scripts/cli/writable-dirs.mjs

@@ -0,0 +1,23 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ACADEMY_HOME, kindOf } from './core.mjs';
+
+/** The Lane 2 proposal queue a kind's skills write to. */
+export const proposalsDir = (kind) => join(ACADEMY_HOME, 'proposals', kind);
+
+// Every kind is granted ACADEMY_HOME: its proposal queue, user.md and the other
+// shared files live there, outside its home and outside any project. The grant
+// is a directory because a file path is not a directory grant. It reaches more
+// than the queue, so the one-writer rule for shared files is the operating
+// model's to keep, not the sandbox's. The queue is created first, which also
+// creates ACADEMY_HOME: a provider may refuse an --add-dir that does not exist.
+export function sharedWritableDirArgs(dir) {
+  mkdirSync(proposalsDir(kindOf(dir)), { recursive: true });
+  return ['--add-dir', ACADEMY_HOME];
+}
+
+// Codex sandboxes writes to its -C root, so a project run must also be granted
+// the agent home.
+export function codexWritableDirArgs(dir) {
+  return ['--add-dir', dir, ...sharedWritableDirArgs(dir)];
+}

package/scripts/cli/yaml.mjs

@@ -44,7 +44,7 @@ export function writeAgentYamlScalar(dir, key, value) {
 }
 
 // The same write for a caller that already holds the agent's lifecycle lock.
-// `rename` moves the directory and rewrites `name:` in one critical section, so
+// `rename` rewrites `name:` inside the agent's lifecycle lock, so
 // taking the lock a second time here would block against its own holder until
 // the timeout and report `lock_timeout` for work that was never contended.
 export function rewriteAgentYamlScalar(dir, key, value) {