@tangle-network/agent-interface 2.9.0 → 2.10.0

package/dist/agent-profile.d.ts

@@ -12,6 +12,7 @@
  * fixed. This package is the canonical public home for these symbols.
  */
 import type { HarnessType } from "./harness.js";
+import type { Sha256Digest } from "./agent-candidate.js";
 /**
  * Permission policy value for a capability.
  */
@@ -343,6 +344,53 @@ export interface AgentProfileConnection {
      */
     alias?: string;
 }
+/** Router namespace reserved for checkpoint-backed models. Receipt-free profiles cannot use it. */
+export declare const TRAINED_MODEL_PREFIX = "tangle-trained/";
+/** An immutable Router alias; serving must independently attest this artifact-to-route binding. */
+export declare function trainedModelIdForArtifact(digest: Sha256Digest): string;
+/** Identity of a task whose data was exposed to training or model selection. */
+export interface AgentTrainingTask {
+    benchmark: string;
+    task: string;
+    contentDigest: Sha256Digest;
+}
+/** Complete exposure inventory, derived from the exact dataset delivered to a trainer. */
+export interface AgentTrainingDatasetIdentity {
+    digest: Sha256Digest;
+    taskSetDigest: Sha256Digest;
+    tasks: AgentTrainingTask[];
+}
+export interface AgentTrainingReceipt {
+    version: 1;
+    dataset: AgentTrainingDatasetIdentity;
+    parentProfileDigest: Sha256Digest;
+    /** Null only when the parent has no training receipt. */
+    parentReceiptDigest: Sha256Digest | null;
+    executionRef: Sha256Digest;
+    trainer: {
+        mode: "command" | "managed";
+        id: string;
+        revision: Sha256Digest;
+        /** Public hyperparameters only; credentials belong to the private executor. */
+        parameters: Record<string, string | number | boolean | null>;
+    };
+    checkpoint: {
+        artifactDigest: Sha256Digest;
+        artifactBytes: number;
+        routerModelId: string;
+        /** Digest of independently verified serving evidence, not trainer stdout. */
+        servingDigest: Sha256Digest;
+    };
+}
+export interface AgentProfileTraining {
+    receipt: AgentTrainingReceipt;
+    /** Immediate parent first, terminating at a receipt with parentReceiptDigest=null. */
+    ancestors: AgentTrainingReceipt[];
+}
+export interface AgentProfileMetadata extends Record<string, unknown> {
+    /** Reserved: a trained model is admitted only with a complete checkpoint receipt. */
+    training?: AgentProfileTraining;
+}
 /**
  * Public provider-neutral agent profile contract.
  */
