@forgezero/agent 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+import { type NodeKeyPair } from '@forgezero/runtime/identity';
+import { startAgent, type AgentOptions, type AttestationSource } from './socket';
+import type { SecretCache } from './cache';
+/**
+ * fz-agent — runs on the metal, driven over SSH before the platform exists and
+ * over HTTPS after it does. One implementation, two front doors: bootstrap is
+ * not a special case, it is the general case run first, because a tenant's own
+ * bare metal has no ForgeZero on it either.
+ *
+ * Everything it does is recorded in a hash-chained journal from its first
+ * command — before there is a database to log into. A flat log written then is
+ * a log anyone could have edited afterwards; the chain either verifies or
+ * visibly does not, and it is replayed into `audit_log` once the platform is
+ * operational.
+ *
+ * ## What it serves
+ *
+ * A unix socket that SIGNS and never surrenders the key. `@forgezero/vault`
+ * discovers `/run/forgezero.sock` and prefers it over `FORGEZERO_API_KEY`, so
+ * moving an application onto managed compute means deleting an environment
+ * variable rather than changing a line of code — and a machine that used to hold
+ * a signing seed now holds nothing an attacker can take.
+ *
+ * That preference was implemented in the client long before anything listened.
+ * See `socket.ts` for why it signs rather than handing back a token.
+ */
+export declare const VERSION = "0.1.0";
+export { startAgent, handleRequest } from './socket';
+export type { AgentOptions, AttestationSource, Request, Response } from './socket';
+export { createSecretCache, CacheError } from './cache';
+export type { SecretCache, CacheOptions } from './cache';
+/**
+ * The node seed, on disk, owner-only.
+ *
+ * Generated on first run rather than shipped: a seed baked into an image is a
+ * seed every guest from that image shares, and a fleet becomes one identity
+ * wearing many hostnames. Losing the file loses the node's identity, which is
+ * correct — re-enrolment is the recovery path, not a backup of the secret.
+ */
+export declare function loadOrCreateSeed(path: string): Uint8Array;
+export interface AgentConfig {
+    socketPath?: string;
+    seedPath?: string;
+    /** As the platform knows this node. Absent before enrolment. */
+    nodeKey?: string;
+    attestation?: AttestationSource;
+    /**
+     * Secrets cached in memory on this guest, if this node serves any.
+     *
+     * Never written to disk. That would hand an attacker with filesystem access
+     * every secret the guest has ever read — precisely the file that does not
+     * exist today, and the whole reason a node holds a signing key rather than a
+     * `.env`. A restart re-fetches; that costs one round trip.
+     */
+    cache?: SecretCache;
+    record?: AgentOptions['record'];
+}
+/**
+ * The path the agent LISTENS on, taken from the client that discovers it.
+ *
+ * Both ends declared this literal independently — `@forgezero/vault` as
+ * `DEFAULT_SOCKET` because discovery is part of its published contract, and the
+ * agent as its own constant because it is the thing that binds. Moving either
+ * one leaves an agent listening where nothing looks, and the symptom is every
+ * app silently falling back to an API key: strictly weaker, entirely working,
+ * and invisible.
+ *
+ * The published client is the authority here rather than the other way round.
+ * A tenant's application ships with `@forgezero/vault` and cannot be asked to
+ * follow a path this repository moved.
+ */
+export declare const DEFAULT_SOCKET_PATH = "/run/forgezero.sock";
+export declare const DEFAULT_SEED_PATH = "/var/lib/forgezero/node.seed";
+/**
+ * Bring the agent up.
+ *
+ * Returns the keys alongside the server so an enrolment flow can read the public
+ * halves without going through the socket — the same values it would get there,
+ * from the process that already holds them.
+ */
+export declare function runAgent(config?: AgentConfig): {
+    server: ReturnType<typeof startAgent>;
+    keys: NodeKeyPair;
+    nodeKey: string;
+};

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pipeline.d.ts

