harnery 0.15.0 → 0.16.0

package/dist/lib/tunnel/gate.js

@@ -38,13 +38,18 @@ const server = Bun.serve({
     // Bun's max, and beyond any realistic single-turn delay.
     idleTimeout: 255,
     async fetch(req, server) {
+        const url = new URL(req.url);
         if (ACCESS === "cloudflare-allowlist") {
             const ip = req.headers.get("cf-connecting-ip") ?? "";
             if (!ALLOW.has(ip)) {
+                // Log denials so operators can whitelist a phone/laptop that just
+                // hit 403 without asking the human to dig up their public IP.
+                console.log(
+                // lint-ok-emission: detached worker, see file note above
+                `deny: ${ip || "(missing-cf-connecting-ip)"} ${req.method} ${url.pathname}`);
                 return new Response("403 Forbidden\n", { status: 403 });
             }
         }
-        const url = new URL(req.url);
         if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
             if (server.upgrade(req, { data: { path: url.pathname + url.search } })) {
                 return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/commands/supervisor.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
@@ -8,12 +8,21 @@ import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
 import type { PolicyIsolation } from "../core/policy/index.ts";
 import { loadPolicyFile } from "../core/policy/index.ts";
 import {
+  configureSupervisorService,
   createSupervisor,
   listSupervisors,
   readSupervisor,
+  readSupervisorServiceConfig,
+  readSupervisorServiceStatus,
+  requestSupervisorServiceStop,
   runSupervisor,
+  runSupervisorServiceDaemon,
   type SupervisorRecord,
   type SupervisorRunReport,
+  type SupervisorServiceConfig,
+  type SupervisorServiceStatus,
+  spawnSupervisorService,
+  supervisorServiceLogPath,
 } from "../core/supervisor/index.ts";
 import type { WorkflowSpecialistProfile } from "../core/workflow/index.ts";
 
@@ -45,6 +54,13 @@ interface RunOpts {
   json?: boolean;
 }
 
+interface ServiceOpts extends RunOpts {
+  wakeIntervalMs?: string;
+  heartbeatIntervalMs?: string;
+  errorBackoffBaseMs?: string;
+  errorBackoffMaxMs?: string;
+}
+
 export function registerSupervisorCommand(program: Command, emit: EmitContext): void {
   const registry = createBuiltinHarnessRegistry();
   const supervisor = program
@@ -133,10 +149,250 @@ export function registerSupervisorCommand(program: Command, emit: EmitContext):
       });
     });
 
+  registerServiceCommand(supervisor, registry, emit);
   registerRunCommand(supervisor, "tick", registry, emit);
   registerRunCommand(supervisor, "run", registry, emit);
 }
 
