@joenandez/academy 0.4.0-rc.1

package/scripts/cli/hire-headless.mjs

@@ -0,0 +1,229 @@
+import { rmSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  ACADEMY_ROOT,
+  RuntimeUnavailableError,
+  contractOk,
+  exitJsonError,
+  resolveExecutable,
+  validateName,
+} from './core.mjs';
+import { MUST_EXIST, assertAgentNameFree, provisionAgent } from './create.mjs';
+import { appendLifecycleEvent } from './eventlog.mjs';
+import { HireSpecError, readHireSpec } from './hire-spec.mjs';
+import { agentRecord } from './inspect.mjs';
+import { deleteNightlyConsolidation } from './lifecycle.mjs';
+import { writeAgentYamlScalar } from './yaml.mjs';
+
+// `hire --spec <path> [--json]` — the headless form. The interactive form
+// spawns with inherited stdio and exits on the child's status, so no envelope
+// can ever print from it and the child's own streams would pollute the JSON a
+// client parses. This path captures both child streams and forwards neither.
+//
+// The risk this phase carries is that a specification file drives a runtime
+// holding an explicit non-interactive write permission. Every fault Academy can
+// name is therefore answered before the runtime is resolved or spawned: the
+// file is proved acceptable, the name is proved free, and only then does a
+// child exist. Creation and nightly registration stay outside the child
+// entirely, so the runtime never decides what an Academy agent is.
+
+/**
+ * How long the runtime gets before it is killed. A `-p` turn that writes eight
+ * surfaces is minutes of work, and a client waiting on a synchronous command
+ * cannot wait on a wedged child forever.
+ */
+const DEFAULT_TIMEOUT_MS = 600_000;
+
+/** Enough captured output to report a failure, and a bound on a chatty child. */
+const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
+const REPORTED_OUTPUT_CHARS = 500;
+
+function hireTimeoutMs() {
+  const configured = Number.parseInt(process.env.ACADEMY_HIRE_TIMEOUT_MS ?? '', 10);
+  return Number.isInteger(configured) && configured > 0 ? configured : DEFAULT_TIMEOUT_MS;
+}
+
+function failHire(code, message, fields, json) {
+  if (json) exitJsonError(code, message, fields);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+// Not a usage dump: the headless form publishes an envelope, so the option it
+// does not know is answered inside it.
+function assertKnownOptions(invalidOption, json) {
+  if (!invalidOption) return;
+  failHire(
+    'invalid_spec',
+    `Unknown hire option: ${invalidOption}. Use --spec <path> and --json.`,
+    { option: invalidOption },
+    json,
+  );
+}
+
+function loadSpec(specPath, json) {
+  try {
+    return readHireSpec(specPath);
+  } catch (error) {
+    if (!(error instanceof HireSpecError)) throw error;
+    failHire(error.code, error.message, error.fields, json);
+  }
+}
+
+function resolveHireRuntime(json) {
+  try {
+    return resolveExecutable('ACADEMY_CLAUDE_BIN', 'claude', MUST_EXIST);
+  } catch (error) {
+    if (!(error instanceof RuntimeUnavailableError)) throw error;
+    failHire(error.code, error.message, error.fields, json);
+  }
+}
+
+// The specification's own fields, persisted before the child starts so the
+// runtime reads its brief from the same agent.yaml every other command reads.
+// Quoted through JSON.stringify: the free-text fields already refuse control
+// characters, quotes and backslashes, so the quoted form round-trips exactly
+// through the CLI's line-regex reader.
+function writeSpecScalars(dir, spec) {
+  writeAgentYamlScalar(dir, 'role', JSON.stringify(spec.role));
+  writeAgentYamlScalar(dir, 'objective', JSON.stringify(spec.objective));
+  if (spec.runtime) writeAgentYamlScalar(dir, 'runtime', spec.runtime);
+}
+
+// Not contract. The specification schema and the response envelope are the
+// published surface; what Academy says to its own runtime is Academy's to
+// change. `role` and `objective` are caller-supplied text and reach the model
+// here, which is why they are capped and single-line and why the child is given
+// no authority over creation, naming, scheduling or the event log.
+function headlessHirePrompt({ name, role, objective }) {
+  return [
+    `Use the Academy hire skill to finish hiring the agent "${name}".`,
+    'Its home is the current working directory and already holds the scaffolded',
+    'boot surfaces, agent.yaml and ownership marker.',
+    `Role: ${role}`,
+    `Objective: ${objective}`,
+    'Rewrite the eight surface files in place and stop. Do not create, rename,',
+    'archive or delete any agent, and do not write outside this directory.',
+    'There is no user to ask, so make your own best inference and proceed.',
+  ].join('\n');
+}
+
+// `acceptEdits` rather than `bypassPermissions`: the child has to write eight
+// markdown files in its own working directory and needs nothing beyond that.
+// stdio is captured on both streams and stdin is closed, so a runtime that
+// falls back to asking a question fails fast instead of holding the timeout.
+function runHeadlessRuntime(claudeBin, dir, spec) {
+  return spawnSync(
+    claudeBin,
+    [
+      '-p',
+      headlessHirePrompt(spec),
+      '--permission-mode',
+      'acceptEdits',
+      '--plugin-dir',
+      ACADEMY_ROOT,
+    ],
+    {
+      cwd: dir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: hireTimeoutMs(),
+      // SIGKILL, because a hire being rolled back has nothing left to clean up
+      // and a runtime that ignores SIGTERM would hold the client open.
+      killSignal: 'SIGKILL',
+      maxBuffer: MAX_CAPTURE_BYTES,
+    },
+  );
+}
+
+// The success signal is the child's exit status. A sentinel in its output was
+// rejected: it would make a prompt token load-bearing, and the hire skill's
+// prompts are explicitly not contract.
+function runtimeFault(result, claudeBin) {
+  const timedOut = result.error?.code === 'ETIMEDOUT' || result.signal !== null;
+  if (timedOut) {
+    return {
+      message: `runtime ${claudeBin} did not finish within ${hireTimeoutMs()}ms`,
+      fields: { executable: claudeBin, status: null, timedOut: true },
+    };
+  }
+  if (result.error) {
+    return {
+      message: `failed to start runtime ${claudeBin}: ${result.error.message}`,
+      fields: { executable: claudeBin, status: null, timedOut: false },
+    };
+  }
+  if (result.status === 0) return null;
+  return {
+    message: `runtime ${claudeBin} exited ${result.status}: ${excerpt(result.stderr || result.stdout)}`,
+    fields: { executable: claudeBin, status: result.status, timedOut: false },
+  };
+}
+
+function excerpt(output) {
+  const text = (output ?? '').trim();
+  if (text === '') return '(no output)';
+  return text.length > REPORTED_OUTPUT_CHARS
+    ? `${text.slice(0, REPORTED_OUTPUT_CHARS - 3)}...`
+    : text;
+}
+
+// A hire that did not finish is not a hire. The envelope says ok:false, so the
+// disk must agree: the nightly job is unscheduled and the directory removed,
+// and the append-only log gets a compensating agent_deleted rather than losing
+// the agent_created that was already published. Leaving the half-hired agent
+// would register nightly consolidation for a specialist nobody hired and would
+// block every retry of the same name behind a manual delete.
+function rollbackHire(name, dir, nightlyTask) {
+  let dirReal = resolve(dir);
+  try {
+    dirReal = realpathSync(dir);
+  } catch {
+    /* already gone; the unschedule still names the canonical path */
+  }
+  if (nightlyTask.registered) deleteNightlyConsolidation(name, dirReal);
+  rmSync(dir, { recursive: true, force: true });
+  try {
+    appendLifecycleEvent('agent_deleted', name, dir);
+    return null;
+  } catch (error) {
+    // Reported inside the runtime fault rather than swallowed: a client
+    // replaying the log has to know the compensating record is missing.
+    return error.message;
+  }
+}
+
+function failRuntime(name, dir, nightlyTask, fault, json) {
+  const rollbackFault = rollbackHire(name, dir, nightlyTask);
+  const fields = { name, ...fault.fields };
+  if (rollbackFault) fields.rollbackFault = rollbackFault;
+  failHire('runtime_unavailable', `hire of "${name}" failed: ${fault.message}`, fields, json);
+}
+
+function reportHired(name, dir, nightlyTask, json) {
+  if (json) {
+    contractOk('hire', {
+      hired: true,
+      ...agentRecord(name),
+      scheduledJobId: nightlyTask.registered ? nightlyTask.id : null,
+    });
+    return;
+  }
+  console.log(`Hired agent "${name}" at ${dir}`);
+}
+
+export function hireFromSpec({ spec, json, invalidOption }) {
+  assertKnownOptions(invalidOption, json);
+  const parsed = loadSpec(spec, json);
+  // The one field that reaches a path join, held to the rule every other
+  // agent-addressed command applies.
+  validateName(parsed.name);
+  assertAgentNameFree(parsed.name, json);
+  const claudeBin = resolveHireRuntime(json);
+  const { dir, nightlyTask } = provisionAgent(parsed.name, json);
+  writeSpecScalars(dir, parsed);
+  const fault = runtimeFault(runHeadlessRuntime(claudeBin, dir, parsed), claudeBin);
+  if (fault) failRuntime(parsed.name, dir, nightlyTask, fault, json);
+  reportHired(parsed.name, dir, nightlyTask, json);
+}

package/scripts/cli/hire-spec.mjs

@@ -0,0 +1,164 @@
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { toRuntimeToken } from './runtime.mjs';
+
+// The `hire --spec` file is the whole published input to a headless hire, and
+// it is untrusted: it reaches a path join, a yaml scalar write, and a prompt
+// handed to a runtime running with an explicit non-interactive permission mode.
+// Everything here runs before the runtime is resolved or spawned, so a file
+// Academy will not accept never becomes a child process.
+//
+// Schema — the same fields `create` writes into agent.yaml:
+//   { "name": "<kebab-case>", "role": "<text>", "objective": "<text>",
+//     "runtime": "claude_code" | "codex" (optional) }
+
+/** Required keys. Every other published key is optional. */
+const HIRE_SPEC_REQUIRED = ['name', 'role', 'objective'];
+
+/** The closed key set. An unpublished key is a rejection, not a silent drop. */
+const HIRE_SPEC_KEYS = [...HIRE_SPEC_REQUIRED, 'runtime'];
+
+/** Longest a free-text field may be. Both fields land in agent.yaml. */
+const HIRE_SPEC_TEXT_CAP = 2000;
+
+/** Largest specification file Academy will read into memory. */
+const SPEC_FILE_CAP = 64 * 1024;
+
+// Control characters would close the yaml scalar the writer emits and open a
+// second top-level key; a quote or a backslash survives the write but not the
+// CLI's line-regex reader, so the round-trip would stop being exact.
+const UNSAFE_TEXT_RE = /[\p{Cc}"\\]/u;
+
+// Thrown rather than exited so the caller answers in the envelope it owns.
+// `code` is one of the published fifteen: `invalid_spec` for a file Academy
+// cannot read or a schema it does not accept, `invalid_runtime` for a runtime
+// outside the canonical set.
+export class HireSpecError extends Error {
+  constructor(code, message, fields = {}) {
+    super(message);
+    this.code = code;
+    this.fields = fields;
+  }
+}
+
+function invalidSpec(message, specPath, fields = {}) {
+  return new HireSpecError('invalid_spec', message, { specPath, ...fields });
+}
+
+export function readHireSpec(path) {
+  const specPath = resolve(path);
+  return validateHireSpec(parseSpecFile(readSpecFile(specPath), specPath), specPath);
+}
+
+// A missing file, a directory, an unreadable one and an oversized one are all
+// the same answer to the client: this is not a specification Academy can read.
+function readSpecFile(specPath) {
+  let stats;
+  try {
+    stats = statSync(specPath);
+  } catch (error) {
+    throw invalidSpec(`cannot read hire specification at ${specPath}: ${error.code}`, specPath);
+  }
+  if (!stats.isFile()) {
+    throw invalidSpec(`hire specification at ${specPath} is not a file`, specPath);
+  }
+  if (stats.size > SPEC_FILE_CAP) {
+    throw invalidSpec(
+      `hire specification at ${specPath} is ${stats.size} bytes, over the ${SPEC_FILE_CAP}-byte limit`,
+      specPath,
+    );
+  }
+  try {
+    return readFileSync(specPath, 'utf8');
+  } catch (error) {
+    throw invalidSpec(`cannot read hire specification at ${specPath}: ${error.code}`, specPath);
+  }
+}
+
+function parseSpecFile(text, specPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw invalidSpec(
+      `hire specification at ${specPath} is not valid JSON: ${error.message}`,
+      specPath,
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw invalidSpec(`hire specification at ${specPath} must be a JSON object`, specPath);
+  }
+  return parsed;
+}
+
+// The name is checked for shape here and for the agent-name rule by
+// `validateName` in the caller, so a headless hire is held to exactly the rule
+// every other agent-addressed command applies.
+function validateHireSpec(parsed, specPath) {
+  assertKnownKeys(parsed, specPath);
+  const spec = { specPath, runtime: null };
+  for (const field of HIRE_SPEC_REQUIRED) {
+    spec[field] = assertText(parsed, field, specPath);
+  }
+  if ('runtime' in parsed) spec.runtime = assertRuntime(parsed.runtime, specPath);
+  return spec;
+}
+
+function assertKnownKeys(parsed, specPath) {
+  const unknown = Object.keys(parsed).filter((key) => !HIRE_SPEC_KEYS.includes(key));
+  if (unknown.length === 0) return;
+  throw invalidSpec(
+    `hire specification at ${specPath} declares unpublished key(s): ${unknown.join(', ')}. Use ${HIRE_SPEC_KEYS.join(', ')}.`,
+    specPath,
+    { keys: unknown },
+  );
+}
+
+function assertText(parsed, field, specPath) {
+  const value = parsed[field];
+  if (typeof value !== 'string') {
+    throw invalidSpec(`hire specification at ${specPath} needs a string "${field}"`, specPath, {
+      field,
+    });
+  }
+  const text = value.trim();
+  if (text === '') {
+    throw invalidSpec(`hire specification at ${specPath} has an empty "${field}"`, specPath, {
+      field,
+    });
+  }
+  if (text.length > HIRE_SPEC_TEXT_CAP) {
+    throw invalidSpec(
+      `hire specification at ${specPath} has a "${field}" of ${text.length} characters, over the ${HIRE_SPEC_TEXT_CAP}-character limit`,
+      specPath,
+      { field },
+    );
+  }
+  if (UNSAFE_TEXT_RE.test(text)) {
+    throw invalidSpec(
+      `hire specification at ${specPath} has a "${field}" carrying a control character, quote or backslash`,
+      specPath,
+      { field },
+    );
+  }
+  return text;
+}
+
+// The spec speaks the yaml and JSON vocabulary (claude_code), never the
+// `--agent` token (claude-code), so the two forms cannot be used interchangeably
+// by a client reading the published schema.
+function assertRuntime(value, specPath) {
+  if (typeof value !== 'string') {
+    throw invalidSpec(`hire specification at ${specPath} needs a string "runtime"`, specPath, {
+      field: 'runtime',
+    });
+  }
+  if (!toRuntimeToken(value)) {
+    throw new HireSpecError(
+      'invalid_runtime',
+      `Runtime "${value}" is not a runtime Academy supports. Use claude_code or codex.`,
+      { runtime: value, specPath },
+    );
+  }
+  return value;
+}

package/scripts/cli/hire.mjs

@@ -0,0 +1,92 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  ACADEMY_ROOT,
+  AGENTS_ROOT,
+  RuntimeUnavailableError,
+  contractError,
+  resolveExecutable,
+} from './core.mjs';
+
+function hireContextPath() {
+  const baseDir = join(process.env.HOME || homedir(), '.academy', 'hire-contexts');
+  mkdirSync(baseDir, { recursive: true });
+  const contextDir = mkdtempSync(join(baseDir, 'hire-'));
+  return join(contextDir, 'context.json');
+}
+
+function writeHireContext(passthrough) {
+  const path = hireContextPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    path,
+    JSON.stringify(
+      {
+        createdAt: new Date().toISOString(),
+        packageRoot: ACADEMY_ROOT,
+        agentsRoot: resolve(AGENTS_ROOT),
+        passthrough,
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+  return path;
+}
+
+// `hire` is published in doctor's frozen command list, so a --json caller is
+// entitled to parse the answer. The launch itself inherits stdio and no
+// envelope can wrap it, but a launch that never happens is a command failure
+// like any other. Asked before the context is written, so a run that cannot
+// start leaves no orphaned hire-context directory behind.
+function assertHireRuntime(json) {
+  if (process.env.ACADEMY_DRY_RUN === '1') return;
+  try {
+    resolveExecutable('ACADEMY_CLAUDE_BIN', 'claude', { throwOnMissing: true });
+  } catch (error) {
+    if (!(error instanceof RuntimeUnavailableError)) throw error;
+    if (json) contractError('hire', error.code, error.message, error.fields);
+    console.error(`[ACADEMY_RUNTIME] ${error.message}`);
+    process.exit(1);
+  }
+}
+
+export function hireAgent(passthrough, json = false) {
+  // The hire skill is the orchestrator: it calls `academy create <slug>`,
+  // writes runnable starter surfaces, then schedules knowledge enrichment
+  // after the user-facing hiring summary.
+  // Positional arg seeds the first user message; session stays interactive.
+  assertHireRuntime(json);
+  const contextPath = writeHireContext(passthrough);
+  launchClaude(['--plugin-dir', ACADEMY_ROOT, 'run /hire', ...passthrough], {
+    cwd: ACADEMY_ROOT,
+    env: { ...process.env, ACADEMY_HIRE_CONTEXT: '1', ACADEMY_HIRE_CONTEXT_PATH: contextPath },
+    message: 'Launching Academy hire flow',
+  });
+}
+
+export function launchClaude(args, { cwd, env, message }) {
+  console.log(message);
+  const claudeBin =
+    process.env.ACADEMY_DRY_RUN === '1'
+      ? process.env.ACADEMY_CLAUDE_BIN || 'claude'
+      : resolveExecutable('ACADEMY_CLAUDE_BIN', 'claude');
+  if (process.env.ACADEMY_DRY_RUN === '1') {
+    console.log(`[dry-run] ${claudeBin} ${args.join(' ')}`);
+    console.log(`[dry-run] cwd=${cwd}`);
+    if (env?.ACADEMY_AGENT_DIR) console.log(`[dry-run] ACADEMY_AGENT_DIR=${env.ACADEMY_AGENT_DIR}`);
+    if (env?.ACADEMY_PROJECT_DIR)
+      console.log(`[dry-run] ACADEMY_PROJECT_DIR=${env.ACADEMY_PROJECT_DIR}`);
+    process.exit(0);
+  }
+  const result = spawnSync(claudeBin, args, { stdio: 'inherit', cwd, env });
+  if (result.error) {
+    console.error(
+      `[ACADEMY_RUNTIME] Failed to launch Claude Code at ${claudeBin}: ${result.error.message}`,
+    );
+    process.exit(1);
+  }
+  process.exit(result.status ?? 0);
+}