@@ -0,0 +1,108 @@
+/**
+ * CI/CD on the compute, through the agent — and never around it.
+ *
+ * A deploy needs two things at the same time: the tenant's secrets, and the
+ * right to run commands on their machine. Every hosted CI answers that by
+ * copying the secrets INTO the runner, which is why a compromised build step is
+ * a compromised production credential everywhere that model is used.
+ *
+ * The agent already holds the secrets and already runs on the box. So the build
+ * happens here, the secrets are handed to the step's process and to nothing
+ * else, and nothing is ever written where a later step could read it.
+ *
+ * ## Attestation gates the run, not the read
+ *
+ * Reading a secret is gated by the socket's filesystem permissions, and that is
+ * proportionate — an application on this box is meant to read its own config.
+ * RUNNING A PIPELINE is different: it executes attacker-chosen commands if the
+ * pipeline definition is attacker-chosen, so the platform has to know it is
+ * talking to the machine it thinks it is.
+ *
+ * On an attested compute that is a hardware report. On one that is merely
+ * enrolled it is the node's hybrid signature, which proves possession of a key
+ * the platform issued and NOT what the machine is running. Both are honest
+ * postures and the difference is recorded on the run, so a tenant can require
+ * the stronger one — and `requireAttestation` is what makes that a refusal
+ * rather than a preference.
+ *
+ * ## Secrets never reach disk, and never reach the log
+ *
+ * They are passed as environment to the spawned process and redacted from
+ * captured output on the way back. The redaction is a last line, not the
+ * mechanism: a step that deliberately prints a secret has already been given it.
+ * What redaction buys is that a step which prints its environment while
+ * debugging does not put a production key in a log somebody ships to a vendor.
+ */
+export type StepOutcome = 'ok' | 'failed' | 'skipped';
+export interface PipelineStep {
+    name: string;
+    run: string;
+    /** Secret names this step needs. Nothing it does not name is in its env. */
+    secrets?: readonly string[];
+    /** Run even when an earlier step failed — cleanup, teardown, notifications. */
+    always?: boolean;
+    timeoutMs?: number;
+}
+export interface Pipeline {
+    name: string;
+    steps: readonly PipelineStep[];
+    /**
+     * Refuse to run at all unless the agent can produce a hardware attestation.
+     *
+     * A tenant deploying something that matters sets this. It is the difference
+     * between "a machine holding our node key ran this" and "a machine we can
+     * prove is running the image we expect ran this".
+     */
+    requireAttestation?: boolean;
+}
+export interface StepResult {
+    name: string;
+    outcome: StepOutcome;
+    exitCode: number | null;
+    /** Combined output, with every secret value replaced. */
+    log: string;
+    durationMs: number;
+}
+export interface RunResult {
+    pipeline: string;
+    ok: boolean;
+    /** How the machine authenticated itself for this run. Recorded, not inferred. */
+    assurance: 'attested' | 'enrolled';
+    steps: readonly StepResult[];
+}
+export declare class PipelineError extends Error {
+    readonly code: 'ATTESTATION_REQUIRED' | 'ATTESTATION_FAILED' | 'SECRET_MISSING';
+    constructor(code: 'ATTESTATION_REQUIRED' | 'ATTESTATION_FAILED' | 'SECRET_MISSING', message: string);
+}
+export interface RunOptions {
+    pipeline: Pipeline;
+    /** Reads one secret. The agent's replica, so this is a memory lookup. */
+    secret(name: string): Promise<string>;
+    /** Spawns a step. Injected, so a pipeline is testable without a shell. */
+    exec(input: {
+        command: string;
+        env: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    /**
+     * Produces a hardware report, or throws. The agent's `attest` operation,
+     * which REFUSES when no source is configured rather than returning something
+     * attestation-shaped.
+     */
+    attest?: () => Promise<{
+        report: string;
+        source: string;
+    }>;
+    now?: () => number;
+}
+/**
+ * Replace every secret value wherever it appears.
+ *
+ * Longest first, so a value that contains another value does not leave the
+ * shorter one's suffix exposed after the longer one is replaced.
+ */
+export declare function redact(text: string, values: readonly string[]): string;
+export declare function runPipeline(options: RunOptions): Promise<RunResult>;

package/dist/pipeline.js

@@ -0,0 +1,81 @@
+// src/pipeline.ts
+class PipelineError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PipelineError";
+  }
+}
+function redact(text, values) {
+  let out = text;
+  for (const value of [...values].sort((a, b) => b.length - a.length)) {
+    if (value.length < 8)
+      continue;
+    out = out.split(value).join("••••redacted••••");
+  }
+  return out;
+}
+async function runPipeline(options) {
+  const now = options.now ?? (() => Date.now());
+  const { pipeline } = options;
+  let assurance = "enrolled";
+  if (options.attest) {
+    try {
+      await options.attest();
+      assurance = "attested";
+    } catch (cause) {
+      if (pipeline.requireAttestation) {
+        throw new PipelineError("ATTESTATION_FAILED", `${pipeline.name} requires attestation and this machine could not produce one: ${cause.message}`);
+      }
+    }
+  } else if (pipeline.requireAttestation) {
+    throw new PipelineError("ATTESTATION_REQUIRED", `${pipeline.name} requires attestation. This agent has no attestation source, so it cannot run it.`);
+  }
+  const steps = [];
+  let failed = false;
+  for (const step of pipeline.steps) {
+    if (failed && !step.always) {
+      steps.push({ name: step.name, outcome: "skipped", exitCode: null, log: "", durationMs: 0 });
+      continue;
+    }
+    const env = {};
+    const values = [];
+    for (const name of step.secrets ?? []) {
+      try {
+        const value = await options.secret(name);
+        env[name] = value;
+        values.push(value);
+      } catch {
+        throw new PipelineError("SECRET_MISSING", `step "${step.name}" needs ${name}, which is not in this compute's scope.`);
+      }
+    }
+    const started = now();
+    let exitCode;
+    let output;
+    try {
+      const result = await options.exec({ command: step.run, env, timeoutMs: step.timeoutMs });
+      exitCode = result.exitCode;
+      output = result.output;
+    } catch (cause) {
+      exitCode = -1;
+      output = cause.message;
+    }
+    const outcome = exitCode === 0 ? "ok" : "failed";
+    if (outcome === "failed")
+      failed = true;
+    steps.push({
+      name: step.name,
+      outcome,
+      exitCode,
+      log: redact(output, values),
+      durationMs: now() - started
+    });
+  }
+  return { pipeline: pipeline.name, ok: !failed, assurance, steps };
+}
+export {
+  runPipeline,
+  redact,
+  PipelineError
+};

