@forgezero/agent 0.1.74 → 0.1.75

package/README.md

@@ -63,6 +63,8 @@ Every row links to the detailed explanation and named-import/example area below.
 | @forgezero/agent/credential-schema | Canonical systemd credential names and validation shared by bootstrap and services. | Bun/Node host | [Reference + usage](#forgezero-agent-credential-schema) |
 | @forgezero/agent/definition | Legacy version 3 JSON deployment compatibility contract. | Bun/Node host | [Reference + usage](#forgezero-agent-definition) |
 | @forgezero/agent/deploy | Typed deployment authoring builders, built-in provider requirements and versioned action constructors. | Bun/Node host | [Reference + usage](#forgezero-agent-deploy) |
+| @forgezero/agent/deployment-targets | Bounded input resolution and stable compute-target assignment for typed plans; emits requirements and slots rather than physical hostnames. | Bun/Node host | [Reference + usage](#forgezero-agent-deployment-targets) |
+| @forgezero/agent/deployment-connectivity | Root-owned application of per-target Cloudflare Tunnel or WARP connector capabilities without exposing the project management token to a compute. | Bun/Node host | [Reference + usage](#forgezero-agent-deployment-connectivity) |
 | @forgezero/agent/deploy-plan | Runtime validation, canonicalization and semantic digest for inert deployment plans. | Bun/Node host | [Reference + usage](#forgezero-agent-deploy-plan) |
 | @forgezero/agent/deploy-plan-runner | Conditional DAG execution with bounded retry, compensation and failure policy over injected action handlers. | Bun/Node host | [Reference + usage](#forgezero-agent-deploy-plan-runner) |
 | @forgezero/agent/deploy-compiler | Explicit developer/CI compiler from forgezero.deploy.ts to canonical .fz/deploy.plan.json; never used to execute project TypeScript in production. | Bun/Node host | [Reference + usage](#forgezero-agent-deploy-compiler) |
@@ -495,7 +497,7 @@ export const selectedCapability = PipelineError;
 <a id="forgezero-agent-agent-heartbeat"></a>
 ## @forgezero/agent/agent-heartbeat
 
-Signed node health publication with bounded renewal and shutdown withdrawal. This entry exposes 3 named value exports and 3 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Signed node health publication with bounded renewal and shutdown withdrawal. This entry exposes 3 named value exports and 4 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -507,6 +509,7 @@ import {
 import type {
   AgentHeartbeatOptions,
   AgentHeartbeatResponse,
+  AgentHostMetrics,
   AgentObservation,
 } from '@forgezero/agent/agent-heartbeat';
 ```
@@ -1064,7 +1067,7 @@ export const selectedCapability = DEPLOY_SCHEMA_URL;
 <a id="forgezero-agent-deploy"></a>
 ## @forgezero/agent/deploy
 
-Typed deployment authoring builders, built-in provider requirements and versioned action constructors. This entry exposes 14 named value exports and 35 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Typed deployment authoring builders, built-in provider requirements and versioned action constructors. This entry exposes 14 named value exports and 41 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -1091,17 +1094,22 @@ import type {
   BunProviderConfig,
   CloudflaredProviderConfig,
   ComponentDefinition,
+  ComputeConnectivityDefinition,
+  ComputePoolDefinition,
   Condition,
   ConditionOperand,
+  ContainerdProviderConfig,
   CredentialDefinition,
   DatabaseComponent,
   DeploymentSource,
   DockerProviderConfig,
   HealthDefinition,
   InputDefinition,
+  IntegerValue,
   JsonObject,
   JsonPrimitive,
   JsonValue,
+  KataProviderConfig,
   NetworkDefinition,
   NginxProviderConfig,
   OpenSshProviderConfig,
@@ -1113,6 +1121,7 @@ import type {
   StageDefinition,
   StepScope,
   StorageMount,
+  StringValue,
   SystemdProviderConfig,
   TargetDefinition,
   UfwProviderConfig,
@@ -1123,16 +1132,19 @@ import type {
 } from '@forgezero/agent/deploy';
 ```
 
-## @forgezero/agent/deploy — Author a typed native or Docker deployment
+## @forgezero/agent/deploy — Author a typed, placed containerd deployment
 
-TypeScript is authoring only. The checked-in canonical plan is what Agents validate and execute. Docker is additive: native Bun/ArangoDB remains available, while container applications must declare hard CPU, memory and PID limits, storage class, loopback ingress and a fixed health gate.
+TypeScript is authoring only. The checked-in canonical plan is what Agents validate and execute. Targets declare bounded resource/cardinality intent, not hostnames. The API reserves eligible project capacity or provisions only under the reviewed plan and spend ceiling, assigns stable slots, and the Agent runs only its exact assignment. runc containers must declare hard CPU, memory and PID limits, bounded storage, loopback ingress and a health-gated rollout; select Kata QEMU SNP when the workload needs host isolation.
 
 ```text
 import {
   actions,
-  application,
-  defineDeployment,
-  providers,
+	  application,
+	  credential,
+	  defineDeployment,
+	  input,
+	  providers,
+	  ref,
   stage,
   target,
   workflow,
@@ -1142,24 +1154,117 @@ export default defineDeployment({
   apiVersion: 'deploy.forgezero.net/v1', kind: 'Deployment',
   metadata: { name: 'orders-api' },
   spec: {
-    targets: { api: target.compute({ selector: { profiles: ['api'] }, cardinality: { minimum: 1, desired: 2, maximum: 16 } }) },
-    requirements: { docker: providers.docker.require(), nginx: providers.nginx.require() },
+	inputs: {
+	  replicas: input.integer({ minimum: 1, maximum: 16, default: 1 }),
+	  cpuCores: input.integer({ minimum: 1, maximum: 32, default: 1 }),
+	  memoryMiB: input.integer({ minimum: 256, maximum: 131072, default: 512 }),
+	  storageGiB: input.integer({ minimum: 4, maximum: 2048, default: 8 })
+	},
+	credentials: {
+	  cloudflare: credential.vault({ schema: 'forgezero.cloudflare/management@1', name: 'cloudflare-management' })
+	},
+	targets: { api: target.compute({
+	  profiles: ['api'], replicas: { minimum: 1, desired: input.ref('replicas'), maximum: 16 },
+	  resources: { cpuCores: input.ref('cpuCores'), memoryMiB: input.ref('memoryMiB'), storageGiB: input.ref('storageGiB') },
+	  os: 'ubuntu-24.04', runtime: 'oci-runc', sharing: 'shared', reuse: 'prefer',
+	  provisioning: {
+	    planKey: 'app-small', regionKey: 'default', imageKey: 'ubuntu-24.04-x64',
+	    environmentKey: 'production', ownership: 'platform', maxMonthlySpendMinor: '25000'
+	  },
+	  connectivity: {
+	    private: { mode: 'private-lan' },
+	    public: { mode: 'cloudflare-tunnel', credential: 'cloudflare', zone: 'example.com', hostname: { mode: 'indexed', prefix: 'api' } }
+	  }
+	}) },
+	requirements: {
+	  containerd: providers.containerd.require(), nginx: providers.nginx.require(),
+	  cloudflared: providers.cloudflared.require()
+	},
     components: {
       api: application({
         target: 'api',
-        runtime: { kind: 'container', provider: 'forgezero.docker', requirement: 'docker', image: { source: { kind: 'build', context: '.', dockerfile: 'Dockerfile' } }, security: { privileged: false, noNewPrivileges: true, root: 'read-only', dropCapabilities: ['ALL'] } },
+		runtime: { kind: 'container', provider: 'forgezero.containerd', requirement: 'containerd', runtimeClass: 'runc', image: { source: { kind: 'build', context: '.', dockerfile: 'Dockerfile' } }, security: { privileged: false, noNewPrivileges: true, root: 'read-only', dropCapabilities: ['ALL'] } },
         service: { protocol: 'http', port: 3000, health: { protocol: 'http', method: 'GET', path: '/health', expectedStatus: [200], timeoutMs: 2000 } },
-        resources: { cpu: { limit: 2 }, memory: { limitMiB: 2048, swap: 'disabled' }, pids: { limit: 256 } },
+		resources: { cpu: { limit: 1 }, memory: { limitMiB: 512, swap: 'disabled' }, pids: { limit: 256 } },
         storage: [{ class: 'ephemeral', path: '/tmp', type: 'tmpfs', sizeMiB: 128 }],
-        network: { ingress: { exposure: 'loopback', stablePort: 3000 }, container: { mode: 'bridge', network: 'api' } },
+	        network: {
+	          ingress: { exposure: 'public', stablePort: 3000 },
+	          public: { mode: 'cloudflare-tunnel' },
+	          container: { mode: 'bridge', network: 'api' }
+	        },
         rollout: { strategy: 'blue-green', proxy: 'nginx', automaticRollback: true }
       })
     },
-    workflows: { deploy: workflow({ stages: { prepare: stage({ strategy: { mode: 'sequential' }, steps: { software: actions.software.ensure({ requirements: ['docker', 'nginx'] }, { scope: { kind: 'each-target', target: 'api' } }) } }) } }) }
+	workflows: { deploy: workflow({ stages: {
+	  prepare: stage({ strategy: { mode: 'sequential' }, steps: {
+		    software: actions.software.ensure({ requirements: ['containerd', 'nginx', 'cloudflared'] }, { scope: { kind: 'each-target', target: 'api' } }),
+		    network: actions.network.ensure({ target: 'api' }, { scope: { kind: 'each-target', target: 'api' } }),
+		    image: actions.container.build({ component: 'api' }, { scope: { kind: 'each-target', target: 'api' } })
+	  } }),
+	  release: stage({ dependsOn: ['prepare'], strategy: { mode: 'blue-green' }, steps: {
+	    promote: actions.service.promote({ component: 'api', imageDigest: ref.stepOutput('image', 'digest') }, { scope: { kind: 'each-target', target: 'api' } })
+	  } })
+	} }) }
   }
 });
 ```
 
+<a id="forgezero-agent-deployment-targets"></a>
+## @forgezero/agent/deployment-targets
+
+Bounded input resolution and stable compute-target assignment for typed plans; emits requirements and slots rather than physical hostnames. This entry exposes 3 named value exports and 0 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+
+```text
+import {
+  DeploymentInputError,
+  resolveDeploymentInputs,
+  resolveDeploymentTargets,
+} from '@forgezero/agent/deployment-targets';
+```
+
+## @forgezero/agent/deployment-targets — Use this entry point
+
+This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
+
+```text
+import {
+  DeploymentInputError,
+} from '@forgezero/agent/deployment-targets';
+
+export const selectedCapability = DeploymentInputError;
+```
+
+<a id="forgezero-agent-deployment-connectivity"></a>
+## @forgezero/agent/deployment-connectivity
+
+Root-owned application of per-target Cloudflare Tunnel or WARP connector capabilities without exposing the project management token to a compute. This entry exposes 1 named value export and 5 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+
+```text
+import {
+  applyDeploymentConnectivity,
+} from '@forgezero/agent/deployment-connectivity';
+
+import type {
+  DeploymentConnectivityCapabilities,
+  DeploymentConnectivityEvidence,
+  DeploymentConnectivityHost,
+  DeploymentConnectivityIntent,
+  DeploymentConnectivityRequest,
+} from '@forgezero/agent/deployment-connectivity';
+```
+
+## @forgezero/agent/deployment-connectivity — Use this entry point
+
+This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
+
+```text
+import {
+  applyDeploymentConnectivity,
+} from '@forgezero/agent/deployment-connectivity';
+
+export const selectedCapability = applyDeploymentConnectivity;
+```
+
 <a id="forgezero-agent-deploy-plan"></a>
 ## @forgezero/agent/deploy-plan
 
@@ -1540,11 +1645,14 @@ if (!validate(deploymentDefinition)) throw new Error(JSON.stringify(validate.err
 <a id="forgezero-agent-software"></a>
 ## @forgezero/agent/software
 
-Exact managed-software inventory, requirement and evidence contracts. This entry exposes 10 named value exports and 10 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Exact managed-software inventory, requirement and evidence contracts. This entry exposes 13 named value exports and 10 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
+  BUILDKIT_VERSION,
   BUN_RELEASE_SHA256,
+  KATA_CONTAINERS_VERSION,
+  NERDCTL_VERSION,
   OS_CATALOG,
   PINNED_BUN_VERSION,
   SOFTWARE_CATALOG,
@@ -1576,16 +1684,16 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  BUN_RELEASE_SHA256,
+  BUILDKIT_VERSION,
 } from '@forgezero/agent/software';
 
-export const selectedCapability = BUN_RELEASE_SHA256;
+export const selectedCapability = BUILDKIT_VERSION;
 ```
 
 <a id="forgezero-agent-software-helper"></a>
 ## @forgezero/agent/software-helper
 
-Root-owned fixed installation/update boundary for declared software. This entry exposes 8 named value exports and 0 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Root-owned fixed installation/update boundary for declared software. This entry exposes 9 named value exports and 0 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -1594,6 +1702,7 @@ import {
   SOFTWARE_HELPER_UNIT_PATH,
   requestContainerActivation,
   requestContainerBuild,
+  requestDeploymentConnectivity,
   requestServiceActivation,
   requestSoftware,
   startSoftwareHelper,

package/dist/agent-heartbeat.d.ts

@@ -10,6 +10,22 @@ export interface AgentObservation {
     };
     architecture: string;
     mode: 'attested' | 'enrolled';
+    runtimeCapabilities?: {
+        native: true;
+        ociRunc: boolean;
+        kataQemuSnp: boolean;
+    };
+    /** Signed host evidence. Placement still reserves declared capacity; it never chases transient utilization. */
+    capacity?: {
+        logicalCpu: number;
+        memoryMiB: number;
+        storageGiB: number;
+    };
+    utilization?: {
+        load1mMilli: number;
+        memoryUsedMiB: number;
+        storageUsedGiB: number;
+    };
     update?: AgentUpdateReceipt;
     deploymentIntake?: {
         generation: number;
@@ -32,6 +48,14 @@ export interface AgentHeartbeatResponse {
         state: 'running' | 'paused';
     };
 }
+export interface AgentHostMetrics {
+    logicalCpu: number;
+    memoryBytes: number;
+    memoryFreeBytes: number;
+    storageBytes: number;
+    storageFreeBytes: number;
+    load1m: number;
+}
 export interface AgentHeartbeatOptions {
     apiUrl: string;
     nodeKey: string;
@@ -58,7 +82,7 @@ export interface AgentHeartbeatOptions {
     onEvent?: (event: string, detail?: unknown) => void;
     telemetry?: AgentOperationTelemetry;
 }
-export declare function observeAgentHost(version?: string, mode?: AgentObservation['mode'], osRelease?: string, architecture?: NodeJS.Architecture): AgentObservation;
+export declare function observeAgentHost(version?: string, mode?: AgentObservation['mode'], osRelease?: string, architecture?: NodeJS.Architecture, metrics?: AgentHostMetrics): AgentObservation;
 /** One PQ-authenticated observation and optional supervised update decision. */
 export declare function heartbeatAgentOnce(options: AgentHeartbeatOptions): Promise<AgentHeartbeatResponse>;
 /** Server-paced heartbeat; stopping waits for the active PQ request/update handoff. */

package/dist/agent-heartbeat.js

@@ -677,7 +677,8 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 }
 
 // src/agent-heartbeat.ts
-import { readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, statfsSync } from "node:fs";
+import { cpus, freemem, loadavg, totalmem } from "node:os";
 
 // src/signed-node-http.ts
 import {
@@ -749,25 +750,64 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.74";
+var VERSION3 = "0.1.75";
 
 // src/agent-heartbeat.ts
+function readAgentHostMetrics() {
+  const filesystem = statfsSync("/");
+  return {
+    logicalCpu: cpus().length,
+    memoryBytes: totalmem(),
+    memoryFreeBytes: freemem(),
+    storageBytes: Number(filesystem.blocks) * Number(filesystem.bsize),
+    storageFreeBytes: Number(filesystem.bavail) * Number(filesystem.bsize),
+    load1m: loadavg()[0]
+  };
+}
 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) {
+function observeAgentHost(version = VERSION3, mode = "enrolled", osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch, metrics = readAgentHostMetrics()) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
     const separator = line.indexOf("=");
     return separator > 0 ? [[line.slice(0, separator), unquote(line.slice(separator + 1))]] : [];
   }));
+  const osId = (values.ID ?? "unknown").toLowerCase();
+  const osVersion = values.VERSION_ID ?? "unknown";
+  const ubuntuX64 = osId === "ubuntu" && ["24.04", "26.04"].includes(osVersion) && architecture === "x64";
+  const enabled = (path) => {
+    try {
+      return /^(?:1|y)$/i.test(readFileSync3(path, "utf8").trim());
+    } catch {
+      return false;
+    }
+  };
+  const gib = 1024 ** 3;
+  const mib = 1024 ** 2;
+  const storageGiB = Math.max(1, Math.floor(metrics.storageBytes / gib));
   return {
     version,
-    os: { id: (values.ID ?? "unknown").toLowerCase(), versionId: values.VERSION_ID ?? "unknown" },
+    os: { id: osId, versionId: osVersion },
     architecture,
-    mode
+    mode,
+    runtimeCapabilities: {
+      native: true,
+      ociRunc: ubuntuX64,
+      kataQemuSnp: ubuntuX64 && osVersion === "26.04" && existsSync3("/dev/kvm") && existsSync3("/dev/sev") && enabled("/sys/module/kvm_amd/parameters/sev") && enabled("/sys/module/kvm_amd/parameters/sev_snp")
+    },
+    capacity: {
+      logicalCpu: Math.max(1, metrics.logicalCpu),
+      memoryMiB: Math.max(1, Math.floor(metrics.memoryBytes / mib)),
+      storageGiB
+    },
+    utilization: {
+      load1mMilli: Math.max(0, Math.round(metrics.load1m * 1000)),
+      memoryUsedMiB: Math.max(0, Math.floor((metrics.memoryBytes - metrics.memoryFreeBytes) / mib)),
+      storageUsedGiB: Math.max(0, Math.min(storageGiB, Math.ceil((metrics.storageBytes - metrics.storageFreeBytes) / gib)))
+    }
   };
 }
 async function heartbeatAgentOnce(options) {

package/dist/bootstrap.js

@@ -1416,7 +1416,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.74";
+var VERSION = "0.1.75";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";