@forgezero/agent 0.1.32 → 0.1.34

package/README.md

@@ -17,14 +17,17 @@ The one public package installs both commands. Keeping bootstrap and the daemon
 in one version prevents a newly installed `fz` from provisioning a different
 agent protocol.
 
-The operator command launches a platform, runs custody ceremonies, inspects
-status, wraps processes, and installs the daemon:
+The operator command starts browser-first platform genesis, inspects status,
+wraps processes, and installs the daemon. Genesis opens the one-use founder
+invitation, waits for the new passkey account to approve this CLI through device
+authorization, then continues custody in the browser. Passkey PRF output and
+both recovery phrases never enter the terminal:
 
 ```bash
 fz keys
 fz status
-fz genesis --mode 2-of-3
-fz unlock
+fz genesis --mode 2-of-3 --api https://api.example --app https://console.example
+fz unlock --phrase-file /secure/offline-phrase.txt # run once per participating custodian
 ```
 
 Install the service explicitly:
@@ -136,6 +139,44 @@ are generated adapters. They contain no independent architecture or progress.
 by hand. Tools and skills remain optional execution aids; accepted decisions and
 status live in the repository and therefore survive switching AI agents.
 
+## Browser-authorized project control
+
+Sign in from any checkout with the public CLI. The terminal displays a device
+code and the browser approves it in the selected tenant realm:
+
+```bash
+fz login --api https://api.forgezero.net --realm acme
+fz whoami
+fz ui routes --json
+```
+
+The short session is stored by API origin and realm in an owner-only local file.
+It is never committed to `.fz/config.json`. A protected mutation opens a browser
+page for passkey or TOTP proof and then replays the exact request once; the CLI
+has no privileged server mode.
+
+Any ordinary website operation is available to developers and AI agents through
+the same API and access matrix:
+
+```bash
+fz ui routes pipeline
+fz ui get /workspace/pipelines --query projectKey=my-project
+fz api post /workspace/pipelines/status \
+  --data '{"pipelineKey":"pl_…","enabled":false}'
+generate-request | fz api post /workspace/action --data -
+```
+
+Only realm-relative paths are accepted, so the saved session cannot be forwarded
+to another origin. Inline JSON, stdin and JSON files are supported. Use
+`fz logout` to revoke the remote session and remove the local copy.
+
+`fz ui routes --json` reads the action catalog from the API's enforced access
+matrix. It lists only the current account's current realm, stage and grants, so
+developers and AI agents can discover the available control surface without a
+copied CLI command list or a visit to the website. Execute any listed action
+with `fz ui <method> <path>`; sensitive actions open the same fresh-proof flow
+as the website and replay the exact request once.
+
 ## Deployment definitions
 
 A repository may commit `.fz/deploy.json` with its own profiles, prerequisite
