@tangle-network/agent-interface 0.20.0 → 0.21.0

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

@@ -0,0 +1,263 @@
+import { z } from "zod";
+import { agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
+import { agentCandidateExecutionPlanEvidenceSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateResolvedModelSchema, } from "./agent-candidate-execution-plan-schema.js";
+import { agentCandidateSpendSchema, } from "./agent-candidate-lineage-schema.js";
+import { gitObjectSchema, isCanonicalJsonValue, isSafeRelativePath, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { harnessTypeSchema } from "./harness.js";
+const entrypointReceiptSchema = z
+    .object({
+    path: z
+        .string()
+        .refine((value) => isSafeRelativePath(value, false), "entrypoint path must be a canonical candidate-relative path"),
+    sha256: sha256DigestSchema,
+    byteLength: z.number().int().nonnegative(),
+})
+    .strict();
+const ociPlatformSchema = z
+    .object({
+    os: z.string().min(1),
+    architecture: z.string().min(1),
+    variant: z.string().min(1).optional(),
+})
+    .strict();
+export const agentCandidateTraceEvidenceSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    artifact: agentCandidateCapturedArtifactSchema,
+    eventCount: z.number().int().positive(),
+    modelCallCount: z.number().int().nonnegative(),
+})
+    .strict()
+    .superRefine((trace, ctx) => {
+    if (trace.artifact.byteLength === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["artifact", "byteLength"],
+            message: "trace artifact must contain captured events",
+        });
+    }
+    if (trace.eventCount < trace.modelCallCount) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["eventCount"],
+            message: "trace must contain at least one event for every model call",
+        });
+    }
+});
+export const agentCandidateModelUsageSchema = z
+    .object({
+    resolved: agentCandidateResolvedModelSchema,
+    usage: agentCandidateSpendSchema,
+})
+    .strict();
+export const agentCandidateMemoryReceiptSchema = 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),
+        resetEvidenceDigest: sha256DigestSchema,
+        beforeStateDigest: sha256DigestSchema,
+        afterState: agentCandidateWorkspaceSnapshotEvidenceSchema,
+    })
+        .strict(),
+]);
+export const agentCandidateTerminationSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("exit"), exitCode: z.number().int() }).strict(),
+    z
+        .object({
+        kind: z.literal("timeout"),
+        timeoutMs: z.number().int().positive(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("signal"),
+        signal: z.string().regex(/^SIG[A-Z0-9]+$/),
+    })
+        .strict(),
+    z.object({ kind: z.literal("cancelled") }).strict(),
+]);
+export const agentCandidateMaterializationReceiptSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-materialization"),
+    digestAlgorithm: z.literal("rfc8785-sha256"),
+    bundleDigest: sha256DigestSchema,
+    profilePlan: agentCandidateProfilePlanEvidenceSchema,
+    executionPlan: agentCandidateExecutionPlanEvidenceSchema,
+    candidateWorkspace: agentCandidateWorkspaceSnapshotEvidenceSchema.optional(),
+    codeKind: z.enum(["disabled", "no-op", "git-patch"]),
+    materializedTree: gitObjectSchema.optional(),
+    harness: harnessTypeSchema,
+    harnessVersion: z.string().min(1),
+    container: z
+        .object({
+        source: z.enum(["pinned-container", "evaluator-task-container"]),
+        image: z.string().min(1),
+        indexDigest: sha256DigestSchema,
+        manifestDigest: sha256DigestSchema,
+        platform: ociPlatformSchema,
+    })
+        .strict(),
+    resolvedModel: agentCandidateResolvedModelSchema,
+    knowledgeManifestDigest: sha256DigestSchema.optional(),
+    entrypoint: entrypointReceiptSchema.optional(),
+    digest: sha256DigestSchema,
+})
+    .strict()
+    .superRefine((receipt, ctx) => {
+    const plan = receipt.executionPlan.material;
+    if (receipt.codeKind === "disabled") {
+        if (receipt.materializedTree !== undefined ||
+            receipt.entrypoint !== undefined ||
+            receipt.candidateWorkspace !== undefined) {
+            ctx.addIssue({
+                code: "custom",
+                message: "disabled code must not claim a materialized tree, entrypoint, or workspace",
+            });
+        }
+    }
+    else if (receipt.materializedTree === undefined ||
+        receipt.entrypoint === undefined ||
+        receipt.candidateWorkspace === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "active code requires a materialized tree, entrypoint, and workspace receipt",
+        });
+    }
+    else {
+        const entrypoint = receipt.candidateWorkspace.material.files.find((file) => file.path === receipt.entrypoint?.path);
+        if (entrypoint === undefined ||
+            entrypoint.sha256 !== receipt.entrypoint.sha256 ||
+            entrypoint.byteLength !== receipt.entrypoint.byteLength) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["entrypoint"],
+                message: "entrypoint receipt must identify exact candidate-workspace bytes",
+            });
+        }
+    }
+    const checks = [
+        [
+            receipt.bundleDigest === plan.bundleDigest,
+            ["executionPlan", "material", "bundleDigest"],
+            "execution plan must bind the receipt bundle",
+        ],
+        [
+            receipt.profilePlan.digest === plan.profile.planDigest,
+            ["executionPlan", "material", "profile", "planDigest"],
+            "execution plan must bind the exact profile plan",
+        ],
+        [
+            JSON.stringify(plan.profile.mountPaths) ===
+                JSON.stringify(receipt.profilePlan.material.files.map((file) => file.relPath)),
+            ["executionPlan", "material", "profile", "mountPaths"],
+            "execution plan must bind every profile mount path",
+        ],
+        [
+            receipt.codeKind === plan.codeKind,
+            ["executionPlan", "material", "codeKind"],
+            "execution plan code kind must match materialization",
+        ],
+        [
+            receipt.harness === plan.harness &&
+                receipt.harnessVersion === plan.harnessVersion,
+            ["executionPlan", "material", "harness"],
+            "execution plan must bind the exact harness and version",
+        ],
+        [
+            receipt.container.source === plan.container.source &&
+                receipt.container.image === plan.container.image &&
+                receipt.container.indexDigest === plan.container.indexDigest &&
+                receipt.container.manifestDigest === plan.container.manifestDigest &&
+                receipt.container.platform.os === plan.container.platform.os &&
+                receipt.container.platform.architecture ===
+                    plan.container.platform.architecture &&
+                receipt.container.platform.variant === plan.container.platform.variant,
+            ["executionPlan", "material", "container"],
+            "execution plan must bind the selected container bytes",
+        ],
+        [
+            JSON.stringify(receipt.resolvedModel) ===
+                JSON.stringify(plan.model.resolved),
+            ["executionPlan", "material", "model", "resolved"],
+            "execution plan must bind the exact resolved model",
+        ],
+        [
+            receipt.knowledgeManifestDigest === plan.knowledgeManifestDigest,
+            ["executionPlan", "material", "knowledgeManifestDigest"],
+            "execution plan knowledge must match materialization",
+        ],
+        [
+            JSON.stringify(receipt.candidateWorkspace) ===
+                JSON.stringify(plan.candidateWorkspace),
+            ["executionPlan", "material", "candidateWorkspace"],
+            "execution plan must bind the exact uploaded candidate workspace",
+        ],
+        [
+            receipt.profilePlan.material.harness === receipt.harness,
+            ["profilePlan", "material", "harness"],
+            "profile plan harness must match materialization",
+        ],
+    ];
+    for (const [valid, path, message] of checks) {
+        if (!valid)
+            ctx.addIssue({ code: "custom", path, message });
+    }
+    if (!isCanonicalJsonValue(receipt)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "materialization receipt must contain only RFC 8785 JSON values",
+        });
+    }
+});
+export const agentCandidateRunReceiptSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-run"),
+    digestAlgorithm: z.literal("rfc8785-sha256"),
+    bundleDigest: sha256DigestSchema,
+    materializationReceiptDigest: sha256DigestSchema,
+    executionPlanDigest: sha256DigestSchema,
+    memory: agentCandidateMemoryReceiptSchema,
+    usage: agentCandidateSpendSchema,
+    modelUsage: agentCandidateModelUsageSchema,
+    trace: agentCandidateTraceEvidenceSchema,
+    termination: agentCandidateTerminationSchema,
+    digest: sha256DigestSchema,
+})
+    .strict()
+    .superRefine((receipt, ctx) => {
+    const usageMatchesModel = receipt.usage.costUsd === receipt.modelUsage.usage.costUsd &&
+        receipt.usage.inputTokens === receipt.modelUsage.usage.inputTokens &&
+        receipt.usage.outputTokens === receipt.modelUsage.usage.outputTokens &&
+        receipt.usage.cachedInputTokens ===
+            receipt.modelUsage.usage.cachedInputTokens &&
+        receipt.usage.modelCalls === receipt.modelUsage.usage.modelCalls;
+    if (!usageMatchesModel) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["modelUsage", "usage"],
+            message: "single-model usage must equal aggregate protected usage",
+        });
+    }
+    if (receipt.trace.modelCallCount !== receipt.modelUsage.usage.modelCalls) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["trace", "modelCallCount"],
+            message: "trace model-call count must match protected single-model usage",
+        });
+    }
+    if (!isCanonicalJsonValue(receipt)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "run receipt must contain only RFC 8785 JSON values",
+        });
+    }
+});
+const _materializationReceiptSchemaMatchesType = true;
+const _runReceiptSchemaMatchesType = true;
+void _materializationReceiptSchemaMatchesType;
+void _runReceiptSchemaMatchesType;

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

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { Sha256Digest } from "./agent-candidate.js";
+export declare const sha256DigestSchema: z.ZodType<Sha256Digest>;
+export declare const gitObjectSchema: z.ZodString;
+export declare const environmentNameSchema: z.ZodString;
+export declare const headerNameSchema: z.ZodString;
+export declare function isWellFormedUnicode(value: string): boolean;
+export declare function isSafeRelativePath(value: string, allowDot: boolean): boolean;
+export declare function isSafeExecutable(value: string): boolean;
+export declare function isObviouslyPrivateHostname(rawHostname: string): boolean;
+export declare function isCanonicalJsonValue(value: unknown, ancestors?: Set<object>): boolean;
+export declare function looksLikeCredential(value: string): boolean;
+export declare const agentCandidateConfigValueSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"public">;
+    value: z.ZodString;
+}, z.core.$strict>;
+export declare const environmentConfigSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    kind: z.ZodLiteral<"public">;
+    value: z.ZodString;
+}, z.core.$strict>>;
+export declare const headerConfigSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    kind: z.ZodLiteral<"public">;
+    value: z.ZodString;
+}, z.core.$strict>>;
+export declare const candidateMetadataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const agentCandidateGitHubRepositorySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"github">;
+    owner: z.ZodString;
+    repo: z.ZodString;
+}, z.core.$strict>;
+export declare function addDuplicateIssues(values: readonly string[] | undefined, path: (string | number)[], ctx: z.RefinementCtx): void;
+export declare function sameGitObjectFormat(...values: string[]): boolean;

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

