@amenophis1er/foreman 0.1.0

package/src/types.ts

@@ -0,0 +1,442 @@
+/**
+ * Shared types for Foreman's orchestrator, persistence, and HTTP layer.
+ *
+ * Everything the UI sees flows through {@link ForemanEvent}: each event is
+ * broadcast to connected SSE clients *and* appended to the run's event log,
+ * so replaying a log reproduces exactly what a live client observed.
+ */
+
+export type RunStatus = 'running' | 'done' | 'error' | 'interrupted';
+
+/** A linked project — a folder Foreman runs missions in. */
+export interface Project {
+  id: string;
+  /** Display name; defaults to the folder's basename. */
+  name: string;
+  /** Absolute path of the working directory. */
+  folder: string;
+  createdAt: number;
+  /** Default budget suggested in the composer. */
+  defaultBudgetUsd: number;
+  /**
+   * Who serves and who pays. Absent means the legacy `claudeInstance` below
+   * (or the server default) — see providerOf() in provider.ts.
+   */
+  provider?: ProviderRef;
+  /** @deprecated Pre-provider pin. Read through providerOf(); never written. */
+  claudeInstance?: ClaudeInstanceRef;
+}
+
+/**
+ * @deprecated The pre-provider shape, still read from records written before
+ * {@link ProviderRef} existed. Never written. See providerFromLegacy().
+ */
+export interface ClaudeInstanceRef {
+  /** CLAUDE_CONFIG_DIR for the agent. */
+  configDir?: string;
+  /** Claude Code executable; the SDK's bundled one when absent. */
+  executable?: string;
+  /**
+   * Who pays for this project's missions.
+   *  - `inherit` (default): whatever the server process authenticates as. An
+   *    ANTHROPIC_API_KEY in the server environment outranks any stored login,
+   *    so every project bills that key.
+   *  - `own-login`: strip inherited API-key credentials from the agent's
+   *    environment so the pinned config dir's own stored login pays. This is
+   *    what makes per-project accounts work on a single shared server.
+   */
+  billing?: 'inherit' | 'own-login';
+}
+
+/**
+ * Who serves the model, who pays for it, and where requests go — one choice,
+ * not three settings. See src/provider.ts and docs/provider-model.md; the
+ * union shape is what makes "subscription login + custom base URL", the
+ * combination that leaks a token, unrepresentable.
+ */
+export type ProviderRef =
+  /** An installed Claude Code, using whatever it is logged into. Ambient. */
+  | {
+      kind: 'claude-code';
+      /** CLAUDE_CONFIG_DIR; the server default when absent. */
+      configDir?: string;
+      /** Claude Code executable; the SDK's bundled one when absent. */
+      executable?: string;
+      /** Strip inherited key credentials so this install's own login pays. */
+      ownLogin?: boolean;
+    }
+  /** An Anthropic API key Foreman is told about by name, never by value. */
+  | {
+      kind: 'anthropic-api';
+      /** Stable id; names this provider's Foreman-owned config dir. */
+      id: string;
+      /** Server environment variable holding the key. Foreman stores no secrets. */
+      apiKeyEnv: string;
+      model?: string;
+    }
+  /** An installed Codex CLI, using the login `codex login` already stored. */
+  | {
+      kind: 'codex';
+      id: string;
+      /** CODEX_HOME; `~/.codex` when absent. */
+      codexHome?: string;
+      /** Codex inference backend; the public one when absent. */
+      upstreamUrl?: string;
+      model?: string;
+    }
+  /** Anything speaking OpenAI Chat Completions: Ollama, OpenRouter, vLLM, … */
+  | {
+      kind: 'openai-compatible';
+      id: string;
+      baseUrl: string;
+      /**
+       * Name of a server environment variable holding the key. The fallback
+       * when nothing is stored for this provider; omit it entirely to use a
+       * stored key alone.
+       */
+      apiKeyEnv?: string;
+      /**
+       * This endpoint requires a credential. Distinguishes "a key is stored
+       * for it" from "it needs none at all" — a local Ollama is the latter,
+       * and inferring from the absence of `apiKeyEnv` would make every stored
+       * key look like no key.
+       */
+      needsKey?: boolean;
+      /** Short name for badges — "Ollama", "OpenRouter". */
+      label?: string;
+      model?: string;
+    };
+
+export type WorkerStatus = 'running' | 'done' | 'error';
+
+/** Persisted, replayable event envelope. */
+export interface ForemanEvent {
+  /** Milliseconds since epoch, assigned at emit time. */
+  ts: number;
+  /** SSE event name; the UI switches on this. */
+  event: string;
+  /** JSON-serializable payload; shape depends on `event`. */
+  data: unknown;
+}
+
+/**
+ * What a run's spend *is* — which is a different question from how much.
+ *
+ * A boolean `metered` used to carry this, and it collapsed two states that
+ * are not the same thing at all: a local model that costs nothing and an
+ * OpenAI key that costs real money Foreman holds no price table for both
+ * answered `false`, and rendered identically. "You are spending nothing" and
+ * "you are spending an amount I cannot tell you" are different sentences to
+ * put in front of someone, and only one of them is a reason to go and look at
+ * a vendor's dashboard.
+ *
+ *  - `priced`   — the dollar figure is the real one. Dollars are displayed,
+ *                 and the budget cap binds.
+ *  - `free`     — nothing is charged per token; the model runs on hardware
+ *                 the operator already owns. Tokens and turns are the only
+ *                 true units.
+ *  - `unpriced` — real spend, of an amount Foreman cannot state: a paid
+ *                 endpoint with no price source, or a subscription allowance
+ *                 being consumed. Shown in tokens and turns like `free`, but
+ *                 said out loud to be untracked rather than passed off as
+ *                 costing nothing.
+ *
+ * Only `priced` may display or enforce dollars. `free` and `unpriced` differ
+ * in what they say and never in what they enforce — which is why this is
+ * three states and not four: the fourth distinction people reach for
+ * (subscription vs. pay-as-you-go) changes no behaviour here, and the
+ * provider label already carries it in words.
+ */
+export type CostBasis = 'priced' | 'free' | 'unpriced';
+
+/**
+ * A run's cost basis, including for runs that predate the field.
+ *
+ * The old `metered: false` meant "not priceable", which is the union of
+ * `free` and `unpriced` — so it cannot be split after the fact. This reads it
+ * as `unpriced`, because of the two possible errors, describing real spend as
+ * free is the one that costs somebody money.
+ */
+export function costBasisOf(meta: { costBasis?: CostBasis; metered?: boolean }): CostBasis {
+  if (meta.costBasis) return meta.costBasis;
+  return meta.metered === false ? 'unpriced' : 'priced';
+}
+
+/**
+ * One cost basis for a run whose two roles may not share one.
+ *
+ * `priced` wins outright: if any part of the run bills real dollars, the
+ * dollar cap must still arm, because the alternative is an uncapped run
+ * spending genuine money. It is not a *precise* figure on a mixed run — the
+ * SDK prices the gateway role's tokens with Anthropic's table too, so the
+ * total overstates — but overstating a real bill is a safe error in a way
+ * that ignoring one is not. A per-role price table is what fixes it properly.
+ *
+ * Otherwise `unpriced` beats `free`, on the same principle that decides a
+ * single provider: never call a run free when part of it is not.
+ */
+export function combineBasis(a: CostBasis, b: CostBasis): CostBasis {
+  if (a === 'priced' || b === 'priced') return 'priced';
+  if (a === 'unpriced' || b === 'unpriced') return 'unpriced';
+  return 'free';
+}
+
+/** Whether dollars may be displayed or enforced at all. The one real branch. */
+export function isPriced(meta: { costBasis?: CostBasis; metered?: boolean }): boolean {
+  return costBasisOf(meta) === 'priced';
+}
+
+/**
+ * Real token usage. `costUsd` is notional on a subscription plan and
+ * fictional through a gateway (the SDK prices foreign tokens with
+ * Anthropic's rate table) — token counts are what actually moved on any
+ * provider, so this is what an unmetered run's meter should show instead of
+ * a dollar figure nobody billed.
+ */
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+
+/** Snapshot of one worker, persisted in run metadata. */
+export interface WorkerMeta {
+  id: string;
+  status: WorkerStatus;
+  costUsd: number;
+  sessionId?: string;
+  /** First 500 chars of the task brief, for run-history display. */
+  task: string;
+  /**
+   * The worker's final report, kept on the record rather than handed back
+   * once and forgotten: spawning is asynchronous, so the director reads
+   * results through check_workers / wait_for_worker — possibly more than
+   * once, possibly after a restart — and a report that lived only in a
+   * returned promise would be gone by then.
+   */
+  report?: string;
+  isError?: boolean;
+  startedAt?: number;
+  endedAt?: number;
+  /** Last SDK message seen; what "seconds since last activity" is measured from. */
+  lastActivityAt?: number;
+  toolCalls?: number;
+  /**
+   * Rolling window of the last few activity lines (tool name + a short arg
+   * hint, or the head of an assistant message). The director cannot see a
+   * worker's transcript; this is the glance that tells "reading tests" apart
+   * from "re-running the same failing command".
+   */
+  recent?: string[];
+  /**
+   * The worker's own account of where it is, from its report_progress tool.
+   * Kept apart from `recent` because the two answer different questions:
+   * `recent` is what the harness saw the worker call, this is what the
+   * worker says it is doing and how far along it is — the only signal that
+   * tells "two of three files written, stuck on the third" from flailing.
+   * Latest report wins; `at` dates it so a stale one reads as stale.
+   */
+  progress?: WorkerProgress;
+}
+
+/** One report_progress call, as stored on the record and sent to the UI. */
+export interface WorkerProgress {
+  /** One-line summary, capped at 200 chars by the tool. */
+  status: string;
+  done?: string[];
+  next?: string;
+  blocked?: string;
+  at: number;
+}
+
+/**
+ * Model for an agent: a harness alias (opus/sonnet/haiku), a full claude-*
+ * model id, or `undefined` to inherit the harness default.
+ */
+export type ModelChoice = string | undefined;
+
+/** Per-tool decision applied before any prompt is considered. */
+export type ToolPolicy = Record<string, 'allow' | 'ask' | 'deny'>;
+
+/** Persisted run metadata (meta.json). Small, rewritten atomically on change. */
+export interface RunMeta {
+  /** Effective tool policy, snapshotted from Settings at run start. */
+  toolPolicy?: ToolPolicy;
+  /** Whether read-only tools run silently (Settings; default true). */
+  autoAllowReadOnly?: boolean;
+  id: string;
+  /**
+   * Short generated name for the mission, from one cheap model call at start.
+   * Absent when the call failed or the run predates titling — the UI falls
+   * back to the brief, so nothing depends on this being here.
+   */
+  title?: string;
+  /** Owning project; absent on runs recorded before projects existed. */
+  projectId?: string;
+  /** Model override for the director session. */
+  directorModel?: ModelChoice;
+  /** Model override for worker sessions (cost lever). */
+  workerModel?: ModelChoice;
+  /**
+   * Provider serving each role, when it differs from the run's own.
+   *
+   * A model carries the provider that serves it, so a run can put a capable
+   * director on one and cheap workers on another — the configuration the
+   * whole provider model exists to make possible. Absent means "the run's
+   * provider", which is every run recorded before this existed.
+   */
+  directorProviderId?: string;
+  workerProviderId?: string;
+  /**
+   * Provider frozen at dispatch, so history and resume agree — and so a later
+   * settings change cannot move an in-flight or resumed run to another
+   * provider, or another bill.
+   */
+  provider?: ProviderRef;
+  /** @deprecated Pre-provider pin, still read for runs recorded before providers. */
+  claudeInstance?: ClaudeInstanceRef;
+  /** Number of times this run was resumed after an interruption. */
+  resumes?: number;
+  /** Tools the human granted "always allow" for this run (survives resume). */
+  allowedTools?: string[];
+  /**
+   * Absolute directories the human opened for this run by approving "always"
+   * on a folder-boundary card (see `PendingPermission.escapedPath`). Paths
+   * under them count as inside the mission folder. Persisted beside
+   * `allowedTools` for the same reason: a resume must not re-ask what the
+   * human already answered.
+   */
+  allowedRoots?: string[];
+  /** Dev servers the crew exposed through Foreman's proxy (see services.ts). */
+  services?: Array<{ port: number; label: string; path: string; since: number }>;
+  /**
+   * How long an approval card or director question may wait for the human
+   * before it is resolved with its unattended default (deny / "decide
+   * yourself"). Absent means the orchestrator's default; 0 disables the timer
+   * for a run someone intends to babysit.
+   */
+  askTimeoutMs?: number;
+  /** Give agents a headless Playwright browser (navigate, click, screenshot). */
+  browserTools?: boolean;
+  folder: string;
+  mission: string;
+  budgetUsd: number;
+  /**
+   * What this run's spend *is* — see {@link CostBasis}. Absent on runs
+   * recorded before the split; read it through {@link costBasisOf}, never
+   * directly, so those runs keep answering.
+   */
+  costBasis?: CostBasis;
+  /**
+   * @deprecated Superseded by {@link costBasis}, which distinguishes the two
+   * states this boolean collapsed. Still read for runs recorded before the
+   * split, and still written beside `costBasis` so a downgrade is survivable.
+   * Nothing new should branch on it.
+   */
+  metered?: boolean;
+  /** Director turns before the run winds down. Universal; provider-independent. */
+  maxTurns?: number;
+  /** Wall-clock cap. Matters most exactly where dollars matter least. */
+  maxSeconds?: number;
+  /**
+   * How long a worker may produce nothing before it is treated as stalled and
+   * stopped. Absent means the orchestrator's default. Raise it for slow local
+   * models whose first token legitimately takes minutes.
+   */
+  workerSilenceMs?: number;
+  status: RunStatus;
+  costUsd: number;
+  /**
+   * Where `costUsd` came from, kept apart so a resume adds to the right
+   * pile: `native` is the SDK's own figure for Anthropic-native roles,
+   * `rated` is gateway tokens priced from published or listed rates, and
+   * `ledger` is what a gateway upstream itself reported per response. When
+   * the upstream reports, its number outranks the rated one for the same
+   * tokens — the party that sends the bill wins.
+   */
+  costParts?: { native: number; rated: number; ledger: number };
+  /**
+   * Token counts accumulated from every director and worker `result`
+   * message's `usage` object. Absent on runs recorded before this landed.
+   */
+  usage?: TokenUsage;
+  /**
+   * Director turns taken so far, persisted so a resumed run keeps counting
+   * against {@link maxTurns} instead of restarting the cap from zero — the
+   * orchestrator's private counter is only ever accurate within one process.
+   */
+  turns?: number;
+  createdAt: number;
+  endedAt?: number;
+  directorSessionId?: string;
+  workers: WorkerMeta[];
+}
+
+/** Listing entry returned by GET /runs (meta without heavy fields). */
+export type RunSummary = RunMeta;
+
+/**
+ * A project's planning conversation — the talk that happens before a mission.
+ *
+ * Only the session id and the running tally are kept here; the conversation
+ * itself is the append-only event log beside this file, exactly like a run's.
+ * There is no process behind it: each turn resumes the stored session and
+ * exits, so an idle conversation costs nothing but disk.
+ */
+export interface ChatMeta {
+  projectId: string;
+  /** Claude Code session to resume; absent until the first turn completes. */
+  sessionId?: string;
+  /** Everything this conversation has cost, for the whole of its life. */
+  costUsd: number;
+  createdAt: number;
+  updatedAt: number;
+  /** The most recent mission the planner proposed, if it has not been used. */
+  proposal?: MissionProposal;
+}
+
+/** A mission the planner drafted, waiting for the human to start or discard. */
+export interface MissionProposal {
+  id: string;
+  /** The brief, ready to go into the composer. */
+  mission: string;
+  /** Verifiable completion criteria, shown as a checklist. */
+  doneWhen: string[];
+  /** What the planner thinks it should cost. The human always sees it. */
+  budgetUsd: number;
+  /** Why this budget and this shape — one short paragraph. */
+  rationale?: string;
+  /**
+   * The planner judged the DONE WHEN criteria need a browser (a page must
+   * load, render, be console-clean or be screenshotted). The card starts with
+   * the switch on. Absent means "the planner did not say", not "no".
+   */
+  browser?: boolean;
+  /**
+   * The planner's model recommendations, already validated against the
+   * machine's list — an id it could not have picked from the list is dropped
+   * and the role inherits. The card pre-selects these; the human can change
+   * them. `modelRationale` is the planner's one line on why, shown beside
+   * the pickers so the choice reads as a suggestion with a reason, not a
+   * setting that appeared.
+   */
+  directorModel?: string;
+  workerModel?: string;
+  directorProviderId?: string;
+  workerProviderId?: string;
+  modelRationale?: string;
+  createdAt: number;
+}
+
+/** Result of a permission decision made by the human. */
+export type PermissionDecision = 'allow' | 'allow_always' | 'deny';
+
+/** Free-form UI settings blob (shape owned by the design system's modal). */
+export type SettingsValues = Record<string, unknown>;
+
+/** Persisted settings: global values + sparse per-project overlays. */
+export interface SettingsFile {
+  global: SettingsValues;
+  projects: Record<string, SettingsValues>;
+}

