@joenandez/academy 0.4.0-rc.1

package/hooks/hook_runtime.mjs

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function readPayload() {
+  try {
+    const input = readFileSync(0, 'utf8').trim();
+    return input ? JSON.parse(input) : null;
+  } catch {
+    return null;
+  }
+}
+
+function sameRealPath(left, right) {
+  try {
+    return realpathSync(left) === realpathSync(right);
+  } catch {
+    return left === right;
+  }
+}
+
+export function runtimeEnvFor(payload, env, identityKey) {
+  let resolvedEnv = env;
+  if (!env[identityKey] && env.ACADEMY_RUNTIME_CONTEXT) {
+    try {
+      const context = JSON.parse(readFileSync(env.ACADEMY_RUNTIME_CONTEXT, 'utf8'));
+      const expired = context.expiresAt && Date.parse(context.expiresAt) < Date.now();
+      const merged = expired ? env : { ...env, ...(context.env || {}) };
+      const projectMismatch =
+        payload?.cwd &&
+        merged.ACADEMY_PROJECT_DIR &&
+        !sameRealPath(payload.cwd, merged.ACADEMY_PROJECT_DIR);
+      if (!projectMismatch) resolvedEnv = merged;
+    } catch {
+      // Use the provided environment when the runtime context is not valid.
+    }
+  }
+  return resolvedEnv;
+}
+
+// A session record names the agent directory, not just the agent name: two
+// roots can hold an agent of the same name, and only the resolved directory
+// says which one a session belongs to. An unresolvable path still answers
+// absolutely, because a record Academy cannot attribute is worse than one
+// naming a directory that has since moved.
+export function resolvedAgentDir(dir) {
+  if (!dir) return null;
+  const absolute = resolve(dir);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function withFileLock(lockDir, fn) {
+  const started = Date.now();
+  while (true) {
+    try {
+      mkdirSync(lockDir, { recursive: false });
+      break;
+    } catch {
+      if (Date.now() - started > 5000) return fn();
+      sleep(25);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+export function jsonlHasValue(path, field, value) {
+  if (!existsSync(path)) return false;
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      if (JSON.parse(line)[field] === value) return true;
+    } catch {
+      // Ignore malformed JSONL rows.
+    }
+  }
+  return false;
+}
+
+export function isMainModule(moduleUrl) {
+  if (!process.argv[1]) return false;
+  const modulePath = fileURLToPath(moduleUrl);
+  try {
+    return realpathSync(modulePath) === realpathSync(process.argv[1]);
+  } catch {
+    return modulePath === resolve(process.argv[1]);
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/register_session.mjs"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/sync_memory.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/inject_surface.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""SessionStart hook — emit one boot surface per invocation.
+
+Usage: inject_surface.py <surface>
+
+Surfaces: identity | role | knowledge | goals | priorities | threads | notes | dailys
+
+Each surface lives at ~/.academy/agents/<name>/<surface>.md and is injected
+into the session as additionalContext via stdout JSON.
+
+Agent dir resolution (in priority order):
+  1. ACADEMY_AGENT_DIR env var
+  2. CWD if it contains agent.yaml
+  3. CWD walk-up looking for agent.yaml
+
+Per v3 §10 Phase 0: "8 simple hooks, one per surface" — no manifest, no
+chunking, no inject_section heuristics. The 8 boot files target ~5–6k tokens
+combined and stay well under the per-hook ~10k-char ceiling.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+SURFACES = (
+    "identity",
+    "role",
+    "knowledge",
+    "goals",
+    "priorities",
+    "threads",
+    "notes",
+    "dailys",
+)
+USAGE_ERROR = 2
+EXPECTED_ARG_COUNT = 2
+
+
+def resolve_agent_dir() -> Path | None:
+    """Resolve the agent directory.
+
+    Priority:
+      1. ACADEMY_AGENT_DIR env var (set by `academy run`)
+      2. Walk up from CWD looking for agent.yaml
+    """
+    env_dir = os.environ.get("ACADEMY_AGENT_DIR")
+    if env_dir:
+        p = Path(env_dir)
+        if p.is_dir():
+            return p
+
+    cwd = Path.cwd()
+    for d in (cwd, *cwd.parents):
+        if (d / "agent.yaml").is_file():
+            return d
+    return None
+
+
+def build_context(surface: str, agent_dir: Path) -> str:
+    """Read <surface>.md and return its content as-is.
+
+    The file is self-describing (each starts with its own H1). The hook's job
+    is to deliver the file into context — not to add framing. Empty/missing
+    files emit a one-line placeholder so the agent knows the surface exists
+    but is empty.
+    """
+    surface_file = agent_dir / f"{surface}.md"
+    if not surface_file.is_file():
+        return f"# {surface.title()}\n\n_(No {surface}.md present yet.)_"
+    body = surface_file.read_text(encoding="utf-8").rstrip()
+    if not body:
+        return f"# {surface.title()}\n\n_({surface}.md is empty.)_"
+    return body
+
+
+def emit(context: str) -> None:
+    """Emit Claude Code SessionStart hook JSON output."""
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": context,
+        }
+    }
+    sys.stdout.write(json.dumps(payload))
+    sys.stdout.flush()
+
+
+def main() -> int:
+    if len(sys.argv) != EXPECTED_ARG_COUNT:
+        print(f"usage: inject_surface.py <{'|'.join(SURFACES)}>", file=sys.stderr)
+        return USAGE_ERROR
+
+    surface = sys.argv[1]
+    if surface not in SURFACES:
+        print(
+            f"unknown surface '{surface}'. valid: {', '.join(SURFACES)}",
+            file=sys.stderr,
+        )
+        return USAGE_ERROR
+
+    agent_dir = resolve_agent_dir()
+    if agent_dir is None:
+        # Not running inside an agent — emit nothing, exit clean.
+        # This keeps the hook harmless when the user invokes Claude Code
+        # in a non-agent dir while the plugin is still installed.
+        return 0
+
+    try:
+        context = build_context(surface, agent_dir)
+    except Exception as exc:  # pragma: no cover — defensive
+        print(f"inject_surface[{surface}] error: {exc}", file=sys.stderr)
+        return 0  # never block session start
+
+    emit(context)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/memory_bridge.mjs

@@ -0,0 +1,120 @@
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Academy names no specific client except in this module. The memory sync
+ * bridge stays client-specific by explicit decision, so every client-named
+ * identifier Academy needs — env keys, tool permission, skill guidance, and the
+ * observation copy itself — lives here. Client-neutral layers import these
+ * declarations and inject them only behind ACADEMY_MEMORY_BRIDGE.
+ */
+export const MEMORY_BRIDGE_ENV = {
+  enabled: 'GROVE_MEMORY_ENABLED',
+  project: 'GROVE_PROJECT_NAME',
+  workspace: 'GROVE_WORKSPACE_NAME',
+  home: 'SUBSPACE_HOME',
+};
+
+/** Env keys a sandboxed runtime must forward for the bridge to work. */
+export const MEMORY_BRIDGE_ENV_KEYS = Object.values(MEMORY_BRIDGE_ENV);
+
+/** Tool permission an agent needs to query the bridge directly. */
+export const MEMORY_BRIDGE_PERMISSIONS = ['Bash(subspace-memory:*)'];
+
+/** Optional nightly guidance — the only client-named prose Academy ships. */
+export const MEMORY_BRIDGE_SKILL_GUIDANCE = `### Optional — Subspace memory bridge
+
+Academy names no specific client. This bridge is the one exception, and it is
+optional. Skip this section when \`subspace-memory\` is not installed.
+
+- Run \`subspace-memory status\` if the archive is thin or appears inconsistent.
+- Run \`subspace-memory timeline --days 2\` if more workspace context is needed.
+
+Subspace memory may enrich or corroborate an eligible run. It can never
+establish eligibility.`;
+
+function formatDate(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+function syncDates() {
+  const today = new Date();
+  const yesterday = new Date(today);
+  yesterday.setDate(today.getDate() - 1);
+  return [formatDate(today), formatDate(yesterday)];
+}
+
+function memoryKey(entry) {
+  return `${entry.sessionId || ''}|${entry.timestamp || ''}|${entry.turnNumber || ''}`;
+}
+
+function readExistingKeys(path) {
+  const keys = new Set();
+  if (!existsSync(path)) return keys;
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      keys.add(memoryKey(JSON.parse(trimmed)));
+    } catch {
+      // Ignore malformed archive lines.
+    }
+  }
+  return keys;
+}
+
+function subspaceObservationsDir(env) {
+  const project = env[MEMORY_BRIDGE_ENV.project];
+  const workspace = env[MEMORY_BRIDGE_ENV.workspace];
+  if (!project || !workspace) return null;
+  const roots = [env[MEMORY_BRIDGE_ENV.home], join(env.HOME || homedir(), '.subspace')].filter(
+    Boolean,
+  );
+  for (const root of roots) {
+    const dir = join(root, project, workspace, 'memory', 'observations');
+    if (existsSync(dir)) return dir;
+  }
+  return null;
+}
+
+function memorySyncEnabled(env) {
+  const enabled = env[MEMORY_BRIDGE_ENV.enabled];
+  return enabled === '1' || enabled === 'true';
+}
+
+function syncObservationFile(subspaceFile, agentFile, sessionId) {
+  const existingKeys = readExistingKeys(agentFile);
+  let synced = 0;
+  for (const line of readFileSync(subspaceFile, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const entry = JSON.parse(trimmed);
+      const key = memoryKey(entry);
+      if (entry.sessionId !== sessionId || existingKeys.has(key)) continue;
+      appendFileSync(agentFile, `${trimmed}\n`);
+      existingKeys.add(key);
+      synced++;
+    } catch {
+      // Ignore malformed Subspace observation lines.
+    }
+  }
+  return synced;
+}
+
+/**
+ * Copy the client's observations for this session into the agent's own archive.
+ * The client-neutral hook calls this and learns only a count.
+ */
+export function syncBridgeObservations(env, observationsDir, sessionId) {
+  const subspaceDir = subspaceObservationsDir(env);
+  if (!subspaceDir || !memorySyncEnabled(env)) return 0;
+  let synced = 0;
+  for (const date of syncDates()) {
+    const subspaceFile = join(subspaceDir, `${date}.jsonl`);
+    if (!existsSync(subspaceFile)) continue;
+    synced += syncObservationFile(subspaceFile, join(observationsDir, `${date}.jsonl`), sessionId);
+  }
+  return synced;
+}

package/hooks/memory_store.mjs

@@ -0,0 +1,66 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { jsonlHasValue, resolvedAgentDir, withFileLock } from './hook_runtime.mjs';
+
+// Academy's own per-agent memory state. Client-neutral: nothing here knows
+// which client, if any, feeds the observation archive.
+
+export function pendingMarkerPath(agentDir) {
+  return join(resolve(agentDir), 'memory', 'pending-consolidation.json');
+}
+
+export function markPendingConsolidation(memoryDir) {
+  const markerPath = pendingMarkerPath(resolve(memoryDir, '..'));
+  withFileLock(join(memoryDir, 'pending-consolidation.lock'), () => {
+    let revision = 0;
+    if (existsSync(markerPath)) {
+      try {
+        revision = Number(JSON.parse(readFileSync(markerPath, 'utf8')).revision) || 0;
+      } catch {
+        // Replace malformed private state with the next valid revision.
+      }
+    }
+    const tempPath = join(memoryDir, `.pending-consolidation.${process.pid}.${Date.now()}.tmp`);
+    writeFileSync(
+      tempPath,
+      JSON.stringify(
+        {
+          revision: revision + 1,
+          updatedAt: new Date().toISOString(),
+        },
+        null,
+        2,
+      ) + '\n',
+    );
+    renameSync(tempPath, markerPath);
+  });
+}
+
+export function recordSession(memoryDir, payload, env) {
+  const sessionId = payload.session_id;
+  if (!sessionId) return;
+  const sessionsPath = join(memoryDir, 'sessions.jsonl');
+  mkdirSync(memoryDir, { recursive: true });
+  withFileLock(join(memoryDir, 'sessions.lock'), () => {
+    if (jsonlHasValue(sessionsPath, 'sessionId', sessionId)) return;
+    appendFileSync(
+      sessionsPath,
+      JSON.stringify({
+        sessionId,
+        agentName: env.ACADEMY_AGENT_NAME || null,
+        agentDir: resolvedAgentDir(join(memoryDir, '..')),
+        timestamp: new Date().toISOString(),
+        cwd: payload.cwd || null,
+        projectDir: env.ACADEMY_PROJECT_DIR || null,
+        source: 'stop',
+      }) + '\n',
+    );
+  });
+}

package/hooks/register_session.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  isMainModule,
+  jsonlHasValue,
+  readPayload,
+  resolvedAgentDir,
+  runtimeEnvFor,
+  withFileLock,
+} from './hook_runtime.mjs';
+
+function appendSession(sessionsPath, session) {
+  if (jsonlHasValue(sessionsPath, 'sessionId', session.sessionId)) return true;
+  appendFileSync(sessionsPath, `${JSON.stringify(session)}\n`);
+  return true;
+}
+
+export function registerAcademySession(payload, env = process.env) {
+  env = runtimeEnvFor(payload, env, 'ACADEMY_AGENT_NAME');
+  const sessionId = payload?.session_id;
+  const agentName = env.ACADEMY_AGENT_NAME;
+  const cwd = payload?.cwd;
+  if (!sessionId || !agentName || !cwd) return false;
+  // Absent when the session did not come from `academy run`. Such a record is
+  // unattributable rather than corrupt, so it is written without the field and
+  // counted by `doctor`.
+  const agentDir = resolvedAgentDir(env.ACADEMY_AGENT_DIR);
+
+  try {
+    const academyDir = join(env.HOME || homedir(), '.academy');
+    const sessionsPath = join(academyDir, 'sessions.jsonl');
+    mkdirSync(academyDir, { recursive: true });
+    return withFileLock(join(academyDir, 'sessions.lock'), () =>
+      appendSession(sessionsPath, {
+        sessionId,
+        agentName,
+        ...(agentDir ? { agentDir } : {}),
+        cwd,
+        startedAt: new Date().toISOString(),
+      }),
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  registerAcademySession(readPayload());
+}

package/hooks/sync_memory.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isMainModule, readPayload, runtimeEnvFor } from './hook_runtime.mjs';
+import { syncBridgeObservations } from './memory_bridge.mjs';
+import { markPendingConsolidation, recordSession } from './memory_store.mjs';
+
+export function syncAcademyMemory(payload, env = process.env) {
+  env = runtimeEnvFor(payload, env, 'ACADEMY_AGENT_DIR');
+  const agentDir = env.ACADEMY_AGENT_DIR;
+  const sessionId = payload?.session_id;
+  if (!agentDir || !sessionId) return { synced: 0 };
+
+  const memoryDir = join(resolve(agentDir), 'memory');
+  const observationsDir = join(memoryDir, 'observations');
+  mkdirSync(observationsDir, { recursive: true });
+  recordSession(memoryDir, payload, env);
+  // Eligibility tracks Academy session activity, not the bridge copy, so an
+  // agent still consolidates when the memory bridge is unavailable.
+  if (env.ACADEMY_NIGHTLY_RUN !== '1') markPendingConsolidation(memoryDir);
+
+  return { synced: syncBridgeObservations(env, observationsDir, sessionId) };
+}
+
+if (isMainModule(import.meta.url)) {
+  syncAcademyMemory(readPayload());
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@joenandez/academy",
+  "version": "0.4.0-rc.1",
+  "description": "Academy v3 — portable AI agents with 8 boot surfaces and a skills primitive.",
+  "type": "module",
+  "bin": {
+    "academy": "./bin/academy"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joenandez/academy.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "scripts/agent.mjs",
+    "scripts/cli/",
+    "skills/",
+    "templates/",
+    "hooks/",
+    ".claude-plugin/",
+    "conformance/",
+    "docs/integration-guide.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "quality:setup": "node quality/run.mjs setup",
+    "quality:commit": "node quality/run.mjs commit",
+    "quality:push": "node quality/run.mjs push",
+    "quality:full": "node quality/run.mjs full"
+  },
+  "keywords": ["academy", "ai-agent", "claude-code", "portable-agent"],
+  "author": "Joe Fernandez",
+  "license": "MIT",
+  "devDependencies": {
+    "knip": "5.70.2"
+  }
+}

package/scripts/agent.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Academy v3 CLI entry point. */
+import './cli/main.mjs';