@forgezero/agent 0.1.32 → 0.1.34

package/dist/definition.js

@@ -104,6 +104,121 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
   return results;
 }
 
+// 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
+  };
+}
+
 // src/definition.ts
 var PIPELINE_VERSION = 2;
 var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
@@ -144,6 +259,53 @@ var RESERVED_STEP_ENV = new Set([
   "GIT_SSH",
   "GIT_SSH_COMMAND"
 ]);
+function capacityCalibration(value, where) {
+  const calibration = record(value, where);
+  exactKeys(calibration, [
+    "endpoint",
+    "maxConcurrency",
+    "requestsPerWorker",
+    "maxP95Ms",
+    "maxErrorRate",
+    "headroomRatio",
+    "requestTimeoutMs"
+  ], where);
+  const endpoint = text(calibration.endpoint, `${where}.endpoint`);
+  try {
+    localCalibrationEndpoint(endpoint);
+  } catch (cause) {
+    throw new DefinitionError(cause instanceof Error ? cause.message : `${where}.endpoint is invalid.`);
+  }
+  const optionalNumber = (name) => {
+    const raw = calibration[name];
+    if (raw === undefined)
+      return;
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      throw new DefinitionError(`${where}.${name} must be a finite number.`);
+    }
+    return raw;
+  };
+  const parsed = {
+    endpoint,
+    ...Object.fromEntries([
+      "maxConcurrency",
+      "requestsPerWorker",
+      "maxP95Ms",
+      "maxErrorRate",
+      "headroomRatio",
+      "requestTimeoutMs"
+    ].flatMap((name) => {
+      const found = optionalNumber(name);
+      return found === undefined ? [] : [[name, found]];
+    }))
+  };
+  try {
+    validateCapacityCalibrationOptions(parsed);
+  } catch (cause) {
+    throw new DefinitionError(cause instanceof Error ? cause.message : `${where} bounds are invalid.`);
+  }
+  return parsed;
+}
 function parseDeployDefinition(value, options = {}) {
   const root = record(value, "pipeline");
   exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
@@ -169,11 +331,16 @@ function parseDeployDefinition(value, options = {}) {
     if (!NAME.test(name2))
       throw new DefinitionError(`pipeline profile name is invalid: ${name2}.`);
     const profile = record(raw, `profiles.${name2}`);
-    exactKeys(profile, ["software"], `profiles.${name2}`);
+    exactKeys(profile, ["software", "capacityCalibration"], `profiles.${name2}`);
     if (!Array.isArray(profile.software)) {
       throw new DefinitionError(`profiles.${name2}.software must be an array.`);
     }
-    profiles[name2] = { software: validateSoftwareRequirements(profile.software, options) };
+    profiles[name2] = {
+      software: validateSoftwareRequirements(profile.software, options),
+      ...profile.capacityCalibration === undefined ? {} : {
+        capacityCalibration: capacityCalibration(profile.capacityCalibration, `profiles.${name2}.capacityCalibration`)
+      }
+    };
   }
   const phases = new Set(["build", "release", "migrate", "health"]);
   const steps = root.steps.map((raw, index) => {
@@ -239,6 +406,11 @@ function parseDeployDefinition(value, options = {}) {
   if (new Set(steps.map((step) => step.name)).size !== steps.length) {
     throw new DefinitionError("pipeline.steps must have unique names.");
   }
+  for (const [profile, selected] of Object.entries(profiles)) {
+    if (selected.capacityCalibration && !steps.some((step) => step.phase === "health" && step.scope === "target" && (!step.profiles || step.profiles.includes(profile)))) {
+      throw new DefinitionError(`profiles.${profile}.capacityCalibration requires a target-scoped health step.`);
+    }
+  }
   const name = text(root.name, "pipeline.name");
   if (name.length > 120)
     throw new DefinitionError("pipeline.name must be at most 120 characters.");

package/dist/deploy-file.js

@@ -104,6 +104,121 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
   return results;
 }
 
+// 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
+  };
+}
+
 // src/definition.ts
 var PIPELINE_VERSION = 2;
 var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
@@ -144,6 +259,53 @@ var RESERVED_STEP_ENV = new Set([
   "GIT_SSH",
   "GIT_SSH_COMMAND"
 ]);
+function capacityCalibration(value, where) {
+  const calibration = record(value, where);
+  exactKeys(calibration, [
+    "endpoint",
+    "maxConcurrency",
+    "requestsPerWorker",
+    "maxP95Ms",
+    "maxErrorRate",
+    "headroomRatio",
+    "requestTimeoutMs"
+  ], where);
+  const endpoint = text(calibration.endpoint, `${where}.endpoint`);
+  try {
+    localCalibrationEndpoint(endpoint);
+  } catch (cause) {
+    throw new DefinitionError(cause instanceof Error ? cause.message : `${where}.endpoint is invalid.`);
+  }
+  const optionalNumber = (name) => {
+    const raw = calibration[name];
+    if (raw === undefined)
+      return;
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      throw new DefinitionError(`${where}.${name} must be a finite number.`);
+    }
+    return raw;
+  };
+  const parsed = {
+    endpoint,
+    ...Object.fromEntries([
+      "maxConcurrency",
+      "requestsPerWorker",
+      "maxP95Ms",
+      "maxErrorRate",
+      "headroomRatio",
+      "requestTimeoutMs"
+    ].flatMap((name) => {
+      const found = optionalNumber(name);
+      return found === undefined ? [] : [[name, found]];
+    }))
+  };
+  try {
+    validateCapacityCalibrationOptions(parsed);
+  } catch (cause) {
+    throw new DefinitionError(cause instanceof Error ? cause.message : `${where} bounds are invalid.`);
+  }
+  return parsed;
+}
 function parseDeployDefinition(value, options = {}) {
   const root = record(value, "pipeline");
   exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
@@ -169,11 +331,16 @@ function parseDeployDefinition(value, options = {}) {
     if (!NAME.test(name2))
       throw new DefinitionError(`pipeline profile name is invalid: ${name2}.`);
     const profile = record(raw, `profiles.${name2}`);
-    exactKeys(profile, ["software"], `profiles.${name2}`);
+    exactKeys(profile, ["software", "capacityCalibration"], `profiles.${name2}`);
     if (!Array.isArray(profile.software)) {
       throw new DefinitionError(`profiles.${name2}.software must be an array.`);
     }
-    profiles[name2] = { software: validateSoftwareRequirements(profile.software, options) };
+    profiles[name2] = {
+      software: validateSoftwareRequirements(profile.software, options),
+      ...profile.capacityCalibration === undefined ? {} : {
+        capacityCalibration: capacityCalibration(profile.capacityCalibration, `profiles.${name2}.capacityCalibration`)
+      }
+    };
   }
   const phases = new Set(["build", "release", "migrate", "health"]);
   const steps = root.steps.map((raw, index) => {
@@ -239,6 +406,11 @@ function parseDeployDefinition(value, options = {}) {
   if (new Set(steps.map((step) => step.name)).size !== steps.length) {
     throw new DefinitionError("pipeline.steps must have unique names.");
   }
+  for (const [profile, selected] of Object.entries(profiles)) {
+    if (selected.capacityCalibration && !steps.some((step) => step.phase === "health" && step.scope === "target" && (!step.profiles || step.profiles.includes(profile)))) {
+      throw new DefinitionError(`profiles.${profile}.capacityCalibration requires a target-scoped health step.`);
+    }
+  }
   const name = text(root.name, "pipeline.name");
   if (name.length > 120)
     throw new DefinitionError("pipeline.name must be at most 120 characters.");

package/dist/deployment-pull.d.ts

@@ -1,5 +1,6 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import type { DeploymentManager, DeploymentResult, GitSourceAuth } from './deployment';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 export interface RemoteDeploymentClaim {
     runKey: string;
     pipelineKey: string;
@@ -36,6 +37,7 @@ export interface DeploymentPullOptions {
     setTimer?: (callback: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;
+    telemetry?: AgentOperationTelemetry;
 }
 export type PullResult = {
     status: 'idle';

package/dist/deployment.d.ts

@@ -1,8 +1,10 @@
 import { type DrainReport, type QueueTask } from '@forgezero/runtime/queue';
+import { type GitHostResolver } from './git-egress';
 import type { SoftwareRequirement } from './software';
 import { type RunResult } from './pipeline';
 import type { SecretCache } from './cache';
 import type { AttestationSource } from './socket';
+import { type CapacityCalibration, type CapacityCalibrationOptions } from './capacity-calibration';
 export interface CommandInput {
     command: string;
     cwd?: string;
@@ -31,6 +33,12 @@ export interface DeploymentResult {
     release: string;
     ok: boolean;
     phases: readonly RunResult[];
+    capacity?: CapacityCalibration & {
+        evidencePath: string;
+        recommendedCoordinate: {
+            FZ_CONCURRENCY_LIMIT: string;
+        };
+    };
 }
 /**
  * How the credential-bearing agent may read one server-owned Git source.
@@ -58,6 +66,8 @@ export interface DeploymentOptions {
     knownHostsPath?: string;
     /** Server-owned, operator-pinned host keys for a dynamically assigned source. */
     knownHostsContent?: string;
+    /** Test/embedding seam. Production uses the operating system resolver. */
+    resolveGitHost?: GitHostResolver;
     cache?: Pick<SecretCache, 'get'>;
     /** Non-secret values explicitly passed to every project phase. */
     environment?: Record<string, string>;
@@ -67,6 +77,10 @@ export interface DeploymentOptions {
     projectExec?: (input: CommandInput) => Promise<CommandResult>;
     /** Root-owned fixed strategy helper; repository data contains coordinates only. */
     ensureSoftware?: (requirements: readonly SoftwareRequirement[]) => Promise<unknown>;
+    /** Agent-owned directory; definitions cannot choose or overwrite this path. */
+    capacityEvidenceDirectory?: string;
+    /** Test/embedding seam. Production runs the bounded loopback GET calibrator. */
+    calibrateCapacity?: (options: CapacityCalibrationOptions) => Promise<CapacityCalibration>;
     exec?: (input: CommandInput) => Promise<CommandResult>;
     now?: () => number;
     readDefinition?: (path: string) => unknown;

package/dist/egress-policy.d.ts

@@ -0,0 +1,50 @@
+export declare const AGENT_EGRESS_TABLE = "forgezero_agent_egress";
+export declare const SYSTEMD_RESOLVED_STUB = "/run/systemd/resolve/stub-resolv.conf";
+export declare const SYSTEMD_RESOLVED_ADDRESS = "127.0.0.53";
+export declare const BLOCKED_IPV4: readonly ["0.0.0.0/8", "10.0.0.0/8", "100.64.0.0/10", "127.0.0.0/8", "168.63.129.16/32", "169.254.0.0/16", "172.16.0.0/12", "192.0.0.0/24", "192.0.2.0/24", "192.88.99.0/24", "192.168.0.0/16", "198.18.0.0/15", "198.51.100.0/24", "203.0.113.0/24", "224.0.0.0/4", "240.0.0.0/4"];
+export declare const BLOCKED_IPV6: readonly ["::/128", "::1/128", "::ffff:0:0/96", "64:ff9b::/96", "64:ff9b:1::/48", "100::/64", "fc00::/7", "fec0::/10", "fe80::/10", "ff00::/8", "2001::/32", "2001:2::/48", "2001:10::/28", "2001:20::/28", "2001:db8::/32", "2002::/16", "3fff::/20"];
+export declare const normalizeEgressTcpPorts: (ports: readonly number[]) => readonly number[];
+export interface LoopbackEgressGrant {
+    uid: number;
+    tcpPorts: readonly number[];
+    /** When present, reject every other public protocol/port for this UID. */
+    publicTcpPorts?: readonly number[];
+}
+/** Native cgroup filtering stays active even if an operator later reloads nftables. */
+export declare function systemdAgentEgressDirectives(loopbackTcpPorts?: readonly number[]): string;
+/** One atomic nftables transaction installed before systemd marks the policy ready. */
+export declare function renderAgentEgressNft(uids: readonly number[], replace?: boolean, loopback?: LoopbackEgressGrant): string;
+export interface EgressCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export type EgressCommand = (argv: readonly string[], stdin?: string) => EgressCommandResult;
+export declare function resolveServiceUid(user: string, command?: EgressCommand): number;
+export declare function assertResolvedStub(realpath?: (path: string) => string): void;
+export declare function verifyAgentEgressPolicy(uids: readonly number[], command?: EgressCommand, loopback?: LoopbackEgressGrant): boolean;
+export declare function applyAgentEgressPolicy(options: {
+    users: readonly string[];
+    loopback?: {
+        user: string;
+        tcpPorts: readonly number[];
+        publicTcpPorts?: readonly number[];
+    };
+    command?: EgressCommand;
+    realpath?: (path: string) => string;
+    getuid?: () => number;
+}): readonly number[];
+export declare function superviseAgentEgressPolicy(options: {
+    users: readonly string[];
+    loopback?: {
+        user: string;
+        tcpPorts: readonly number[];
+        publicTcpPorts?: readonly number[];
+    };
+    command?: EgressCommand;
+    realpath?: (path: string) => string;
+    getuid?: () => number;
+    intervalMs?: number;
+    notifyReady?: () => void;
+    wait?: (milliseconds: number) => Promise<void>;
+}): Promise<never>;