+function registerServiceCommand(
+  supervisor: Command,
+  registry: ReturnType<typeof createBuiltinHarnessRegistry>,
+  emit: EmitContext,
+): void {
+  const service = supervisor
+    .command("service")
+    .description("Run explicitly enrolled durable goals in a restartable background service.");
+
+  addServiceOptions(
+    service
+      .command("start [goal-ids...]")
+      .description("Configure and start the detached per-repository supervisor service."),
+  )
+    .option("--json", "Emit complete service status as JSON")
+    .action(async (goalIds: string[], opts: ServiceOpts) => {
+      await withSupervisorRootAsync(emit, async (coordRoot) => {
+        prepareServiceConfig(coordRoot, goalIds, opts, registry);
+        const status = await spawnSupervisorService(coordRoot);
+        emitServiceStatus(status, opts.json, emit);
+      });
+    });
+
+  addServiceOptions(
+    service
+      .command("run [goal-ids...]")
+      .description("Run the persistent service loop in the foreground for a process manager."),
+  )
+    .option("--json", "Emit terminal service status as JSON")
+    .action(async (goalIds: string[], opts: ServiceOpts) => {
+      await withSupervisorRootAsync(emit, async (coordRoot) => {
+        const config = prepareServiceConfig(coordRoot, goalIds, opts, registry);
+        const status = await runSupervisorServiceDaemon({
+          coordRoot,
+          engine: serviceEngine(config, registry),
+          onLog: opts.json ? undefined : (line) => emit.text(`${line}\n`),
+        });
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(status);
+        }
+      });
+    });
+
+  service
+    .command("status")
+    .description("Show service liveness, heartbeat, enrolled goals, and durable wake state.")
+    .option("--json", "Emit complete service status as JSON")
+    .action((opts: { json?: boolean }) => {
+      withSupervisorRoot(emit, (coordRoot) => {
+        emitServiceStatus(readSupervisorServiceStatus(coordRoot), opts.json, emit);
+      });
+    });
+
+  service
+    .command("stop")
+    .description("Request a graceful stop; an active goal tick is allowed to finish safely.")
+    .option("--json", "Emit complete service status as JSON")
+    .action(async (opts: { json?: boolean }) => {
+      await withSupervisorRootAsync(emit, async (coordRoot) => {
+        let status = requestSupervisorServiceStop(coordRoot);
+        const deadline = Date.now() + 5_000;
+        while (status.running && Date.now() < deadline) {
+          await delay(50);
+          status = readSupervisorServiceStatus(coordRoot);
+        }
+        emitServiceStatus(status, opts.json, emit);
+      });
+    });
+
+  service
+    .command("logs")
+    .description("Show the tail of the private background-service log.")
+    .option("--lines <n>", "Number of lines to show (default 50)", "50")
+    .action((opts: { lines: string }) => {
+      withSupervisorRoot(emit, (coordRoot) => {
+        const lines = integer(opts.lines) ?? 50;
+        if (lines > 10_000) throw new Error("service log lines must not exceed 10000");
+        const path = supervisorServiceLogPath(coordRoot);
+        if (!existsSync(path)) {
+          emit.text("no supervisor service log\n");
+          return;
+        }
+        const selected = readFileSync(path, "utf8")
+          .split("\n")
+          .slice(-(lines + 1))
+          .join("\n");
+        emit.text(selected.endsWith("\n") ? selected : `${selected}\n`);
+      });
+    });
+
+  service
+    .command("daemon", { hidden: true })
+    .description("Internal detached service entrypoint.")
+    .action(async () => {
+      await withSupervisorRootAsync(emit, async (coordRoot) => {
+        const config = readSupervisorServiceConfig(coordRoot);
+        await runSupervisorServiceDaemon({
+          coordRoot,
+          engine: serviceEngine(config, registry),
+          onLog: (line) => emit.text(`${line}\n`),
+        });
+      });
+    });
+}
+
+function addServiceOptions(command: Command): Command {
+  return command
+    .option("--wake-interval-ms <n>", "State-change poll interval (default 5000)")
+    .option("--heartbeat-interval-ms <n>", "Heartbeat interval (default 2000)")
+    .option("--error-backoff-base-ms <n>", "Initial service-error backoff (default 2000)")
+    .option("--error-backoff-max-ms <n>", "Maximum service-error backoff (default 300000)")
+    .option("--harness <name>", "Fallback harness for agent calls without a specialist")
+    .option("--cwd <dir>", "Working directory for child agents")
+    .option("--subscription-only", "Require stored harness-login billing")
+    .option("--allow-api-billing", "Permit API-key override billing")
+    .option("--policy <file>", "Host policy JSON/JSONC")
+    .option("--isolation <mode>", "shared | worktree | sandbox | remote")
+    .option("--approval-to <address>", "Address durable ASK requests");
+}
+
+function prepareServiceConfig(
+  coordRoot: string,
+  goalIds: string[],
+  opts: ServiceOpts,
+  registry: ReturnType<typeof createBuiltinHarnessRegistry>,
+): SupervisorServiceConfig {
+  if (goalIds.length === 0) {
+    if (hasServiceConfigOverrides(opts)) {
+      throw new Error("goal ids are required when changing supervisor service options");
+    }
+    return readSupervisorServiceConfig(coordRoot);
+  }
+  if (opts.harness && !registry.get(opts.harness)) {
+    throw new Error(`unknown harness ${JSON.stringify(opts.harness)}`);
+  }
+  const policy = opts.policy ? loadPolicyFile(opts.policy) : undefined;
+  return configureSupervisorService({
+    coordRoot,
+    goalIds,
+    wakeIntervalMs: integer(opts.wakeIntervalMs),
+    heartbeatIntervalMs: integer(opts.heartbeatIntervalMs),
+    errorBackoffBaseMs: integer(opts.errorBackoffBaseMs),
+    errorBackoffMaxMs: integer(opts.errorBackoffMaxMs),
+    engine: {
+      default_harness: opts.harness,
+      cwd: opts.cwd,
+      subscription_only:
+        opts.subscriptionOnly === true ? true : workflowSubscriptionOnly(coordRoot),
+      allow_api_billing: opts.allowApiBilling,
+      policy,
+      isolation: opts.isolation,
+      approval_addressee: opts.approvalTo,
+    },
+  });
+}
+
+function hasServiceConfigOverrides(opts: ServiceOpts): boolean {
+  return Boolean(
+    opts.wakeIntervalMs ||
+      opts.heartbeatIntervalMs ||
+      opts.errorBackoffBaseMs ||
+      opts.errorBackoffMaxMs ||
+      opts.harness ||
+      opts.cwd ||
+      opts.subscriptionOnly ||
+      opts.allowApiBilling ||
+      opts.policy ||
+      opts.isolation ||
+      opts.approvalTo,
+  );
+}
+
+function serviceEngine(
+  config: SupervisorServiceConfig,
+  registry: ReturnType<typeof createBuiltinHarnessRegistry>,
+) {
+  return {
+    spawners: registry.spawners(),
+    defaultHarness: config.engine.default_harness,
+    cwd: config.engine.cwd,
+    subscriptionOnly: config.engine.subscription_only,
+    allowApiBilling: config.engine.allow_api_billing,
+    harnessEvidence: Object.fromEntries(
+      registry
+        .list()
+        .map((adapter) => [
+          adapter.profile.id,
+          { toolEvidence: adapter.profile.capabilities.toolEvidence },
+        ]),
+    ),
+    policy: config.engine.policy,
+    approvalMode: "park" as const,
+    approvalAddressee: config.engine.approval_addressee,
+    isolation: config.engine.isolation,
+    networkAccess: "enabled" as const,
+  };
+}
+
+function emitServiceStatus(
+  status: SupervisorServiceStatus,
+  json: boolean | undefined,
+  emit: EmitContext,
+): void {
+  if (json) {
+    emit.config({ format: "json" });
+    emit.data(status);
+    return;
+  }
+  if (!status.config && !status.record) {
+    emit.text("supervisor service: unconfigured\n");
+    return;
+  }
+  const state = status.running
+    ? (status.record?.state ?? "running")
+    : status.stale
+      ? "stale"
+      : "stopped";
+  const lines = [
+    `supervisor service: ${state}`,
+    `goals: ${status.config?.goal_ids.join(", ") || "none"}`,
+  ];
+  if (status.record) {
+    lines.push(`pid: ${status.record.pid} on ${status.record.host}`);
+    lines.push(`heartbeat: ${status.record.heartbeat_at}`);
+    lines.push(`sweeps: ${status.record.sweep_count}`);
+    if (status.record.active_goal_id) lines.push(`active: ${status.record.active_goal_id}`);
+    if (status.record.next_wake_at) lines.push(`next wake: ${status.record.next_wake_at}`);
+    if (status.record.last_error) lines.push(`error: ${status.record.last_error}`);
+  }
+  const backingOff = Object.entries(status.runtime?.goals ?? {}).filter(
+    ([, runtime]) => runtime.state === "backoff",
+  );
+  if (backingOff.length) {
+    lines.push(`backoff: ${backingOff.map(([goalId]) => goalId).join(", ")}`);
+  }
+  emit.text(`${lines.join("\n")}\n`);
+}
+
 function registerRunCommand(
   supervisor: Command,
   mode: "tick" | "run",
@@ -275,6 +531,10 @@ function integer(value: string | undefined): number | undefined {
   return Number.parseInt(value, 10);
 }
 
+function delay(ms: number): Promise<void> {
+  return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+
 function withSupervisorRoot(emit: EmitContext, fn: (coordRoot: string) => void): void {
   const coordRoot = findCoordRoot();
   if (!coordRoot) {

package/src/core/supervisor/index.ts

@@ -5,6 +5,33 @@ export {
   type SupervisorRunReport,
   type SupervisorStopReason,
 } from "./runner.ts";
+export {
+  type ConfigureSupervisorServiceInput,
+  configureSupervisorService,
+  type RunSupervisorServiceDaemonInput,
+  type RunSupervisorServiceSweepInput,
+  readSupervisorServiceConfig,
+  readSupervisorServiceRuntime,
+  readSupervisorServiceStatus,
+  requestSupervisorServiceStop,
+  runSupervisorServiceDaemon,
+  runSupervisorServiceSweep,
+  SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION,
+  SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION,
+  SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION,
+  type SupervisorServiceConfig,
+  type SupervisorServiceEngineConfig,
+  type SupervisorServiceGoalRuntime,
+  type SupervisorServiceGoalState,
+  type SupervisorServiceProcessState,
+  type SupervisorServiceRuntime,
+  type SupervisorServiceStatus,
+  type SupervisorServiceStatusRecord,
+  type SupervisorServiceSweepOutcome,
+  type SupervisorServiceSweepReport,
+  spawnSupervisorService,
+  supervisorServiceLogPath,
+} from "./service.ts";
 export {
   assertSupervisorId,
   type CreateSupervisorInput,

package/src/core/supervisor/read.ts

@@ -1,3 +1,18 @@
+export type {
+  SupervisorServiceConfig,
+  SupervisorServiceGoalRuntime,
+  SupervisorServiceGoalState,
+  SupervisorServiceProcessState,
+  SupervisorServiceRuntime,
+  SupervisorServiceStatus,
+  SupervisorServiceStatusRecord,
+} from "./service.ts";
+export {
+  readSupervisorServiceConfig,
+  readSupervisorServiceRuntime,
+  readSupervisorServiceStatus,
+  supervisorServiceLogPath,
+} from "./service-read.ts";
 export {
   assertSupervisorId,
   collectSupervisorWork,

package/src/core/supervisor/service-read.ts

@@ -0,0 +1,144 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import type {
+  SupervisorServiceConfig,
+  SupervisorServiceRuntime,
+  SupervisorServiceStatus,
+  SupervisorServiceStatusRecord,
+} from "./service.ts";
+
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_GOALS = 100;
+const FOREIGN_STATUS_STALE_MS = 30_000;
+
+export function readSupervisorServiceConfig(coordRootRaw: string): SupervisorServiceConfig {
+  const coordRoot = resolve(coordRootRaw);
+  const config = readBoundedJson<SupervisorServiceConfig>(
+    join(serviceDir(coordRoot), "config.json"),
+    "supervisor service configuration",
+  );
+  if (
+    config.schema_version !== 1 ||
+    !validTimestamp(config.created_at) ||
+    !Array.isArray(config.goal_ids) ||
+    config.goal_ids.length < 1 ||
+    config.goal_ids.length > MAX_GOALS ||
+    config.goal_ids.some((goalId) => typeof goalId !== "string" || !goalId.trim()) ||
+    !positive(config.wake_interval_ms) ||
+    !positive(config.heartbeat_interval_ms) ||
+    !positive(config.error_backoff_base_ms) ||
+    !positive(config.error_backoff_max_ms) ||
+    config.error_backoff_max_ms < config.error_backoff_base_ms ||
+    !config.engine ||
+    typeof config.engine !== "object" ||
+    typeof config.engine.subscription_only !== "boolean" ||
+    typeof config.engine.allow_api_billing !== "boolean"
+  ) {
+    throw new Error("supervisor service configuration has an unsupported schema");
+  }
+  return config;
+}
+
+export function readSupervisorServiceRuntime(
+  coordRootRaw: string,
+): SupervisorServiceRuntime | undefined {
+  const coordRoot = resolve(coordRootRaw);
+  const path = join(serviceDir(coordRoot), "runtime.json");
+  if (!existsSync(path)) return undefined;
+  const runtime = readBoundedJson<SupervisorServiceRuntime>(path, "supervisor service runtime");
+  if (
+    runtime.schema_version !== 1 ||
+    !validTimestamp(runtime.config_created_at) ||
+    !validTimestamp(runtime.updated_at) ||
+    !runtime.goals ||
+    typeof runtime.goals !== "object" ||
+    Array.isArray(runtime.goals)
+  ) {
+    throw new Error("supervisor service runtime has an unsupported schema");
+  }
+  return runtime;
+}
+
+export function readSupervisorServiceStatus(coordRootRaw: string): SupervisorServiceStatus {
+  const coordRoot = resolve(coordRootRaw);
+  const record = readStatusRecord(coordRoot);
+  let config: SupervisorServiceConfig | undefined;
+  let runtime: SupervisorServiceRuntime | undefined;
+  try {
+    config = readSupervisorServiceConfig(coordRoot);
+  } catch {
+    // Unconfigured or corrupt service state is represented without throwing.
+  }
+  try {
+    runtime = readSupervisorServiceRuntime(coordRoot);
+  } catch {
+    // Runtime is recoverable and must not make the dashboard unreadable.
+  }
+  if (!record) return { running: false, stale: false, config, runtime };
+  const running = statusOwnerIsLive(record);
+  return { running, stale: !running && record.state !== "stopped", record, config, runtime };
+}
+
+export function supervisorServiceLogPath(coordRoot: string): string {
+  return join(serviceDir(resolve(coordRoot)), "service.log");
+}
+
+function readStatusRecord(coordRoot: string): SupervisorServiceStatusRecord | undefined {
+  const path = join(serviceDir(coordRoot), "status.json");
+  if (!existsSync(path)) return undefined;
+  try {
+    const value = readBoundedJson<SupervisorServiceStatusRecord>(path, "supervisor service status");
+    if (
+      value.schema_version !== 1 ||
+      !Number.isSafeInteger(value.pid) ||
+      value.pid < 1 ||
+      typeof value.host !== "string" ||
+      typeof value.nonce !== "string" ||
+      !validTimestamp(value.started_at) ||
+      !validTimestamp(value.heartbeat_at)
+    ) {
+      return undefined;
+    }
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+function statusOwnerIsLive(record: SupervisorServiceStatusRecord): boolean {
+  if (record.state === "stopped") return false;
+  if (record.host === hostname()) {
+    try {
+      process.kill(record.pid, 0);
+      return true;
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+  }
+  const age = Date.now() - Date.parse(record.heartbeat_at);
+  return Number.isFinite(age) && age < FOREIGN_STATUS_STALE_MS;
+}
+
+function readBoundedJson<T>(path: string, label: string): T {
+  if (!existsSync(path)) throw new Error(`${label} does not exist`);
+  const size = statSync(path).size;
+  if (size <= 0 || size > MAX_FILE_BYTES) throw new Error(`${label} has invalid size ${size}`);
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch (error) {
+    throw new Error(`cannot parse ${label}: ${(error as Error).message}`);
+  }
+}
+
+function serviceDir(coordRoot: string): string {
+  return join(coordRoot, ".harnery", "supervisor-service");
+}
+
+function positive(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) > 0;
+}
+
+function validTimestamp(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 40 && Number.isFinite(Date.parse(value));
+}