@tangle-network/agent-interface 0.20.0 → 0.22.0

package/README.md

@@ -62,6 +62,30 @@ const provider: AgentEnvironmentProvider = {
 };
 ```
 
+## Frozen improvement candidates
+
+`AgentCandidateBundle` is the portable output of an improvement run: a recursively strict profile, an explicit disabled/no-op/changed code result, a shell-free launch, optional knowledge, isolated memory, ancestry, and spend.
+Execution either pins a candidate-selected container in the bundle or delegates container selection to the benchmark evaluator.
+For evaluator-owned task images, the protected runtime creates a separate plan for every candidate/task pair and binds the root repository, exact Git base, exact UTF-8 instruction bytes, selected OCI index, manifest, platform, task workspace, model, launch, counted attempt, retry policy, and tool-step limit before execution.
+Instruction delivery is closed to one final argv element, exact stdin bytes followed by EOF, or a fixed file path exposed through `TANGLE_CANDIDATE_TASK_PATH`.
+That plan also binds the profile target workspace and every mounted path; benchmark adapters must restore or exclude task-targeted profile paths before capturing the submitted solution patch.
+Resources are embedded, addressed through closed S3/IPFS locators, or pinned to a full GitHub commit plus content digest.
+Candidate-authored process configuration is explicitly public; model authorization is evaluator-mediated and secret values never belong in the bundle.
+Because prompts and inline files are arbitrary text, producers must also run their normal secret scanner before persistence.
+Candidate v1 rejects unregistered backend extensions instead of accepting an untyped behavior or credential channel.
+
+`agentCandidateBundleSchema.parse()` proves only that the wire shape is valid.
+Before execution, an integrity verifier must omit only the top-level `digest`, canonicalize the rest with RFC 8785, hash the UTF-8 bytes to lowercase `sha256:<hex>`, verify every artifact, apply any Git patch to the declared base tree, and emit an `AgentCandidateMaterializationReceipt`.
+Artifact and OCI resolvers must also reject redirects or DNS results that reach loopback, private, or link-local addresses; schema parsing cannot prove network resolution safety.
+Attach the materialization and `AgentCandidateRunReceipt` records to the benchmark run so the result names the exact profile plan, code tree, launch plan, selected OCI manifest/platform and source, model, memory isolation, trace, termination, harness, and container that ran.
+A timeout, signal, or cancellation remains distinct from a process exit; if the protected evaluator cannot recover complete usage and trace evidence, it must mark the cell as invalid capture instead of minting a zero-usage receipt.
+
+The three code states are intentionally distinct:
+
+- `{ kind: "disabled", reason: "control" }` is the fixed control; `reason: "not-applicable"` keeps code unchanged while another surface is optimized.
+- `{ kind: "no-op" }` means a proposer ran and returned no change.
+- `{ kind: "git-patch" }` carries a non-empty binary Git diff whose resulting tree must be verified.
+
 ## License
 
 MIT

package/dist/agent-candidate-artifact-schema.d.ts

@@ -0,0 +1,311 @@
+import { z } from "zod";
+export declare const agentCandidateS3LocatorSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"s3">;
+    bucket: z.ZodString;
+    key: z.ZodString;
+    region: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const agentCandidateIpfsLocatorSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"ipfs">;
+    cid: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const agentCandidateArtifactLocatorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"s3">;
+    bucket: z.ZodString;
+    key: z.ZodString;
+    region: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"ipfs">;
+    cid: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "kind">;
+export declare const agentCandidateArtifactRefSchema: z.ZodObject<{
+    locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"s3">;
+        bucket: z.ZodString;
+        key: z.ZodString;
+        region: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"ipfs">;
+        cid: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "kind">;
+    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>;
+export declare const agentCandidateEmbeddedArtifactSchema: z.ZodObject<{
+    encoding: z.ZodLiteral<"base64">;
+    content: z.ZodString;
+    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>;
+export declare const agentCandidateCapturedArtifactSchema: z.ZodUnion<readonly [z.ZodObject<{
+    locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"s3">;
+        bucket: z.ZodString;
+        key: z.ZodString;
+        region: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"ipfs">;
+        cid: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "kind">;
+    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    encoding: z.ZodLiteral<"base64">;
+    content: z.ZodString;
+    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>]>;
+export declare const agentCandidateWorkspaceManifestMaterialSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"agent-candidate-workspace-manifest">;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        mode: z.ZodUnion<readonly [z.ZodLiteral<420>, z.ZodLiteral<493>]>;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const agentCandidateWorkspaceSnapshotEvidenceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    material: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        kind: z.ZodLiteral<"agent-candidate-workspace-manifest">;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mode: z.ZodUnion<readonly [z.ZodLiteral<420>, z.ZodLiteral<493>]>;
+            sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    manifest: z.ZodUnion<readonly [z.ZodObject<{
+        locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"s3">;
+            bucket: z.ZodString;
+            key: z.ZodString;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"ipfs">;
+            cid: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "kind">;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        encoding: z.ZodLiteral<"base64">;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>]>;
+    archive: z.ZodUnion<readonly [z.ZodObject<{
+        locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"s3">;
+            bucket: z.ZodString;
+            key: z.ZodString;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"ipfs">;
+            cid: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "kind">;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        encoding: z.ZodLiteral<"base64">;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export declare function validateEmbeddedArtifact(artifact: {
+    content: string;
+    byteLength: number;
+}, ctx: z.RefinementCtx): void;
+export declare const agentCandidateInlineResourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"inline">;
+    name: z.ZodString;
+    content: z.ZodString;
+    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>;
+export declare const agentCandidateGitHubResourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"github">;
+    repository: z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        owner: z.ZodString;
+        repo: z.ZodString;
+    }, z.core.$strict>;
+    path: z.ZodString;
+    commit: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>;
+export declare const agentCandidateResourceRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"inline">;
+    name: z.ZodString;
+    content: z.ZodString;
+    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"github">;
+    repository: z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        owner: z.ZodString;
+        repo: z.ZodString;
+    }, z.core.$strict>;
+    path: z.ZodString;
+    commit: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+export declare const agentCandidateFileMountSchema: z.ZodObject<{
+    path: z.ZodString;
+    resource: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"inline">;
+        name: z.ZodString;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        repository: z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            owner: z.ZodString;
+            repo: z.ZodString;
+        }, z.core.$strict>;
+        path: z.ZodString;
+        commit: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>], "kind">;
+    executable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const agentCandidateResourcesSchema: z.ZodObject<{
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        resource: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"inline">;
+            name: z.ZodString;
+            content: z.ZodString;
+            sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            repository: z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                owner: z.ZodString;
+                repo: z.ZodString;
+            }, z.core.$strict>;
+            path: z.ZodString;
+            commit: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>], "kind">;
+        executable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"inline">;
+        name: z.ZodString;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        repository: z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            owner: z.ZodString;
+            repo: z.ZodString;
+        }, z.core.$strict>;
+        path: z.ZodString;
+        commit: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>], "kind">>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"inline">;
+        name: z.ZodString;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        repository: z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            owner: z.ZodString;
+            repo: z.ZodString;
+        }, z.core.$strict>;
+        path: z.ZodString;
+        commit: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>], "kind">>>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"inline">;
+        name: z.ZodString;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        repository: z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            owner: z.ZodString;
+            repo: z.ZodString;
+        }, z.core.$strict>;
+        path: z.ZodString;
+        commit: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>], "kind">>>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"inline">;
+        name: z.ZodString;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        repository: z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            owner: z.ZodString;
+            repo: z.ZodString;
+        }, z.core.$strict>;
+        path: z.ZodString;
+        commit: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>], "kind">>>;
+    instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"inline">;
+        name: z.ZodString;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        repository: z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            owner: z.ZodString;
+            repo: z.ZodString;
+        }, z.core.$strict>;
+        path: z.ZodString;
+        commit: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>], "kind">]>>;
+    failOnError: z.ZodLiteral<true>;
+}, z.core.$strict>;

package/dist/agent-candidate-artifact-schema.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+import { agentCandidateGitHubRepositorySchema, gitObjectSchema, isSafeRelativePath, isWellFormedUnicode, looksLikeCredential, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+const base64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const base64Alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const s3BucketPattern = /^(?!\d+\.\d+\.\d+\.\d+$)[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
+const awsRegionPattern = /^[a-z]{2}(?:-gov)?-[a-z]+-\d$/;
+const ipfsCidPattern = /^(?:Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{20,})$/;
+function decodedBase64ByteLength(value) {
+    if (value.length === 0)
+        return 0;
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    return (value.length / 4) * 3 - padding;
+}
+function hasCanonicalBase64Padding(value) {
+    if (value.endsWith("==")) {
+        const index = base64Alphabet.indexOf(value.at(-3) ?? "");
+        return index >= 0 && (index & 0x0f) === 0;
+    }
+    if (value.endsWith("=")) {
+        const index = base64Alphabet.indexOf(value.at(-2) ?? "");
+        return index >= 0 && (index & 0x03) === 0;
+    }
+    return true;
+}
+export const agentCandidateS3LocatorSchema = z
+    .object({
+    kind: z.literal("s3"),
+    bucket: z.string().regex(s3BucketPattern),
+    key: z
+        .string()
+        .refine((value) => isSafeRelativePath(value, false) && !looksLikeCredential(value), "S3 key must be a canonical relative artifact path"),
+    region: z.string().regex(awsRegionPattern).optional(),
+})
+    .strict();
+export const agentCandidateIpfsLocatorSchema = z
+    .object({
+    kind: z.literal("ipfs"),
+    cid: z.string().regex(ipfsCidPattern),
+    path: z
+        .string()
+        .refine((value) => isSafeRelativePath(value, false) && !looksLikeCredential(value), "IPFS path must be a canonical relative artifact path")
+        .optional(),
+})
+    .strict();
+export const agentCandidateArtifactLocatorSchema = z.discriminatedUnion("kind", [agentCandidateS3LocatorSchema, agentCandidateIpfsLocatorSchema]);
+export const agentCandidateArtifactRefSchema = z
+    .object({
+    locator: agentCandidateArtifactLocatorSchema,
+    sha256: sha256DigestSchema,
+    byteLength: z.number().int().nonnegative(),
+})
+    .strict();
+export const agentCandidateEmbeddedArtifactSchema = z
+    .object({
+    encoding: z.literal("base64"),
+    content: z.string().regex(base64Pattern),
+    sha256: sha256DigestSchema,
+    byteLength: z.number().int().nonnegative(),
+})
+    .strict()
+    .superRefine(validateEmbeddedArtifact);
+export const agentCandidateCapturedArtifactSchema = z.union([
+    agentCandidateArtifactRefSchema,
+    agentCandidateEmbeddedArtifactSchema,
+]);
+export const agentCandidateWorkspaceManifestMaterialSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-workspace-manifest"),
+    files: z.array(z
+        .object({
+        path: z
+            .string()
+            .refine((value) => isSafeRelativePath(value, false), "workspace manifest paths must be canonical and relative"),
+        mode: z.union([z.literal(0o644), z.literal(0o755)]),
+        sha256: sha256DigestSchema,
+        byteLength: z.number().int().nonnegative(),
+    })
+        .strict()),
+})
+    .strict()
+    .superRefine((material, ctx) => {
+    for (let index = 1; index < material.files.length; index++) {
+        const previous = material.files[index - 1]?.path ?? "";
+        const current = material.files[index]?.path ?? "";
+        if (previous >= current) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["files", index, "path"],
+                message: "workspace manifest paths must be unique and lexicographically sorted",
+            });
+        }
+    }
+});
+export const agentCandidateWorkspaceSnapshotEvidenceSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-workspace-snapshot"),
+    digest: sha256DigestSchema,
+    material: agentCandidateWorkspaceManifestMaterialSchema,
+    manifest: agentCandidateCapturedArtifactSchema,
+    archive: agentCandidateCapturedArtifactSchema,
+})
+    .strict()
+    .superRefine((evidence, ctx) => {
+    if (evidence.manifest.sha256 !== evidence.digest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["manifest", "sha256"],
+            message: "workspace digest must equal the canonical manifest hash",
+        });
+    }
+    if (evidence.manifest.byteLength === 0 || evidence.archive.byteLength === 0) {
+        ctx.addIssue({
+            code: "custom",
+            message: "workspace evidence requires non-empty manifest and archive bytes",
+        });
+    }
+});
+export function validateEmbeddedArtifact(artifact, ctx) {
+    if (!hasCanonicalBase64Padding(artifact.content)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["content"],
+            message: "base64 content must use canonical zero padding bits",
+        });
+    }
+    if (decodedBase64ByteLength(artifact.content) !== artifact.byteLength) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["byteLength"],
+            message: "byteLength must match the decoded base64 content",
+        });
+    }
+}
+export const agentCandidateInlineResourceSchema = z
+    .object({
+    kind: z.literal("inline"),
+    name: z.string().min(1).refine(isWellFormedUnicode),
+    content: z.string().refine(isWellFormedUnicode),
+    sha256: sha256DigestSchema,
+    byteLength: z.number().int().nonnegative(),
+})
+    .strict()
+    .superRefine((resource, ctx) => {
+    if (new TextEncoder().encode(resource.content).byteLength !== resource.byteLength) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["byteLength"],
+            message: "byteLength must match UTF-8 content",
+        });
+    }
+});
+export const agentCandidateGitHubResourceSchema = z
+    .object({
+    kind: z.literal("github"),
+    repository: agentCandidateGitHubRepositorySchema,
+    path: z
+        .string()
+        .refine((value) => isSafeRelativePath(value, false), "path must be a canonical repository-relative path"),
+    commit: gitObjectSchema,
+    name: z.string().min(1).refine(isWellFormedUnicode).optional(),
+    sha256: sha256DigestSchema,
+    byteLength: z.number().int().nonnegative(),
+})
+    .strict();
+export const agentCandidateResourceRefSchema = z.discriminatedUnion("kind", [
+    agentCandidateInlineResourceSchema,
+    agentCandidateGitHubResourceSchema,
+]);
+export const agentCandidateFileMountSchema = z
+    .object({
+    path: z
+        .string()
+        .refine((value) => isSafeRelativePath(value, false), "mount path must be a canonical workspace-relative path"),
+    resource: agentCandidateResourceRefSchema,
+    executable: z.boolean().optional(),
+})
+    .strict();
+export const agentCandidateResourcesSchema = z
+    .object({
+    files: z.array(agentCandidateFileMountSchema).optional(),
+    tools: z.array(agentCandidateResourceRefSchema).optional(),
+    skills: z.array(agentCandidateResourceRefSchema).optional(),
+    agents: z.array(agentCandidateResourceRefSchema).optional(),
+    commands: z.array(agentCandidateResourceRefSchema).optional(),
+    instructions: z
+        .union([z.string().refine(isWellFormedUnicode), agentCandidateResourceRefSchema])
+        .optional(),
+    failOnError: z.literal(true),
+})
+    .strict();