@tangle-network/agent-interface 0.47.0 → 0.48.0

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

@@ -35,6 +35,9 @@ export declare const agentCandidateProfileSchema: z.ZodObject<{
             xhigh: "xhigh";
             ultracode: "ultracode";
         }>>;
+        maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+        maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+        maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
         default: z.ZodOptional<z.ZodString>;
         small: z.ZodOptional<z.ZodString>;
         provider: z.ZodOptional<z.ZodString>;

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

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { agentCandidateResourcesSchema } from "./agent-candidate-artifact-schema.js";
 import { agentCandidateConfigValueSchema, environmentConfigSchema, isCanonicalJsonValue, isSafeExecutable, isSafeRelativePath, isWellFormedUnicode, } from "./agent-candidate-schema-common.js";
 import { harnessTypeSchema } from "./harness.js";
-import { agentProfileConfidentialSchema, agentProfileModeSchema, agentProfileModelHintsSchema, agentProfilePermissionSchema, agentProfilePromptSchema, agentSubagentProfileSchema, } from "./profile-schema.js";
+import { agentProfileConfidentialSchema, agentProfileModeSchema, agentProfileModelHintsBaseSchema, agentProfilePermissionSchema, agentProfilePromptSchema, agentSubagentProfileSchema, enforceModelTokenBounds, } from "./profile-schema.js";
 const executableSchema = z
     .string()
     .refine(isSafeExecutable, "executable must be a canonical non-shell command");
@@ -39,14 +39,15 @@ export const agentCandidateHookCommandSchema = z
     env: environmentConfigSchema.optional(),
 })
     .strict();
-const candidateModelHintsSchema = agentProfileModelHintsSchema
+const candidateModelHintsSchema = agentProfileModelHintsBaseSchema
     .omit({ metadata: true })
     .extend({
     default: z.string().min(1).optional(),
     small: z.string().min(1).optional(),
     provider: z.string().min(1).optional(),
 })
-    .strict();
+    .strict()
+    .superRefine(enforceModelTokenBounds);
 const candidateSubagentSchema = agentSubagentProfileSchema
     .omit({ metadata: true })
     .extend({

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

@@ -26,6 +26,9 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
                     xhigh: "xhigh";
                     ultracode: "ultracode";
                 }>>;
+                maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+                maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+                maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
                 default: z.ZodOptional<z.ZodString>;
                 small: z.ZodOptional<z.ZodString>;
                 provider: z.ZodOptional<z.ZodString>;
@@ -856,6 +859,9 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
                     xhigh: "xhigh";
                     ultracode: "ultracode";
                 }>>;
+                maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+                maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+                maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
                 default: z.ZodOptional<z.ZodString>;
                 small: z.ZodOptional<z.ZodString>;
                 provider: z.ZodOptional<z.ZodString>;
@@ -3599,6 +3605,9 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                         xhigh: "xhigh";
                         ultracode: "ultracode";
                     }>>;
+                    maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+                    maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+                    maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
                     default: z.ZodOptional<z.ZodString>;
                     small: z.ZodOptional<z.ZodString>;
                     provider: z.ZodOptional<z.ZodString>;
@@ -4429,6 +4438,9 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                         xhigh: "xhigh";
                         ultracode: "ultracode";
                     }>>;
+                    maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+                    maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+                    maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
                     default: z.ZodOptional<z.ZodString>;
                     small: z.ZodOptional<z.ZodString>;
                     provider: z.ZodOptional<z.ZodString>;
@@ -8592,6 +8604,9 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                             xhigh: "xhigh";
                             ultracode: "ultracode";
                         }>>;
+                        maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+                        maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+                        maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
                         default: z.ZodOptional<z.ZodString>;
                         small: z.ZodOptional<z.ZodString>;
                         provider: z.ZodOptional<z.ZodString>;
@@ -9422,6 +9437,9 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                             xhigh: "xhigh";
                             ultracode: "ultracode";
                         }>>;
+                        maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+                        maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+                        maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
                         default: z.ZodOptional<z.ZodString>;
                         small: z.ZodOptional<z.ZodString>;
                         provider: z.ZodOptional<z.ZodString>;

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

