@tangle-network/agent-interface 0.19.0 → 0.21.0

package/dist/agent-candidate-execution-plan-schema.js

@@ -0,0 +1,418 @@
+import { z } from "zod";
+import { agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
+import { agentCandidateContainerSchema, agentCandidateInstructionDeliverySchema, agentCandidateWorkingDirectorySchema, } from "./agent-candidate-code-schema.js";
+import { addDuplicateIssues, agentCandidateConfigValueSchema, environmentConfigSchema, gitObjectSchema, isCanonicalJsonValue, isSafeExecutable, isSafeRelativePath, sameGitObjectFormat, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { harnessTypeSchema } from "./harness.js";
+const reasoningEffortSchema = z.enum([
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "ultracode",
+]);
+function isCanonicalAbsolutePath(value) {
+    return (value.startsWith("/") &&
+        value !== "/" &&
+        !value.includes("//") &&
+        isSafeRelativePath(value.slice(1), false));
+}
+function pathsOverlap(left, right) {
+    return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+export const agentCandidateResolvedModelSchema = z
+    .object({
+    requested: z.string().min(1),
+    provider: z.string().min(1),
+    model: z.string().min(1),
+    snapshot: z.string().min(1),
+    reasoningEffort: reasoningEffortSchema,
+})
+    .strict();
+export const agentCandidateProfilePlanMaterialSchema = z
+    .object({
+    version: z.literal(1),
+    harness: harnessTypeSchema,
+    files: z.array(z
+        .object({
+        relPath: z
+            .string()
+            .refine((value) => isSafeRelativePath(value, false), "profile-plan file must use a canonical relative path"),
+        mode: z.number().int().min(0).max(0o777),
+        contentSha256: sha256DigestSchema,
+    })
+        .strict()),
+    env: environmentConfigSchema,
+    flags: z.array(agentCandidateConfigValueSchema),
+    unsupported: z
+        .array(z
+        .object({
+        dimension: z.string().min(1),
+        reason: z.string().min(1),
+    })
+        .strict())
+        .length(0, "sealed candidate materialization cannot omit profile behavior"),
+})
+    .strict()
+    .superRefine((material, ctx) => {
+    addDuplicateIssues(material.files.map((file) => file.relPath), ["files"], ctx);
+    for (let index = 1; index < material.files.length; index++) {
+        if ((material.files[index - 1]?.relPath ?? "") >=
+            (material.files[index]?.relPath ?? "")) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["files", index, "relPath"],
+                message: "profile-plan files must be lexicographically sorted",
+            });
+        }
+    }
+    if (!isCanonicalJsonValue(material)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "profile-plan material must contain only RFC 8785 JSON values",
+        });
+    }
+});
+export const agentCandidateEffectiveMemorySchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("disabled") }).strict(),
+    z
+        .object({
+        mode: z.literal("isolated"),
+        scope: z.literal("task"),
+        effectiveNamespace: z.string().min(1),
+        reset: z
+            .object({
+            kind: z.literal("fresh"),
+            evidence: agentCandidateCapturedArtifactSchema,
+            emptyStateDigest: sha256DigestSchema,
+        })
+            .strict(),
+        beforeState: agentCandidateWorkspaceSnapshotEvidenceSchema,
+        seedDigest: sha256DigestSchema.optional(),
+    })
+        .strict()
+        .superRefine((memory, ctx) => {
+        if (memory.reset.evidence.byteLength === 0) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["reset", "evidence", "byteLength"],
+                message: "task-scoped memory requires non-empty fresh-reset evidence",
+            });
+        }
+    }),
+]);
+export const agentCandidateExecutionLimitsSchema = z
+    .object({
+    timeoutMs: z.number().int().positive(),
+    maxSteps: z.number().int().positive(),
+    maxModelCalls: z.number().int().nonnegative(),
+    maxInputTokens: z.number().int().nonnegative(),
+    maxOutputTokens: z.number().int().nonnegative(),
+    maxCostUsd: z.number().finite().nonnegative(),
+})
+    .strict();
+export const agentCandidateExecutionPlanMaterialSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-execution-plan-material"),
+    bundleDigest: sha256DigestSchema,
+    executionId: z.string().min(1),
+    attempt: z
+        .object({
+        number: z.number().int().min(1),
+        maxAttempts: z.number().int().min(1),
+        retryPolicy: z.enum(["pre-model-infrastructure-only", "none"]),
+    })
+        .strict(),
+    task: z
+        .object({
+        benchmark: z.string().min(1),
+        benchmarkVersion: z.string().min(1),
+        taskId: z.string().min(1),
+        splitDigest: sha256DigestSchema,
+        instruction: z
+            .object({
+            encoding: z.literal("utf8"),
+            sha256: sha256DigestSchema,
+            byteLength: z.number().int().positive(),
+            delivery: agentCandidateInstructionDeliverySchema,
+        })
+            .strict(),
+        repository: z
+            .object({
+            identity: z.string().min(1),
+            rootIdentity: z.string().min(1),
+            baseCommit: gitObjectSchema,
+            baseTree: gitObjectSchema,
+        })
+            .strict(),
+        workspace: agentCandidateWorkspaceSnapshotEvidenceSchema,
+    })
+        .strict(),
+    workspaces: z
+        .object({
+        taskRoot: z
+            .string()
+            .refine(isCanonicalAbsolutePath, "task root must be a canonical absolute path"),
+        candidateRoot: z
+            .string()
+            .refine(isCanonicalAbsolutePath, "candidate root must be a canonical absolute path")
+            .optional(),
+    })
+        .strict(),
+    codeKind: z.enum(["disabled", "no-op", "git-patch"]),
+    candidateWorkspace: agentCandidateWorkspaceSnapshotEvidenceSchema.optional(),
+    profile: z
+        .object({
+        planDigest: sha256DigestSchema,
+        targetWorkspace: z.enum(["task", "candidate"]),
+        mountPaths: z.array(z
+            .string()
+            .refine((value) => isSafeRelativePath(value, false), "profile mount paths must be canonical and relative")),
+    })
+        .strict(),
+    harness: harnessTypeSchema,
+    harnessVersion: z.string().min(1),
+    container: agentCandidateContainerSchema
+        .extend({
+        source: z.enum(["pinned-container", "evaluator-task-container"]),
+        manifestDigest: sha256DigestSchema,
+        platform: z
+            .object({
+            os: z.string().min(1),
+            architecture: z.string().min(1),
+            variant: z.string().min(1).optional(),
+        })
+            .strict(),
+    })
+        .strict(),
+    model: z
+        .object({
+        policy: z.literal("single"),
+        resolved: agentCandidateResolvedModelSchema,
+        access: z
+            .object({
+            kind: z.literal("evaluator-mediated"),
+            grantDigest: sha256DigestSchema,
+        })
+            .strict(),
+        routes: z
+            .array(z.discriminatedUnion("kind", [
+            z
+                .object({
+                kind: z.literal("primary"),
+                requested: z.string().min(1).optional(),
+            })
+                .strict(),
+            z
+                .object({
+                kind: z.literal("small"),
+                requested: z.string().min(1),
+            })
+                .strict(),
+            z
+                .object({
+                kind: z.literal("mode"),
+                name: z.string().min(1),
+                requested: z.string().min(1),
+            })
+                .strict(),
+            z
+                .object({
+                kind: z.literal("subagent"),
+                name: z.string().min(1),
+                requested: z.string().min(1),
+            })
+                .strict(),
+        ]))
+            .min(1),
+    })
+        .strict(),
+    launch: z
+        .object({
+        executable: z
+            .string()
+            .refine(isSafeExecutable, "execution plan requires a non-shell executable"),
+        args: z.array(agentCandidateConfigValueSchema),
+        env: environmentConfigSchema,
+        cwd: agentCandidateWorkingDirectorySchema,
+    })
+        .strict(),
+    knowledgeManifestDigest: sha256DigestSchema.optional(),
+    memory: agentCandidateEffectiveMemorySchema,
+    limits: agentCandidateExecutionLimitsSchema,
+    network: z.object({ mode: z.literal("disabled") }).strict(),
+})
+    .strict()
+    .superRefine((material, ctx) => {
+    if (!sameGitObjectFormat(material.task.repository.baseCommit, material.task.repository.baseTree)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["task", "repository"],
+            message: "task Git object ids must use one object format",
+        });
+    }
+    if (material.attempt.number > material.attempt.maxAttempts) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["attempt", "number"],
+            message: "attempt number cannot exceed the frozen maximum",
+        });
+    }
+    if (material.attempt.retryPolicy === "none" &&
+        material.attempt.maxAttempts !== 1) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["attempt", "maxAttempts"],
+            message: "a no-retry plan must allow exactly one attempt",
+        });
+    }
+    const routeIds = material.model.routes.map((route) => route.kind === "mode" || route.kind === "subagent"
+        ? `${route.kind}:${route.name}`
+        : route.kind);
+    addDuplicateIssues(routeIds, ["model", "routes"], ctx);
+    addDuplicateIssues(material.profile.mountPaths, ["profile", "mountPaths"], ctx);
+    for (let index = 1; index < material.profile.mountPaths.length; index++) {
+        if ((material.profile.mountPaths[index - 1] ?? "") >=
+            (material.profile.mountPaths[index] ?? "")) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["profile", "mountPaths", index],
+                message: "profile mount paths must be lexicographically sorted",
+            });
+        }
+    }
+    if (!material.model.routes.some((route) => route.kind === "primary")) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["model", "routes"],
+            message: "single-model plans must include the primary route",
+        });
+    }
+    for (const [index, route] of material.model.routes.entries()) {
+        if (route.requested !== undefined &&
+            route.requested !== material.model.resolved.requested) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["model", "routes", index, "requested"],
+                message: "every route must request the one resolved model literal",
+            });
+        }
+    }
+    const activeCode = material.codeKind !== "disabled";
+    if (activeCode !== (material.candidateWorkspace !== undefined)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["candidateWorkspace"],
+            message: "active code requires a complete candidate-workspace snapshot",
+        });
+    }
+    if (activeCode !== (material.workspaces.candidateRoot !== undefined)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["workspaces", "candidateRoot"],
+            message: "active code requires a fixed candidate workspace root",
+        });
+    }
+    if (material.workspaces.candidateRoot !== undefined &&
+        pathsOverlap(material.workspaces.taskRoot, material.workspaces.candidateRoot)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["workspaces"],
+            message: "task and candidate workspace roots must be disjoint",
+        });
+    }
+    if (material.launch.cwd.workspace === "candidate" &&
+        material.workspaces.candidateRoot === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["launch", "cwd", "workspace"],
+            message: "candidate cwd requires a pinned candidate workspace root",
+        });
+    }
+    if (material.profile.targetWorkspace === "candidate" &&
+        material.workspaces.candidateRoot === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["profile", "targetWorkspace"],
+            message: "candidate-targeted profile files require a candidate workspace root",
+        });
+    }
+    const delivery = material.task.instruction.delivery;
+    const taskPath = material.launch.env.TANGLE_CANDIDATE_TASK_PATH;
+    if (delivery.kind === "utf8-file") {
+        if (taskPath?.value !== delivery.path) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["launch", "env", "TANGLE_CANDIDATE_TASK_PATH"],
+                message: "file delivery requires the signed fixed task path",
+            });
+        }
+        if (pathsOverlap(material.workspaces.taskRoot, delivery.path) ||
+            (material.workspaces.candidateRoot !== undefined &&
+                pathsOverlap(material.workspaces.candidateRoot, delivery.path))) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["workspaces"],
+                message: "the task instruction file must be outside both workspaces",
+            });
+        }
+    }
+    else if (taskPath !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["launch", "env", "TANGLE_CANDIDATE_TASK_PATH"],
+            message: "non-file delivery cannot expose an instruction path",
+        });
+    }
+    if (activeCode && material.candidateWorkspace?.material.files.length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["candidateWorkspace", "material", "files"],
+            message: "active candidate workspaces cannot be empty",
+        });
+    }
+    if (material.task.workspace.material.files.length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["task", "workspace", "material", "files"],
+            message: "task workspace snapshots cannot be empty",
+        });
+    }
+    if (!isCanonicalJsonValue(material)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "execution-plan material must contain only RFC 8785 JSON values",
+        });
+    }
+});
+function planEvidenceSchema(kind, material) {
+    return z
+        .object({
+        schemaVersion: z.literal(1),
+        kind: z.literal(kind),
+        digest: sha256DigestSchema,
+        material,
+        artifact: agentCandidateCapturedArtifactSchema,
+    })
+        .strict()
+        .superRefine((evidence, ctx) => {
+        if (evidence.artifact.sha256 !== evidence.digest) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["artifact", "sha256"],
+                message: "plan artifact hash must equal its canonical material digest",
+            });
+        }
+        if (evidence.artifact.byteLength === 0) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["artifact", "byteLength"],
+                message: "plan artifact must contain canonical material bytes",
+            });
+        }
+    });
+}
+export const agentCandidateProfilePlanEvidenceSchema = planEvidenceSchema("agent-profile-workspace-plan", agentCandidateProfilePlanMaterialSchema);
+export const agentCandidateExecutionPlanEvidenceSchema = planEvidenceSchema("agent-candidate-execution-plan", agentCandidateExecutionPlanMaterialSchema);

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

