@tangle-network/agent-interface 0.33.0 → 0.35.0

package/dist/agent-candidate.d.ts

@@ -1,5 +1,6 @@
 import type { AgentProfile, AgentProfileFileMount, AgentProfileHookCommand, AgentProfileMode, AgentProfileModelHints, AgentProfileResources, AgentSubagentProfile, ReasoningEffort } from "./agent-profile.js";
 import type { HarnessType } from "./harness.js";
+import type { AgentProfileImprovementMeasuredComparison } from "./agent-profile-improvement.js";
 /** Full SHA-256 digest with an explicit algorithm prefix. */
 export type Sha256Digest = `sha256:${string}`;
 /** RFC 8785 JSON Canonicalization Scheme followed by SHA-256. */
@@ -657,6 +658,7 @@ export interface AgentCandidateRunReceipt {
         endedAtMs: number;
         durationMs: number;
     };
+    steps: number;
     memory: AgentCandidateMemoryReceipt;
     trace: AgentCandidateTraceEvidence;
     termination: AgentCandidateTermination;
@@ -672,11 +674,11 @@ export interface AgentCandidateExperimentMeasurement {
     baseline: CandidateExecutionEvidence;
     candidate: CandidateExecutionEvidence;
 }
-/** Portable paired held-out comparison produced by an evaluation package. */
-export interface AgentImprovementMeasuredComparison {
-    kind: "agent-improvement-measured-comparison";
-    experiment: AgentCandidateExperiment;
-    measurements: AgentCandidateExperimentMeasurement[];
+/** Common measured result shared by sealed and normal-profile experiments. */
+export interface AgentImprovementMeasuredComparisonBase<TExperiment, TMeasurement, TKind extends string> {
+    kind: TKind;
+    experiment: TExperiment;
+    measurements: TMeasurement[];
     overall: {
         name: "composite";
         baseline: number;
@@ -776,6 +778,11 @@ export interface AgentImprovementMeasuredComparison {
         [key: string]: AgentCandidateJsonValue;
     };
 }
+/** Portable paired held-out comparison produced by a sealed candidate executor. */
+export interface AgentImprovementMeasuredComparison extends AgentImprovementMeasuredComparisonBase<AgentCandidateExperiment, AgentCandidateExperimentMeasurement, "agent-improvement-measured-comparison"> {
+}
+/** A reviewable measured result can come from a sealed executor or a normal profile executor. */
+export type AgentImprovementEvaluation = AgentImprovementMeasuredComparison | AgentProfileImprovementMeasuredComparison;
 export interface AgentImprovementProposal {
     kind: "agent-improvement-proposal";
     runId: string;
@@ -784,7 +791,7 @@ export interface AgentImprovementProposal {
     findings: {
         [key: string]: AgentCandidateJsonValue;
     }[];
-    evaluation: AgentImprovementMeasuredComparison;
+    evaluation: AgentImprovementEvaluation;
     digest: Sha256Digest;
 }
 export type AgentImprovementReviewDecision = "approve" | "reject" | "request-changes";
@@ -813,7 +820,8 @@ export interface AgentImprovementActivation {
     proposalDigest: Sha256Digest;
     reviewDigest: Sha256Digest;
     experimentDigest: Sha256Digest;
-    candidateBundleDigest: Sha256Digest;
+    /** Exact proposed state, whether it is a sealed bundle or a normal profile. */
+    candidateDigest: Sha256Digest;
     intent: AgentImprovementActivationIntent;
     targets: [AgentImprovementActivationTarget, ...AgentImprovementActivationTarget[]];
     fundingOwner: string;

package/dist/agent-execution-limits.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { AgentCandidateExecutionLimits, AgentCandidateFixedSpend } from "./agent-candidate.js";
+/** The observable execution facts required to prove a frozen limit was respected. */
+export interface AgentExecutionLimitObservation {
+    durationMs: number;
+    steps: number;
+    usage: AgentCandidateFixedSpend;
+}
+export declare const agentExecutionLimitObservationSchema: z.ZodObject<{
+    durationMs: z.ZodNumber;
+    steps: z.ZodNumber;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cachedInputTokens: z.ZodNumber;
+        reasoningTokens: z.ZodNumber;
+        modelCalls: z.ZodNumber;
+        costUsdNanos: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export interface RefineAgentExecutionWithinLimitsOptions {
+    pathPrefix?: (string | number)[];
+    usagePath?: (string | number)[];
+}
+/** Reject an execution record that cannot satisfy every limit it claims to use. */
+export declare function assertAgentExecutionWithinLimits(limits: AgentCandidateExecutionLimits, observation: AgentExecutionLimitObservation): void;
+/** Add schema issues instead of throwing when a receipt is parsed by Zod. */
+export declare function refineAgentExecutionWithinLimits(limits: AgentCandidateExecutionLimits, observation: AgentExecutionLimitObservation, ctx: z.RefinementCtx, options?: RefineAgentExecutionWithinLimitsOptions): void;

package/dist/agent-execution-limits.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { agentCandidateExecutionLimitsSchema } from "./agent-candidate-execution-plan-schema.js";
+import { agentCandidateFixedSpendSchema } from "./agent-candidate-outcome-schema.js";
+export const agentExecutionLimitObservationSchema = z
+    .object({
+    durationMs: z.number().finite().nonnegative(),
+    steps: z.number().int().nonnegative().safe(),
+    usage: agentCandidateFixedSpendSchema,
+})
+    .strict();
+/** Reject an execution record that cannot satisfy every limit it claims to use. */
+export function assertAgentExecutionWithinLimits(limits, observation) {
+    const parsedLimits = agentCandidateExecutionLimitsSchema.parse(limits);
+    const parsedObservation = agentExecutionLimitObservationSchema.parse(observation);
+    const violations = executionLimitViolations(parsedLimits, parsedObservation);
+    if (violations.length === 0)
+        return;
+    throw new Error(violations
+        .map((violation) => `execution ${violation.label} ${violation.actual} exceeds frozen limit ${violation.maximum}`)
+        .join("; "));
+}
+/** Add schema issues instead of throwing when a receipt is parsed by Zod. */
+export function refineAgentExecutionWithinLimits(limits, observation, ctx, options = {}) {
+    const pathPrefix = options.pathPrefix ?? [];
+    const usagePath = options.usagePath ?? ["usage"];
+    for (const violation of executionLimitViolations(limits, observation)) {
+        const path = violation.path[0] === "usage"
+            ? [...pathPrefix, ...usagePath, ...violation.path.slice(1)]
+            : [...pathPrefix, ...violation.path];
+        ctx.addIssue({
+            code: "custom",
+            path,
+            message: `execution ${violation.label} ${violation.actual} exceeds frozen limit ${violation.maximum}`,
+        });
+    }
+}
+function executionLimitViolations(limits, observation) {
+    const checks = [
+        {
+            path: ["timing", "durationMs"],
+            label: "durationMs",
+            actual: observation.durationMs,
+            maximum: limits.timeoutMs,
+        },
+        {
+            path: ["steps"],
+            label: "steps",
+            actual: observation.steps,
+            maximum: limits.maxSteps,
+        },
+        {
+            path: ["usage", "modelCalls"],
+            label: "modelCalls",
+            actual: observation.usage.modelCalls,
+            maximum: limits.maxModelCalls,
+        },
+        {
+            path: ["usage", "inputTokens"],
+            label: "inputTokens",
+            actual: observation.usage.inputTokens,
+            maximum: limits.maxInputTokens,
+        },
+        {
+            path: ["usage", "outputTokens"],
+            label: "outputTokens",
+            actual: observation.usage.outputTokens,
+            maximum: limits.maxOutputTokens,
+        },
+        {
+            path: ["usage", "costUsdNanos"],
+            label: "costUsd",
+            actual: observation.usage.costUsdNanos / 1_000_000_000,
+            maximum: limits.maxCostUsd,
+        },
+    ];
+    return checks.filter((check) => check.actual > check.maximum);
+}

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

@@ -0,0 +1,198 @@
+import { z } from "zod";
+import type { AgentCandidateEvaluationPolicy, AgentCandidateJsonValue, AgentImprovementMeasuredComparisonBase } from "./agent-candidate.js";
+export declare const canonicalJsonSchema: z.ZodCustom<AgentCandidateJsonValue, AgentCandidateJsonValue>;
+export declare const canonicalJsonObjectSchema: z.ZodRecord<z.ZodString, z.ZodCustom<AgentCandidateJsonValue, AgentCandidateJsonValue>>;
+export declare const agentCandidateEvaluationPolicySchema: z.ZodObject<{
+    confidenceLevel: z.ZodNumber;
+    resamples: z.ZodNumber;
+    bootstrapSeed: z.ZodNumber;
+    deltaThreshold: z.ZodNumber;
+    minProductiveRuns: z.ZodNumber;
+    budgetUsd: z.ZodOptional<z.ZodNumber>;
+    criticalDimensions: z.ZodArray<z.ZodString>;
+    regressionTolerance: z.ZodNumber;
+}, z.core.$strict>;
+export declare const measuredComparisonCommonShape: {
+    overall: z.ZodObject<{
+        direction: z.ZodLiteral<"higher-is-better">;
+        unit: z.ZodLiteral<"score">;
+        baseline: z.ZodNumber;
+        candidate: z.ZodNumber;
+        delta: z.ZodNumber;
+        confidenceInterval: z.ZodObject<{
+            level: z.ZodNumber;
+            lower: z.ZodNumber;
+            upper: z.ZodNumber;
+            method: z.ZodLiteral<"paired-bootstrap">;
+            statistic: z.ZodLiteral<"mean">;
+            resamples: z.ZodNumber;
+        }, z.core.$strict>;
+        n: z.ZodNumber;
+        name: z.ZodLiteral<"composite">;
+    }, z.core.$strict>;
+    objectives: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"objective">;
+        name: z.ZodString;
+        direction: z.ZodLiteral<"higher-is-better">;
+        unit: z.ZodLiteral<"score">;
+        baseline: z.ZodNumber;
+        candidate: z.ZodNumber;
+        delta: z.ZodNumber;
+        confidenceInterval: z.ZodObject<{
+            level: z.ZodNumber;
+            lower: z.ZodNumber;
+            upper: z.ZodNumber;
+            method: z.ZodLiteral<"paired-bootstrap">;
+            statistic: z.ZodLiteral<"mean">;
+            resamples: z.ZodNumber;
+        }, z.core.$strict>;
+        n: z.ZodNumber;
+        availability: z.ZodLiteral<"measured">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"objective">;
+        name: z.ZodString;
+        direction: z.ZodLiteral<"higher-is-better">;
+        unit: z.ZodLiteral<"score">;
+        availability: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"dimension">;
+        objective: z.ZodString;
+        name: z.ZodString;
+        direction: z.ZodLiteral<"higher-is-better">;
+        unit: z.ZodLiteral<"score">;
+        baseline: z.ZodNumber;
+        candidate: z.ZodNumber;
+        delta: z.ZodNumber;
+        confidenceInterval: z.ZodObject<{
+            level: z.ZodNumber;
+            lower: z.ZodNumber;
+            upper: z.ZodNumber;
+            method: z.ZodLiteral<"paired-bootstrap">;
+            statistic: z.ZodLiteral<"mean">;
+            resamples: z.ZodNumber;
+        }, z.core.$strict>;
+        n: z.ZodNumber;
+        availability: z.ZodLiteral<"measured">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"dimension">;
+        objective: z.ZodString;
+        name: z.ZodString;
+        direction: z.ZodLiteral<"higher-is-better">;
+        unit: z.ZodLiteral<"score">;
+        availability: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"cost">;
+        name: z.ZodLiteral<"cost">;
+        direction: z.ZodLiteral<"lower-is-better">;
+        unit: z.ZodLiteral<"usd">;
+        baseline: z.ZodNumber;
+        candidate: z.ZodNumber;
+        delta: z.ZodNumber;
+        confidenceInterval: z.ZodObject<{
+            level: z.ZodNumber;
+            lower: z.ZodNumber;
+            upper: z.ZodNumber;
+            method: z.ZodLiteral<"paired-bootstrap">;
+            statistic: z.ZodLiteral<"mean">;
+            resamples: z.ZodNumber;
+        }, z.core.$strict>;
+        n: z.ZodNumber;
+        availability: z.ZodLiteral<"measured">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"latency">;
+        name: z.ZodLiteral<"latency">;
+        direction: z.ZodLiteral<"lower-is-better">;
+        unit: z.ZodLiteral<"milliseconds">;
+        baseline: z.ZodNumber;
+        candidate: z.ZodNumber;
+        delta: z.ZodNumber;
+        confidenceInterval: z.ZodObject<{
+            level: z.ZodNumber;
+            lower: z.ZodNumber;
+            upper: z.ZodNumber;
+            method: z.ZodLiteral<"paired-bootstrap">;
+            statistic: z.ZodLiteral<"mean">;
+            resamples: z.ZodNumber;
+        }, z.core.$strict>;
+        n: z.ZodNumber;
+        availability: z.ZodLiteral<"measured">;
+    }, z.core.$strict>]>>;
+    candidate: z.ZodOptional<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        rationale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    decision: z.ZodObject<{
+        outcome: z.ZodEnum<{
+            ship: "ship";
+            hold: "hold";
+            need_more_work: "need_more_work";
+            model_ceiling: "model_ceiling";
+            arch_ceiling: "arch_ceiling";
+        }>;
+        reasons: z.ZodArray<z.ZodString>;
+        contributingChecks: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            passed: z.ZodBoolean;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    power: z.ZodObject<{
+        sufficient: z.ZodBoolean;
+        n: z.ZodNumber;
+        minimumDetectableDelta: z.ZodNumber;
+        confidenceLevel: z.ZodNumber;
+        scaleAssumed: z.ZodBoolean;
+        sharedScorerChannel: z.ZodBoolean;
+        reason: z.ZodString;
+    }, z.core.$strict>;
+    provenance: z.ZodObject<{
+        kind: z.ZodLiteral<"agent-eval-loop">;
+        schema: z.ZodString;
+        runId: z.ZodString;
+        recordDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        baselineContentHash: z.ZodString;
+        candidateContentHash: z.ZodString;
+    }, z.core.$strict>;
+    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;
+    }, z.core.$strict>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<AgentCandidateJsonValue, AgentCandidateJsonValue>>>;
+};
+type MeasuredComparison = Pick<AgentImprovementMeasuredComparisonBase<unknown, unknown, string>, "overall" | "objectives" | "power" | "evaluation">;
+interface MeasuredComparisonIdentity {
+    kind: string;
+    value: string;
+    path?: (string | number)[];
+}
+/** Keep receipt identity reuse rules identical across measured source formats. */
+export declare function createMeasuredComparisonIdentityRegistry(options: {
+    ctx: z.RefinementCtx;
+    identityLabel: string;
+}): (identities: readonly MeasuredComparisonIdentity[], fallbackPath: (string | number)[]) => void;
+export declare function refineMeasuredComparisonSummary<TReceipt>(comparison: MeasuredComparison, policy: Pick<AgentCandidateEvaluationPolicy, "confidenceLevel" | "resamples">, expectedN: number, measurements: readonly {
+    baseline: TReceipt;
+    candidate: TReceipt;
+}[], values: {
+    score(receipt: TReceipt): number;
+    dimension(receipt: TReceipt, name: string): number | undefined;
+    cost(receipt: TReceipt): number;
+    latency(receipt: TReceipt): number;
+}, ctx: z.RefinementCtx): void;
+export declare function refineEstimate(estimate: {
+    baseline: number;
+    candidate: number;
+    delta: number;
+    confidenceInterval: {
+        lower: number;
+        upper: number;
+    };
+}, path: (string | number)[], ctx: z.RefinementCtx): void;
+export {};