@tangle-network/agent-interface 0.48.0 → 0.49.0

package/dist/environment-observation.d.ts

@@ -0,0 +1,1076 @@
+import { z } from "zod";
+/**
+ * Freshness discriminator for one observed value. A missing value never reads
+ * as a measured zero: a value exists only on `known` and `stale`, so the
+ * absence of a number is always visible as `unavailable`, `redacted`, or
+ * `unknown`.
+ */
+export type ObservationState = "known" | "stale" | "unavailable" | "redacted" | "unknown";
+export declare const ObservationStateSchema: z.ZodEnum<{
+    unknown: "unknown";
+    unavailable: "unavailable";
+    known: "known";
+    stale: "stale";
+    redacted: "redacted";
+}>;
+/** How a known or stale value was obtained, and when. */
+export interface ObservationProvenance {
+    origin: "measured" | "reported" | "estimated";
+    observedAt: string;
+    source?: string;
+}
+export declare const ObservationProvenanceSchema: z.ZodObject<{
+    origin: z.ZodEnum<{
+        estimated: "estimated";
+        measured: "measured";
+        reported: "reported";
+    }>;
+    observedAt: z.ZodISODateTime;
+    source: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * One freshness-tagged value. The security invariant is structural: the
+ * discriminator is required, and `value` is present only when the state is
+ * `known` or `stale`. An `unavailable`, `redacted`, or `unknown` payload
+ * carries no value, so downstream code cannot read a missing measurement as a
+ * real zero.
+ */
+export type Observation<T> = {
+    state: "known";
+    value: T;
+    provenance: ObservationProvenance;
+} | {
+    state: "stale";
+    value: T;
+    provenance: ObservationProvenance;
+    reason: string;
+} | {
+    state: "unavailable";
+    reason: string;
+} | {
+    state: "redacted";
+    reason: string;
+} | {
+    state: "unknown";
+};
+/** Build a freshness-tagged observation schema around one value schema. */
+export declare function observationOf<Schema extends z.ZodTypeAny>(value: Schema): z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"known">;
+    value: Schema;
+    provenance: z.ZodObject<{
+        origin: z.ZodEnum<{
+            estimated: "estimated";
+            measured: "measured";
+            reported: "reported";
+        }>;
+        observedAt: z.ZodISODateTime;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"stale">;
+    value: Schema;
+    provenance: z.ZodObject<{
+        origin: z.ZodEnum<{
+            estimated: "estimated";
+            measured: "measured";
+            reported: "reported";
+        }>;
+        observedAt: z.ZodISODateTime;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"unavailable">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"redacted">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"unknown">;
+}, z.core.$strict>], "state">;
+/** Safe identifiers for the environment and its provider session. */
+export interface ProviderIdentity {
+    provider: string;
+    environmentId: string;
+    sessionId?: string;
+    backend?: string;
+}
+export declare const ProviderIdentitySchema: z.ZodObject<{
+    provider: z.ZodString;
+    environmentId: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    backend: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const AgentEnvironmentStatusSchema: z.ZodEnum<{
+    unknown: "unknown";
+    failed: "failed";
+    expired: "expired";
+    pending: "pending";
+    running: "running";
+    provisioning: "provisioning";
+    stopped: "stopped";
+}>;
+/** Lifecycle, cleanup, continuity, and persistence of one environment. */
+export declare const EnvironmentLifecycleSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        failed: "failed";
+        expired: "expired";
+        pending: "pending";
+        running: "running";
+        provisioning: "provisioning";
+        stopped: "stopped";
+    }>;
+    cleanup: z.ZodOptional<z.ZodObject<{
+        policy: z.ZodOptional<z.ZodEnum<{
+            manual: "manual";
+            idle: "idle";
+            scheduled: "scheduled";
+            "on-exit": "on-exit";
+        }>>;
+        scheduledAt: z.ZodOptional<z.ZodISODateTime>;
+        confirmed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    continuity: z.ZodOptional<z.ZodObject<{
+        resumable: z.ZodBoolean;
+        mode: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            native: "native";
+            replayed: "replayed";
+        }>>;
+    }, z.core.$strict>>;
+    persistence: z.ZodOptional<z.ZodObject<{
+        durable: z.ZodBoolean;
+        scope: z.ZodOptional<z.ZodEnum<{
+            session: "session";
+            durable: "durable";
+            ephemeral: "ephemeral";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type EnvironmentLifecycle = z.infer<typeof EnvironmentLifecycleSchema>;
+/**
+ * Credential-free network location. There is no field for a user, password,
+ * token, or other secret, and the host and scheme reject embedded credentials.
+ */
+export declare const SafeEndpointSchema: z.ZodObject<{
+    scheme: z.ZodOptional<z.ZodString>;
+    host: z.ZodString;
+    port: z.ZodOptional<z.ZodNumber>;
+    region: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SafeEndpoint = z.infer<typeof SafeEndpointSchema>;
+/** Requested or effective compute shape, including an optional accelerator. */
+export declare const ResourceProfileSchema: z.ZodObject<{
+    cpu: z.ZodOptional<z.ZodNumber>;
+    memoryMb: z.ZodOptional<z.ZodNumber>;
+    diskMb: z.ZodOptional<z.ZodNumber>;
+    accelerator: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        count: z.ZodNumber;
+        memoryMb: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResourceProfile = z.infer<typeof ResourceProfileSchema>;
+/** A point-in-time or peak resource sample. */
+export declare const ResourceUseSampleSchema: z.ZodObject<{
+    cpu: z.ZodOptional<z.ZodNumber>;
+    memoryMb: z.ZodOptional<z.ZodNumber>;
+    diskMb: z.ZodOptional<z.ZodNumber>;
+    acceleratorMemoryMb: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ResourceUseSample = z.infer<typeof ResourceUseSampleSchema>;
+/** Where an environment was requested or verified to run. */
+export declare const PlacementDescriptorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        provider: "provider";
+        local: "local";
+        sandbox: "sandbox";
+        fleet: "fleet";
+    }>;
+    sandboxId: z.ZodOptional<z.ZodString>;
+    fleetId: z.ZodOptional<z.ZodString>;
+    machineId: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PlacementDescriptor = z.infer<typeof PlacementDescriptorSchema>;
+/**
+ * Token usage and cost for one execution. Bound to the shared {@link TokenUsage}
+ * type so a change to the canonical shape is caught here.
+ */
+export declare const ModelUsageSchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    totalTokens: z.ZodOptional<z.ZodNumber>;
+    cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    cost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Provider compute cost charged for one environment. */
+export declare const ComputeBillingSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strict>;
+export type ComputeBilling = z.infer<typeof ComputeBillingSchema>;
+/** Account plan, credits, quota, and billing period. */
+export declare const AccountUsageSchema: z.ZodObject<{
+    plan: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodString;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodString;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+    credits: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodObject<{
+            remaining: z.ZodNumber;
+            unit: z.ZodString;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodObject<{
+            remaining: z.ZodNumber;
+            unit: z.ZodString;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+    quota: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodObject<{
+            limit: z.ZodNumber;
+            used: z.ZodNumber;
+            remaining: z.ZodNumber;
+            unit: z.ZodString;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodObject<{
+            limit: z.ZodNumber;
+            used: z.ZodNumber;
+            remaining: z.ZodNumber;
+            unit: z.ZodString;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+    period: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodObject<{
+            start: z.ZodISODateTime;
+            end: z.ZodISODateTime;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodObject<{
+            start: z.ZodISODateTime;
+            end: z.ZodISODateTime;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+}, z.core.$strict>;
+export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+/**
+ * Optional normalized observation of one execution environment.
+ *
+ * `subject` is the always-known identity used to bind a live observation to its
+ * replay. Every other surface is optional and freshness-tagged, so a provider
+ * that reports nothing still validates and no absent value is a measured zero.
+ */
+export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
+    subject: z.ZodObject<{
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        backend: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    capturedAt: z.ZodISODateTime;
+    identity: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodObject<{
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            backend: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodObject<{
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            backend: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+    lifecycle: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodObject<{
+            status: z.ZodEnum<{
+                unknown: "unknown";
+                failed: "failed";
+                expired: "expired";
+                pending: "pending";
+                running: "running";
+                provisioning: "provisioning";
+                stopped: "stopped";
+            }>;
+            cleanup: z.ZodOptional<z.ZodObject<{
+                policy: z.ZodOptional<z.ZodEnum<{
+                    manual: "manual";
+                    idle: "idle";
+                    scheduled: "scheduled";
+                    "on-exit": "on-exit";
+                }>>;
+                scheduledAt: z.ZodOptional<z.ZodISODateTime>;
+                confirmed: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            continuity: z.ZodOptional<z.ZodObject<{
+                resumable: z.ZodBoolean;
+                mode: z.ZodOptional<z.ZodEnum<{
+                    none: "none";
+                    native: "native";
+                    replayed: "replayed";
+                }>>;
+            }, z.core.$strict>>;
+            persistence: z.ZodOptional<z.ZodObject<{
+                durable: z.ZodBoolean;
+                scope: z.ZodOptional<z.ZodEnum<{
+                    session: "session";
+                    durable: "durable";
+                    ephemeral: "ephemeral";
+                }>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodObject<{
+            status: z.ZodEnum<{
+                unknown: "unknown";
+                failed: "failed";
+                expired: "expired";
+                pending: "pending";
+                running: "running";
+                provisioning: "provisioning";
+                stopped: "stopped";
+            }>;
+            cleanup: z.ZodOptional<z.ZodObject<{
+                policy: z.ZodOptional<z.ZodEnum<{
+                    manual: "manual";
+                    idle: "idle";
+                    scheduled: "scheduled";
+                    "on-exit": "on-exit";
+                }>>;
+                scheduledAt: z.ZodOptional<z.ZodISODateTime>;
+                confirmed: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            continuity: z.ZodOptional<z.ZodObject<{
+                resumable: z.ZodBoolean;
+                mode: z.ZodOptional<z.ZodEnum<{
+                    none: "none";
+                    native: "native";
+                    replayed: "replayed";
+                }>>;
+            }, z.core.$strict>>;
+            persistence: z.ZodOptional<z.ZodObject<{
+                durable: z.ZodBoolean;
+                scope: z.ZodOptional<z.ZodEnum<{
+                    session: "session";
+                    durable: "durable";
+                    ephemeral: "ephemeral";
+                }>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+    endpoint: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodObject<{
+            scheme: z.ZodOptional<z.ZodString>;
+            host: z.ZodString;
+            port: z.ZodOptional<z.ZodNumber>;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodObject<{
+            scheme: z.ZodOptional<z.ZodString>;
+            host: z.ZodString;
+            port: z.ZodOptional<z.ZodNumber>;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+    placement: z.ZodOptional<z.ZodObject<{
+        requested: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                provider: "provider";
+                local: "local";
+                sandbox: "sandbox";
+                fleet: "fleet";
+            }>;
+            sandboxId: z.ZodOptional<z.ZodString>;
+            fleetId: z.ZodOptional<z.ZodString>;
+            machineId: z.ZodOptional<z.ZodString>;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        verified: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"known">;
+            value: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    provider: "provider";
+                    local: "local";
+                    sandbox: "sandbox";
+                    fleet: "fleet";
+                }>;
+                sandboxId: z.ZodOptional<z.ZodString>;
+                fleetId: z.ZodOptional<z.ZodString>;
+                machineId: z.ZodOptional<z.ZodString>;
+                region: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"stale">;
+            value: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    provider: "provider";
+                    local: "local";
+                    sandbox: "sandbox";
+                    fleet: "fleet";
+                }>;
+                sandboxId: z.ZodOptional<z.ZodString>;
+                fleetId: z.ZodOptional<z.ZodString>;
+                machineId: z.ZodOptional<z.ZodString>;
+                region: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"redacted">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unknown">;
+        }, z.core.$strict>], "state">>;
+    }, z.core.$strict>>;
+    resources: z.ZodOptional<z.ZodObject<{
+        requested: z.ZodOptional<z.ZodObject<{
+            cpu: z.ZodOptional<z.ZodNumber>;
+            memoryMb: z.ZodOptional<z.ZodNumber>;
+            diskMb: z.ZodOptional<z.ZodNumber>;
+            accelerator: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodString;
+                count: z.ZodNumber;
+                memoryMb: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        effective: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"known">;
+            value: z.ZodObject<{
+                cpu: z.ZodOptional<z.ZodNumber>;
+                memoryMb: z.ZodOptional<z.ZodNumber>;
+                diskMb: z.ZodOptional<z.ZodNumber>;
+                accelerator: z.ZodOptional<z.ZodObject<{
+                    kind: z.ZodString;
+                    count: z.ZodNumber;
+                    memoryMb: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"stale">;
+            value: z.ZodObject<{
+                cpu: z.ZodOptional<z.ZodNumber>;
+                memoryMb: z.ZodOptional<z.ZodNumber>;
+                diskMb: z.ZodOptional<z.ZodNumber>;
+                accelerator: z.ZodOptional<z.ZodObject<{
+                    kind: z.ZodString;
+                    count: z.ZodNumber;
+                    memoryMb: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"redacted">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unknown">;
+        }, z.core.$strict>], "state">>;
+    }, z.core.$strict>>;
+    resourceUse: z.ZodOptional<z.ZodObject<{
+        current: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"known">;
+            value: z.ZodObject<{
+                cpu: z.ZodOptional<z.ZodNumber>;
+                memoryMb: z.ZodOptional<z.ZodNumber>;
+                diskMb: z.ZodOptional<z.ZodNumber>;
+                acceleratorMemoryMb: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"stale">;
+            value: z.ZodObject<{
+                cpu: z.ZodOptional<z.ZodNumber>;
+                memoryMb: z.ZodOptional<z.ZodNumber>;
+                diskMb: z.ZodOptional<z.ZodNumber>;
+                acceleratorMemoryMb: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"redacted">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unknown">;
+        }, z.core.$strict>], "state">>;
+        peak: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"known">;
+            value: z.ZodObject<{
+                cpu: z.ZodOptional<z.ZodNumber>;
+                memoryMb: z.ZodOptional<z.ZodNumber>;
+                diskMb: z.ZodOptional<z.ZodNumber>;
+                acceleratorMemoryMb: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"stale">;
+            value: z.ZodObject<{
+                cpu: z.ZodOptional<z.ZodNumber>;
+                memoryMb: z.ZodOptional<z.ZodNumber>;
+                diskMb: z.ZodOptional<z.ZodNumber>;
+                acceleratorMemoryMb: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"redacted">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unknown">;
+        }, z.core.$strict>], "state">>;
+    }, z.core.$strict>>;
+    modelUsage: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            totalTokens: z.ZodOptional<z.ZodNumber>;
+            cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+            cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+            reasoningTokens: z.ZodOptional<z.ZodNumber>;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            totalTokens: z.ZodOptional<z.ZodNumber>;
+            cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+            cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+            reasoningTokens: z.ZodOptional<z.ZodNumber>;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+    computeBilling: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"known">;
+        value: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"stale">;
+        value: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strict>;
+        provenance: z.ZodObject<{
+            origin: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+                reported: "reported";
+            }>;
+            observedAt: z.ZodISODateTime;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"redacted">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+    }, z.core.$strict>], "state">>;
+    accountUsage: z.ZodOptional<z.ZodObject<{
+        plan: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"known">;
+            value: z.ZodString;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"stale">;
+            value: z.ZodString;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"redacted">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unknown">;
+        }, z.core.$strict>], "state">>;
+        credits: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"known">;
+            value: z.ZodObject<{
+                remaining: z.ZodNumber;
+                unit: z.ZodString;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"stale">;
+            value: z.ZodObject<{
+                remaining: z.ZodNumber;
+                unit: z.ZodString;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"redacted">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unknown">;
+        }, z.core.$strict>], "state">>;
+        quota: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"known">;
+            value: z.ZodObject<{
+                limit: z.ZodNumber;
+                used: z.ZodNumber;
+                remaining: z.ZodNumber;
+                unit: z.ZodString;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"stale">;
+            value: z.ZodObject<{
+                limit: z.ZodNumber;
+                used: z.ZodNumber;
+                remaining: z.ZodNumber;
+                unit: z.ZodString;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"redacted">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unknown">;
+        }, z.core.$strict>], "state">>;
+        period: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"known">;
+            value: z.ZodObject<{
+                start: z.ZodISODateTime;
+                end: z.ZodISODateTime;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"stale">;
+            value: z.ZodObject<{
+                start: z.ZodISODateTime;
+                end: z.ZodISODateTime;
+            }, z.core.$strict>;
+            provenance: z.ZodObject<{
+                origin: z.ZodEnum<{
+                    estimated: "estimated";
+                    measured: "measured";
+                    reported: "reported";
+                }>;
+                observedAt: z.ZodISODateTime;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"redacted">;
+            reason: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unknown">;
+        }, z.core.$strict>], "state">>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AgentEnvironmentObservation = z.infer<typeof AgentEnvironmentObservationSchema>;
+/**
+ * A live observation and its replay must name the same environment and the
+ * same observed identity and provenance source. Time and freshness may differ,
+ * but the identifiers may not.
+ */
+export declare function agentEnvironmentObservationIdentityMatches(live: AgentEnvironmentObservation, replay: AgentEnvironmentObservation): boolean;
+/**
+ * Report whether an observation payload carries a credential. A credential is a
+ * secret-shaped object key or a string value with embedded userinfo. Contract
+ * tests use this to prove the observation surface never transports a secret.
+ */
+export declare function observationContainsCredential(value: unknown): boolean;
+/** Throw when an observation payload carries a credential. */
+export declare function assertObservationCredentialFree(value: unknown): void;