@app-vitals/agent-runtime 0.0.0-stage → 0.1.0

package/Dockerfile

@@ -0,0 +1,265 @@
+# Agent runtime — container image (ghcr.io/app-vitals/agent)
+#
+# Build from the repository root:  docker build -f runtime/Dockerfile .
+#
+# Environment variables:
+#   AGENT_HOME              — persistent storage root (default: /data/agent-home)
+#                             Mount a PVC here so mise tool caches, workspace files,
+#                             and the ~/.claude symlink target all survive restarts.
+#   SHIPWRIGHT_HEALTH_PORT  — K8s liveness probe port (default: 3459)
+#
+# PVC mount point:
+#   /data/agent-home — mount a PersistentVolumeClaim (or any durable volume) here.
+#                    The agent symlinks ~/.claude → $AGENT_HOME/dot-claude so
+#                    Claude Code settings and memory persist across pod restarts.
+#                    The container runs as uid 1000, so the pod must set
+#                    `securityContext.fsGroup: 1000` for the mounted volume to be
+#                    writable.
+#
+# Required env vars at runtime:
+#   SHIPWRIGHT_AGENT_ID            — the agent's ID in the Shipwright platform
+#   SHIPWRIGHT_API_URL             — base URL of the Shipwright API
+#   SHIPWRIGHT_AGENT_API_KEY       — bearer token for the config endpoint
+#   ANTHROPIC_API_KEY              — Anthropic API key (or CLAUDE_CODE_OAUTH_TOKEN)
+
+# ─── Node.js binary source ─────────────────────────────────────────────────
+# Copied into the base stage below instead of piping deb.nodesource.com's
+# setup script through bash — that endpoint intermittently 403s in CI,
+# blocking every build. node:22-trixie-slim matches oven/bun:1-slim's Debian
+# release (trixie) so the copied binary is glibc-compatible.
+FROM node:24-trixie-slim AS node-source
+
+# ─── Base: system tooling installed as root ───────────────────────────────────
+
+FROM oven/bun:1-slim AS base
+
+# Install system dependencies:
+#   - git          — required by Claude Code and mise
+#   - curl         — used by the mise installer and gh keyring setup
+#   - ca-certificates — TLS trust for API calls
+#   - unzip        — needed by some mise-managed tools
+#   - jq           — bash JSON parsing in the time-tracking Claude Code hooks
+#   - build-essential / libssl-dev / pkg-config — native + Rust toolchain so the
+#     agent can build client code at runtime (e.g. Rust projects + OpenSSL crates).
+#     (Piper TTS for voice-out is bundled in the runtime stage below; ffmpeg /
+#     python-edge-tts stay omitted — Piper emits WAV natively.)
+#   - Chromium/chromium-headless-shell OS deps for Playwright (PW-1.1/PW-1.2 —
+#     agent/src/runtime/browser.ts, follow-up task) — installed here as root so the
+#     runtime stage's `playwright install chromium-headless-shell` (run as USER
+#     1000, no --with-deps) has everything the binary needs to actually launch.
+#     This exact package list is Playwright 1.61.1's real dependency set —
+#     verified by running `playwright install-deps --dry-run chromium-headless-shell`
+#     against an installed 1.61.1, not assumed from docs or an older version's
+#     source. That dry run confirms chromium-headless-shell needs the identical
+#     package set as full `chromium` on this OS.
+#     oven/bun:1-slim is Debian trixie (13) — see node-source stage comment above
+#     — hence the t64-suffixed package names (Debian's 64-bit time_t transition).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    ca-certificates \
+    unzip \
+    jq \
+    build-essential \
+    libssl-dev \
+    pkg-config \
+    fonts-freefont-ttf \
+    fonts-ipafont-gothic \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    fonts-tlwg-loma-otf \
+    fonts-unifont \
+    fonts-wqy-zenhei \
+    libasound2t64 \
+    libatk-bridge2.0-0t64 \
+    libatk1.0-0t64 \
+    libatspi2.0-0t64 \
+    libcairo2 \
+    libcups2t64 \
+    libdbus-1-3 \
+    libdrm2 \
+    libfontconfig1 \
+    libfreetype6 \
+    libgbm1 \
+    libglib2.0-0t64 \
+    libnspr4 \
+    libnss3 \
+    libpango-1.0-0 \
+    libx11-6 \
+    libxcb1 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxext6 \
+    libxfixes3 \
+    libxkbcommon0 \
+    libxrandr2 \
+    xfonts-scalable \
+    xvfb \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install gh CLI via official GitHub apt keyring
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      > /etc/apt/sources.list.d/github-cli.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends gh \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install the mise binary to a world-executable location (NOT /root, so the
+# non-root runtime user can invoke it). Downloaded to a file first (rather than
+# piped straight into sh) so curl's own exit code gates the step — dash (this
+# base image's /bin/sh) has no pipefail, so `curl ... | sh` on a transient
+# curl failure (e.g. a mid-download connection reset) sends sh 0 bytes on
+# stdin, which sh happily runs as a no-op and exits 0, silently shipping an
+# image with no /usr/local/bin/mise. The trailing `test -x` is a second,
+# independent gate against the installer itself running but not landing the
+# binary at this exact path.
+RUN curl -fsSL -o /tmp/mise-install.sh https://mise.run \
+    && MISE_INSTALL_PATH=/usr/local/bin/mise sh /tmp/mise-install.sh \
+    && rm /tmp/mise-install.sh \
+    && test -x /usr/local/bin/mise
+
+# Install Node.js + Claude Code CLI system-wide (as root) on /usr/bin.
+# claude is a plain binary on PATH (/usr/bin/claude) backed by system node — it is
+# NOT a mise shim, so its resolution never depends on the active mise/workspace
+# context (which is what broke the previous mise-reshim approach: "claude is not a
+# valid shim"). mise stays purely a runtime *workspace* tool-version manager.
+# Node itself is copied from the node-source stage above rather than fetched via
+# deb.nodesource.com (see that stage's comment).
+COPY --from=node-source /usr/local/bin/node /usr/local/bin/node
+COPY --from=node-source /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/npm
+# renovate: datasource=npm depName=@anthropic-ai/claude-code
+ARG CLAUDE_CODE_VERSION=2.1.292
+# The trailing check fails the build if the installed CLI doesn't report exactly
+# the pinned version (e.g. a registry/tag mismatch), so a drifted image can't ship.
+RUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
+    && ln -s /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx \
+    && npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION} \
+    && INSTALLED="$(claude --version)" \
+    && echo "claude --version: ${INSTALLED}" \
+    && case "${INSTALLED}" in \
+         "${CLAUDE_CODE_VERSION} "*) ;; \
+         *) echo "claude --version reported '${INSTALLED}', expected ${CLAUDE_CODE_VERSION}" >&2; exit 1 ;; \
+       esac
+
+# Anthropic's container guidance for reproducible builds: pin the version above
+# and disable the in-container auto-updater. Self-update can't work here anyway
+# (root-owned npm global dir, uid 1000 runtime, ephemeral pods). Set in the base
+# stage so it carries into runtime; runtime/claude.ts builds the child env
+# from process.env, so spawned claude processes inherit it.
+ENV DISABLE_AUTOUPDATER=1
+
+# ─── Build stage ──────────────────────────────────────────────────────────────
+
+FROM base AS build
+
+WORKDIR /app
+
+# Workspace manifests first (layer caching for deps). admin/prisma is needed
+# because admin's postinstall runs `prisma generate`. bun.lock is copied when
+# the repository has one.
+COPY package.json bunfig.toml bun.lock* ./
+COPY runtime/package.json ./runtime/
+COPY admin/package.json ./admin/
+COPY admin/prisma ./admin/prisma/
+COPY admin/prisma.config.ts ./admin/
+COPY lib/package.json ./lib/
+COPY patches/ ./patches/
+
+RUN if [ -f bun.lock ]; then bun install --frozen-lockfile; else bun install; fi
+
+# Workspace sources. @app-vitals/agent-lib / -runtime / -admin are workspace
+# symlinks; only their package.json files were copied above, so the sources
+# must exist for the symlinks to resolve.
+COPY runtime/ ./runtime/
+COPY admin/ ./admin/
+COPY lib/ ./lib/
+# Agent-type definitions (setup.ts reads identity.templatesDir from them).
+COPY agent-types/ ./agent-types/
+# Composition root spawned by runtime/entrypoint.ts (../index.ts).
+COPY index.ts ./index.ts
+COPY scripts/ ./scripts/
+
+# Module-resolution guard: bundle every runtime source file as its own entry
+# point so an unresolvable import fails the build itself, rather than only
+# surfacing as a runtime crash after the image ships. A plain `docker build`
+# succeeding is not proof the image runs; this bundles the whole runtime tree,
+# not just entrypoint-main.ts's reachable graph.
+# playwright/playwright-core are externalized: bun's bundler eagerly resolves
+# playwright-core's internal optional chromium-bidi requires, which aren't
+# actually installed or used by our CDP-based launch path.
+RUN find runtime -name "*.ts" | xargs bun build --target=bun --external playwright --external playwright-core --outdir=/tmp/module-check
+
+# ─── Runtime stage (non-root) ─────────────────────────────────────────────────
+
+FROM base AS runtime
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+# AGENT_HOME: mount a persistent volume here.
+ENV AGENT_HOME=/data/agent-home
+
+# Create the persistent-volume mount point and hand it to uid 1000 so the agent
+# can write when no volume is mounted. A mounted PVC needs `fsGroup: 1000`.
+RUN mkdir -p /data/agent-home && chown 1000:1000 /data/agent-home
+
+USER 1000
+ENV HOME=/home/bun
+
+# mise workspace tool shims first on PATH; /app/scripts/bin holds the
+# git-credential helper (runtime/entrypoint-main.ts resolves it relative to
+# the repository root), the gh owner-routing wrapper and the git wrapper that
+# routes push through signed-push.
+ENV PATH="/home/bun/.local/share/mise/shims:/app/scripts/bin:${PATH}"
+
+COPY --from=build --chown=1000:1000 /app/node_modules ./node_modules
+COPY --from=build --chown=1000:1000 /app/runtime ./runtime
+COPY --from=build --chown=1000:1000 /app/admin ./admin
+COPY --from=build --chown=1000:1000 /app/lib ./lib
+COPY --from=build --chown=1000:1000 /app/agent-types ./agent-types
+COPY --from=build --chown=1000:1000 /app/index.ts ./index.ts
+COPY --from=build --chown=1000:1000 /app/scripts ./scripts
+COPY --from=build --chown=1000:1000 /app/package.json ./package.json
+
+RUN chmod +x /app/scripts/bin/git-credential-shipwright.sh \
+    && chmod +x /app/scripts/bin/gh \
+    && chmod +x /app/scripts/bin/git
+
+# ─── Playwright chromium-headless-shell (runtime/browser.ts) ──────────────────
+# Installed as the already-active USER 1000 under /home/bun, so nothing lands
+# root-owned. No --with-deps: the OS-level deps were installed as root in the
+# base stage.
+ENV PLAYWRIGHT_BROWSERS_PATH=/home/bun/.cache/ms-playwright
+RUN bunx playwright install chromium-headless-shell
+
+# ─── Piper offline TTS (voice-out) ────────────────────────────────────────────
+# runtime/piper-voice.ts hardcodes the model dir to /app/agent/voices/, so the
+# model MUST live at that exact path. amd64 only.
+USER root
+ARG PIPER_VERSION=2023.11.14-2
+RUN curl -fsSL -o /tmp/piper.tar.gz \
+      "https://github.com/rhasspy/piper/releases/download/${PIPER_VERSION}/piper_linux_x86_64.tar.gz" \
+    && tar -xzf /tmp/piper.tar.gz -C /opt \
+    && rm /tmp/piper.tar.gz \
+    && mkdir -p /app/agent/voices \
+    && curl -fsSL -o /app/agent/voices/en_US-hfc_female-medium.onnx \
+      "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/hfc_female/medium/en_US-hfc_female-medium.onnx" \
+    && curl -fsSL -o /app/agent/voices/en_US-hfc_female-medium.onnx.json \
+      "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/hfc_female/medium/en_US-hfc_female-medium.onnx.json" \
+    && chown -R 1000:1000 /app/agent/voices
+ENV PATH="/opt/piper:${PATH}"
+USER 1000
+
+VOLUME ["/data/agent-home"]
+
+# Health probe port
+EXPOSE 3459
+
+# Base-image contract (downstream images build FROM this one):
+#   - marketplaces COPYed to /opt/shipwright/marketplaces/<name>/ are registered
+#     at boot by installPlugins() (runtime/setup.ts)
+#   - the entrypoint path below is stable
+ENTRYPOINT ["bun", "run", "/app/runtime/entrypoint-main.ts"]