package/dist/pipeline.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/provision.d.ts

@@ -0,0 +1,117 @@
+/**
+ * How a machine becomes one that can run the agent — as DATA, with no transport.
+ *
+ * There are two ways this ever happens and they must not be two implementations:
+ *
+ *   fz agent install    an operator, on the box, executing locally
+ *   the platform        enrolling a compute, executing the same steps over SSH
+ *
+ * So nothing here connects to anything. A check is a command string plus a
+ * predicate over its output; a plan is an ordered list of them. `fz` runs them
+ * with `Bun.spawn`, the control plane runs them through an SSH session, and
+ * because it is the same list, a machine provisioned by hand and one provisioned
+ * by the platform end up identical.
+ *
+ * This was briefly two implementations — a `Check`-based preflight inside the
+ * API that could run remotely, and a separate local-only planner in the CLI that
+ * called `existsSync` directly and could not. Two answers to "is this box ready"
+ * is one answer nobody can trust, and the local one would have been the one that
+ * drifted, because it is the one somebody runs while debugging.
+ *
+ * ## Every command must be non-interactive and repeatable
+ *
+ * Non-interactive because there is nobody at the terminal on the SSH path, and a
+ * prompt there does not fail — it HANGS, which is much worse. Repeatable because
+ * enrolment is retried: a half-provisioned box that cannot be re-provisioned is
+ * a box somebody rebuilds by hand.
+ */
+export interface Check {
+    /** Run over SSH or locally. Must be non-interactive and safe to repeat. */
+    command: string;
+    /** True when the output proves the property. */
+    satisfied: (stdout: string, exitCode: number) => boolean;
+    /** Shown when it fails. Says what to do, not merely what is wrong. */
+    remedy: string;
+}
+/**
+ * Semver-ish floor check tolerant of `v` prefixes and build suffixes.
+ *
+ * Version output is not a standard. `v1.2.3`, `1.2.3-rc1` and
+ * `bun 1.2.3 (abc123)` all mean the same thing to a human and nothing to a
+ * naive comparison, and a preflight that rejects a good box is a preflight
+ * people learn to skip.
+ */
+export declare function atLeast(version: string, floor: string): boolean;
+export type AgentMode = 'attested' | 'enrolled';
+/**
+ * What the machine can prove about itself.
+ *
+ * Expressed as checks rather than as filesystem calls precisely so the answer is
+ * the same whether it was gathered on the box or over SSH. A control plane that
+ * decided `attested` from something it could only observe locally would be
+ * deciding it from nothing at all.
+ */
+export declare const CAPABILITY_CHECKS: Record<string, Check> & {
+    snpGuest: Check;
+    systemd: Check;
+    bun: Check;
+};
+export type CapabilityId = 'snpGuest' | 'systemd' | 'bun';
+/** The answers, however they were gathered. */
+export type Capabilities = Record<CapabilityId, boolean>;
+/**
+ * Which posture the agent runs in.
+ *
+ * Derived, never chosen. An operator picking `attested` would make attestation
+ * a claim, and a claim is the one thing an attestation must not be.
+ */
+export declare const modeFor: (capabilities: Pick<Capabilities, "snpGuest">) => AgentMode;
+export declare const reasonFor: (mode: AgentMode) => string;
+export interface UnitOptions {
+    mode: AgentMode;
+    socketPath: string;
+    seedPath: string;
+    /** Where `fz-agent` ended up. `bun add -g` puts it on PATH. */
+    binPath?: string;
+    user?: string;
+    apiUrl?: string;
+    project?: string;
+    environment?: string;
+}
+/**
+ * A systemd unit for the agent.
+ *
+ * The hardening is not decoration. This process holds a node signing key and a
+ * project-scoped vault replica in memory, so the two things worth spending
+ * effort on are keeping that memory out of a core dump and keeping the
+ * filesystem read-only.
+ */
+export declare function agentUnit(options: UnitOptions): string;
+export interface Step {
+    /** Shell, non-interactive, safe to repeat. */
+    command: string;
+    /** What it is for, in an operator's words. */
+    label: string;
+    /** A step that may fail without failing the provision. */
+    optional?: boolean;
+}
+export interface ProvisionPlan {
+    mode: AgentMode;
+    reason: string;
+    unitPath: string;
+    unit: string;
+    socketPath: string;
+    user: string;
+    steps: readonly Step[];
+}
+export declare const UNIT_PATH = "/etc/systemd/system/forgezero-agent.service";
+/**
+ * Everything that has to happen, in order, on a machine that is going to run
+ * the agent.
+ *
+ * The last two steps are the reason this is not just "write a file and start
+ * it". A unit that starts and immediately exits is `enabled` and
+ * `active (exited)`, which reads as success at a glance — so the plan checks the
+ * service is running AND that the socket applications actually need exists.
+ */
+export declare function planProvision(options: UnitOptions): ProvisionPlan;