@@ -186,7 +186,16 @@ export function isCanonicalJsonValue(value, ancestors = new Set()) {
     }
     const nextAncestors = new Set(ancestors).add(value);
     if (Array.isArray(value)) {
-        return value.every((entry) => isCanonicalJsonValue(entry, nextAncestors));
+        for (let index = 0; index < value.length; index += 1) {
+            // A sparse hole serializes to the same bytes as a dense null but is a
+            // distinct in-memory value, so two observable inputs would share one
+            // content digest. Reject the sparse form; never change the output bytes.
+            if (!(index in value))
+                return false;
+            if (!isCanonicalJsonValue(value[index], nextAncestors))
+                return false;
+        }
+        return true;
     }
     return Object.entries(value).every(([key, entry]) => isWellFormedUnicode(key) && isCanonicalJsonValue(entry, nextAncestors));
 }

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

@@ -30,6 +30,9 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
                 xhigh: "xhigh";
                 ultracode: "ultracode";
             }>>;
+            maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+            maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+            maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
             default: z.ZodOptional<z.ZodString>;
             small: z.ZodOptional<z.ZodString>;
             provider: z.ZodOptional<z.ZodString>;

package/dist/agent-profile.d.ts

@@ -122,8 +122,26 @@ export interface AgentProfileModelHints {
     /**
      * Reasoning/thinking effort hint — a first-class, portable model dimension (not buried in
      * `extensions`). Backends map it to their native control at materialization.
+     *
+     * This is a quality dial, not a spend limit. It never bounds token count.
      */
     reasoningEffort?: ReasoningEffort;
+    /**
+     * Maximum visible answer tokens a backend may bill for one completion.
+     * A positive integer. Independent of the reasoning and total ceilings.
+     */
+    maxVisibleOutputTokens?: number;
+    /**
+     * Maximum hidden reasoning tokens a backend may bill for one completion.
+     * A positive integer, separate from visible answer tokens.
+     */
+    maxReasoningTokens?: number;
+    /**
+     * Maximum total billed completion tokens for visible answer and hidden
+     * reasoning tokens together. A positive integer. When it is set with either
+     * single ceiling, that single ceiling must not exceed it.
+     */
+    maxTotalOutputTokens?: number;
     /**
      * Backend-agnostic model metadata/hints.
      */

package/dist/interaction-data.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { boundedIdentifierSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_MAP_ENTRIES, } from "./contract-limits.js";
-import { InteractionFieldNameSchema } from "./interaction-fields.js";
+import { InteractionFieldNameSchema, RESERVED_INTERACTION_FIELD_NAMES, } from "./interaction-fields.js";
 export const InteractionSecretReferenceSchema = z.strictObject({
     kind: z.literal("secret_handle"),
     handleId: boundedIdentifierSchema,
@@ -15,6 +15,25 @@ const InteractionDataValueSchema = z.union([
 ]);
 /** Field values keyed by InteractionField.name. */
 export const InteractionDataSchema = z
+    .unknown()
+    // A record parser assigns keys onto an ordinary object, so a raw own key
+    // `__proto__` invokes the legacy prototype setter and vanishes before any
+    // key schema runs. Reject reserved keys on the raw input, so this schema and
+    // `validateInteractionResponse` refuse the same value rather than one of them
+    // accepting a silently emptied object.
+    .superRefine((value, refinement) => {
+    if (value === null || typeof value !== "object")
+        return;
+    for (const key of Object.getOwnPropertyNames(value)) {
+        if (RESERVED_INTERACTION_FIELD_NAMES.has(key)) {
+            refinement.addIssue({
+                code: "custom",
+                message: `interaction field name "${key}" is reserved`,
+            });
+        }
+    }
+})
+    .pipe(z
     .record(InteractionFieldNameSchema, InteractionDataValueSchema)
     .superRefine((data, refinement) => {
     if (Object.keys(data).length > CONTRACT_MAX_MAP_ENTRIES) {
@@ -23,7 +42,7 @@ export const InteractionDataSchema = z
             message: "interaction data has too many fields",
         });
     }
-})
+}))
     .transform((data) => {
     const safe = Object.create(null);
     for (const key of Object.keys(data))

package/dist/interaction-fields.d.ts

@@ -1,4 +1,11 @@
 import { z } from "zod";
+/**
+ * Field names whose own-key form collides with object internals. A record
+ * parser drops a raw `__proto__` key through the legacy prototype setter before
+ * a key schema runs, so every schema and validator over interaction data
+ * rejects these names against one owner rather than a private copy.
+ */
+export declare const RESERVED_INTERACTION_FIELD_NAMES: ReadonlySet<string>;
 export declare const InteractionFieldNameSchema: z.ZodString;
 export declare const InteractionFieldSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text">;

package/dist/interaction-fields.js

@@ -1,7 +1,17 @@
 import { z } from "zod";
 import { boundedIdentifierSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_STRING_LENGTH, } from "./contract-limits.js";
-const forbiddenFieldNames = new Set(["__proto__", "constructor", "prototype"]);
-export const InteractionFieldNameSchema = boundedIdentifierSchema.refine((value) => !forbiddenFieldNames.has(value), "interaction field name is reserved");
+/**
+ * Field names whose own-key form collides with object internals. A record
+ * parser drops a raw `__proto__` key through the legacy prototype setter before
+ * a key schema runs, so every schema and validator over interaction data
+ * rejects these names against one owner rather than a private copy.
+ */
+export const RESERVED_INTERACTION_FIELD_NAMES = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+export const InteractionFieldNameSchema = boundedIdentifierSchema.refine((value) => !RESERVED_INTERACTION_FIELD_NAMES.has(value), "interaction field name is reserved");
 // =============================================================================
 // Answer specification — describes the shape of a valid answer.
 // =============================================================================

package/dist/interaction-response-validation.js

@@ -1,6 +1,6 @@
 import { InteractionRequestSchema, InteractionResponseCommandSchema, InteractionResponseSchema, } from "./interaction-envelope.js";
+import { RESERVED_INTERACTION_FIELD_NAMES } from "./interaction-fields.js";
 import { validateResolutionForRequest } from "./interaction-resolution-validation.js";
-const FORBIDDEN_DATA_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 function validResponse(response) {
     const result = { ok: true };
     Object.defineProperty(result, "response", {
@@ -17,7 +17,7 @@ function forbiddenKeyErrors(response) {
     if (!data || typeof data !== "object")
         return [];
     return Object.getOwnPropertyNames(data)
-        .filter((key) => FORBIDDEN_DATA_KEYS.has(key))
+        .filter((key) => RESERVED_INTERACTION_FIELD_NAMES.has(key))
         .map((key) => `unknown field "${key}"`);
 }
 /** Validate one response against the exact outstanding request. */

package/dist/profile-schema.d.ts

@@ -120,6 +120,34 @@ export declare const reasoningEffortSchema: z.ZodEnum<{
     xhigh: "xhigh";
     ultracode: "ultracode";
 }>;
+/**
+ * Enforce the token ceilings that live together: each single ceiling must not
+ * exceed the total. It fails loud on a violation and never clamps a value.
+ * `reasoningEffort` is a separate quality dial and is not a bound here.
+ */
+export declare function enforceModelTokenBounds(hints: {
+    maxVisibleOutputTokens?: number;
+    maxReasoningTokens?: number;
+    maxTotalOutputTokens?: number;
+}, context: z.RefinementCtx): void;
+export declare const agentProfileModelHintsBaseSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodString>;
+    small: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    reasoningEffort: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        ultracode: "ultracode";
+    }>>;
+    maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+    maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+    maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+}, z.core.$strict>;
 export declare const agentProfileModelHintsSchema: z.ZodObject<{
     default: z.ZodOptional<z.ZodString>;
     small: z.ZodOptional<z.ZodString>;
@@ -133,6 +161,9 @@ export declare const agentProfileModelHintsSchema: z.ZodObject<{
         xhigh: "xhigh";
         ultracode: "ultracode";
     }>>;
+    maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+    maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+    maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
     metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
 }, z.core.$strict>;
 /**
@@ -321,6 +352,9 @@ export declare const agentProfileSchema: z.ZodObject<{
             xhigh: "xhigh";
             ultracode: "ultracode";
         }>>;
+        maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+        maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+        maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
         metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
     }, z.core.$strict>>;
     harness: z.ZodOptional<z.ZodEnum<{

package/dist/profile-schema.js

@@ -91,13 +91,45 @@ export const agentProfileResourcesSchema = z.strictObject({
     failOnError: z.boolean().optional(),
 });
 export const reasoningEffortSchema = z.enum(REASONING_EFFORTS);
-export const agentProfileModelHintsSchema = z.strictObject({
+/**
+ * Enforce the token ceilings that live together: each single ceiling must not
+ * exceed the total. It fails loud on a violation and never clamps a value.
+ * `reasoningEffort` is a separate quality dial and is not a bound here.
+ */
+export function enforceModelTokenBounds(hints, context) {
+    const { maxVisibleOutputTokens, maxReasoningTokens, maxTotalOutputTokens } = hints;
+    if (maxTotalOutputTokens === undefined)
+        return;
+    if (maxVisibleOutputTokens !== undefined &&
+        maxVisibleOutputTokens > maxTotalOutputTokens) {
+        context.addIssue({
+            code: "custom",
+            path: ["maxVisibleOutputTokens"],
+            message: "maxVisibleOutputTokens must not exceed maxTotalOutputTokens",
+        });
+    }
+    if (maxReasoningTokens !== undefined &&
+        maxReasoningTokens > maxTotalOutputTokens) {
+        context.addIssue({
+            code: "custom",
+            path: ["maxReasoningTokens"],
+            message: "maxReasoningTokens must not exceed maxTotalOutputTokens",
+        });
+    }
+}
+// Base shape without cross-field checks, so candidate derivations may still
+// call `.omit`/`.extend`; zod refuses those on a schema that carries a refinement.
+export const agentProfileModelHintsBaseSchema = z.strictObject({
     default: z.string().optional(),
     small: z.string().optional(),
     provider: z.string().optional(),
     reasoningEffort: reasoningEffortSchema.optional(),
+    maxVisibleOutputTokens: z.number().int().positive().optional(),
+    maxReasoningTokens: z.number().int().positive().optional(),
+    maxTotalOutputTokens: z.number().int().positive().optional(),
     metadata: ownPropertyRecordSchema(z.unknown()).optional(),
 });
+export const agentProfileModelHintsSchema = agentProfileModelHintsBaseSchema.superRefine(enforceModelTokenBounds);
 /**
  * Replacement and addition are separate, independently optional fields, and the
  * pair is admitted on purpose: the effective prompt is `systemPrompt` followed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -16,6 +16,41 @@
       "import": "./dist/environment-provider.js",
       "types": "./dist/environment-provider.d.ts",
       "default": "./dist/environment-provider.js"
+    },
+    "./profile": {
+      "import": "./dist/agent-profile.js",
+      "types": "./dist/agent-profile.d.ts",
+      "default": "./dist/agent-profile.js"
+    },
+    "./profile-snapshot": {
+      "import": "./dist/agent-profile-snapshot.js",
+      "types": "./dist/agent-profile-snapshot.d.ts",
+      "default": "./dist/agent-profile-snapshot.js"
+    },
+    "./profile-schema": {
+      "import": "./dist/profile-schema.js",
+      "types": "./dist/profile-schema.d.ts",
+      "default": "./dist/profile-schema.js"
+    },
+    "./profile-security": {
+      "import": "./dist/profile-security.js",
+      "types": "./dist/profile-security.d.ts",
+      "default": "./dist/profile-security.js"
+    },
+    "./harness": {
+      "import": "./dist/harness.js",
+      "types": "./dist/harness.d.ts",
+      "default": "./dist/harness.js"
+    },
+    "./harness-capabilities": {
+      "import": "./dist/harness-capabilities.js",
+      "types": "./dist/harness-capabilities.d.ts",
+      "default": "./dist/harness-capabilities.js"
+    },
+    "./interaction": {
+      "import": "./dist/interaction.js",
+      "types": "./dist/interaction.d.ts",
+      "default": "./dist/interaction.js"
     }
   },
   "repository": {