package/agent-account-status-ref.ts

@@ -0,0 +1,53 @@
+/**
+ * agent/src/runtime/agent-account-status-ref.ts
+ *
+ * A tiny mutable box holding the agent's most recently synced owning-account
+ * status (SSP-8.3), so agent/src/runtime/slack.ts's isAccountPaused() gate can read a
+ * live view without closing over a single syncConfig() tick. Pure and
+ * zero-I/O — mirrors agent-trial-expiry-ref.ts exactly.
+ */
+
+export interface AgentAccountStatusRef {
+  /**
+   * Most recently synced account status ('active' | 'suspended' |
+   * 'trial_expired'), or null when set() was never called or the agent has
+   * no account. Use hasSynced() to tell "never synced" from "no account".
+   */
+  get(): string | null;
+  /**
+   * True once set() has been called at least once. Consumers gating on
+   * account status should fail open while this is false, so a persistent
+   * config-sync failure never locks a customer out of their own agent.
+   */
+  hasSynced(): boolean;
+  /** Replaces the current account status. */
+  set(status: string | null): void;
+}
+
+/** Creates a new, independent ref defaulting to "no account". */
+export function createAgentAccountStatusRef(): AgentAccountStatusRef {
+  let accountStatus: string | null = null;
+  let synced = false;
+
+  return {
+    get(): string | null {
+      return accountStatus;
+    },
+    hasSynced(): boolean {
+      return synced;
+    },
+    set(next: string | null): void {
+      accountStatus = next;
+      synced = true;
+    },
+  };
+}
+
+/**
+ * The process-wide account-status ref. agent/src/index.ts's syncConfig()
+ * writes into it on every successful config-sync tick; slack.ts's
+ * isAccountPaused() reads it on every inbound Slack event, so a status change
+ * (suspension or reactivation) takes effect on the next sync with no restart.
+ */
+export const agentAccountStatusRef: AgentAccountStatusRef =
+  createAgentAccountStatusRef();