@@ -0,0 +1,78 @@
+import { z } from "zod";
+export declare const agentCandidateKnowledgeSchema: z.ZodObject<{
+    snapshotId: z.ZodString;
+    manifest: 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.core.$strict>;
+export declare const agentCandidateMemoryPolicySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"disabled">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"isolated">;
+    scope: z.ZodLiteral<"task">;
+    seed: z.ZodOptional<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.core.$strict>], "mode">;
+export declare const agentCandidateSpendSchema: z.ZodObject<{
+    costUsd: z.ZodNumber;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    modelCalls: z.ZodNumber;
+}, z.core.$strict>;
+export declare const agentCandidateLineageSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        optimizer: "optimizer";
+        human: "human";
+        import: "import";
+        compound: "compound";
+    }>;
+    parentDigests: z.ZodOptional<z.ZodArray<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>>;
+    runIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    profileDiffIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    modelSnapshots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    benchmark: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        splitDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>>;
+    spend: z.ZodOptional<z.ZodObject<{
+        proposal: z.ZodObject<{
+            costUsd: z.ZodNumber;
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+            modelCalls: z.ZodNumber;
+        }, z.core.$strict>;
+        evaluation: z.ZodObject<{
+            costUsd: z.ZodNumber;
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+            modelCalls: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

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

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { agentCandidateArtifactRefSchema } from "./agent-candidate-artifact-schema.js";
+import { addDuplicateIssues, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+export const agentCandidateKnowledgeSchema = z
+    .object({
+    snapshotId: z.string().min(1),
+    manifest: agentCandidateArtifactRefSchema,
+})
+    .strict();
+export const agentCandidateMemoryPolicySchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("disabled") }).strict(),
+    z
+        .object({
+        mode: z.literal("isolated"),
+        scope: z.literal("task"),
+        seed: agentCandidateArtifactRefSchema.optional(),
+    })
+        .strict(),
+]);
+export const agentCandidateSpendSchema = z
+    .object({
+    costUsd: z.number().finite().nonnegative(),
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    cachedInputTokens: z.number().int().nonnegative().optional(),
+    modelCalls: z.number().int().nonnegative(),
+})
+    .strict();
+export const agentCandidateLineageSchema = z
+    .object({
+    source: z.enum(["optimizer", "human", "import", "compound"]),
+    parentDigests: z.array(sha256DigestSchema).optional(),
+    runIds: z.array(z.string().min(1)).optional(),
+    profileDiffIds: z.array(z.string().min(1)).optional(),
+    modelSnapshots: z.array(z.string().min(1)).optional(),
+    benchmark: z
+        .object({
+        name: z.string().min(1),
+        version: z.string().min(1),
+        splitDigest: sha256DigestSchema,
+    })
+        .strict()
+        .optional(),
+    spend: z
+        .object({
+        proposal: agentCandidateSpendSchema,
+        evaluation: agentCandidateSpendSchema,
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((lineage, ctx) => {
+    addDuplicateIssues(lineage.parentDigests, ["parentDigests"], ctx);
+    addDuplicateIssues(lineage.runIds, ["runIds"], ctx);
+    addDuplicateIssues(lineage.profileDiffIds, ["profileDiffIds"], ctx);
+    addDuplicateIssues(lineage.modelSnapshots, ["modelSnapshots"], ctx);
+    if (lineage.source === "compound" &&
+        (lineage.parentDigests?.length ?? 0) < 2) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["parentDigests"],
+            message: "compound candidates must name at least two distinct parents",
+        });
+    }
+    if (lineage.source === "optimizer" || lineage.source === "compound") {
+        if ((lineage.parentDigests?.length ?? 0) === 0) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["parentDigests"],
+                message: "generated candidates must name at least one parent",
+            });
+        }
+        if ((lineage.runIds?.length ?? 0) === 0) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["runIds"],
+                message: "generated candidates must name their producing run",
+            });
+        }
+        if (lineage.benchmark === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["benchmark"],
+                message: "generated candidates must pin their development split",
+            });
+        }
+        if (lineage.spend === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["spend"],
+                message: "generated candidates must record proposal and evaluation spend",
+            });
+        }
+    }
+});