@tangle-network/agent-interface 0.34.0 → 0.36.0

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

@@ -178,6 +178,11 @@ export declare const agentProfileImprovementSuiteInputsSchema: z.ZodObject<{
 export declare const agentProfileImprovementArmSchema: z.ZodObject<{
     stateDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
 }, z.core.$strict>;
+export declare const agentProfileImprovementExecutionRefSchema: z.ZodObject<{
+    identity: z.ZodString;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+}, z.core.$strict>;
 /**
  * The first product path changes only prompt and skills, but it uses the
  * shared profile-diff language so execution and activation apply identical
@@ -194,6 +199,11 @@ export declare const agentProfileImprovementExperimentSchema: z.ZodObject<{
         sourceDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         sourceRevision: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
     }, z.core.$strict>;
+    executionRef: z.ZodObject<{
+        identity: z.ZodString;
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+    }, z.core.$strict>;
     baseline: z.ZodObject<{
         stateDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     }, z.core.$strict>;
@@ -360,6 +370,11 @@ export declare const agentProfileImprovementRunReceiptSchema: z.ZodObject<{
     kind: z.ZodLiteral<"agent-profile-improvement-run">;
     digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
     executionId: z.ZodString;
+    executionRef: z.ZodObject<{
+        identity: z.ZodString;
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+    }, z.core.$strict>;
     runCell: z.ZodObject<{
         kind: z.ZodLiteral<"agent-profile-improvement-run-cell">;
         experimentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -395,6 +410,7 @@ export declare const agentProfileImprovementRunReceiptSchema: z.ZodObject<{
         endedAtMs: z.ZodNumber;
         durationMs: z.ZodNumber;
     }, z.core.$strict>;
+    steps: z.ZodNumber;
     resolvedModel: z.ZodObject<{
         requested: z.ZodString;
         provider: z.ZodString;
@@ -425,6 +441,10 @@ export declare const agentProfileImprovementRunReceiptSchema: z.ZodObject<{
         reasoningTokens: z.ZodNumber;
         modelCalls: z.ZodNumber;
         costUsdNanos: z.ZodNumber;
+        costProvenance: z.ZodEnum<{
+            observed: "observed";
+            estimated: "estimated";
+        }>;
     }, z.core.$strict>;
     trace: z.ZodObject<{
         evidence: z.ZodObject<{
@@ -484,6 +504,10 @@ export declare const agentProfileImprovementRunReceiptSchema: z.ZodObject<{
             reasoningTokens: z.ZodNumber;
             modelCalls: z.ZodNumber;
             costUsdNanos: z.ZodNumber;
+            costProvenance: z.ZodEnum<{
+                observed: "observed";
+                estimated: "estimated";
+            }>;
         }, z.core.$strict>;
         score: z.ZodNumber;
         passed: z.ZodBoolean;
@@ -639,12 +663,37 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
     diff: z.ZodString;
     evaluation: z.ZodObject<{
         generationsExplored: z.ZodNumber;
-        searchDurationMs: z.ZodNumber;
-        executionDurationMs: z.ZodNumber;
-        durationMs: z.ZodNumber;
-        searchCostUsd: z.ZodNumber;
-        executionCostUsd: z.ZodNumber;
-        totalCostUsd: z.ZodNumber;
+        preparation: z.ZodObject<{
+            wallDurationMs: z.ZodNumber;
+            cost: z.ZodObject<{
+                usd: z.ZodNumber;
+                provenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        measurement: z.ZodObject<{
+            wallDurationMs: z.ZodNumber;
+            workDurationMs: z.ZodNumber;
+            cost: z.ZodObject<{
+                usd: z.ZodNumber;
+                provenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        total: z.ZodObject<{
+            wallDurationMs: z.ZodNumber;
+            cost: z.ZodObject<{
+                usd: z.ZodNumber;
+                provenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
     }, z.core.$strict>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<import("./agent-candidate.js").AgentCandidateJsonValue, import("./agent-candidate.js").AgentCandidateJsonValue>>>;
     kind: z.ZodLiteral<"agent-profile-improvement-measured-comparison">;
@@ -657,6 +706,11 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
             sourceDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             sourceRevision: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
         }, z.core.$strict>;
+        executionRef: z.ZodObject<{
+            identity: z.ZodString;
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+        }, z.core.$strict>;
         baseline: z.ZodObject<{
             stateDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         }, z.core.$strict>;
@@ -808,6 +862,11 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
             kind: z.ZodLiteral<"agent-profile-improvement-run">;
             digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
             executionId: z.ZodString;
+            executionRef: z.ZodObject<{
+                identity: z.ZodString;
+                digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+            }, z.core.$strict>;
             runCell: z.ZodObject<{
                 kind: z.ZodLiteral<"agent-profile-improvement-run-cell">;
                 experimentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -843,6 +902,7 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                 endedAtMs: z.ZodNumber;
                 durationMs: z.ZodNumber;
             }, z.core.$strict>;
+            steps: z.ZodNumber;
             resolvedModel: z.ZodObject<{
                 requested: z.ZodString;
                 provider: z.ZodString;
@@ -873,6 +933,10 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                 reasoningTokens: z.ZodNumber;
                 modelCalls: z.ZodNumber;
                 costUsdNanos: z.ZodNumber;
+                costProvenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
             }, z.core.$strict>;
             trace: z.ZodObject<{
                 evidence: z.ZodObject<{
@@ -932,6 +996,10 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                     reasoningTokens: z.ZodNumber;
                     modelCalls: z.ZodNumber;
                     costUsdNanos: z.ZodNumber;
+                    costProvenance: z.ZodEnum<{
+                        observed: "observed";
+                        estimated: "estimated";
+                    }>;
                 }, z.core.$strict>;
                 score: z.ZodNumber;
                 passed: z.ZodBoolean;
@@ -946,6 +1014,11 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
             kind: z.ZodLiteral<"agent-profile-improvement-run">;
             digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
             executionId: z.ZodString;
+            executionRef: z.ZodObject<{
+                identity: z.ZodString;
+                digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+            }, z.core.$strict>;
             runCell: z.ZodObject<{
                 kind: z.ZodLiteral<"agent-profile-improvement-run-cell">;
                 experimentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -981,6 +1054,7 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                 endedAtMs: z.ZodNumber;
                 durationMs: z.ZodNumber;
             }, z.core.$strict>;
+            steps: z.ZodNumber;
             resolvedModel: z.ZodObject<{
                 requested: z.ZodString;
                 provider: z.ZodString;
@@ -1011,6 +1085,10 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                 reasoningTokens: z.ZodNumber;
                 modelCalls: z.ZodNumber;
                 costUsdNanos: z.ZodNumber;
+                costProvenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
             }, z.core.$strict>;
             trace: z.ZodObject<{
                 evidence: z.ZodObject<{
@@ -1070,6 +1148,10 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                     reasoningTokens: z.ZodNumber;
                     modelCalls: z.ZodNumber;
                     costUsdNanos: z.ZodNumber;
+                    costProvenance: z.ZodEnum<{
+                        observed: "observed";
+                        estimated: "estimated";
+                    }>;
                 }, z.core.$strict>;
                 score: z.ZodNumber;
                 passed: z.ZodBoolean;

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

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { agentCandidateLineageSchema } from "./agent-candidate-lineage-schema.js";
 import { canonicalCandidateDigest, isCanonicalJsonValue, omitTopLevelDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { refineAgentExecutionWithinLimits } from "./agent-execution-limits.js";
 import { agentCandidateBenchmarkGraderIdentitySchema, agentCandidateExecutionLimitsSchema, agentCandidateResolvedModelSchema, } from "./agent-candidate-execution-plan-schema.js";
 import { agentCandidateBenchmarkDimensionSchema, agentCandidateFixedSpendSchema, } from "./agent-candidate-outcome-schema.js";
 import { agentCandidateEvaluationPolicySchema, createMeasuredComparisonIdentityRegistry, measuredComparisonCommonShape, refineMeasuredComparisonSummary, } from "./agent-improvement-measurement-schema.js";
@@ -97,6 +98,11 @@ export const agentProfileImprovementArmSchema = z
     stateDigest: sha256DigestSchema,
 })
     .strict();
+export const agentProfileImprovementExecutionRefSchema = profileImprovementEvidenceSchema
+    .extend({
+    kind: z.literal("agent-profile-improvement-execution-ref"),
+})
+    .strict();
 /**
  * The first product path changes only prompt and skills, but it uses the
  * shared profile-diff language so execution and activation apply identical
@@ -175,6 +181,7 @@ export const agentProfileImprovementExperimentSchema = z
     kind: z.literal("agent-profile-improvement-experiment"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     source: agentImprovementSourceSchema,
+    executionRef: agentProfileImprovementExecutionRefSchema,
     baseline: agentProfileImprovementArmSchema,
     candidate: agentProfileImprovementArmSchema,
     change: agentProfileImprovementChangeSchema,
@@ -304,12 +311,14 @@ export const agentProfileImprovementRunReceiptSchema = z
     kind: z.literal("agent-profile-improvement-run"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     executionId: z.string().min(1).max(500),
+    executionRef: agentProfileImprovementExecutionRefSchema,
     runCell: agentProfileImprovementRunCellSchema,
     runRecord: profileImprovementEvidenceSchema,
     billing: z
         .tuple([profileImprovementEvidenceSchema])
         .rest(profileImprovementEvidenceSchema),
     timing: timingSchema,
+    steps: z.number().int().nonnegative().safe(),
     resolvedModel: agentCandidateResolvedModelSchema,
     limits: agentCandidateExecutionLimitsSchema,
     usage: agentCandidateFixedSpendSchema,
@@ -357,6 +366,11 @@ export const agentProfileImprovementRunReceiptSchema = z
             message: "profile trace must retain at least one event for every model call",
         });
     }
+    refineAgentExecutionWithinLimits(receipt.limits, {
+        durationMs: receipt.timing.durationMs,
+        steps: receipt.steps,
+        usage: combinedProfileUsage(receipt.usage, receipt.grading.usage),
+    }, ctx);
     const billing = receipt.billing.map(evidenceKey);
     if (new Set(billing).size !== billing.length) {
         ctx.addIssue({
@@ -373,6 +387,19 @@ export const agentProfileImprovementRunReceiptSchema = z
         });
     }
 });
+function combinedProfileUsage(execution, grading) {
+    return {
+        inputTokens: execution.inputTokens + grading.inputTokens,
+        outputTokens: execution.outputTokens + grading.outputTokens,
+        cachedInputTokens: execution.cachedInputTokens + grading.cachedInputTokens,
+        reasoningTokens: execution.reasoningTokens + grading.reasoningTokens,
+        modelCalls: execution.modelCalls + grading.modelCalls,
+        costUsdNanos: execution.costUsdNanos + grading.costUsdNanos,
+        costProvenance: execution.costProvenance === "observed" && grading.costProvenance === "observed"
+            ? "observed"
+            : "estimated",
+    };
+}
 const agentProfileImprovementMeasurementSchema = z
     .object({
     baseline: agentProfileImprovementRunReceiptSchema,
@@ -448,6 +475,11 @@ function refineProfileImprovementComparison(comparison, ctx) {
                         [...armPath, "runCell", "experimentDigest"],
                         "profile run receipt must bind the measured experiment",
                     ],
+                    [
+                        JSON.stringify(receipt.executionRef) === JSON.stringify(comparison.experiment.executionRef),
+                        [...armPath, "executionRef"],
+                        "profile run receipt must bind the measured executor",
+                    ],
                     [
                         cell.arm === arm,
                         [...armPath, "runCell", "arm"],
@@ -530,6 +562,7 @@ function refineProfileImprovementComparison(comparison, ctx) {
         score: (receipt) => receipt.grading.score,
         dimension: (receipt, name) => receipt.grading.dimensions.find((dimension) => dimension.name === name)?.score,
         cost: profileImprovementExecutionCostUsd,
+        costProvenance: profileImprovementExecutionCostProvenance,
         latency: profileImprovementExecutionLatencyMs,
     }, ctx);
     if (!isCanonicalJsonValue(comparison)) {
@@ -548,6 +581,12 @@ function evidenceKey(evidence) {
 function profileImprovementExecutionCostUsd(receipt) {
     return (receipt.usage.costUsdNanos + receipt.grading.usage.costUsdNanos) / 1_000_000_000;
 }
+function profileImprovementExecutionCostProvenance(receipt) {
+    return receipt.usage.costProvenance === "observed" &&
+        receipt.grading.usage.costProvenance === "observed"
+        ? "observed"
+        : "estimated";
+}
 function profileImprovementExecutionLatencyMs(receipt) {
     return receipt.timing.durationMs + receipt.grading.timing.durationMs;
 }

package/dist/agent-profile-improvement.d.ts

@@ -44,6 +44,10 @@ export interface AgentProfileImprovementSuiteInputs {
 export interface AgentProfileImprovementArm {
     stateDigest: Sha256Digest;
 }
+/** Exact non-secret identity of the runner that measured and can activate a profile change. */
+export interface AgentProfileImprovementExecutionRef extends AgentProfileImprovementEvidence {
+    kind: "agent-profile-improvement-execution-ref";
+}
 /**
  * Ordered portable profile patches retained for review and activation.
  *
@@ -58,6 +62,7 @@ export interface AgentProfileImprovementExperimentMaterial {
     kind: "agent-profile-improvement-experiment";
     digestAlgorithm: AgentCandidateDigestAlgorithm;
     source: AgentImprovementSource;
+    executionRef: AgentProfileImprovementExecutionRef;
     baseline: AgentProfileImprovementArm;
     candidate: AgentProfileImprovementArm;
     change: AgentProfileImprovementChange;
@@ -89,6 +94,7 @@ export interface AgentProfileImprovementRunReceipt {
     kind: "agent-profile-improvement-run";
     digestAlgorithm: AgentCandidateDigestAlgorithm;
     executionId: string;
+    executionRef: AgentProfileImprovementExecutionRef;
     runCell: AgentProfileImprovementRunCell;
     runRecord: AgentProfileImprovementEvidence;
     billing: [AgentProfileImprovementEvidence, ...AgentProfileImprovementEvidence[]];
@@ -97,6 +103,7 @@ export interface AgentProfileImprovementRunReceipt {
         endedAtMs: number;
         durationMs: number;
     };
+    steps: number;
     resolvedModel: AgentCandidateResolvedModel;
     limits: AgentCandidateExecutionLimits;
     usage: AgentCandidateFixedSpend;

package/dist/index.d.ts

@@ -613,11 +613,15 @@ export interface SdkProviderAdapter {
 export * from "./interaction.js";
 export * from "./agent-candidate.js";
 export * from "./agent-candidate-schema.js";
+export type { Sha256Digest } from "./agent-candidate.js";
+export { canonicalCandidateBytes, canonicalCandidateDigest, canonicalCandidateJson, sha256Bytes, sha256DigestSchema, sha256Utf8, } from "./agent-candidate-schema-common.js";
+export { numbersApproximatelyEqual } from "./number-validation.js";
 export * from "./agent-candidate-promotion-schema.js";
 export { agentCandidateEvaluationPolicySchema } from "./agent-improvement-measurement-schema.js";
 export * from "./agent-improvement-source.js";
 export * from "./agent-profile-improvement.js";
 export * from "./agent-profile-improvement-schema.js";
+export * from "./agent-execution-limits.js";
 export * from "./agent-profile.js";
 export * from "./certified-context.js";
 export * from "./profile-diff.js";

package/dist/index.js

@@ -126,11 +126,14 @@ export function resolveNativeWebTools(tools) {
 export * from "./interaction.js";
 export * from "./agent-candidate.js";
 export * from "./agent-candidate-schema.js";
+export { canonicalCandidateBytes, canonicalCandidateDigest, canonicalCandidateJson, sha256Bytes, sha256DigestSchema, sha256Utf8, } from "./agent-candidate-schema-common.js";
+export { numbersApproximatelyEqual } from "./number-validation.js";
 export * from "./agent-candidate-promotion-schema.js";
 export { agentCandidateEvaluationPolicySchema } from "./agent-improvement-measurement-schema.js";
 export * from "./agent-improvement-source.js";
 export * from "./agent-profile-improvement.js";
 export * from "./agent-profile-improvement-schema.js";
+export * from "./agent-execution-limits.js";
 export * from "./agent-profile.js";
 export * from "./certified-context.js";
 export * from "./profile-diff.js";

package/package.json

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