package/agent-account-status-ref.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { createAgentAccountStatusRef } from "./agent-account-status-ref.ts";
+
+describe("createAgentAccountStatusRef", () => {
+  test("defaults to unsynced with a null status", () => {
+    const ref = createAgentAccountStatusRef();
+    expect(ref.hasSynced()).toBe(false);
+    expect(ref.get()).toBeNull();
+  });
+
+  test("set() stores the status and marks the ref synced", () => {
+    const ref = createAgentAccountStatusRef();
+    ref.set("suspended");
+    expect(ref.hasSynced()).toBe(true);
+    expect(ref.get()).toBe("suspended");
+  });
+
+  test("set(null) marks synced with no account", () => {
+    const ref = createAgentAccountStatusRef();
+    ref.set(null);
+    expect(ref.hasSynced()).toBe(true);
+    expect(ref.get()).toBeNull();
+  });
+});

package/agent-extension.ts

@@ -0,0 +1,144 @@
+/**
+ * agent/src/runtime/agent-extension.ts
+ *
+ * The extension seam between the generic agent runtime (boot.ts, config
+ * sync, cron scheduling) and specialty-specific behavior (today: the coding
+ * agent's PR/task reconcilers and shipwright-loop orchestrator).
+ *
+ * The runtime calls an AgentExtension at fixed points:
+ *
+ *   onConfigSync(bundle)      — every successful config-sync tick
+ *   periodicPasses            — each tick of the periodic reconciler interval
+ *   onCronJobs(jobs)          — every cron-sync tick, BEFORE classifyCronJobs
+ *   classifyCronJobs(jobs)    — which jobs get a schedule + dispatch kind
+ *   dispatchLoop(loopCronId)  — fire of a job classified as dispatch "loop"
+ *
+ * Every hook is optional; the defaults reproduce an agent with no extension
+ * (all jobs generic, no periodic passes). This file must not import any
+ * coding module — index.ts (the composition root) is the only file that wires
+ * a concrete extension in.
+ */
+
+import type { ErrorCapturingClient } from "@app-vitals/agent-lib/sentry";
+import type { createRunClaude } from "./claude.ts";
+import type { createConfig } from "./config.ts";
+import type { createContextStampReader } from "./context-stamp.ts";
+import type { CronRunReporter } from "./cron-run-reporter.ts";
+import type { createFileSessionStore } from "./sessions.ts";
+
+/** Minimal structural view of a cron job, as the seam needs it. */
+export interface ExtensionCronJob {
+  id: string;
+  name: string | null;
+  enabled: boolean;
+  parentCronId: string | null;
+}
+
+export type CronDispatchKind = "loop" | "generic";
+
+export interface ScheduledCronJob<T extends ExtensionCronJob> {
+  job: T;
+  dispatch: CronDispatchKind;
+}
+
+/** A named, independent unit of periodic work run on the reconciler tick. */
+export interface PeriodicPass {
+  name: string;
+  /** Prefix for the non-fatal failure log: `${logPrefix} tick failed (non-fatal):`. */
+  logPrefix: string;
+  run(): Promise<void>;
+}
+
+/** Everything an extension may need from the runtime to build itself. */
+export interface AgentExtensionContext {
+  config: ReturnType<typeof createConfig>["config"];
+  runner: ReturnType<typeof createRunClaude>;
+  sessions: ReturnType<typeof createFileSessionStore>;
+  cronRunReporter: CronRunReporter | undefined;
+  contextStamp: ReturnType<typeof createContextStampReader>;
+  sentryClient: ErrorCapturingClient | undefined;
+}
+
+export interface AgentExtension<TBundle = unknown> {
+  onConfigSync?(bundle: TBundle): void;
+  periodicPasses?: PeriodicPass[];
+  onCronJobs?(jobs: ExtensionCronJob[]): void;
+  classifyCronJobs?<T extends ExtensionCronJob>(
+    jobs: T[],
+  ): ScheduledCronJob<T>[];
+  /** Runs one loop tick; the orchestrator behind it is built once, lazily. */
+  dispatchLoop?(loopCronId: string): Promise<void>;
+}
+
+/** Default classification: every enabled job is independently scheduled, generic. */
+export function classifyAllGeneric<T extends ExtensionCronJob>(
+  jobs: T[],
+): ScheduledCronJob<T>[] {
+  return jobs
+    .filter((job) => job.enabled)
+    .map((job) => ({ job, dispatch: "generic" as const }));
+}
+
+/**
+ * One cron-sync tick's view of the job list: tells the extension about the
+ * fresh list first (so e.g. the loop's live jobs ref is current even when
+ * nothing gets rescheduled), then classifies it.
+ */
+export function planCronSchedule<T extends ExtensionCronJob>(
+  extension: AgentExtension,
+  jobs: T[],
+): ScheduledCronJob<T>[] {
+  extension.onCronJobs?.(jobs);
+  return (extension.classifyCronJobs ?? classifyAllGeneric)(jobs);
+}
+
+/**
+ * Runs passes in order, each in its own try/catch so one failing pass never
+ * prevents the next. Failures are logged non-fatally with the pass's prefix.
+ */
+export async function runPeriodicPasses(
+  passes: readonly PeriodicPass[],
+): Promise<void> {
+  for (const pass of passes) {
+    try {
+      await pass.run();
+    } catch (err) {
+      console.error(
+        `${pass.logPrefix} tick failed (non-fatal):`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+}
+
+/** Builds an extension from the runtime context once the runtime has booted far enough to provide it. */
+export type AgentExtensionFactory = (
+  ctx: AgentExtensionContext,
+) => AgentExtension;
+
+/**
+ * Folds the extensions a consumer passed to startAgent into the single
+ * extension the runtime talks to. No extensions reproduces an agent with no
+ * specialty behavior; one extension is returned as-is. With several, notify
+ * hooks (onConfigSync, onCronJobs) fan out to all, periodic passes concatenate
+ * in order, and the first extension defining classifyCronJobs / dispatchLoop
+ * owns it — those two decide a single outcome, so they cannot be merged.
+ */
+export function composeExtensions(
+  extensions: readonly AgentExtension[],
+): AgentExtension {
+  if (extensions.length === 1) return extensions[0];
+  const classifier = extensions.find((ext) => ext.classifyCronJobs);
+  const dispatcher = extensions.find((ext) => ext.dispatchLoop);
+  return {
+    onConfigSync: (bundle) => {
+      for (const ext of extensions) ext.onConfigSync?.(bundle);
+    },
+    periodicPasses: extensions.flatMap((ext) => ext.periodicPasses ?? []),
+    onCronJobs: (jobs) => {
+      for (const ext of extensions) ext.onCronJobs?.(jobs);
+    },
+    classifyCronJobs: classifier?.classifyCronJobs?.bind(classifier),
+    dispatchLoop: dispatcher?.dispatchLoop?.bind(dispatcher),
+  };
+}

package/agent-extension.unit.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it, spyOn } from "bun:test";
+import {
+  type AgentExtension,
+  classifyAllGeneric,
+  composeExtensions,
+  type ExtensionCronJob,
+  type PeriodicPass,
+  planCronSchedule,
+  runPeriodicPasses,
+} from "./agent-extension.ts";
+
+const job = (id: string, enabled = true): ExtensionCronJob => ({
+  id,
+  name: id,
+  enabled,
+  parentCronId: null,
+});
+
+describe("planCronSchedule", () => {
+  it("calls onCronJobs before classifyCronJobs, with the same fresh list", () => {
+    const calls: string[] = [];
+    const jobs = [job("a")];
+    const extension: AgentExtension = {
+      onCronJobs: (j) => {
+        calls.push(`onCronJobs:${j === jobs}`);
+      },
+      classifyCronJobs: (j) => {
+        calls.push(`classify:${j === jobs}`);
+        return [];
+      },
+    };
+    planCronSchedule(extension, jobs);
+    planCronSchedule(extension, jobs);
+    expect(calls).toEqual([
+      "onCronJobs:true",
+      "classify:true",
+      "onCronJobs:true",
+      "classify:true",
+    ]);
+  });
+
+  it("defaults to all-generic when the extension has no classifier", () => {
+    const planned = planCronSchedule({}, [job("a"), job("b", false)]);
+    expect(planned).toEqual([{ job: job("a"), dispatch: "generic" }]);
+  });
+});
+
+describe("classifyAllGeneric", () => {
+  it("keeps only enabled jobs, all generic", () => {
+    expect(
+      classifyAllGeneric([job("a"), job("b", false)]).map((e) => e.dispatch),
+    ).toEqual(["generic"]);
+  });
+});
+
+describe("runPeriodicPasses", () => {
+  it("runs passes in order and isolates a failing pass with its own log prefix", async () => {
+    const order: string[] = [];
+    const errors = spyOn(console, "error").mockImplementation(() => {});
+    const pass = (name: string, fail = false): PeriodicPass => ({
+      name,
+      logPrefix: `[${name}]`,
+      run: async () => {
+        order.push(name);
+        if (fail) throw new Error("boom");
+      },
+    });
+    await runPeriodicPasses([pass("one"), pass("two", true), pass("three")]);
+    expect(order).toEqual(["one", "two", "three"]);
+    expect(errors).toHaveBeenCalledWith(
+      "[two] tick failed (non-fatal):",
+      "boom",
+    );
+    errors.mockRestore();
+  });
+});
+
+describe("composeExtensions", () => {
+  it("with no extensions behaves like an agent with no specialty behavior", async () => {
+    const extension = composeExtensions([]);
+    expect(() => extension.onConfigSync?.({})).not.toThrow();
+    expect(extension.periodicPasses).toEqual([]);
+    expect(planCronSchedule(extension, [job("a"), job("b", false)])).toEqual([
+      { job: job("a"), dispatch: "generic" },
+    ]);
+    expect(extension.dispatchLoop).toBeUndefined();
+  });
+
+  it("returns a single extension as-is", () => {
+    const stub: AgentExtension = { periodicPasses: [] };
+    expect(composeExtensions([stub])).toBe(stub);
+  });
+
+  it("fans out notify hooks and concatenates passes in order", () => {
+    const calls: string[] = [];
+    const pass = (name: string): PeriodicPass => ({
+      name,
+      logPrefix: `[${name}]`,
+      run: async () => {},
+    });
+    const a: AgentExtension = {
+      onConfigSync: () => calls.push("a:sync"),
+      onCronJobs: () => calls.push("a:jobs"),
+      periodicPasses: [pass("a1")],
+    };
+    const b: AgentExtension = {
+      onConfigSync: () => calls.push("b:sync"),
+      periodicPasses: [pass("b1"), pass("b2")],
+    };
+    const composed = composeExtensions([a, b]);
+    composed.onConfigSync?.({});
+    composed.onCronJobs?.([]);
+    expect(calls).toEqual(["a:sync", "b:sync", "a:jobs"]);
+    expect(composed.periodicPasses?.map((p) => p.name)).toEqual([
+      "a1",
+      "b1",
+      "b2",
+    ]);
+  });
+
+  it("lets the first extension defining classify / dispatchLoop own it", async () => {
+    const dispatched: string[] = [];
+    const owner: AgentExtension = {
+      classifyCronJobs: (jobs) =>
+        jobs.map((j) => ({ job: j, dispatch: "loop" })),
+      dispatchLoop: async (id) => {
+        dispatched.push(id);
+      },
+    };
+    const composed = composeExtensions([
+      {},
+      owner,
+      { dispatchLoop: async () => {} },
+    ]);
+    expect(planCronSchedule(composed, [job("x")])[0].dispatch).toBe("loop");
+    await composed.dispatchLoop?.("x");
+    expect(dispatched).toEqual(["x"]);
+  });
+});