package/dist/provision.js

@@ -0,0 +1,128 @@
+// src/provision.ts
+function atLeast(version, floor) {
+  const parse = (value) => (value.trim().replace(/^v/, "").match(/\d+/g) ?? []).slice(0, 3).map(Number);
+  const got = parse(version);
+  const want = parse(floor);
+  if (got.length === 0)
+    return false;
+  for (let index = 0;index < want.length; index += 1) {
+    const a = got[index] ?? 0;
+    const b = want[index] ?? 0;
+    if (a > b)
+      return true;
+    if (a < b)
+      return false;
+  }
+  return true;
+}
+var CAPABILITY_CHECKS = {
+  snpGuest: {
+    command: "test -e /dev/sev-guest && echo yes || echo no",
+    satisfied: (stdout) => stdout.trim() === "yes",
+    remedy: "Not a confidential guest. The agent will run in `enrolled` mode, which is still stronger than an API key in the application."
+  },
+  systemd: {
+    command: "test -d /run/systemd/system && echo yes || echo no",
+    satisfied: (stdout) => stdout.trim() === "yes",
+    remedy: "systemd is what supervises the agent. On a non-systemd host, run `fz-agent` under whatever supervises services there."
+  },
+  bun: {
+    command: "bun --version 2>/dev/null || echo missing",
+    satisfied: (stdout) => atLeast(stdout, "1.1.0"),
+    remedy: "Install bun: curl -fsSL https://bun.sh/install | bash"
+  }
+};
+var modeFor = (capabilities) => capabilities.snpGuest ? "attested" : "enrolled";
+var reasonFor = (mode) => mode === "attested" ? "SEV-SNP guest device present, so the agent can prove what it is running and the platform can refuse it if the measurement is wrong." : "No SEV-SNP guest device. The agent authenticates with its enrolment token and hybrid Ed25519 + ML-DSA signature — weaker than attestation, stronger than an API key in the application.";
+function agentUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  const user = options.user ?? "forgezero";
+  const environment = [
+    `FZ_SOCKET_PATH=${options.socketPath}`,
+    `FZ_SEED_PATH=${options.seedPath}`,
+    `FZ_AGENT_MODE=${options.mode}`,
+    options.apiUrl ? `FZ_API=${options.apiUrl}` : null,
+    options.project ? `FZ_PROJECT=${options.project}` : null,
+    options.environment ? `FZ_ENVIRONMENT=${options.environment}` : null
+  ].filter((line) => line !== null);
+  return `[Unit]
+Description=ForgeZero node agent (${options.mode})
+Documentation=https://forgezero.net/docs/agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+Group=${user}
+ExecStart=${bin}
+Restart=always
+RestartSec=2
+
+${environment.map((line) => `Environment=${line}`).join(`
+`)}
+
+# The node seed and the vault replica live in this process's memory. A core dump
+# writes both to disk, which is the one artefact this design exists to remove.
+LimitCORE=0
+
+# The socket is the entire interface: anything that can read it can read the
+# scope. So it lives in a directory systemd creates with a known owner rather
+# than wherever the process happened to have write access.
+RuntimeDirectory=forgezero
+RuntimeDirectoryMode=0710
+
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+ReadWritePaths=${options.seedPath.replace(/\/[^/]+$/, "")}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+var UNIT_PATH = "/etc/systemd/system/forgezero-agent.service";
+function planProvision(options) {
+  const mode = options.mode;
+  const user = options.user ?? "forgezero";
+  const seedDir = options.seedPath.replace(/\/[^/]+$/, "");
+  return {
+    mode,
+    reason: reasonFor(mode),
+    unitPath: UNIT_PATH,
+    unit: agentUnit({ ...options, mode }),
+    socketPath: options.socketPath,
+    user,
+    steps: [
+      {
+        label: "service account",
+        command: `useradd --system --no-create-home --shell /usr/sbin/nologin ${user} || true`
+      },
+      {
+        label: "seed directory",
+        command: `install -d -o ${user} -g ${user} -m 0700 ${seedDir}`
+      },
+      { label: "reload units", command: "systemctl daemon-reload" },
+      { label: "enable and start", command: "systemctl enable --now forgezero-agent.service" },
+      { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
+      { label: "prove the socket exists", command: `test -S ${options.socketPath}` }
+    ]
+  };
+}
+export {
+  reasonFor,
+  planProvision,
+  modeFor,
+  atLeast,
+  agentUnit,
+  UNIT_PATH,
+  CAPABILITY_CHECKS
+};

package/dist/socket.d.ts

@@ -0,0 +1,163 @@
+import { type Server } from 'node:net';
+import { signRequest, type NodeKeyPair } from '@forgezero/runtime/identity';
+import { type Pipeline, type RunResult, type RunOptions } from './pipeline';
+import type { SecretCache } from './cache';
+/**
+ * The signing socket — why the application on managed compute holds nothing.
+ *
+ * `@forgezero/vault` discovers `/run/forgezero.sock` and prefers it over
+ * `FORGEZERO_API_KEY`, so moving an app onto managed compute is DELETING an
+ * environment variable. That only means anything if something is listening, and
+ * for a long time nothing was: the client knew how to prefer the socket and the
+ * agent was a version constant.
+ *
+ * ## The key never leaves
+ *
+ * There is no `getKey` operation and there is deliberately no way to add one:
+ * the socket signs, and signing is all it does. An application that could ask
+ * for the key is an application that holds the key the moment it is compromised,
+ * which is the entire difference between this and an API key in the environment.
+ *
+ * ## Why a signature and not a token
+ *
+ * A token would have to be handed to the caller, which puts it in a process we
+ * do not control, in memory we do not own, for as long as the process lives. A
+ * signature is bound to one method, one path and one body digest by
+ * `canonicalString`, so a caller that captures one cannot reuse it for anything
+ * else — and it expires with the clock-skew window rather than with the process.
+ *
+ * ## Peer credentials, not a shared secret
+ *
+ * Access control is the filesystem's: the socket is created 0600, owned by the
+ * user the agent runs as, and only that user's processes can connect. A token
+ * checked over the socket would have to live somewhere both sides can read,
+ * which is the problem this exists to remove rather than a solution to it.
+ */
+export declare class AgentError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** One line of JSON in, one line of JSON out. */
+export type Request = {
+    op: 'identity';
+} | {
+    op: 'sign';
+    method: string;
+    path: string;
+    query?: string;
+    body?: string;
+} | {
+    op: 'attest';
+    nonce?: string;
+} | {
+    op: 'get';
+    name: string;
+} | {
+    op: 'sync';
+} | {
+    op: 'held';
+} | {
+    op: 'run';
+    pipeline: Pipeline;
+};
+export type Response = {
+    ok: true;
+    op: 'identity';
+    nodeKey: string;
+    publicKeys: NodeKeyPair['ed25519'] & {
+        mlDsa: string;
+    };
+} | {
+    ok: true;
+    op: 'sign';
+    envelope: ReturnType<typeof signRequest>;
+} | {
+    ok: true;
+    op: 'attest';
+    report: string;
+    source: string;
+} | {
+    ok: true;
+    op: 'get';
+    value: string;
+} | {
+    ok: true;
+    op: 'sync';
+    invalidated: string[];
+    cursor: number;
+    resync: boolean;
+} | {
+    ok: true;
+    op: 'held';
+    names: string[];
+    staleForMs: number;
+} | {
+    ok: true;
+    op: 'run';
+    result: RunResult;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * Produces a hardware attestation report for this guest.
+ *
+ * Injected rather than implemented here, and ABSENT by default. A SEV-SNP report
+ * is only meaningful if something verifies it against a measurement and a
+ * freshness window, and the freshness window is an open architectural question
+ * in this repo — `architecture.ts` carries it as `status: 'open'`. Inventing a
+ * number would produce a check that looks like attestation and is not one.
+ *
+ * So with no source configured, `attest` REFUSES. It does not return an empty
+ * report, and it does not silently succeed: a caller that believes it verified
+ * an attestation when nothing did is worse off than one told plainly that
+ * attestation is unavailable here.
+ */
+export interface AttestationSource {
+    readonly name: string;
+    report(nonce: string): Promise<string>;
+}
+export interface AgentOptions {
+    socketPath: string;
+    keys: NodeKeyPair;
+    /** The node's identifier, as the platform knows it. */
+    nodeKey: string;
+    attestation?: AttestationSource;
+    /**
+     * Runs a pipeline step. ABSENT by default, and that is the security posture.
+     *
+     * An agent that can execute arbitrary commands is a remote shell with a vault
+     * attached. Shipping one on by default would mean every compute that installs
+     * the agent for its secrets also accepts remote execution, which is not the
+     * trade anybody agreed to. An operator turns it on for the boxes that deploy.
+     */
+    exec?: RunOptions['exec'];
+    /**
+     * Secrets, cached in memory on this guest.
+     *
+     * Optional: an agent that only signs is a complete agent, and a box with no
+     * project bound to it has nothing to cache. When absent, `get` says so rather
+     * than returning nothing — an application that receives an empty value for a
+     * database URL fails somewhere far from here.
+     */
+    cache?: SecretCache;
+    /** Every request, for the hash-chained journal. */
+    record?: (entry: {
+        op: string;
+        outcome: 'ok' | 'refused';
+        detail?: string;
+    }) => void;
+}
+export declare function handleRequest(options: AgentOptions, request: Request): Promise<Response>;
+/**
+ * Listen, with the socket file replaced rather than reused.
+ *
+ * A stale socket from a killed process makes `listen` fail with EADDRINUSE, and
+ * an agent that will not start after an unclean shutdown is an outage that needs
+ * a human. The file is unlinked first — safe because only one agent runs per
+ * guest, and a live one would be holding the path.
+ */
+export declare function startAgent(options: AgentOptions): Server;

package/dist/socket.test.d.ts

@@ -0,0 +1 @@
+export {};