@joenandez/academy 0.4.0 → 0.5.12

package/scripts/cli/run.mjs

@@ -1,19 +1,19 @@
-import { existsSync, unlinkSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { isatty } from 'node:tty';
+import { bridgeEnvPresent, bridgeLauncher, MEMORY_BRIDGE_ENV } from '../../hooks/memory_bridge.mjs';
 import { pendingMarkerPath } from '../../hooks/memory_store.mjs';
 import {
   codexRuntimeContextPath,
   launchCodex,
   readJsonFile,
+  withRepoCheck,
   writeCodexHooks,
   writeCodexProfile,
 } from './codex.mjs';
 import {
+  ACADEMY_ROOT,
   CLI_NAME,
-  ACADEMY_CLI_PATH,
-  SCHEDULED_CLAUDE_PERMISSION_ARGS,
-  SCHEDULED_CODEX_PERMISSION_ARGS,
   LockTimeoutError,
   agentDir,
   delegateLegacyRun,
@@ -21,17 +21,56 @@ import {
   legacyAcademyRoot,
   validateName,
 } from './core.mjs';
-import { registerNightlyConsolidationTask } from './create.mjs';
+import { agentIdOf, currentAgentName } from './agent-id.mjs';
+import { refuseNotStarted } from './agent-gate.mjs';
+import { beadsEnv } from './beads.mjs';
+import { INTRO_PENDING_MARKER, jobLabel, registerAcademyJobs } from './create.mjs';
 import { launchClaude } from './hire.mjs';
+import {
+  MEMORY_RELAUNCH_FLAG,
+  memoryEnvRecord,
+  relaunchWithMemoryEnv,
+  resolveMemoryEnv,
+} from './memory-env.mjs';
+import {
+  NIGHTLY_JOB_FLAG,
+  nightlySkillFor,
+  recordNightlyOutcome,
+  removeMarkerIfUnchanged,
+  skipNightlyWithoutMarker,
+  skipNightlyWithoutWork,
+  sweepBeforeNightly,
+} from './nightly.mjs';
+import { launchNightlyChild, nightlyChildEnv } from './nightly-launch.mjs';
+import { appendedPromptLaunch } from './prompt-append.mjs';
+import { printHelmSkip } from './helm-skip.mjs';
+import { guardOwnerHeartbeat } from './heartbeat.mjs';
+import { applyRunContext } from './run-context.mjs';
 import { readRuntimeProvider, toRuntimeProvider, toRuntimeToken } from './runtime.mjs';
+import { bundledTldrPluginRoot, schedulerJobId } from './tldr.mjs';
+import { logUserWorkView } from './user-work-view.mjs';
+import { codexWritableDirArgs, sharedWritableDirArgs } from './writable-dirs.mjs';
 import { AgentSpecError, writeAgentYamlScalar } from './yaml.mjs';
 import {
   renderAcademySystemPrompt,
+  scaffoldLocalRules,
   writeProjectCodexSkillBridge,
   writeProjectPluginInstance,
   writeSkillsScaffold,
 } from './scaffold.mjs';
 
+// The `roque` plugin replaces any installed `roque` for the session, so Roque
+// never runs twice next to a normal-session install. Two more plugins load only
+// on a machine without the Mac's installs: the bundled tldr plugin (tldr did not
+// resolve from a Claude plugin install) and Backstory (no memory wrapper).
+export function claudePluginArgs(pluginDir, dir, env = process.env, academyRoot = ACADEMY_ROOT) {
+  const dirs = [pluginDir, join(academyRoot, 'hooks', 'roque')];
+  const tldr = bundledTldrPluginRoot(env, academyRoot);
+  if (tldr) dirs.push(tldr);
+  if (!bridgeLauncher(env)) dirs.push(join(academyRoot, 'hooks', 'backstory'));
+  return [...dirs.flatMap((d) => ['--plugin-dir', d]), ...sharedWritableDirArgs(dir)];
+}
+
 // The agent's runtime is only knowable once the agent is resolved. A bare run
 // reads what the agent already declared, so it can neither launch the wrong
 // provider nor re-register the nightly job under one. Only an explicit --agent
@@ -56,50 +95,130 @@ function persistRuntime(dir, requested) {
   }
 }
 
-function prepareAgentRun(name, requestedRuntime, passthrough) {
-  validateName(name);
-  const dir = agentDir(name);
+// A scheduler job whose agent is not here (a job registered under another
+// AGENTS_ROOT) is a decision to skip, not a failed start: a failed start makes
+// the scheduler launch a fallback session that lacks Academy's context. A
+// person's run has no job id and still fails with the not-found message.
+function skipMissingAgentUnderJob(name) {
+  const jobId = schedulerJobId();
+  if (!jobId) return;
+  console.error(
+    JSON.stringify({
+      event: 'run.agent_missing',
+      status: 'warn',
+      params: { agent: name, jobId },
+      result: { skip: 'agent_not_found' },
+    }),
+  );
+  printHelmSkip('agent_not_found', name);
+  process.exit(0);
+}
+
+// A new Principal's first interactive session starts with one plain sentence
+// that points at its own rendered intro skill by path: a command name resolves
+// differently in Claude project mode and Codex project mode. Any passthrough
+// at all means a caller (a schedule, a resume, a host) already chose the first
+// message, so only an empty one is seeded. No terminal, no seed.
+export function introSeed({ dir, runtime, passthrough, isTTY }) {
+  if (!isTTY || passthrough.length > 0 || !existsSync(join(dir, INTRO_PENDING_MARKER))) return;
+  const surface = runtime === 'codex' ? '.agents' : '.claude';
+  return [
+    `Start your first-session intro: read and follow ${dir}/${surface}/skills/principal-intro/SKILL.md`,
+  ];
+}
+
+function seedFirstSession(dir, name, runtime, passthrough) {
+  const seed = introSeed({ dir, runtime, passthrough, isTTY: isatty(0) });
+  if (!seed) return passthrough;
+  console.error(JSON.stringify({ event: 'run.intro_seed', params: { agent: name, runtime } }));
+  return seed;
+}
+
+// `id` keys everything that must survive a name change: the heartbeat's Beads
+// label, the Beads actor, job registration, the relaunch and per-agent paths.
+// The current name is what the session is told it is.
+function prepareAgentRun(id, requestedRuntime, passthrough) {
+  validateName(id);
+  const dir = agentDir(id);
   if (!existsSync(dir)) {
-    console.error(`Agent "${name}" not found at ${dir}`);
-    console.error(`Run \`${CLI_NAME} create ${name}\` or \`${CLI_NAME} hire\` first.`);
+    skipMissingAgentUnderJob(id);
+    console.error(`Agent "${id}" not found at ${dir}`);
+    console.error(`Run \`${CLI_NAME} create ${id}\` or \`${CLI_NAME} hire\` first.`);
     process.exit(1);
   }
 
   const legacyRoot = legacyAcademyRoot(dir);
   if (legacyRoot) {
-    delegateLegacyRun(name, passthrough, legacyRoot);
+    delegateLegacyRun(id, passthrough, legacyRoot);
     return null;
   }
+  const name = currentAgentName(dir);
 
+  // Before any model session, and once: the memory relaunch's child inherits
+  // the parent's decision. Runs of one agent may overlap; only a scheduled
+  // Owner heartbeat checks first whether it has anything to do.
+  const relaunchRuntime = requestedRuntime ?? toRuntimeToken(readRuntimeProvider(dir));
+  if (process.env[MEMORY_RELAUNCH_FLAG] !== '1') {
+    guardOwnerHeartbeat(dir, id);
+    // Seeded before the relaunch so the child receives it as its passthrough
+    // and, under the flag, does not decide again.
+    passthrough = seedFirstSession(dir, id, relaunchRuntime, passthrough);
+  }
+  relaunchWithMemoryEnv({
+    dir,
+    name: id,
+    passthrough,
+    requestedRuntime,
+    runtime: relaunchRuntime,
+  });
   const runtime = resolveRuntime(dir, requestedRuntime);
+  scaffoldLocalRules(dir, name);
   writeSkillsScaffold(dir, name);
-  const systemPromptPath = renderAcademySystemPrompt(dir, name);
+  const { promptPath: systemPromptPath, surfaces } = renderAcademySystemPrompt(dir, name);
+  logUserWorkView(name, surfaces);
   const projectDir = resolve(process.cwd());
   const inAgentHome = isInside(projectDir, dir);
   const codex =
     runtime === 'codex'
-      ? { ...writeCodexProfile(dir, name), runtimeContextPath: codexRuntimeContextPath() }
+      ? { ...writeCodexProfile(dir, id), runtimeContextPath: codexRuntimeContextPath() }
       : undefined;
   if (codex) writeCodexHooks(codex.runtimeContextPath);
-  const nightlyTask = requestedRuntime ? registerNightlyConsolidationTask(dir, name) : null;
-  if (nightlyTask && !nightlyTask.registered && process.env.ACADEMY_SKIP_NIGHTLY_TASK !== '1') {
-    console.error(
-      `Warning: nightly consolidation job "${nightlyTask.id}" not updated: ${nightlyTask.reason}`,
-    );
+  const jobs = requestedRuntime ? registerAcademyJobs(dir, id) : [];
+  for (const job of jobs.filter(({ registered, skipped }) => !registered && !skipped)) {
+    console.error(`Warning: ${jobLabel(job.id)} "${job.id}" not updated: ${job.reason}`);
   }
 
+  const { [MEMORY_RELAUNCH_FLAG]: _relaunched, ...inherited } = process.env;
+  // A session's Beads actor names this process, which waits on the provider,
+  // so the actor lives exactly as long as the session.
   const env = {
-    ...process.env,
+    ...inherited,
     ACADEMY_AGENT_DIR: dir,
     ACADEMY_AGENT_NAME: name,
+    // One compaction point per agent session; Roque's hints fire at fractions of it.
+    CLAUDE_CODE_AUTO_COMPACT_WINDOW: inherited.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '430000',
+    // The client's memory is always on in a topic, but a scheduled job's
+    // wrapper sets only the topic; without the flag no turn is captured or recorded.
+    ...(bridgeEnvPresent(inherited) && {
+      [MEMORY_BRIDGE_ENV.enabled]: inherited[MEMORY_BRIDGE_ENV.enabled] || '1',
+    }),
+    ...beadsEnv(`${id}@${process.pid}`),
   };
   return { codex, dir, env, inAgentHome, name, passthrough, projectDir, runtime, systemPromptPath };
 }
 
 function launchInAgentHome(context) {
   const { codex, dir, env, name, passthrough, systemPromptPath } = context;
+  const { promptArgs, passthrough: rest } = appendedPromptLaunch({
+    runtime: codex ? 'codex' : 'claude',
+    promptPath: systemPromptPath,
+    passthrough,
+  });
   if (!codex) {
-    launchClaude(['--system-prompt-file', systemPromptPath, ...passthrough], {
+    // The home is its own plugin root: `create` links `.claude-plugin` and
+    // `hooks` into it. Claude Code loads a plugin only when told to, so without
+    // this flag a home run registers no session and syncs no memory.
+    launchClaude([...claudePluginArgs(dir, dir), ...promptArgs, ...rest], {
       cwd: dir,
       env,
       message: `Launching ${name} with Claude Code in agent home (${dir})`,
@@ -112,11 +231,9 @@ function launchInAgentHome(context) {
       codex.profileName,
       '-C',
       dir,
-      '--add-dir',
-      dir,
-      '-c',
-      `model_instructions_file=${JSON.stringify(systemPromptPath)}`,
-      ...passthrough,
+      ...codexWritableDirArgs(dir),
+      ...promptArgs,
+      ...withRepoCheck(rest),
     ],
     { cwd: dir, env, message: `Launching ${name} with Codex in agent home (${dir})`, ...codex },
   );
@@ -124,6 +241,11 @@ function launchInAgentHome(context) {
 
 function launchInProject(context) {
   const { codex, dir, env, name, passthrough, projectDir, systemPromptPath } = context;
+  const { promptArgs, passthrough: rest } = appendedPromptLaunch({
+    runtime: codex ? 'codex' : 'claude',
+    promptPath: systemPromptPath,
+    passthrough,
+  });
   if (codex) {
     writeProjectCodexSkillBridge(projectDir, dir);
     launchCodex(
@@ -132,11 +254,9 @@ function launchInProject(context) {
         codex.profileName,
         '-C',
         projectDir,
-        '--add-dir',
-        dir,
-        '-c',
-        `model_instructions_file=${JSON.stringify(systemPromptPath)}`,
-        ...passthrough,
+        ...codexWritableDirArgs(dir),
+        ...promptArgs,
+        ...rest,
       ],
       {
         cwd: projectDir,
@@ -148,78 +268,115 @@ function launchInProject(context) {
     return;
   }
 
-  const pluginDir = writeProjectPluginInstance(projectDir, name, dir);
-  launchClaude(
-    ['--plugin-dir', pluginDir, '--system-prompt-file', systemPromptPath, ...passthrough],
-    {
-      cwd: projectDir,
-      env: { ...env, ACADEMY_PROJECT_DIR: projectDir },
-      message: `Launching ${name} with Claude Code for project ${basename(projectDir)} (plugin: ${pluginDir})`,
-    },
-  );
+  // Keyed by the id folder, so a name change does not orphan the instance.
+  const pluginDir = writeProjectPluginInstance(projectDir, basename(dir), dir);
+  launchClaude([...claudePluginArgs(pluginDir, dir), ...promptArgs, ...rest], {
+    cwd: projectDir,
+    env: { ...env, ACADEMY_PROJECT_DIR: projectDir },
+    message: `Launching ${name} with Claude Code for project ${basename(projectDir)} (plugin: ${pluginDir})`,
+  });
 }
 
 export function runAgent(name, runtime, passthrough) {
-  const context = prepareAgentRun(name, runtime, passthrough);
+  // First: an Academy job's flags come from its job id, which is keyed by the
+  // fixed id, and the nightly dispatch below is one of them. The name is
+  // checked before that, so no path it names is read.
+  validateName(name);
+  const id = agentIdOf(name);
+  applyRunContext(id);
+  refuseNotStarted(agentDir(id), id);
+  if (process.env[NIGHTLY_JOB_FLAG] === '1') {
+    dispatchNightlyJob(id, passthrough);
+    return;
+  }
+  const context = prepareAgentRun(id, runtime, passthrough);
   if (!context) return;
   if (context.inAgentHome) launchInAgentHome(context);
   else launchInProject(context);
 }
 
+// An Academy-provider nightly job reaches `academy run` with the provider's own
+// argv. The flag routes it into the routine `academy nightly` runs, so both
+// share one preflight and one verdict; the routine's child runs without the
+// flag and is an ordinary run. The provider argv (prompt, runtime token) is
+// not launched: the routine builds its prompt and reads the persisted runtime.
+// Only its permission and output flags reach the child: the job approved the
+// one, and its scheduler reads the provider's session id through the other.
+function dispatchNightlyJob(name, passthrough) {
+  console.log(
+    JSON.stringify({
+      event: 'nightly.dispatch',
+      params: { agent: name, source: 'academy_provider', providerArgs: passthrough.length },
+    }),
+  );
+  runNightly(name, { providerArgv: passthrough });
+}
+
 // Runtime-agnostic by construction. An `--agent` on this command line comes
 // from a job an earlier build registered; it is accepted and ignored, because
 // the persisted scalar is the only source of truth a scheduled run may read.
 // The child is spawned bare, so it persists nothing and cannot revert the
 // operator's edit — editing agent.yaml is the published way to change a
 // runtime, and a nightly that carried a snapshot undid that edit every night.
-export function runNightly(name) {
-  validateName(name);
-  const dir = agentDir(name);
+// `providerArgv` is a provider job's own argv; `templatesRoot` serves tests.
+//
+// The pending marker is the one input check: any session activity since the
+// last nightly that exited 0. The skill decides what in the archive is new.
+export function runNightly(nameOrId, { providerArgv, templatesRoot } = {}) {
+  validateName(nameOrId);
+  // The nightly is keyed by the fixed id: its job, its child run, its skip line.
+  const id = agentIdOf(nameOrId);
+  const dir = agentDir(id);
   if (!existsSync(dir)) {
-    console.error(`Agent "${name}" not found at ${dir}`);
+    skipMissingAgentUnderJob(id);
+    console.error(`Agent "${id}" not found at ${dir}`);
     process.exit(1);
   }
-  const runtime = toRuntimeToken(readRuntimeProvider(dir));
+  refuseNotStarted(dir, id);
+  const provider = readRuntimeProvider(dir);
+  const attempt = {
+    dir,
+    name: id,
+    provider,
+    startedAt: new Date(),
+    memory: memoryEnvRecord(resolveMemoryEnv(dir, { cwd: dir, env: nightlyChildEnv() })),
+  };
 
+  sweepBeforeNightly(dir, id);
   const markerPath = pendingMarkerPath(dir);
   if (!existsSync(markerPath)) {
-    console.log(
-      `Skipping nightly consolidation for ${name}: no new session activity since the last run.`,
-    );
+    skipNightlyWithoutMarker(attempt);
     return;
   }
 
+  // Read the revision before the run, so activity that lands during it bumps
+  // the revision and keeps the marker.
   const revision = Number(readJsonFile(markerPath, {}).revision);
-  const prompt = [
-    "Use the nightly-consolidation skill to consolidate today's pending observation memory.",
-    'Update the v3 memory surfaces conservatively, write the dreams report,',
-    'and finish with the dreams report path.',
-  ].join(' ');
-  const providerArgs =
-    runtime === 'codex'
-      ? [...SCHEDULED_CODEX_PERMISSION_ARGS, prompt]
-      : [...SCHEDULED_CLAUDE_PERMISSION_ARGS, '-p', prompt];
-  const result = spawnSync(
-    process.execPath,
-    [ACADEMY_CLI_PATH, 'run', name, '--', ...providerArgs],
-    {
-      stdio: 'inherit',
-      cwd: dir,
-      env: {
-        ...process.env,
-        ACADEMY_SKIP_NIGHTLY_TASK: '1',
-        ACADEMY_NIGHTLY_RUN: '1',
-      },
-    },
-  );
-  const status = result.status ?? 1;
-
-  if (status === 0 && existsSync(markerPath)) {
-    const currentRevision = Number(readJsonFile(markerPath, {}).revision);
-    if (currentRevision === revision) unlinkSync(markerPath);
-  }
+  if (skipNightlyWithoutWork(attempt, markerPath, revision)) return;
+  const skill = requireNightlySkill(attempt, templatesRoot);
+  const runtime = toRuntimeToken(provider);
+  const exitCode = launchNightlyChild(dir, id, { runtime, skill, providerArgv });
+  // A pass takes its gate mark under the marker lock; a failure keeps the marker.
+  const gate = exitCode === 0 ? removeMarkerIfUnchanged(markerPath, revision) : {};
+  recordNightlyOutcome(attempt, {
+    status: exitCode === 0 ? 'pass' : 'failed',
+    reason: exitCode === 0 ? 'exit_0' : `exit_code_${exitCode}`,
+    exitCode,
+    ...gate,
+  });
+  process.exit(exitCode);
+}
 
-  process.exit(status);
+// A kind whose nightly skill is not installed fails before launch: running the
+// universal skill instead would consolidate against the wrong surfaces.
+function requireNightlySkill(attempt, templatesRoot) {
+  const { kind, skill, present } = nightlySkillFor(attempt.dir, templatesRoot);
+  if (present) return skill;
+  console.error(
+    `Error: nightly skill "${skill}" is not installed for ${kind} agent "${attempt.name}".`,
+  );
+  recordNightlyOutcome(attempt, { status: 'failed', reason: 'nightly_skill_missing' });
+  process.exit(1);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────