Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

6.9 KB
Raw Blame
/**
 * Identity of the running build and of this machine's harness store — what
 * `penguin version --json` prints and what GET /api/version returns.
 *
 * Deliberately not part of the interface contracts: this says nothing about the LLM or the
 * Environment, and no boundary of the agent loop carries it. Core's `buildInfo()` produces
 * the {@link BuildInfo} half; only a caller that knows which data root is in play can fill
 * the harness half.
 */

/**
 * Node and OS the build is executing on — the part of a build's identity that is a property
 * of the run rather than of the artifact.
 */
export interface BuildRuntimeInfo {
  /** `process.versions.node`. */
  node: string;
  /** `process.platform`. */
  platform: string;
  /** `process.arch`. */
  arch: string;
}

/**
 * Identity of the running build: everything `penguin version --json` prints and everything
 * GET /api/version returns. Both render this object without adding facts of their own, so a
 * report gathered over HTTP and one gathered at a shell are the same report.
 *
 * Produced by core's `buildInfo()`. Which fields carry information depends on `channel`: a
 * release knows its date and the commit it was built from, a source build knows its git
 * position instead.
 */
export interface BuildInfo {
  /** Dotted release number, from core's VERSION constant. Never null, never prefixed. */
  version: string;
  /**
   * The one-line human identity, and the whole of `penguin version`'s output: `v0.2.3` for a
   * release, and git's own description for a source build — `v0.2.3-14-g9e8f7d6-dirty` reads
   * as fourteen commits past v0.2.3, at 9e8f7d6, with uncommitted changes. Always begins
   * `v` followed by a digit, so any form reads as a version.
   *
   * Not necessarily `v{version}`: a tag description names the nearest reachable TAG, which
   * during release preparation is the previous one — `VERSION` is bumped in its own commit
   * and the new tag is created afterwards, so a build from that window truthfully reports
   * `v0.2.3-N-g…` while `version` already reads 0.2.4. Compare `version` when you mean the
   * release number and `describe` when you mean the position in history.
   */
  describe: string;
  /** `release` once the release workflow has stamped the build; `source` for every other build. */
  channel: "release" | "source";
  /** Release build date (UTC yyyy-mm-dd); null in a source build. */
  buildDate: string | null;
  /** Full commit sha this build came from; null when neither the stamp nor git supplied one. */
  commit: string | null;
  /** Branch checked out at build time; null for a release, and for a detached HEAD. */
  branch: string | null;
  /**
   * Whether tracked files differed from the commit. Null means the question does not apply
   * rather than "clean": a release stamps its constants into the tree before building, so
   * cleanliness is not a fact about release artifacts.
   */
  dirty: boolean | null;
  runtime: BuildRuntimeInfo;
}

/**
 * Where a hot update was pushed from, as the pusher recorded it. Provenance only: nothing
 * here is ever executed or resolved, and both fields are whatever the pushing client sent.
 */
export interface HarnessSource {
  /** The pushing checkout's origin remote, or its directory name when it has no remote. */
  repo: string;
  /** `git describe --tags --dirty` of the pushing checkout, spelled as {@link BuildInfo.describe}. */
  revision: string;
}

/**
 * What this machine's HMR store has committed — the harness code a hot update put there,
 * which a restart resumes. A property of the data root rather than of the running process:
 * it answers "which harness was pushed here", not "which code is executing".
 *
 * That distinction matters because the two can differ. `penguin` runs the packaged CLI
 * while `penguin-hmr` runs the store's; a server whose committed version failed to restore
 * warns and falls back to its packaged platform. Null in {@link VersionReport} means
 * nothing was ever pushed to this root.
 */
export interface HarnessInfo {
  /** Null for a version pushed by a client that recorded no provenance. */
  source: HarnessSource | null;
  /** When the version was committed to the store (ISO 8601); null if it predates the record. */
  pushedAt: string | null;
  /**
   * The committed artifacts' content-addressed pointers, relative to `<root>/hmr` — the
   * identity of the pushed code itself, independent of what the pusher claimed about it.
   */
  bundles: {
    platform: string | null;
    cli: string | null;
    web: string | null;
  };
}

/** What a stored interface table says about itself, without reading it. */
export interface IfacesSummary {
  hash: string;
  nodes: number;
  interfaces: number;
  types: number;
}

/**
 * What `penguin version --json` prints and what GET /api/version returns: the running
 * build's identity, plus the harness this machine has in its HMR store.
 *
 * The two halves come from different places and neither can supply the other. {@link
 * BuildInfo} describes the artifact this process is executing and core resolves it alone;
 * `harness` describes the data root's store, so only a caller that knows which root is in
 * play can fill it.
 */
/**
 * One harness version, as the platform that WAS that version recorded it at its boot: the
 * runtime's commit record (provenance, commit time, bundles) plus the interface table the
 * platform was built from. The runtime only commits; what was pushed is written by the
 * pushed code itself, so the record is complete on any runtime that can boot it.
 */
export interface HarnessHistoryEntry {
  /** The version's identity in the history: derived from its bundles (or its table, for a packaged boot). */
  id: string;
  /** Whether the platform kept this version's artifacts, so it can be pushed back. */
  rollbackable: boolean;
  source: HarnessSource | null;
  /** When the version was committed (ISO 8601); null for a commit that predates the record. */
  pushedAt: string | null;
  bundles: HarnessInfo["bundles"];
  ifaces: IfacesSummary | null;
}

/**
 * The harness versions that have booted on this data root, newest first, and the one the
 * runtime currently has committed. Kept by the platform under `<root>/harness-history/`,
 * apart from the runtime's store.
 */
export interface HarnessHistory {
  current: HarnessInfo | null;
  entries: HarnessHistoryEntry[];
  /**
   * The last push back the runtime refused, or null. A refused rollback leaves the platform
   * that asked for it running, so it is the one that can say why; a rollback that lands
   * replaces that platform, and the new one reports nothing here.
   */
  lastRollback: RollbackFailure | null;
}

/** Why a rollback did not happen, in the runtime's own words. */
export interface RollbackFailure {
  /** The version that was to be pushed back. */
  id: string;
  error: string;
  /** When the refusal came (ISO 8601). */
  at: string;
}

export interface VersionReport extends BuildInfo {
  harness: HarnessInfo | null;
}