@tangle-network/agent-interface 0.44.0 → 0.46.0

package/dist/workspace-fork.js

@@ -0,0 +1,267 @@
+import { z } from "zod";
+import { AgentExactRunControlRefSchema } from "./runtime-control.js";
+import { idSchema, jsonRecordSchema, sameOptionalWireValue, sha256DigestSchema, wireDigest } from "./workspace-branching-shared.js";
+import { WorkspaceCheckpointRefSchema } from "./workspace-checkpoint.js";
+import { ConfidentialAttestationSchema, ConfidentialExecutionRequestSchema, confidentialExecutionVerified, } from "./workspace-confidentiality.js";
+import { boundedStringSchema } from "./contract-limits.js";
+const PlacementInfoSchema = z.strictObject({
+    kind: z.enum(["local", "sandbox", "fleet", "provider"]),
+    sandboxId: idSchema.optional(),
+    fleetId: idSchema.optional(),
+    machineId: idSchema.optional(),
+    region: idSchema.optional(),
+    providerMetadata: jsonRecordSchema.optional(),
+});
+const WorkspaceForkMaterialSchema = z.strictObject({
+    checkpoint: WorkspaceCheckpointRefSchema,
+    name: idSchema.optional(),
+    metadata: jsonRecordSchema.optional(),
+    placement: PlacementInfoSchema,
+    confidential: ConfidentialExecutionRequestSchema.optional(),
+});
+export function workspaceForkRequestDigest(material) {
+    const parsed = WorkspaceForkMaterialSchema.parse(material);
+    return wireDigest({
+        checkpoint: parsed.checkpoint,
+        ...(parsed.name === undefined ? {} : { name: parsed.name }),
+        ...(parsed.metadata === undefined ? {} : { metadata: parsed.metadata }),
+        placement: parsed.placement,
+        ...(parsed.confidential === undefined
+            ? {}
+            : { confidential: parsed.confidential }),
+    });
+}
+export const WorkspaceForkRequestSchema = z
+    .strictObject({
+    checkpoint: WorkspaceCheckpointRefSchema,
+    name: idSchema.optional(),
+    metadata: jsonRecordSchema.optional(),
+    placement: PlacementInfoSchema,
+    confidential: ConfidentialExecutionRequestSchema.optional(),
+    idempotencyKey: idSchema,
+    requestDigest: sha256DigestSchema,
+})
+    .superRefine((request, refinement) => {
+    if (request.requestDigest !==
+        workspaceForkRequestDigest({
+            checkpoint: request.checkpoint,
+            name: request.name,
+            metadata: request.metadata,
+            placement: request.placement,
+            confidential: request.confidential,
+        })) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["requestDigest"],
+            message: "fork request digest does not match its material",
+        });
+    }
+    if (request.confidential?.requested === true &&
+        (request.confidential.nonce === undefined ||
+            request.confidential.policy === undefined ||
+            request.confidential.profileDigest === undefined)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["confidential"],
+            message: "a confidential fork request must bind a nonce, policy, and profile digest",
+        });
+    }
+});
+export const ForkedEnvironmentRefSchema = z
+    .strictObject({
+    provider: idSchema,
+    environmentId: idSchema,
+    sourceEnvironmentId: idSchema,
+    source: AgentExactRunControlRefSchema,
+    sourceCheckpointId: idSchema,
+    idempotencyKey: idSchema,
+    requestDigest: sha256DigestSchema,
+    createdAt: z.iso.datetime().max(64),
+    placement: PlacementInfoSchema,
+    confidentialRequested: z.boolean(),
+    confidentialAttestation: ConfidentialAttestationSchema.optional(),
+    confidential: z.boolean().optional(),
+    metadata: jsonRecordSchema.optional(),
+})
+    .superRefine((environment, refinement) => {
+    if (environment.environmentId === environment.sourceEnvironmentId) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["environmentId"],
+            message: "a forked environment must differ from its source environment",
+        });
+    }
+    if (environment.source.environmentId !== environment.sourceEnvironmentId) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["sourceEnvironmentId"],
+            message: "source environment id must match the complete source identity",
+        });
+    }
+    if (environment.provider !== environment.source.provider) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["provider"],
+            message: "fork provider must match the source provider",
+        });
+    }
+    if (environment.confidentialAttestation !== undefined &&
+        environment.confidentialAttestation.environmentId !==
+            environment.environmentId) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["confidentialAttestation", "environmentId"],
+            message: "attestation must be bound to the forked environment",
+        });
+    }
+    if (environment.confidentialAttestation !== undefined &&
+        environment.confidentialRequested !== true) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["confidentialAttestation"],
+            message: "attestation cannot accompany a fork that did not request confidentiality",
+        });
+    }
+});
+/** The only supported way to decide whether a fork may be shown confidential. */
+export function forkedEnvironmentConfidentialityVerified(request, environment, verifyProviderAttestation) {
+    const parsedRequest = WorkspaceForkRequestSchema.safeParse(request);
+    const parsedEnvironment = ForkedEnvironmentRefSchema.safeParse(environment);
+    if (!parsedRequest.success || !parsedEnvironment.success)
+        return false;
+    const exactRequest = parsedRequest.data;
+    const exactEnvironment = parsedEnvironment.data;
+    if (exactEnvironment.requestDigest !== exactRequest.requestDigest ||
+        exactEnvironment.provider !== exactRequest.checkpoint.provider ||
+        exactEnvironment.sourceCheckpointId !== exactRequest.checkpoint.checkpointId ||
+        exactEnvironment.sourceEnvironmentId !== exactRequest.checkpoint.source.environmentId ||
+        wireDigest(exactEnvironment.source) !==
+            wireDigest(exactRequest.checkpoint.source) ||
+        wireDigest(exactEnvironment.placement) !==
+            wireDigest(exactRequest.placement) ||
+        !sameOptionalWireValue(exactEnvironment.metadata, exactRequest.metadata)) {
+        return false;
+    }
+    return confidentialExecutionVerified({
+        request: exactRequest.confidential ?? { requested: false },
+        environment: {
+            provider: exactEnvironment.provider,
+            environmentId: exactEnvironment.environmentId,
+            source: exactEnvironment.source,
+            requestDigest: exactEnvironment.requestDigest,
+            confidentialRequested: exactEnvironment.confidentialRequested,
+        },
+        attestation: parsedEnvironment.data.confidentialAttestation,
+        ...(verifyProviderAttestation ? { verifyProviderAttestation } : {}),
+    });
+}
+const forkOperationBase = {
+    idempotencyKey: idSchema,
+    requestDigest: sha256DigestSchema,
+};
+export const WorkspaceForkResultSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.enum(["created", "replayed"]),
+        ...forkOperationBase,
+        environment: ForkedEnvironmentRefSchema,
+    }),
+    z.strictObject({
+        status: z.literal("conflict"),
+        ...forkOperationBase,
+        existingRequestDigest: sha256DigestSchema,
+    }),
+    z.strictObject({
+        status: z.literal("unknown"),
+        ...forkOperationBase,
+        message: boundedStringSchema.min(1),
+        retryable: z.boolean(),
+    }),
+]).superRefine((result, refinement) => {
+    if ((result.status === "created" || result.status === "replayed") &&
+        (result.environment.idempotencyKey !== result.idempotencyKey ||
+            result.environment.requestDigest !== result.requestDigest)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["environment"],
+            message: "forked environment identity must match its operation",
+        });
+    }
+    if (result.status === "conflict" &&
+        result.existingRequestDigest === result.requestDigest) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["existingRequestDigest"],
+            message: "a conflict must identify a different existing request",
+        });
+    }
+});
+export const WorkspaceForkLookupResultSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("found"),
+        ...forkOperationBase,
+        environment: ForkedEnvironmentRefSchema,
+    }),
+    z.strictObject({ status: z.literal("not_found"), ...forkOperationBase }),
+    z.strictObject({
+        status: z.literal("conflict"),
+        ...forkOperationBase,
+        existingRequestDigest: sha256DigestSchema,
+    }),
+    z.strictObject({
+        status: z.literal("unknown"),
+        ...forkOperationBase,
+        message: boundedStringSchema.min(1),
+        retryable: z.boolean(),
+    }),
+]).superRefine((result, refinement) => {
+    if (result.status === "found" &&
+        (result.environment.idempotencyKey !== result.idempotencyKey ||
+            result.environment.requestDigest !== result.requestDigest)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["environment"],
+            message: "forked environment identity must match its lookup operation",
+        });
+    }
+    if (result.status === "conflict" &&
+        result.existingRequestDigest === result.requestDigest) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["existingRequestDigest"],
+            message: "a conflict must identify a different existing request",
+        });
+    }
+});
+export function workspaceForkResultMatchesRequest(request, result) {
+    const parsedRequest = WorkspaceForkRequestSchema.safeParse(request);
+    const parsedResult = WorkspaceForkResultSchema.safeParse(result);
+    const parsedLookup = WorkspaceForkLookupResultSchema.safeParse(result);
+    if (!parsedRequest.success)
+        return false;
+    const exactRequest = parsedRequest.data;
+    if (parsedResult.success &&
+        (parsedResult.data.status === "created" ||
+            parsedResult.data.status === "replayed")) {
+        return forkResultMatchesParsed(exactRequest, parsedResult.data);
+    }
+    if (parsedLookup.success && parsedLookup.data.status === "found") {
+        return forkResultMatchesParsed(exactRequest, parsedLookup.data);
+    }
+    return false;
+}
+function forkResultMatchesParsed(request, result) {
+    const source = request.checkpoint.source;
+    return (result.idempotencyKey === request.idempotencyKey &&
+        result.requestDigest === request.requestDigest &&
+        result.environment.idempotencyKey === request.idempotencyKey &&
+        result.environment.requestDigest === request.requestDigest &&
+        result.environment.sourceCheckpointId === request.checkpoint.checkpointId &&
+        result.environment.provider === request.checkpoint.provider &&
+        result.environment.sourceEnvironmentId === source.environmentId &&
+        wireDigest(result.environment.source) === wireDigest(source) &&
+        result.environment.environmentId !== source.environmentId &&
+        wireDigest(result.environment.placement) === wireDigest(request.placement) &&
+        result.environment.confidentialRequested ===
+            (request.confidential?.requested ?? false) &&
+        sameOptionalWireValue(result.environment.metadata, request.metadata));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",