@@ -0,0 +1,251 @@
+import { z } from "zod";
+const sha256Pattern = /^sha256:[a-f0-9]{64}$/;
+const gitObjectPattern = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const environmentNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const headerNamePattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const githubComponentPattern = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
+const secretNamePattern = /(?:^|[_-])(?:api[_-]?key|access[_-]?key|private[_-]?key|token|secret|password|credentials?|authorization|cookie|database[_-]?url|dsn|pat)(?:[_-]|$)/i;
+const obviousSecretValuePattern = /(?:\b(?:sk|gh[pousr]|github_pat|AKIA)[-_A-Za-z0-9]{12,}\b|-----BEGIN [A-Z ]*PRIVATE KEY-----|\bBearer\s+\S+)/;
+const controlCharacterPattern = /[\u0000-\u001f\u007f]/;
+const reservedWorkspaceRoots = new Set([".git", ".sidecar"]);
+const shellNames = new Set([
+    "sh",
+    "bash",
+    "zsh",
+    "fish",
+    "cmd",
+    "cmd.exe",
+    "powershell",
+    "pwsh",
+]);
+const blockedHostnames = new Set([
+    "localhost",
+    "metadata.google.internal",
+    "metadata.google",
+]);
+export const sha256DigestSchema = z
+    .string()
+    .regex(sha256Pattern);
+export const gitObjectSchema = z.string().regex(gitObjectPattern);
+export const environmentNameSchema = z.string().regex(environmentNamePattern);
+export const headerNameSchema = z.string().regex(headerNamePattern);
+export function isWellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+            index++;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return false;
+        }
+    }
+    return true;
+}
+export function isSafeRelativePath(value, allowDot) {
+    if (value.length === 0 ||
+        controlCharacterPattern.test(value) ||
+        !isWellFormedUnicode(value) ||
+        value.startsWith("/") ||
+        value.startsWith("\\") ||
+        value.includes("\\") ||
+        /^[A-Za-z]:/.test(value)) {
+        return false;
+    }
+    if (value === ".")
+        return allowDot;
+    const parts = value.split("/");
+    return (parts.every((part) => part.length > 0 && part !== "." && part !== "..") &&
+        !parts.some((part) => reservedWorkspaceRoots.has(part)));
+}
+export function isSafeExecutable(value) {
+    if (value.length === 0 ||
+        controlCharacterPattern.test(value) ||
+        !isWellFormedUnicode(value) ||
+        /\s/.test(value) ||
+        value.includes("\\") ||
+        !/^[A-Za-z0-9._+/-]+$/.test(value)) {
+        return false;
+    }
+    const parts = value.split("/");
+    if (value.startsWith("/"))
+        parts.shift();
+    if (parts.length === 0 ||
+        parts.some((part) => part.length === 0 || part === "." || part === "..")) {
+        return false;
+    }
+    return !shellNames.has(parts.at(-1)?.toLowerCase() ?? "");
+}
+export function isObviouslyPrivateHostname(rawHostname) {
+    const literal = rawHostname.toLowerCase().replace(/^\[|\]$/g, "");
+    let hostname = literal;
+    try {
+        const parsed = new URL(`http://${literal.includes(":") ? `[${literal}]` : literal}/`);
+        hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+    }
+    catch {
+        // Non-URL hostnames remain ordinary DNS names and are handled below.
+    }
+    if (blockedHostnames.has(hostname) || hostname.endsWith(".localhost")) {
+        return true;
+    }
+    if (hostname.includes(":")) {
+        const firstHextet = hostname.split(":", 1)[0] ?? "";
+        if (hostname === "::" ||
+            hostname === "::1" ||
+            hostname.startsWith("fe8") ||
+            hostname.startsWith("fe9") ||
+            hostname.startsWith("fea") ||
+            hostname.startsWith("feb") ||
+            firstHextet.startsWith("fc") ||
+            firstHextet.startsWith("fd") ||
+            hostname.startsWith("::ffff:")) {
+            return true;
+        }
+    }
+    const parts = hostname.split(".").map(Number);
+    if (parts.length !== 4 ||
+        parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    const [a, b] = parts;
+    if (a === undefined || b === undefined) {
+        return false;
+    }
+    if (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        a >= 224) {
+        return true;
+    }
+    return false;
+}
+export function isCanonicalJsonValue(value, ancestors = new Set()) {
+    if (value === null || typeof value === "boolean")
+        return true;
+    if (typeof value === "string")
+        return isWellFormedUnicode(value);
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || ancestors.has(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) &&
+        prototype !== Object.prototype &&
+        prototype !== null) {
+        return false;
+    }
+    const nextAncestors = new Set(ancestors).add(value);
+    if (Array.isArray(value)) {
+        return value.every((entry) => isCanonicalJsonValue(entry, nextAncestors));
+    }
+    return Object.entries(value).every(([key, entry]) => isWellFormedUnicode(key) && isCanonicalJsonValue(entry, nextAncestors));
+}
+function hasCredentialBearingUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.username !== "" || url.password !== "")
+            return true;
+        return [...url.searchParams.keys()].some((key) => secretNamePattern.test(key));
+    }
+    catch {
+        return false;
+    }
+}
+export function looksLikeCredential(value) {
+    return obviousSecretValuePattern.test(value) || hasCredentialBearingUrl(value);
+}
+function isPublicConfigValue(value) {
+    return (!controlCharacterPattern.test(value) &&
+        isWellFormedUnicode(value) &&
+        !looksLikeCredential(value));
+}
+export const agentCandidateConfigValueSchema = z
+    .object({
+    kind: z.literal("public"),
+    value: z
+        .string()
+        .refine(isPublicConfigValue, "candidate config cannot carry credentials; the evaluator owns model authorization"),
+})
+    .strict();
+function configRecordSchema(keySchema) {
+    return z
+        .record(keySchema, agentCandidateConfigValueSchema)
+        .superRefine((config, ctx) => {
+        for (const [name, value] of Object.entries(config)) {
+            if (secretNamePattern.test(name)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: [name],
+                    message: "candidate config cannot declare credential-bearing names",
+                });
+            }
+        }
+    });
+}
+export const environmentConfigSchema = configRecordSchema(environmentNameSchema);
+export const headerConfigSchema = configRecordSchema(headerNameSchema);
+export const candidateMetadataSchema = z
+    .record(z.string(), z.unknown())
+    .superRefine((metadata, ctx) => {
+    if (hasSensitiveMetadataKey(metadata)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "metadata must not contain credential-bearing keys",
+        });
+    }
+});
+function hasSensitiveMetadataKey(value, ancestors = new Set()) {
+    if (value === null || typeof value !== "object" || ancestors.has(value)) {
+        return false;
+    }
+    const nextAncestors = new Set(ancestors).add(value);
+    if (Array.isArray(value)) {
+        return value.some((entry) => hasSensitiveMetadataKey(entry, nextAncestors));
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        if (secretNamePattern.test(key))
+            return true;
+        if (hasSensitiveMetadataKey(entry, nextAncestors))
+            return true;
+    }
+    return false;
+}
+export const agentCandidateGitHubRepositorySchema = z
+    .object({
+    kind: z.literal("github"),
+    owner: z
+        .string()
+        .regex(githubComponentPattern)
+        .refine((value) => value !== "." && value !== ".."),
+    repo: z
+        .string()
+        .regex(githubComponentPattern)
+        .refine((value) => value !== "." && value !== ".."),
+})
+    .strict();
+export function addDuplicateIssues(values, path, ctx) {
+    if (!values)
+        return;
+    const seen = new Set();
+    for (const [index, value] of values.entries()) {
+        if (seen.has(value)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [...path, index],
+                message: `duplicate value '${value}'`,
+            });
+        }
+        seen.add(value);
+    }
+}
+export function sameGitObjectFormat(...values) {
+    return new Set(values.map((value) => value.length)).size === 1;
+}