@forgezero/agent 0.1.31 → 0.1.33

package/dist/provisioning-pull.d.ts

@@ -1,5 +1,6 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import { type SignedNodeHttpOptions } from './signed-node-http';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 interface RemoteProvisionClaimBase {
     computeKey: string;
     claimToken: string;
@@ -73,6 +74,7 @@ export interface ProvisioningPullOptions extends SignedNodeHttpOptions {
         kvm: boolean;
         helper: boolean;
     };
+    telemetry?: AgentOperationTelemetry;
 }
 export type ProvisionPullResult = {
     status: 'idle';

package/dist/provisioning-pull.js

@@ -70,6 +70,7 @@ async function postSignedNode(options, path, body) {
 // src/provisioning-pull.ts
 class ProvisionClaimLostError extends Error {
 }
+var remoteOutcome = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : "retryable";
 var post = (options, operation, body) => postSignedNode(options, `v1/metal/computes/${operation}`, body);
 async function runClaim(options, claim) {
   const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
@@ -88,10 +89,11 @@ async function runClaim(options, claim) {
       if (stopped || renewal)
         return;
       let retry;
-      renewal = post(options, "renew", {
+      const renew = () => post(options, "renew", {
         computeKey: claim.computeKey,
         claimToken: claim.claimToken
-      }).then((response) => {
+      });
+      renewal = (options.telemetry ? options.telemetry.observe("provisioning.renew", renew, () => "success", remoteOutcome) : renew()).then((response) => {
         expires = response.claimExpiresAtTs;
         options.onEvent?.("lease-renewed", { computeKey: claim.computeKey, claimExpiresAtTs: expires });
       }).catch((cause) => {
@@ -112,7 +114,8 @@ async function runClaim(options, claim) {
   schedule();
   let result;
   try {
-    result = await options.run(claim);
+    const run = () => options.run(claim);
+    result = options.telemetry ? await options.telemetry.observe("provisioning.apply", run) : await run();
   } finally {
     stopped = true;
     clearTimer(timer);
@@ -143,7 +146,8 @@ async function complete(options, body) {
 async function pullProvisioningOnce(options) {
   if (options.metalPreflight) {
     const report = options.metalPreflight();
-    const accepted = await postSignedNode(options, "v1/metal/preflight", report);
+    const preflight = () => postSignedNode(options, "v1/metal/preflight", report);
+    const accepted = options.telemetry ? await options.telemetry.observe("provisioning.preflight", preflight, (value) => value.ready ? "success" : "refused", remoteOutcome) : await preflight();
     if (options.metalHostname && accepted.hostname !== options.metalHostname) {
       throw new Error(`metal agent: configured inventory hostname ${options.metalHostname} is bound as ${accepted.hostname}; refusing work.`);
     }
@@ -156,7 +160,8 @@ async function pullProvisioningOnce(options) {
     if (!accepted.ready)
       return { status: "idle" };
   }
-  const response = await post(options, "claim", {});
+  const claimWork = () => post(options, "claim", {});
+  const response = options.telemetry ? await options.telemetry.observe("provisioning.claim", claimWork, (value) => value.claim ? "success" : "idle", remoteOutcome) : await claimWork();
   if (!response.claim)
     return { status: "idle" };
   const claim = response.claim;
@@ -167,20 +172,28 @@ async function pullProvisioningOnce(options) {
     if (cause instanceof ProvisionClaimLostError)
       throw cause;
     const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
-    await complete(options, {
+    const acknowledge2 = () => complete(options, {
       computeKey: claim.computeKey,
       claimToken: claim.claimToken,
       ok: false,
       detail: reason
     });
+    if (options.telemetry) {
+      await options.telemetry.observe("provisioning.complete", acknowledge2, () => "success", remoteOutcome);
+    } else
+      await acknowledge2();
     return { status: "failed", claim, reason };
   }
-  await complete(options, {
+  const acknowledge = () => complete(options, {
     computeKey: claim.computeKey,
     claimToken: claim.claimToken,
     ok: true,
     ...result.guestAddress ? { guestAddress: result.guestAddress } : {}
   });
+  if (options.telemetry) {
+    await options.telemetry.observe("provisioning.complete", acknowledge, () => "success", remoteOutcome);
+  } else
+    await acknowledge();
   return { status: claim.action === "delete" ? "terminated" : "running", claim, result };
 }
 function startProvisioningPull(options) {

package/dist/telemetry-runtime.d.ts

@@ -0,0 +1,20 @@
+import type { AgentTelemetry, AgentTelemetryEvent, AgentTelemetryOperation, AgentTelemetryOutcome } from './telemetry';
+/**
+ * Process-wide operation/state accounting layered over the deliberately small
+ * OTLP emitter. Callers still cannot attach arbitrary attributes or payloads.
+ */
+export declare class AgentTelemetryRuntime {
+    private readonly telemetry;
+    private readonly now;
+    private active;
+    private completed;
+    private failed;
+    private draining;
+    constructor(telemetry: AgentTelemetry, now?: () => number);
+    event(event: AgentTelemetryEvent): void;
+    setDraining(draining: boolean): void;
+    observe<T>(operation: AgentTelemetryOperation, work: () => Promise<T>, outcome?: (value: T) => AgentTelemetryOutcome, errorOutcome?: (cause: unknown) => AgentTelemetryOutcome): Promise<T>;
+    close(): Promise<void>;
+    private recordState;
+}
+export type AgentOperationTelemetry = Pick<AgentTelemetryRuntime, 'observe'>;

package/dist/telemetry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Dependency-free OTLP/HTTP telemetry for the machine Agent.
+ *
+ * Callers can name only reviewed operations, outcomes and lifecycle events.
+ * There is deliberately no field for a URL, request/response body, header,
+ * credential, tenant coordinate, command, error detail or arbitrary label.
+ */
+export declare const AGENT_TELEMETRY_OPERATIONS: readonly ["agent.heartbeat", "agent.update", "attestation.refresh", "deployment.claim", "deployment.run", "deployment.renew", "deployment.complete", "migration.claim", "migration.run", "migration.renew", "migration.complete", "provisioning.preflight", "provisioning.claim", "provisioning.apply", "provisioning.renew", "provisioning.complete", "vault.sync", "agent.other"];
+export type AgentTelemetryOperation = (typeof AGENT_TELEMETRY_OPERATIONS)[number];
+export declare const AGENT_TELEMETRY_OUTCOMES: readonly ["success", "idle", "refused", "retryable", "failed"];
+export type AgentTelemetryOutcome = (typeof AGENT_TELEMETRY_OUTCOMES)[number];
+export declare const AGENT_TELEMETRY_EVENTS: readonly ["agent.started", "agent.draining", "agent.stopped", "agent.update_prepared", "agent.update_recovered", "telemetry.queue_overflow"];
+export type AgentTelemetryEvent = (typeof AGENT_TELEMETRY_EVENTS)[number];
+export interface AgentTelemetryConfig {
+    endpoint: string;
+    serviceName: string;
+    instanceId: string;
+    environment: 'production' | 'development';
+    flushIntervalMs: number;
+    traceSampleRatio: number;
+}
+export interface AgentOperationObservation {
+    operation: AgentTelemetryOperation;
+    outcome: AgentTelemetryOutcome;
+    startedAtMs: number;
+    durationMs: number;
+}
+export interface AgentTelemetryState {
+    active: number;
+    completed: number;
+    failed: number;
+    draining: boolean;
+}
+export interface AgentTelemetry {
+    recordOperation(observation: AgentOperationObservation): void;
+    recordEvent(event: AgentTelemetryEvent): void;
+    recordState(state: AgentTelemetryState): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare const AGENT_OTLP_EXPORT_TIMEOUT_MS = 5000;
+export declare const AGENT_OTLP_MAX_ATTEMPTS = 2;
+export declare const AGENT_OTLP_MAX_RETRY_DELAY_MS = 1000;
+export declare const AGENT_TELEMETRY_MAX_SPANS = 256;
+export declare const AGENT_TELEMETRY_MAX_LOGS = 64;
+/** Resolve once at process startup; production refuses to run without an exporter. */
+export declare function resolveAgentTelemetryConfig(env?: Record<string, string | undefined>): AgentTelemetryConfig | null;
+export declare function createAgentTelemetry(input: AgentTelemetryConfig | null, options?: {
+    fetch?: FetchLike;
+    warn?: (message: string) => void;
+    now?: () => number;
+    random?: () => number;
+    wait?: (milliseconds: number) => Promise<void>;
+}): AgentTelemetry;
+export {};

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.31";
+export declare const VERSION = "0.1.33";

package/package.json

@@ -1,7 +1,6 @@
 {
-	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/agent",
-	"version": "0.1.31",
+	"version": "0.1.33",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",
@@ -18,19 +17,20 @@
 		"@noble/post-quantum": "^0.6.1"
 	},
 	"dependencies": {
-		"@forgezero/runtime": "^0.1.4",
-		"@forgezero/vault": "^0.1.7",
-		"@noble/curves": "^2.2.0",
-		"@noble/hashes": "^2.2.0",
-		"@noble/post-quantum": "^0.6.1",
-		"@scure/bip39": "^2.2.0"
+		"@forgezero/runtime": "0.1.5",
+		"@forgezero/vault": "0.1.8",
+		"@noble/curves": "2.2.0",
+		"@noble/hashes": "2.2.0",
+		"@noble/post-quantum": "0.6.1",
+		"@scure/bip39": "2.2.0"
 	},
 	"bin": {
 		"fz-agent": "dist/fz-agent.js",
 		"fz": "dist/fz.js"
 	},
 	"publishConfig": {
-		"access": "public"
+		"access": "public",
+		"provenance": true
 	},
 	"files": [
 		"dist",
@@ -53,7 +53,7 @@
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/forgezero-net/packages.git",
-		"directory": "packages/agent"
+		"directory": "agent"
 	},
 	"bugs": "https://github.com/forgezero-net/packages/issues",
 	"exports": {