@@ -155,6 +196,20 @@ fz deploy check
 fz deploy sync
 ```
 
+After sign-in, create and operate the durable pipeline from the same checkout.
+The project defaults to `.fz/config.json`; compute/profile attachments remain
+control-plane state rather than fields in the deploy file:
+
+```bash
+fz deploy connect --provider github --repository acme/web \
+  --clone-url https://github.com/acme/web.git --auth public \
+  --target compute-eu@api --target compute-us@api
+fz deploy list
+fz deploy runs --pipeline <pipeline-key>
+fz deploy release --pipeline <pipeline-key> \
+  --revision <full-40-character-commit> --wait
+```
+
 `init` refuses to invent a generic release or health check: both generated steps
 exit non-zero until the project replaces them. `check` validates the published
 v2 schema and active software coordinates, then prints a formatting-independent
@@ -209,7 +264,7 @@ only claims assigned to its enrolled hostname, then passes
 the fixed claim over a local Unix socket to a narrowly privileged root helper.
 The helper can materialize the audited QEMU profile; it cannot clone a project,
 read Vault data, accept arbitrary commands, or retain tenant credentials. Root
-SSH is an operator-only platform-genesis/recovery path, not the normal tenant
+SSH is an operator-only platform recovery path, not the normal tenant
 dispatch mechanism.
 
 New guests also call this same public `fz agent install --apply --enrol` path

package/dist/agent-heartbeat.d.ts

@@ -1,6 +1,7 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import { type AgentRelease } from './agent-update';
 import { type AgentUpdateReceipt, type AgentUpdateResponse } from './agent-update-helper';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 export interface AgentObservation {
     version: string;
     os: {
@@ -42,6 +43,7 @@ export interface AgentHeartbeatOptions {
     setTimer?: (callback: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;
+    telemetry?: AgentOperationTelemetry;
 }
 export declare function observeAgentHost(version?: string, mode?: AgentObservation['mode'], osRelease?: string, architecture?: NodeJS.Architecture): AgentObservation;
 /** One PQ-authenticated observation and optional supervised update decision. */

package/dist/agent-heartbeat.js

@@ -229,6 +229,7 @@ var AGENT_UPDATE_JOURNAL = "/var/lib/forgezero/agent-update.json";
 var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update-receipt.json";
 var MAX_REQUEST_BYTES = 8 * 1024;
 var COMPUTE_HELPER_UNITS = [
+  "forgezero-agent-egress.service",
   "forgezero-deploy-runner.service",
   "forgezero-lifecycle-helper.service",
   "forgezero-software-helper.service"
@@ -743,10 +744,14 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.32";
+var VERSION3 = "0.1.34";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");
+var remoteOutcome = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : cause instanceof SignedNodeHttpError ? "retryable" : "failed";
+
+class AgentUpdateRefusedError extends Error {
+}
 function observeAgentHost(version = VERSION3, mode = "enrolled", osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
@@ -794,17 +799,25 @@ async function heartbeatAgentOnce(options) {
       try {
         await options.prepareUpdate?.(release);
         prepared = true;
-        const applied = await (options.applyUpdate ?? ((next, current, attemptId) => requestAgentUpdate({
-          op: "apply",
-          target: options.updateTarget ?? "compute",
-          release: next,
-          currentVersion: current,
-          attemptId
-        })))(release, observation.version, desired.attemptId);
-        if (!applied.ok)
-          throw new Error(`agent update refused: ${applied.error.message}`);
-        if (applied.attemptId !== desired.attemptId) {
-          throw new Error("agent update helper returned the wrong rollout attempt");
+        const apply = async () => {
+          const applied = await (options.applyUpdate ?? ((next, current, attemptId) => requestAgentUpdate({
+            op: "apply",
+            target: options.updateTarget ?? "compute",
+            release: next,
+            currentVersion: current,
+            attemptId
+          })))(release, observation.version, desired.attemptId);
+          if (!applied.ok)
+            throw new AgentUpdateRefusedError(`agent update refused: ${applied.error.message}`);
+          if (applied.attemptId !== desired.attemptId) {
+            throw new Error("agent update helper returned the wrong rollout attempt");
+          }
+          return applied;
+        };
+        if (options.telemetry) {
+          await options.telemetry.observe("agent.update", apply, () => "success", (cause) => cause instanceof AgentUpdateRefusedError ? "refused" : "failed");
+        } else {
+          await apply();
         }
         options.onEvent?.("update-staged", { from: observation.version, to: release.version });
       } catch (cause) {
@@ -826,7 +839,8 @@ function startAgentHeartbeat(options) {
     if (stopped || active)
       return;
     let nextSeconds = 30;
-    active = heartbeatAgentOnce(options).then((response) => {
+    const heartbeat = () => heartbeatAgentOnce(options);
+    active = (options.telemetry ? options.telemetry.observe("agent.heartbeat", heartbeat, () => "success", remoteOutcome) : heartbeat()).then((response) => {
       nextSeconds = Math.max(5, Math.min(response.intervalSeconds, 300));
     }).catch((cause) => options.onEvent?.("heartbeat-failed", cause)).finally(() => {
       active = null;

package/dist/agent-update-helper.js

@@ -229,6 +229,7 @@ var AGENT_UPDATE_JOURNAL = "/var/lib/forgezero/agent-update.json";
 var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update-receipt.json";
 var MAX_REQUEST_BYTES = 8 * 1024;
 var COMPUTE_HELPER_UNITS = [
+  "forgezero-agent-egress.service",
   "forgezero-deploy-runner.service",
   "forgezero-lifecycle-helper.service",
   "forgezero-software-helper.service"

package/dist/attestation-client.d.ts

@@ -1,6 +1,7 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import type { AttestationSource } from './socket';
 import { type SignedNodeHttpOptions } from './signed-node-http';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 export interface NodeAttestationOptions extends SignedNodeHttpOptions {
     keys: NodeKeyPair;
     source: AttestationSource;
@@ -10,6 +11,7 @@ export interface NodeAttestationOptions extends SignedNodeHttpOptions {
     setTimer?: (callback: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;
+    telemetry?: AgentOperationTelemetry;
 }
 /** One challenge, one PSP report, one signed presentation. */
 export declare function attestNodeOnce(options: NodeAttestationOptions): Promise<{

package/dist/capacity-calibration.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bounded, node-local HTTP concurrency calibration.
+ *
+ * This deliberately benchmarks a real application probe rather than CPU. A
+ * database-bound API can have idle CPU while every request is waiting on I/O.
+ * The caller chooses a representative, idempotent GET endpoint; ForgeZero's
+ * cluster rehearsal uses its typed Arango read query.
+ */
+export interface CapacityStage {
+    concurrency: number;
+    requests: number;
+    succeeded: number;
+    failed: number;
+    overloaded: number;
+    throughputPerSecond: number;
+    p95Ms: number;
+}
+export interface CapacityCalibration {
+    endpoint: string;
+    recommendedConcurrency: number;
+    stopReason: 'maximum-tested' | 'latency' | 'errors' | 'throughput-regression';
+    stages: CapacityStage[];
+}
+export interface CapacityCalibrationOptions {
+    endpoint: string;
+    maxConcurrency?: number;
+    requestsPerWorker?: number;
+    maxP95Ms?: number;
+    maxErrorRate?: number;
+    headroomRatio?: number;
+    requestTimeoutMs?: number;
+}
+export interface ValidatedCapacityCalibrationOptions {
+    endpoint: URL;
+    maxConcurrency: number;
+    requestsPerWorker: number;
+    maxP95Ms: number;
+    maxErrorRate: number;
+    headroomRatio: number;
+    requestTimeoutMs: number;
+}
+/** Only a service on this node may be stressed by an install-time probe. */
+export declare function localCalibrationEndpoint(value: string): URL;
+/** Parse every bound without sending a request; deploy definitions use this fail-closed gate. */
+export declare function validateCapacityCalibrationOptions(options: CapacityCalibrationOptions): ValidatedCapacityCalibrationOptions;
+/**
+ * Increase load geometrically and stop at the first unsafe stage. The returned
+ * limit is the last safe stage with explicit headroom; it is evidence, not a
+ * promise that a different route or future release has the same capacity.
+ */
+export declare function calibrateHttpConcurrency(options: CapacityCalibrationOptions, fetcher?: typeof fetch): Promise<CapacityCalibration>;

package/dist/capacity-calibration.js

@@ -0,0 +1,119 @@
+// src/capacity-calibration.ts
+var percentile95 = (values) => {
+  if (values.length === 0)
+    return Number.POSITIVE_INFINITY;
+  const sorted = values.toSorted((left, right) => left - right);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)];
+};
+function localCalibrationEndpoint(value) {
+  const endpoint = new URL(value);
+  if (endpoint.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname) || !endpoint.port || endpoint.username || endpoint.password || endpoint.hash) {
+    throw new Error("Capacity calibration requires an explicit loopback HTTP endpoint and port.");
+  }
+  return endpoint;
+}
+function validateCapacityCalibrationOptions(options) {
+  const endpoint = localCalibrationEndpoint(options.endpoint);
+  const maxConcurrency = options.maxConcurrency ?? 256;
+  const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maxP95Ms = options.maxP95Ms ?? 250;
+  const maxErrorRate = options.maxErrorRate ?? 0.01;
+  const headroomRatio = options.headroomRatio ?? 0.8;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(headroomRatio) || headroomRatio < 0.25 || headroomRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000) {
+    throw new Error("Capacity calibration bounds are invalid.");
+  }
+  return {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    headroomRatio,
+    requestTimeoutMs
+  };
+}
+async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher) {
+  const latencies = [];
+  let succeeded = 0;
+  let failed = 0;
+  let overloaded = 0;
+  const started = performance.now();
+  await Promise.all(Array.from({ length: concurrency }, async () => {
+    for (let request = 0;request < requestsPerWorker; request += 1) {
+      const requestStarted = performance.now();
+      try {
+        const response = await fetcher(endpoint, {
+          method: "GET",
+          headers: { accept: "application/json", "user-agent": "forgezero-capacity-calibration/1" },
+          signal: AbortSignal.timeout(timeoutMs),
+          redirect: "error"
+        });
+        await response.body?.cancel();
+        if (response.ok)
+          succeeded += 1;
+        else {
+          failed += 1;
+          if (response.status === 503)
+            overloaded += 1;
+        }
+      } catch {
+        failed += 1;
+      } finally {
+        latencies.push(performance.now() - requestStarted);
+      }
+    }
+  }));
+  const elapsedSeconds = Math.max((performance.now() - started) / 1000, 0.001);
+  return {
+    concurrency,
+    requests: concurrency * requestsPerWorker,
+    succeeded,
+    failed,
+    overloaded,
+    throughputPerSecond: Number(((succeeded + failed) / elapsedSeconds).toFixed(2)),
+    p95Ms: Number(percentile95(latencies).toFixed(2))
+  };
+}
+async function calibrateHttpConcurrency(options, fetcher = fetch) {
+  const {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    headroomRatio,
+    requestTimeoutMs: timeoutMs
+  } = validateCapacityCalibrationOptions(options);
+  const stages = [];
+  let lastSafe = 1;
+  let stopReason = "maximum-tested";
+  for (let concurrency = 1;; concurrency = Math.min(maxConcurrency, concurrency * 2)) {
+    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher);
+    stages.push(measured);
+    const errorRate = measured.failed / measured.requests;
+    const previous = stages.at(-2);
+    const throughputRegressed = Boolean(previous && concurrency > 1 && measured.throughputPerSecond < previous.throughputPerSecond * 0.9);
+    if (measured.overloaded > 0 || errorRate > maxErrorRate)
+      stopReason = "errors";
+    else if (measured.p95Ms > maxP95Ms)
+      stopReason = "latency";
+    else if (throughputRegressed)
+      stopReason = "throughput-regression";
+    else
+      lastSafe = concurrency;
+    if (stopReason !== "maximum-tested" || concurrency === maxConcurrency)
+      break;
+  }
+  return {
+    endpoint: endpoint.toString(),
+    recommendedConcurrency: Math.max(1, Math.floor(lastSafe * headroomRatio)),
+    stopReason,
+    stages
+  };
+}
+export {
+  validateCapacityCalibrationOptions,
+  localCalibrationEndpoint,
+  calibrateHttpConcurrency
+};

package/dist/cli/agent-install.d.ts

@@ -16,6 +16,8 @@ import { type Capabilities, type ProvisionPlan } from '../provision';
 export type { ProvisionPlan };
 /** Parse NAME=value pairs used only for non-secret unit coordinates and credential paths. */
 export declare function parseAssignments(value: string | undefined): Record<string, string> | undefined;
+/** Parse an explicit provisioning-owned TCP allowlist; repository data never reaches this input. */
+export declare function parseTcpPorts(value: string | undefined): readonly number[] | undefined;
 /**
  * Answer the capability checks by running their commands.
  *
@@ -50,6 +52,9 @@ export interface InstallOptions {
     deploymentEnvironment?: Record<string, string>;
     deploymentCredentials?: Record<string, string>;
     pullDeployments?: boolean;
+    enforceEgress?: boolean;
+    runnerLoopbackPorts?: readonly number[];
+    runnerPublicTcpPorts?: readonly number[];
     pullMigrations?: boolean;
     lifecycleProfilePath?: string;
     lifecycleHelperSocketPath?: string;
@@ -71,6 +76,7 @@ export interface InstallOptions {
     enrolStatePath?: string;
     nodeLabel?: string;
     nodeHostname?: string;
+    telemetryEndpoint?: string;
 }
 export declare function planInstall(options: InstallOptions): ProvisionPlan;
 /** Execute the same ordered plan the control plane executes over SSH. */

package/dist/cli/genesis.d.ts

@@ -1,19 +1,5 @@
 import { type SealedShare } from '@forgezero/runtime/custody-share';
-import type { UsableIdentity } from './custody';
-/**
- * The genesis ceremony, driven from a terminal.
- *
- * Every value that matters is produced HERE and only sealed material crosses
- * the wire:
- *
- *   phrase   generated locally, printed once, never transmitted or stored
- *   ssh key  derived locally from an agent signature, never transmitted
- *
- * The API receives the derived 32-byte keys because that is what seals a share,
- * and it holds them for exactly the length of one request. Nothing here gives
- * the CLI a privileged path — it calls the same endpoints the browser does, and
- * a bypass that existed for bootstrapping would exist for an attacker too.
- */
+/** Transport shared by the post-genesis vault unlock routine. */
 export interface Transport {
     (path: string, init?: {
         method?: string;
@@ -23,32 +9,6 @@ export interface Transport {
         body: unknown;
     }>;
 }
-export interface GenesisResult {
-    ceremonyKey: string;
-    phrase: string[];
-    fingerprint: string;
-    activated: boolean;
-}
-/**
- * Run a single-custodian genesis.
- *
- * Deliberately limited to the operator running the command. A multi-custodian
- * genesis needs each person at their own terminal with their own agent, which
- * is a coordination problem rather than a code one — and pretending to do it
- * from one shell would mean one machine briefly holding every share.
- */
-export declare function runGenesis(args: {
-    api: Transport;
-    modeId: string;
-    userKey: string;
-    email: string;
-    identity: UsableIdentity;
-    /** The `plt_` token setup.sh wrote. Required — see below. */
-    token: string;
-    displayName?: string;
-    socketPath?: string;
-    onStep?: (message: string) => void;
-}): Promise<GenesisResult>;
 /**
  * Reconstruct the seed and unlock.
  *
@@ -59,9 +19,9 @@ export declare function runGenesis(args: {
 export declare function runUnlock(args: {
     api: Transport;
     userKey: string;
-    identity?: UsableIdentity;
-    phrase?: string[];
-    socketPath?: string;
+    phrase: string[];
+    ceremonyKey: string;
+    fingerprint: string;
     /**
      * This custodian's sealed envelope, read from the ceremony.
      *
@@ -69,11 +29,10 @@ export declare function runUnlock(args: {
      * unlocking. Opening it is a local step now, so no factor travels.
      */
     sealed?: SealedShare;
-    /** The salt the phrase wrapping key was derived over. */
-    phraseSalt?: string;
     onStep?: (message: string) => void;
 }): Promise<{
     fingerprint: string;
+    collected?: number;
+    required?: number;
+    unlocked?: boolean;
 }>;
-/** Resolve `--key` to a usable identity, with an actionable error if it cannot. */
-export declare function resolveIdentity(selector: string | undefined, socketPath?: string): Promise<UsableIdentity>;

package/dist/cli/index.d.ts

@@ -10,3 +10,8 @@ import { type AgentIdentity } from '@forgezero/runtime/ssh-agent';
  */
 export declare function requestHeaders(apiBase: string, cookie: string | null): Record<string, string>;
 export declare function useCustodyIdentity(identity: AgentIdentity, socketPath?: string): void;
+export declare function safeApiPath(value: string): string;
+export declare function targetCoordinate(value: string): {
+    computeReference: string;
+    profile: string;
+};

package/dist/cli/session-store.d.ts

@@ -0,0 +1,22 @@
+/** A short-lived browser-authorized session used only by the public CLI. */
+export interface CliSession {
+    api: string;
+    /** Browser application origin that approved this session and fresh actions. */
+    app?: string;
+    realm: string;
+    cookie: string;
+    createdAtTs: number;
+    lastUsedAtTs: number;
+    user?: {
+        key?: string;
+        email?: string;
+        displayName?: string;
+    };
+}
+export declare function canonicalApi(value: string): string;
+export declare const sessionId: (api: string, realm: string) => string;
+export declare function defaultSessionPath(env?: NodeJS.ProcessEnv): string;
+export declare function activeSession(path?: string): CliSession | null;
+export declare function sessionFor(api: string, realm: string, path?: string): CliSession | null;
+export declare function saveSession(session: CliSession, path?: string): void;
+export declare function removeSession(api: string, realm: string, path?: string): void;

package/dist/definition.d.ts

@@ -1,5 +1,6 @@
 import type { Pipeline, PipelineStep } from './pipeline';
 import { type DeploymentChannel, type SoftwareRequirement } from './software';
+import { type CapacityCalibrationOptions } from './capacity-calibration';
 /**
  * Version two separates a repository's deploy recipe from the computes that use
  * it. A target chooses one named profile in the control plane; compute names,
@@ -9,6 +10,8 @@ export declare const PIPELINE_VERSION: 2;
 export declare const DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
 export interface PipelineProfile {
     software: readonly SoftwareRequirement[];
+    /** Explicit opt-in, provider-neutral loopback GET probe run after target health. */
+    capacityCalibration?: CapacityCalibrationOptions;
 }
 export interface DeployStep extends PipelineStep {
     phase: 'build' | 'release' | 'migrate' | 'health';