@@ -374,7 +422,7 @@ export interface AgentProfile {
     hooks?: Record<string, AgentProfileHookCommand[]>;
     modes?: Record<string, AgentProfileMode>;
     confidential?: AgentProfileConfidential;
-    metadata?: Record<string, unknown>;
+    metadata?: AgentProfileMetadata;
     /**
      * Non-portable backend-specific extensions.
      *

package/dist/agent-profile.js

@@ -63,6 +63,12 @@ export function defineAgentProfileSecretRef(key, format) {
         ...(format === undefined ? {} : { format }),
     };
 }
+/** Router namespace reserved for checkpoint-backed models. Receipt-free profiles cannot use it. */
+export const TRAINED_MODEL_PREFIX = "tangle-trained/";
+/** An immutable Router alias; serving must independently attest this artifact-to-route binding. */
+export function trainedModelIdForArtifact(digest) {
+    return `${TRAINED_MODEL_PREFIX}${digest.slice("sha256:".length)}`;
+}
 /**
  * Helper for declaring typed profiles in application code.
  */

package/dist/environment-interactive-start.d.ts

@@ -216,7 +216,7 @@ export declare const AgentInteractiveSessionStartSchema: z.ZodObject<{
             sealed: z.ZodOptional<z.ZodBoolean>;
             attestationRefresh: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
-        metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+        metadata: z.ZodOptional<z.ZodType<import("./agent-profile.js").AgentProfileMetadata, unknown, z.core.$ZodTypeInternals<import("./agent-profile.js").AgentProfileMetadata, unknown>>>;
         extensions: z.ZodOptional<z.ZodType<Record<string, Record<string, unknown> | undefined>, unknown, z.core.$ZodTypeInternals<Record<string, Record<string, unknown> | undefined>, unknown>>>;
     }, z.core.$strict>;
     requestedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;

package/dist/profile-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type AgentProfile, type AgentProfileMcpServer } from "./agent-profile.js";
+import { type AgentProfile, type AgentProfileMetadata, type AgentTrainingTask, type AgentProfileMcpServer } from "./agent-profile.js";
 import type { AgentProfileDiff } from "./profile-diff.js";
 import { type SandboxSizePreset } from "./sandbox-size.js";
 export declare const agentProfilePermissionValueSchema: z.ZodEnum<{
@@ -326,6 +326,116 @@ export declare const agentProfileDiffRemovalSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
     extensions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>;
+export declare const agentTrainingTaskSchema: z.ZodObject<{
+    benchmark: z.ZodString;
+    task: z.ZodString;
+    contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+/** The same order is used by dataset ingestion, receipt admission and holdout checks. */
+export declare function agentTrainingTaskKey(task: AgentTrainingTask): string;
+export declare const agentTrainingDatasetIdentitySchema: z.ZodObject<{
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    taskSetDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    tasks: z.ZodArray<z.ZodObject<{
+        benchmark: z.ZodString;
+        task: z.ZodString;
+        contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const agentTrainingParametersSchema: z.ZodType<Record<string, string | number | boolean | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | number | boolean | null>, unknown>>;
+export declare const agentTrainingReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    dataset: z.ZodObject<{
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        taskSetDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        tasks: z.ZodArray<z.ZodObject<{
+            benchmark: z.ZodString;
+            task: z.ZodString;
+            contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    parentProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    parentReceiptDigest: z.ZodNullable<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+    executionRef: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    trainer: z.ZodObject<{
+        mode: z.ZodEnum<{
+            command: "command";
+            managed: "managed";
+        }>;
+        id: z.ZodString;
+        revision: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        parameters: z.ZodType<Record<string, string | number | boolean | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | number | boolean | null>, unknown>>;
+    }, z.core.$strict>;
+    checkpoint: z.ZodObject<{
+        artifactDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        artifactBytes: z.ZodNumber;
+        routerModelId: z.ZodString;
+        servingDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const agentProfileTrainingSchema: z.ZodObject<{
+    receipt: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        dataset: z.ZodObject<{
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            taskSetDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            tasks: z.ZodArray<z.ZodObject<{
+                benchmark: z.ZodString;
+                task: z.ZodString;
+                contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        parentProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        parentReceiptDigest: z.ZodNullable<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        executionRef: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        trainer: z.ZodObject<{
+            mode: z.ZodEnum<{
+                command: "command";
+                managed: "managed";
+            }>;
+            id: z.ZodString;
+            revision: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            parameters: z.ZodType<Record<string, string | number | boolean | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | number | boolean | null>, unknown>>;
+        }, z.core.$strict>;
+        checkpoint: z.ZodObject<{
+            artifactDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            artifactBytes: z.ZodNumber;
+            routerModelId: z.ZodString;
+            servingDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    ancestors: z.ZodArray<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        dataset: z.ZodObject<{
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            taskSetDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            tasks: z.ZodArray<z.ZodObject<{
+                benchmark: z.ZodString;
+                task: z.ZodString;
+                contentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        parentProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        parentReceiptDigest: z.ZodNullable<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        executionRef: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        trainer: z.ZodObject<{
+            mode: z.ZodEnum<{
+                command: "command";
+                managed: "managed";
+            }>;
+            id: z.ZodString;
+            revision: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            parameters: z.ZodType<Record<string, string | number | boolean | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | number | boolean | null>, unknown>>;
+        }, z.core.$strict>;
+        checkpoint: z.ZodObject<{
+            artifactDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            artifactBytes: z.ZodNumber;
+            routerModelId: z.ZodString;
+            servingDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const agentProfileMetadataSchema: z.ZodType<AgentProfileMetadata>;
 /**
  * The complete provider-neutral agent profile schema — the runtime validator for
  * the canonical {@link AgentProfile} TS contract. Kept structurally in lock-step
@@ -523,7 +633,7 @@ export declare const agentProfileSchema: z.ZodObject<{
         sealed: z.ZodOptional<z.ZodBoolean>;
         attestationRefresh: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
-    metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+    metadata: z.ZodOptional<z.ZodType<AgentProfileMetadata, unknown, z.core.$ZodTypeInternals<AgentProfileMetadata, unknown>>>;
     extensions: z.ZodOptional<z.ZodType<Record<string, Record<string, unknown> | undefined>, unknown, z.core.$ZodTypeInternals<Record<string, Record<string, unknown> | undefined>, unknown>>>;
 }, z.core.$strict>;
 /**

package/dist/profile-schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { REASONING_EFFORTS, } from "./agent-profile.js";
-import { environmentNameSchema, headerNameSchema, isSafeExecutable, isSafeRelativePath, isWellFormedUnicode, looksLikeCredential, } from "./agent-candidate-schema-common.js";
+import { REASONING_EFFORTS, TRAINED_MODEL_PREFIX, trainedModelIdForArtifact, } from "./agent-profile.js";
+import { canonicalCandidateDigest, sha256DigestSchema, environmentNameSchema, headerNameSchema, isSafeExecutable, isSafeRelativePath, isWellFormedUnicode, looksLikeCredential, } from "./agent-candidate-schema-common.js";
 import { harnessTypeSchema } from "./harness.js";
 import { SANDBOX_SIZE_PRESET_NAMES, } from "./sandbox-size.js";
 /**
@@ -322,6 +322,88 @@ export const agentProfileDiffRemovalSchema = z.strictObject({
     metadata: removeListSchema.optional(),
     extensions: removeListSchema.optional(),
 });
+const trainingIdentitySchema = z.string().min(1).max(500).refine((value) => value.trim() === value && isWellFormedUnicode(value) &&
+    !controlCharacterPattern.test(value) && !looksLikeCredential(value), "training identity must be canonical public text");
+export const agentTrainingTaskSchema = z.strictObject({
+    benchmark: trainingIdentitySchema,
+    task: trainingIdentitySchema,
+    contentDigest: sha256DigestSchema,
+});
+/** The same order is used by dataset ingestion, receipt admission and holdout checks. */
+export function agentTrainingTaskKey(task) {
+    return JSON.stringify([task.benchmark, task.task, task.contentDigest]);
+}
+export const agentTrainingDatasetIdentitySchema = z.strictObject({
+    digest: sha256DigestSchema,
+    taskSetDigest: sha256DigestSchema,
+    tasks: z.array(agentTrainingTaskSchema).min(1).max(10_000),
+}).superRefine((dataset, context) => {
+    const keys = dataset.tasks.map(agentTrainingTaskKey);
+    if (keys.some((key, index) => index > 0 && key <= keys[index - 1])) {
+        context.addIssue({ code: "custom", path: ["tasks"], message: "training tasks must be sorted and unique" });
+    }
+    if (canonicalCandidateDigest(dataset.tasks) !== dataset.taskSetDigest) {
+        context.addIssue({ code: "custom", path: ["taskSetDigest"], message: "training task inventory digest mismatch" });
+    }
+});
+export const agentTrainingParametersSchema = ownPropertyRecordSchema(z.union([z.string().max(2_048).pipe(publicProfileConfigStringSchema), z.number().finite(), z.boolean(), z.null()])).superRefine((parameters, context) => {
+    if (Object.keys(parameters).length > 100) {
+        context.addIssue({ code: "custom", message: "at most 100 public training parameters are allowed" });
+    }
+    for (const name of Object.keys(parameters)) {
+        if (!trainingIdentitySchema.safeParse(name).success || isCredentialBearingProfileConfigName(name)) {
+            context.addIssue({ code: "custom", path: [name], message: "training parameter name must be public and non-credential" });
+        }
+    }
+});
+export const agentTrainingReceiptSchema = z.strictObject({
+    version: z.literal(1),
+    dataset: agentTrainingDatasetIdentitySchema,
+    parentProfileDigest: sha256DigestSchema,
+    parentReceiptDigest: sha256DigestSchema.nullable(),
+    executionRef: sha256DigestSchema,
+    trainer: z.strictObject({
+        mode: z.enum(["command", "managed"]),
+        id: trainingIdentitySchema,
+        revision: sha256DigestSchema,
+        parameters: agentTrainingParametersSchema,
+    }),
+    checkpoint: z.strictObject({
+        artifactDigest: sha256DigestSchema,
+        artifactBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+        routerModelId: trainingIdentitySchema,
+        servingDigest: sha256DigestSchema,
+    }),
+}).superRefine((receipt, context) => {
+    if (receipt.checkpoint.routerModelId !== trainedModelIdForArtifact(receipt.checkpoint.artifactDigest)) {
+        context.addIssue({ code: "custom", path: ["checkpoint", "routerModelId"], message: "trained Router model must be artifact-addressed" });
+    }
+});
+export const agentProfileTrainingSchema = z.strictObject({
+    receipt: agentTrainingReceiptSchema,
+    ancestors: z.array(agentTrainingReceiptSchema).max(8),
+}).superRefine((training, context) => {
+    const chain = [training.receipt, ...training.ancestors];
+    const digests = chain.map(canonicalCandidateDigest);
+    if (new Set(digests).size !== digests.length) {
+        context.addIssue({ code: "custom", message: "training receipt ancestry must not repeat" });
+    }
+    for (let index = 0; index < chain.length; index++) {
+        if (chain[index].parentReceiptDigest !== (digests[index + 1] ?? null)) {
+            context.addIssue({ code: "custom", message: "training receipt ancestry is incomplete or has been altered" });
+        }
+    }
+});
+export const agentProfileMetadataSchema = ownPropertyRecordSchema(z.unknown()).superRefine((metadata, context) => {
+    if (!Object.hasOwn(metadata, "training"))
+        return;
+    const result = agentProfileTrainingSchema.safeParse(metadata.training);
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            context.addIssue({ code: "custom", path: ["training", ...issue.path], message: issue.message });
+        }
+    }
+});
 /**
  * The complete provider-neutral agent profile schema — the runtime validator for
  * the canonical {@link AgentProfile} TS contract. Kept structurally in lock-step
@@ -345,11 +427,27 @@ export const agentProfileSchema = z
     hooks: ownPropertyRecordSchema(z.array(agentProfileHookCommandSchema)).optional(),
     modes: ownPropertyRecordSchema(agentProfileModeSchema).optional(),
     confidential: agentProfileConfidentialSchema.optional(),
-    metadata: ownPropertyRecordSchema(z.unknown()).optional(),
+    metadata: agentProfileMetadataSchema.optional(),
     extensions: ownPropertyRecordSchema(z.union([ownPropertyRecordSchema(z.unknown()), z.undefined()])).optional(),
 })
     .superRefine((profile, context) => {
     validateNestedRecordKeys(profile, context, [], new Set());
+    const training = agentProfileTrainingSchema.safeParse(profile.metadata?.training);
+    if (profile.model?.default?.startsWith(TRAINED_MODEL_PREFIX) && !training.success) {
+        context.addIssue({ code: "custom", path: ["metadata", "training"], message: "trained model requires a checkpoint receipt" });
+    }
+    const auxiliaryModels = [
+        profile.model?.small,
+        ...Object.values(profile.subagents ?? {}).map((agent) => agent.model),
+        ...Object.values(profile.modes ?? {}).map((mode) => mode.model),
+    ];
+    if (auxiliaryModels.some((model) => model?.startsWith(TRAINED_MODEL_PREFIX) &&
+        (!training.success || model !== training.data.receipt.checkpoint.routerModelId))) {
+        context.addIssue({ code: "custom", message: "trained auxiliary models require the same receipted checkpoint" });
+    }
+    if (training.success && profile.model?.default !== training.data.receipt.checkpoint.routerModelId) {
+        context.addIssue({ code: "custom", path: ["model", "default"], message: "trained profile model must equal the receipt's Router model" });
+    }
 });
 const encodedRecordKeyPattern = "^u(?:[0-9a-f]{4})*$";
 function isEncodedRecordKeyPropertyNames(value) {

package/package.json

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