@tangle-network/agent-interface 2.7.0 → 2.9.0

package/README.md

@@ -172,6 +172,13 @@ When caller environment values merge into a bridge or harness process, reject na
 Use `isCredentialBearingProfileConfigName(name)` before retaining public config.
 These checks do not apply to a replacement environment owned by caller code.
 
+## Failed execution accounting
+
+An adapter can reject with `AgentExecutionError` and retain observed usage and timing in its immutable `receipt`.
+Absent fields remain unknown.
+The receipt records a lower bound, not complete accounting or a successful outcome.
+Hosts must preserve it when publishing a failed or cancelled execution.
+
 ## Exact process environments
 
 Providers may expose the optional `exactProcess` capability for isolated, reproducible process execution.

package/dist/environment-runtime.d.ts

@@ -5,7 +5,7 @@ import type { Sha256Digest } from "./agent-candidate.js";
 import type { AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
 import type { InputPart } from "./parts.js";
 import type { StreamEvent } from "./stream-events.js";
-import type { TokenUsage } from "./execution-types.js";
+import { type TokenUsage } from "./execution-types.js";
 import { type InteractionAcknowledgement, type InteractionCapabilities, type InteractionResponseCommand, type RequestedInteractions } from "./interaction.js";
 import { type ContextTransferReceipt, type ContextTransferRequest, type ContextTransferResult, type NativeContextBoundaryProof, type NativeContextContinuationRequest, type NativeContextContinuationTurn } from "./portable-context.js";
 import { type AgentExactRunControlRef, type AgentRunCancellationAcknowledgement, type AgentRunCancellationRequest, type AgentRunControlRef } from "./runtime-control.js";

package/dist/environment-runtime.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 export { AgentRuntimeAttachmentsSchema } from "./runtime-attachments.js";
 import { canonicalCandidateDigest, canonicalCandidateJson, } from "./agent-candidate-schema-common.js";
+import { TokenUsageSchema } from "./execution-types.js";
 import { InteractionCapabilitiesSchema, RequestedInteractionsSchema } from "./interaction.js";
 import { ContextTransferReceiptSchema, ContextTransferRequestSchema, NativeContextBoundaryProofSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches } from "./portable-context.js";
 import { AgentExactRunControlRefSchema, AgentRunControlRefSchema, CanonicalStreamEventSchema } from "./runtime-control.js";
@@ -31,15 +32,6 @@ export const AgentTurnInputSchema = z.strictObject({
     signal: z.custom().optional(),
     providerOptions: boundedJsonRecordSchema.optional(),
 });
-const TokenUsageSchema = z.strictObject({
-    inputTokens: z.number().int().nonnegative(),
-    outputTokens: z.number().int().nonnegative(),
-    totalTokens: z.number().int().nonnegative().optional(),
-    cacheReadInputTokens: z.number().int().nonnegative().optional(),
-    cacheCreationInputTokens: z.number().int().nonnegative().optional(),
-    reasoningTokens: z.number().int().nonnegative().optional(),
-    cost: z.number().finite().nonnegative().optional(),
-});
 const AgentEnvironmentEventSchema = z.strictObject({
     type: boundedIdentifierSchema,
     data: boundedEventContentRecordSchema,

package/dist/execution-failure.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const AgentExecutionFailureReceiptSchema: z.ZodObject<{
+    tokenUsage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        totalTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        cacheReadInputTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        cacheCreationInputTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        reasoningTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        cost: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    timing: z.ZodOptional<z.ZodObject<{
+        startedAt: z.ZodNumber;
+        completedAt: z.ZodNumber;
+        durationMs: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Observed accounting only; a failed execution may have additional unreported usage. */
+export type AgentExecutionFailureReceipt = z.infer<typeof AgentExecutionFailureReceiptSchema>;
+/** Retains observed resource use while preserving the adapter's rejection contract. */
+export declare class AgentExecutionError extends Error {
+    readonly receipt: AgentExecutionFailureReceipt;
+    constructor(message: string, receipt: AgentExecutionFailureReceipt, options?: ErrorOptions);
+}

package/dist/execution-failure.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { deepFreeze } from "./deep-freeze.js";
+import { TokenUsageSchema } from "./execution-types.js";
+export const AgentExecutionFailureReceiptSchema = z.strictObject({
+    tokenUsage: TokenUsageSchema.partial().optional(),
+    timing: z.strictObject({
+        startedAt: z.number().finite().nonnegative(),
+        completedAt: z.number().finite().nonnegative(),
+        durationMs: z.number().finite().nonnegative(),
+    }).optional(),
+});
+/** Retains observed resource use while preserving the adapter's rejection contract. */
+export class AgentExecutionError extends Error {
+    receipt;
+    constructor(message, receipt, options) {
+        super(message, options);
+        this.name = "AgentExecutionError";
+        this.receipt = deepFreeze(AgentExecutionFailureReceiptSchema.parse(receipt));
+    }
+}

package/dist/execution-types.d.ts

@@ -3,6 +3,7 @@ import type { InputPart } from "./parts.js";
 import type { ProviderConfig } from "./provider-config.js";
 import type { InteractionExecutionBinding } from "./interaction-envelope.js";
 import type { RequestedInteractions } from "./interaction-permissions.js";
+import { z } from "zod";
 export type ToolInvocation = {
     toolName: string;
     input: unknown;
@@ -18,6 +19,15 @@ export type TokenUsage = {
     reasoningTokens?: number;
     cost?: number;
 };
+export declare const TokenUsageSchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    totalTokens: z.ZodOptional<z.ZodNumber>;
+    cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    cost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
 export type ExecutionTiming = {
     startedAt: number;
     completedAt: number;

package/dist/execution-types.js

@@ -1 +1,10 @@
-export {};
+import { z } from "zod";
+export const TokenUsageSchema = z.strictObject({
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    totalTokens: z.number().int().nonnegative().optional(),
+    cacheReadInputTokens: z.number().int().nonnegative().optional(),
+    cacheCreationInputTokens: z.number().int().nonnegative().optional(),
+    reasoningTokens: z.number().int().nonnegative().optional(),
+    cost: z.number().finite().nonnegative().optional(),
+});

package/dist/index.d.ts

@@ -2,6 +2,7 @@
 export * from "./parts.js";
 export * from "./stream-events.js";
 export * from "./execution-types.js";
+export * from "./execution-failure.js";
 export * from "./backend-message.js";
 export * from "./provider-config.js";
 export * from "./host-services.js";
@@ -40,5 +41,5 @@ export * from "./harness-capabilities.js";
 export * from "./profile-schema.js";
 export * from "./profile-security.js";
 export * from "./sandbox-size.js";
-export { CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, CONTRACT_MAX_JSON_BYTES, boundedEventContentJsonSchema, boundedEventContentRecordSchema, boundedEventContentStringSchema, isBoundedEventContentJson, } from "./contract-limits.js";
+export { CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, CONTRACT_MAX_IDENTIFIER_LENGTH, CONTRACT_MAX_JSON_BYTES, CONTRACT_MAX_JSON_DEPTH, CONTRACT_MAX_JSON_NODES, CONTRACT_MAX_MAP_ENTRIES, CONTRACT_MAX_STRING_LENGTH, boundedEventContentJsonSchema, boundedEventContentRecordSchema, boundedEventContentStringSchema, isBoundedEventContentJson, } from "./contract-limits.js";
 export { AgentEnvironmentEgressPolicySchema } from "./environment-requests.js";

package/dist/index.js

@@ -2,6 +2,7 @@
 export * from "./parts.js";
 export * from "./stream-events.js";
 export * from "./execution-types.js";
+export * from "./execution-failure.js";
 export * from "./backend-message.js";
 export * from "./provider-config.js";
 export * from "./host-services.js";
@@ -38,5 +39,9 @@ export * from "./harness-capabilities.js";
 export * from "./profile-schema.js";
 export * from "./profile-security.js";
 export * from "./sandbox-size.js";
-export { CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, CONTRACT_MAX_JSON_BYTES, boundedEventContentJsonSchema, boundedEventContentRecordSchema, boundedEventContentStringSchema, isBoundedEventContentJson, } from "./contract-limits.js";
+export { 
+// Every bound a consumer may be asked to honour is public, so a package that WRITES values
+// this contract validates can assert its own limits fit — the seam test in agent-provider-tangle
+// does exactly that, after three bound mismatches shipped through it (agent-sdk#311, #312, #314).
+CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, CONTRACT_MAX_IDENTIFIER_LENGTH, CONTRACT_MAX_JSON_BYTES, CONTRACT_MAX_JSON_DEPTH, CONTRACT_MAX_JSON_NODES, CONTRACT_MAX_MAP_ENTRIES, CONTRACT_MAX_STRING_LENGTH, boundedEventContentJsonSchema, boundedEventContentRecordSchema, boundedEventContentStringSchema, isBoundedEventContentJson, } from "./contract-limits.js";
 export { AgentEnvironmentEgressPolicySchema } from "./environment-requests.js";

package/package.json

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