package/ui/dist/assets/index-LAj0Dy9p.css

@@ -0,0 +1 @@
+@import"https://fonts.googleapis.com/css2?family=Source+Sans+3:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap";:root{color-scheme:dark;--bg-app: #121417;--bg-panel: #1a1d22;--bg-card: #22262d;--bg-inset: #14161a;--bg-hover: #1e2228;--line: #2d323b;--line-strong: #3a4048;--ink-0: #e8e6df;--ink-1: #a7afb9;--ink-2: #6d7683;--brand: #e8b04b;--brand-ink: #14161a;--agent-director: var(--brand);--agent-worker: #9c86e8;--agent-worker-1: #9c86e8;--agent-worker-2: #7f9ff0;--agent-worker-3: #c48be0;--agent-worker-4: #b3a6f2;--agent-worker-5: #7a72d8;--agent-worker-6: #d19ac8;--status-good: #3fb950;--status-warning: #fab219;--status-serious: #ec835a;--status-critical: #e5484d;--brand-wash: rgba(232, 176, 75, .06);--brand-wash-strong: rgba(232, 176, 75, .12);--scrim: rgba(0, 0, 0, .55);--diff-add-bg: rgba(63, 185, 80, .12);--diff-del-bg: rgba(229, 72, 77, .12)}[data-theme=light]{color-scheme:light;--bg-app: #ecebe6;--bg-panel: #f6f5f1;--bg-card: #ffffff;--bg-inset: #e4e2db;--bg-hover: #f0efea;--line: #d9d6cd;--line-strong: #c2beb2;--ink-0: #1c1e22;--ink-1: #555c67;--ink-2: #7b828d;--brand: #c98f1f;--brand-ink: #ffffff;--agent-worker: #6f57d6;--agent-worker-1: #6f57d6;--agent-worker-2: #4a6fdc;--agent-worker-3: #a35bc9;--agent-worker-4: #8a78e0;--agent-worker-5: #5449b8;--agent-worker-6: #b3609e;--status-good: #1f8f3a;--status-warning: #b8790a;--status-serious: #c4592c;--status-critical: #c8323a;--brand-wash: rgba(201, 143, 31, .08);--brand-wash-strong: rgba(201, 143, 31, .16);--scrim: rgba(20, 22, 26, .45);--diff-add-bg: rgba(31, 143, 58, .12);--diff-del-bg: rgba(200, 50, 58, .12)}:root{--font-ui: "Source Sans 3", ui-sans-serif, system-ui, -apple-system, sans-serif;--font-mono: "IBM Plex Mono", ui-monospace, "SF Mono", Menlo, monospace;--ui-scale: 1;--fs-xs: .75rem;--fs-sm: .8125rem;--fs-md: .9375rem;--fs-lg: 1.0625rem;--fs-xl: 1.25rem;--lh: 1.45;--lh-prose: 1.55;--fw-regular: 400;--fw-medium: 500;--fw-semibold: 600;--ls-caps: .08em;--icon-sm: 14px;--icon-md: 16px;--icon-lg: 20px;--icon-stroke: 1.75}:root{--sp-1: 4px;--sp-2: 8px;--sp-3: 12px;--sp-4: 16px;--sp-5: 24px;--r-sm: 6px;--r-md: 10px;--r-pill: 999px;--rail-left: 15.625rem;--rail-right: 21.25rem;--bp-narrow: 900px;--bp-medium: 1180px;--fleet-max: 75rem;--composer-max: 45rem;--spine-max: 62rem;--card-min: 18.75rem;--card-min-h: 8.125rem;--modal-w: 30rem;--modal-w-wide: 32.5rem;--accent-w: 3px;--meter-h: 4px;--dot: 8px;--dot-sm: 6px;--focus: 0 0 0 2px var(--bg-app), 0 0 0 4px var(--brand)}:root{--dur-fast: .12s;--dur-meter: .3s;--dur-pulse: 1.6s;--ease: ease-in-out}@keyframes pulse{0%,to{opacity:1}50%{opacity:.55}}.pulse{animation:pulse var(--dur-pulse) var(--ease) infinite}@keyframes ticker-in{0%{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}.ticker{animation:ticker-in var(--dur-fast, .15s) var(--ease) both}:root{--surface-app: var(--bg-app);--surface-panel: var(--bg-panel);--surface-card: var(--bg-card);--surface-inset: var(--bg-inset);--surface-overlay: var(--bg-panel);--border-subtle: var(--line);--border-strong: var(--line-strong);--text-body: var(--ink-0);--text-secondary: var(--ink-1);--text-muted: var(--ink-2);--text-on-brand: var(--brand-ink);--text-accent: var(--brand);--text-danger: var(--status-critical);--intent-primary: var(--brand);--intent-affirm: var(--status-good);--intent-deny: var(--status-critical);--intent-caution: var(--status-warning);--intent-degraded: var(--status-serious);--state-idle: var(--ink-2);--state-running: var(--status-good);--state-done: var(--status-good);--state-interrupted: var(--status-serious);--state-error: var(--status-critical)}*{box-sizing:border-box}html,body,#root{height:100%}html{font-size:calc(100% * var(--ui-scale))}body{margin:0;background:var(--bg-app);color:var(--ink-0);font:var(--fs-md)/var(--lh) var(--font-ui)}button,input,textarea,select{font:inherit;color:inherit}:is(button,input,textarea,select):focus-visible{outline:none;box-shadow:var(--focus)}a{color:var(--brand);text-decoration:none}a:hover{text-decoration:underline}::-webkit-scrollbar{width:10px;height:10px}::-webkit-scrollbar-thumb{background:var(--line-strong);border-radius:5px}::-webkit-scrollbar-track{background:transparent}