@tangle-network/agent-interface 0.19.0 → 0.21.0

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

@@ -0,0 +1,295 @@
+import { z } from "zod";
+export declare const agentCandidateCodeDisabledSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"disabled">;
+    reason: z.ZodEnum<{
+        control: "control";
+        "not-applicable": "not-applicable";
+    }>;
+}, z.core.$strict>;
+export declare const agentCandidateCodeNoOpSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"no-op">;
+    reason: z.ZodLiteral<"proposer-no-change">;
+    repository: z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        owner: z.ZodString;
+        repo: z.ZodString;
+    }, z.core.$strict>;
+    baseCommit: z.ZodString;
+    baseTree: z.ZodString;
+}, z.core.$strict>;
+export declare const agentCandidateGitPatchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"git-patch">;
+    repository: z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        owner: z.ZodString;
+        repo: z.ZodString;
+    }, z.core.$strict>;
+    baseCommit: z.ZodString;
+    baseTree: z.ZodString;
+    candidateTree: z.ZodString;
+    patch: z.ZodObject<{
+        format: z.ZodLiteral<"git-diff-binary">;
+        artifact: 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>;
+}, z.core.$strict>;
+export declare const agentCandidateCodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"disabled">;
+    reason: z.ZodEnum<{
+        control: "control";
+        "not-applicable": "not-applicable";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"no-op">;
+    reason: z.ZodLiteral<"proposer-no-change">;
+    repository: z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        owner: z.ZodString;
+        repo: z.ZodString;
+    }, z.core.$strict>;
+    baseCommit: z.ZodString;
+    baseTree: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"git-patch">;
+    repository: z.ZodObject<{
+        kind: z.ZodLiteral<"github">;
+        owner: z.ZodString;
+        repo: z.ZodString;
+    }, z.core.$strict>;
+    baseCommit: z.ZodString;
+    baseTree: z.ZodString;
+    candidateTree: z.ZodString;
+    patch: z.ZodObject<{
+        format: z.ZodLiteral<"git-diff-binary">;
+        artifact: 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>;
+}, z.core.$strict>], "kind">;
+export declare const agentCandidateContainerSchema: z.ZodObject<{
+    image: z.ZodString;
+    indexDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export declare const agentCandidatePinnedContainerEnvironmentSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"pinned-container">;
+    container: z.ZodObject<{
+        image: z.ZodString;
+        indexDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const agentCandidateEvaluatorTaskEnvironmentSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"evaluator-task-container">;
+}, z.core.$strict>;
+export declare const agentCandidateExecutionEnvironmentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"pinned-container">;
+    container: z.ZodObject<{
+        image: z.ZodString;
+        indexDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"evaluator-task-container">;
+}, z.core.$strict>], "kind">;
+export declare const agentCandidateWorkingDirectorySchema: z.ZodObject<{
+    workspace: z.ZodEnum<{
+        candidate: "candidate";
+        task: "task";
+    }>;
+    path: z.ZodString;
+}, z.core.$strict>;
+export declare const agentCandidateContainerLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"container-command">;
+    executable: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"public">;
+        value: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const agentCandidateEntrypointLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"candidate-entrypoint">;
+    entrypoint: z.ZodString;
+    interpreter: z.ZodOptional<z.ZodEnum<{
+        node: "node";
+        python: "python";
+        python3: "python3";
+        bun: "bun";
+        deno: "deno";
+        tsx: "tsx";
+        uv: "uv";
+    }>>;
+    args: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"public">;
+        value: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const agentCandidateLaunchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"container-command">;
+    executable: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"public">;
+        value: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"candidate-entrypoint">;
+    entrypoint: z.ZodString;
+    interpreter: z.ZodOptional<z.ZodEnum<{
+        node: "node";
+        python: "python";
+        python3: "python3";
+        bun: "bun";
+        deno: "deno";
+        tsx: "tsx";
+        uv: "uv";
+    }>>;
+    args: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"public">;
+        value: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>], "kind">;
+export declare const agentCandidateInstructionDeliverySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"argv-append">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"stdin-utf8">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"utf8-file">;
+    env: z.ZodLiteral<"TANGLE_CANDIDATE_TASK_PATH">;
+    path: z.ZodLiteral<"/tangle/input/task.txt">;
+}, z.core.$strict>], "kind">;
+export declare const agentCandidateExecutionSchema: z.ZodObject<{
+    harness: z.ZodEnum<{
+        "claude-code": "claude-code";
+        claude: "claude";
+        claudish: "claudish";
+        nanoclaw: "nanoclaw";
+        codex: "codex";
+        opencode: "opencode";
+        "kimi-code": "kimi-code";
+        kimi: "kimi";
+        pi: "pi";
+        gemini: "gemini";
+        hermes: "hermes";
+        openclaw: "openclaw";
+        amp: "amp";
+        "factory-droids": "factory-droids";
+        acp: "acp";
+        "cli-base": "cli-base";
+    }>;
+    harnessVersion: z.ZodString;
+    launch: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"container-command">;
+        executable: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodLiteral<"public">;
+            value: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"candidate-entrypoint">;
+        entrypoint: z.ZodString;
+        interpreter: z.ZodOptional<z.ZodEnum<{
+            node: "node";
+            python: "python";
+            python3: "python3";
+            bun: "bun";
+            deno: "deno";
+            tsx: "tsx";
+            uv: "uv";
+        }>>;
+        args: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodLiteral<"public">;
+            value: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>], "kind">;
+    instructionDelivery: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"argv-append">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"stdin-utf8">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"utf8-file">;
+        env: z.ZodLiteral<"TANGLE_CANDIDATE_TASK_PATH">;
+        path: z.ZodLiteral<"/tangle/input/task.txt">;
+    }, z.core.$strict>], "kind">;
+    cwd: z.ZodObject<{
+        workspace: z.ZodEnum<{
+            candidate: "candidate";
+            task: "task";
+        }>;
+        path: z.ZodString;
+    }, z.core.$strict>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodLiteral<"public">;
+        value: z.ZodString;
+    }, z.core.$strict>>>;
+    environment: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"pinned-container">;
+        container: z.ZodObject<{
+            image: z.ZodString;
+            indexDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"evaluator-task-container">;
+    }, z.core.$strict>], "kind">;
+    workspace: z.ZodOptional<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>>;
+    isolation: z.ZodObject<{
+        network: z.ZodLiteral<"disabled">;
+        remoteIntegrations: z.ZodLiteral<"disabled">;
+        candidateSecrets: z.ZodLiteral<"disabled">;
+    }, z.core.$strict>;
+}, z.core.$strict>;

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

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { agentCandidateEmbeddedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
+import { agentCandidateConfigValueSchema, agentCandidateGitHubRepositorySchema, environmentConfigSchema, gitObjectSchema, isObviouslyPrivateHostname, isSafeExecutable, isSafeRelativePath, sameGitObjectFormat, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { harnessTypeSchema } from "./harness.js";
+function isSafeOciImage(value) {
+    if (!/^[A-Za-z0-9._:/-]+$/.test(value) ||
+        /\s/.test(value) ||
+        value.includes("@") ||
+        value.includes("://")) {
+        return false;
+    }
+    const parts = value.split("/");
+    if (parts.length < 2)
+        return true;
+    const first = parts[0] ?? "";
+    const hasExplicitRegistry = first.includes(".") || first.includes(":") || first === "localhost";
+    if (!hasExplicitRegistry)
+        return true;
+    const hostname = first.startsWith("[")
+        ? first.slice(1, first.indexOf("]"))
+        : first.split(":")[0] ?? "";
+    return hostname.length > 0 && !isObviouslyPrivateHostname(hostname);
+}
+const executableSchema = z
+    .string()
+    .refine(isSafeExecutable, "executable must be a canonical non-shell command");
+export const agentCandidateCodeDisabledSchema = z
+    .object({
+    kind: z.literal("disabled"),
+    reason: z.enum(["control", "not-applicable"]),
+})
+    .strict();
+export const agentCandidateCodeNoOpSchema = z
+    .object({
+    kind: z.literal("no-op"),
+    reason: z.literal("proposer-no-change"),
+    repository: agentCandidateGitHubRepositorySchema,
+    baseCommit: gitObjectSchema,
+    baseTree: gitObjectSchema,
+})
+    .strict()
+    .superRefine((code, ctx) => {
+    if (!sameGitObjectFormat(code.baseCommit, code.baseTree)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Git object ids in one code record must use one object format",
+        });
+    }
+});
+export const agentCandidateGitPatchSchema = z
+    .object({
+    kind: z.literal("git-patch"),
+    repository: agentCandidateGitHubRepositorySchema,
+    baseCommit: gitObjectSchema,
+    baseTree: gitObjectSchema,
+    candidateTree: gitObjectSchema,
+    patch: z
+        .object({
+        format: z.literal("git-diff-binary"),
+        artifact: agentCandidateEmbeddedArtifactSchema,
+    })
+        .strict(),
+})
+    .strict()
+    .superRefine((code, ctx) => {
+    if (!sameGitObjectFormat(code.baseCommit, code.baseTree, code.candidateTree)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Git object ids in one code record must use one object format",
+        });
+    }
+    if (code.baseTree === code.candidateTree) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["candidateTree"],
+            message: "git-patch must change the tree; use code.kind='no-op'",
+        });
+    }
+    if (code.patch.artifact.byteLength === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["patch", "artifact", "byteLength"],
+            message: "git-patch must contain bytes; use code.kind='no-op'",
+        });
+    }
+});
+export const agentCandidateCodeSchema = z.discriminatedUnion("kind", [
+    agentCandidateCodeDisabledSchema,
+    agentCandidateCodeNoOpSchema,
+    agentCandidateGitPatchSchema,
+]);
+export const agentCandidateContainerSchema = z
+    .object({
+    image: z
+        .string()
+        .min(1)
+        .refine(isSafeOciImage, "image must be a non-private OCI reference without credentials or an embedded digest"),
+    indexDigest: sha256DigestSchema,
+})
+    .strict();
+export const agentCandidatePinnedContainerEnvironmentSchema = z
+    .object({
+    kind: z.literal("pinned-container"),
+    container: agentCandidateContainerSchema,
+})
+    .strict();
+export const agentCandidateEvaluatorTaskEnvironmentSchema = z
+    .object({
+    kind: z.literal("evaluator-task-container"),
+})
+    .strict();
+export const agentCandidateExecutionEnvironmentSchema = z.discriminatedUnion("kind", [
+    agentCandidatePinnedContainerEnvironmentSchema,
+    agentCandidateEvaluatorTaskEnvironmentSchema,
+]);
+export const agentCandidateWorkingDirectorySchema = z
+    .object({
+    workspace: z.enum(["candidate", "task"]),
+    path: z
+        .string()
+        .refine((value) => isSafeRelativePath(value, true), "cwd path must be a canonical workspace-relative path"),
+})
+    .strict();
+export const agentCandidateContainerLaunchSchema = z
+    .object({
+    kind: z.literal("container-command"),
+    executable: executableSchema,
+    args: z.array(agentCandidateConfigValueSchema).optional(),
+})
+    .strict();
+export const agentCandidateEntrypointLaunchSchema = z
+    .object({
+    kind: z.literal("candidate-entrypoint"),
+    entrypoint: z
+        .string()
+        .refine((value) => isSafeRelativePath(value, false), "entrypoint must be a canonical candidate-relative path"),
+    interpreter: z
+        .enum(["node", "python", "python3", "bun", "deno", "tsx", "uv"])
+        .optional(),
+    args: z.array(agentCandidateConfigValueSchema).optional(),
+})
+    .strict();
+export const agentCandidateLaunchSchema = z.discriminatedUnion("kind", [
+    agentCandidateContainerLaunchSchema,
+    agentCandidateEntrypointLaunchSchema,
+]);
+export const agentCandidateInstructionDeliverySchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("argv-append") }).strict(),
+    z.object({ kind: z.literal("stdin-utf8") }).strict(),
+    z
+        .object({
+        kind: z.literal("utf8-file"),
+        env: z.literal("TANGLE_CANDIDATE_TASK_PATH"),
+        path: z.literal("/tangle/input/task.txt"),
+    })
+        .strict(),
+]);
+export const agentCandidateExecutionSchema = z
+    .object({
+    harness: harnessTypeSchema,
+    harnessVersion: z.string().min(1),
+    launch: agentCandidateLaunchSchema,
+    instructionDelivery: agentCandidateInstructionDeliverySchema,
+    cwd: agentCandidateWorkingDirectorySchema,
+    env: environmentConfigSchema.optional(),
+    environment: agentCandidateExecutionEnvironmentSchema,
+    workspace: agentCandidateWorkspaceSnapshotEvidenceSchema.optional(),
+    isolation: z
+        .object({
+        network: z.literal("disabled"),
+        remoteIntegrations: z.literal("disabled"),
+        candidateSecrets: z.literal("disabled"),
+    })
+        .strict(),
+})
+    .strict()
+    .superRefine((execution, ctx) => {
+    if (execution.env?.TANGLE_CANDIDATE_TASK_PATH !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["env", "TANGLE_CANDIDATE_TASK_PATH"],
+            message: "the evaluator exclusively owns task-instruction delivery",
+        });
+    }
+});