@tangle-network/agent-interface 2.3.1 → 2.5.0

package/README.md

@@ -228,3 +228,10 @@ An exhaustiveness check that assigns the remaining case to `never` fails when a
 ## License
 
 MIT
+
+`AgentEnvironmentEvent.usageMode` describes token usage within one turn.
+`delta` contributes new usage; `cumulative` includes earlier contributions and replaces the prior turn total.
+Repeated cumulative totals do not add spend.
+An absent mode means the aggregation semantics are unknown.
+Materialization receipts cover all three model token ceilings at their exact requested paths.
+A strict profile rejects unsupported ceilings instead of silently accepting them.

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

@@ -10,6 +10,10 @@ export declare const agentCandidateKnowledgeSchema: z.ZodObject<{
         evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     }, z.core.$strict>;
+    stateScope: z.ZodOptional<z.ZodObject<{
+        pagesDirectory: z.ZodString;
+        researchState: z.ZodBoolean;
+    }, z.core.$strict>>;
     snapshot: z.ZodObject<{
         kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
         digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { agentCandidateArtifactRefSchema, agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
-import { addDuplicateIssues, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { addDuplicateIssues, isSafeRelativePath, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 export const agentCandidateKnowledgeSchema = z
     .object({
     candidate: z
@@ -15,6 +15,15 @@ export const agentCandidateKnowledgeSchema = z
         promotionPlanHash: sha256DigestSchema,
     })
         .strict(),
+    stateScope: z
+        .object({
+        pagesDirectory: z
+            .string()
+            .refine((value) => isSafeRelativePath(value, false), "pagesDirectory must be a canonical workspace-relative directory"),
+        researchState: z.boolean(),
+    })
+        .strict()
+        .optional(),
     snapshot: agentCandidateWorkspaceSnapshotEvidenceSchema,
     retrievalConfig: agentCandidateCapturedArtifactSchema.optional(),
     evaluation: agentCandidateCapturedArtifactSchema,

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

@@ -724,6 +724,10 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
                 evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             }, z.core.$strict>;
+            stateScope: z.ZodOptional<z.ZodObject<{
+                pagesDirectory: z.ZodString;
+                researchState: z.ZodBoolean;
+            }, z.core.$strict>>;
             snapshot: z.ZodObject<{
                 kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                 digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -1557,6 +1561,10 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
                 evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             }, z.core.$strict>;
+            stateScope: z.ZodOptional<z.ZodObject<{
+                pagesDirectory: z.ZodString;
+                researchState: z.ZodBoolean;
+            }, z.core.$strict>>;
             snapshot: z.ZodObject<{
                 kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                 digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -4313,6 +4321,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                     evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 }, z.core.$strict>;
+                stateScope: z.ZodOptional<z.ZodObject<{
+                    pagesDirectory: z.ZodString;
+                    researchState: z.ZodBoolean;
+                }, z.core.$strict>>;
                 snapshot: z.ZodObject<{
                     kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                     digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -5146,6 +5158,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                     evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 }, z.core.$strict>;
+                stateScope: z.ZodOptional<z.ZodObject<{
+                    pagesDirectory: z.ZodString;
+                    researchState: z.ZodBoolean;
+                }, z.core.$strict>>;
                 snapshot: z.ZodObject<{
                     kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                     digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -9332,6 +9348,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                         evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                         promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     }, z.core.$strict>;
+                    stateScope: z.ZodOptional<z.ZodObject<{
+                        pagesDirectory: z.ZodString;
+                        researchState: z.ZodBoolean;
+                    }, z.core.$strict>>;
                     snapshot: z.ZodObject<{
                         kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                         digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -10165,6 +10185,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                         evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                         promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     }, z.core.$strict>;
+                    stateScope: z.ZodOptional<z.ZodObject<{
+                        pagesDirectory: z.ZodString;
+                        researchState: z.ZodBoolean;
+                    }, z.core.$strict>>;
                     snapshot: z.ZodObject<{
                         kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
                         digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;

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

@@ -728,6 +728,10 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
             evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         }, z.core.$strict>;
+        stateScope: z.ZodOptional<z.ZodObject<{
+            pagesDirectory: z.ZodString;
+            researchState: z.ZodBoolean;
+        }, z.core.$strict>>;
         snapshot: z.ZodObject<{
             kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
             digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;

package/dist/agent-candidate.d.ts

@@ -227,8 +227,15 @@ export interface AgentCandidateKnowledgeRef {
     evidenceHash: Sha256Digest;
     promotionPlanHash: Sha256Digest;
 }
+/** Canonical selection of knowledge state included in the candidate hash. */
+export interface AgentCandidateKnowledgeStateScope {
+    pagesDirectory: string;
+    researchState: boolean;
+}
 export interface AgentCandidateKnowledge {
     candidate: AgentCandidateKnowledgeRef;
+    /** Absent scopes retain the knowledge provider's default selection. */
+    stateScope?: AgentCandidateKnowledgeStateScope;
     snapshot: AgentCandidateWorkspaceSnapshotEvidence;
     retrievalConfig?: AgentCandidateCapturedArtifact;
     evaluation: AgentCandidateCapturedArtifact;

package/dist/agent-execution-preparation-receipt.d.ts

@@ -111,6 +111,9 @@ export declare const agentExecutionPreparationAxisResultSchema: z.ZodObject<{
         mcp: "mcp";
         metadata: "metadata";
         modelDefault: "modelDefault";
+        modelMaxReasoningTokens: "modelMaxReasoningTokens";
+        modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+        modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
         modelMetadata: "modelMetadata";
         modelProvider: "modelProvider";
         modelReasoningEffort: "modelReasoningEffort";
@@ -259,6 +262,9 @@ export declare const agentExecutionPreparationReceiptSchema: z.ZodObject<{
             mcp: "mcp";
             metadata: "metadata";
             modelDefault: "modelDefault";
+            modelMaxReasoningTokens: "modelMaxReasoningTokens";
+            modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+            modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
             modelMetadata: "modelMetadata";
             modelProvider: "modelProvider";
             modelReasoningEffort: "modelReasoningEffort";

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

@@ -1,6 +1,6 @@
 import type { AgentProfile } from "./agent-profile.js";
 /**
- * The 30 canonical AgentProfile leaves that can affect one execution.
+ * The canonical AgentProfile leaves that can affect one execution.
  *
  * Compound parents such as `model`, `prompt`, and `resources` are deliberately
  * absent. A producer must report the exact requested leaf instead of claiming
@@ -9,7 +9,7 @@ import type { AgentProfile } from "./agent-profile.js";
  * can only add text must report the requested replacement as unsatisfied rather
  * than acknowledge it.
  */
-export declare const AGENT_PROFILE_MATERIALIZATION_AXES: readonly ["name", "description", "version", "tags", "systemPrompt", "appendSystemPrompt", "instructions", "modelDefault", "modelSmall", "modelProvider", "modelReasoningEffort", "modelMetadata", "harness", "permissions", "tools", "mcp", "connections", "subagents", "files", "resourceTools", "skills", "resourceAgents", "commands", "resourceInstructions", "resourceFailOnError", "hooks", "modes", "confidential", "metadata", "extensions"];
+export declare const AGENT_PROFILE_MATERIALIZATION_AXES: readonly ["name", "description", "version", "tags", "systemPrompt", "appendSystemPrompt", "instructions", "modelDefault", "modelSmall", "modelProvider", "modelReasoningEffort", "modelMaxVisibleOutputTokens", "modelMaxReasoningTokens", "modelMaxTotalOutputTokens", "modelMetadata", "harness", "permissions", "tools", "mcp", "connections", "subagents", "files", "resourceTools", "skills", "resourceAgents", "commands", "resourceInstructions", "resourceFailOnError", "hooks", "modes", "confidential", "metadata", "extensions"];
 /** One exact leaf of the public AgentProfile contract. */
 export type AgentProfileMaterializationAxis = (typeof AGENT_PROFILE_MATERIALIZATION_AXES)[number];
 /** Compatibility name used by runtimes that distinguish canonical axes. */

package/dist/agent-profile-materialization.js

@@ -1,5 +1,5 @@
 /**
- * The 30 canonical AgentProfile leaves that can affect one execution.
+ * The canonical AgentProfile leaves that can affect one execution.
  *
  * Compound parents such as `model`, `prompt`, and `resources` are deliberately
  * absent. A producer must report the exact requested leaf instead of claiming
@@ -20,6 +20,9 @@ export const AGENT_PROFILE_MATERIALIZATION_AXES = [
     "modelSmall",
     "modelProvider",
     "modelReasoningEffort",
+    "modelMaxVisibleOutputTokens",
+    "modelMaxReasoningTokens",
+    "modelMaxTotalOutputTokens",
     "modelMetadata",
     "harness",
     "permissions",
@@ -58,6 +61,16 @@ const profileProperties = [
 ];
 const profilePropertiesAreExhaustive = true;
 void profilePropertiesAreExhaustive;
+const MODEL_AXES = {
+    default: "modelDefault",
+    small: "modelSmall",
+    provider: "modelProvider",
+    reasoningEffort: "modelReasoningEffort",
+    maxVisibleOutputTokens: "modelMaxVisibleOutputTokens",
+    maxReasoningTokens: "modelMaxReasoningTokens",
+    maxTotalOutputTokens: "modelMaxTotalOutputTokens",
+    metadata: "modelMetadata",
+};
 const AXIS_DESCRIPTORS = [
     { axis: "name", rootPath: "/name", value: (profile) => profile.name },
     {
@@ -82,31 +95,11 @@ const AXIS_DESCRIPTORS = [
         rootPath: "/prompt/instructions",
         value: (profile) => profile.prompt?.instructions,
     },
-    {
-        axis: "modelDefault",
-        rootPath: "/model/default",
-        value: (profile) => profile.model?.default,
-    },
-    {
-        axis: "modelSmall",
-        rootPath: "/model/small",
-        value: (profile) => profile.model?.small,
-    },
-    {
-        axis: "modelProvider",
-        rootPath: "/model/provider",
-        value: (profile) => profile.model?.provider,
-    },
-    {
-        axis: "modelReasoningEffort",
-        rootPath: "/model/reasoningEffort",
-        value: (profile) => profile.model?.reasoningEffort,
-    },
-    {
-        axis: "modelMetadata",
-        rootPath: "/model/metadata",
-        value: (profile) => profile.model?.metadata,
-    },
+    ...Object.entries(MODEL_AXES).map(([property, axis]) => ({
+        axis,
+        rootPath: `/model/${property}`,
+        value: (profile) => profile.model?.[property],
+    })),
     { axis: "harness", rootPath: "/harness", value: (profile) => profile.harness },
     {
         axis: "permissions",

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

@@ -105,6 +105,9 @@ export declare const AgentInteractiveSessionRefSchema: z.ZodObject<{
                 mcp: "mcp";
                 metadata: "metadata";
                 modelDefault: "modelDefault";
+                modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                 modelMetadata: "modelMetadata";
                 modelProvider: "modelProvider";
                 modelReasoningEffort: "modelReasoningEffort";
@@ -277,6 +280,9 @@ export declare const AgentInteractiveSessionControlClaimRequestSchema: z.ZodObje
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";
@@ -442,6 +448,9 @@ export declare const AgentInteractiveSessionControlClaimAcknowledgementSchema: z
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";
@@ -628,6 +637,9 @@ export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnio
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";
@@ -773,6 +785,9 @@ export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnio
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";
@@ -926,6 +941,9 @@ export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnio
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";
@@ -1084,6 +1102,9 @@ export declare const AgentInteractiveSessionStopCommandSchema: z.ZodObject<{
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";
@@ -1251,6 +1272,9 @@ export declare const AgentInteractiveSessionStopAcknowledgementSchema: z.ZodObje
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";
@@ -1434,6 +1458,9 @@ export declare const AgentInteractiveSessionPromptCommandSchema: z.ZodObject<{
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";
@@ -1600,6 +1627,9 @@ export declare const AgentInteractiveSessionPromptAcknowledgementSchema: z.ZodOb
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
+                    modelMaxReasoningTokens: "modelMaxReasoningTokens";
+                    modelMaxTotalOutputTokens: "modelMaxTotalOutputTokens";
+                    modelMaxVisibleOutputTokens: "modelMaxVisibleOutputTokens";
                     modelMetadata: "modelMetadata";
                     modelProvider: "modelProvider";
                     modelReasoningEffort: "modelReasoningEffort";

package/dist/environment-runtime.d.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import type { AgentRuntimeAttachments } from "./runtime-attachments.js";
+export { AgentRuntimeAttachmentsSchema, type AgentRuntimeAttachments } from "./runtime-attachments.js";
 import type { Sha256Digest } from "./agent-candidate.js";
 import type { AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
 import type { InputPart } from "./parts.js";
@@ -283,6 +285,10 @@ export declare const AgentTurnResultSchema: z.ZodObject<{
             reasoningTokens: z.ZodOptional<z.ZodNumber>;
             cost: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
+        usageMode: z.ZodOptional<z.ZodEnum<{
+            cumulative: "cumulative";
+            delta: "delta";
+        }>>;
         providerEvent: z.ZodOptional<z.ZodCustom<unknown, unknown>>;
     }, z.core.$strict>>>;
     contextTransferReceipt: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -435,6 +441,10 @@ export declare const AgentNativeContextContinuationResultSchema: z.ZodUnion<read
                 reasoningTokens: z.ZodOptional<z.ZodNumber>;
                 cost: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>>;
+            usageMode: z.ZodOptional<z.ZodEnum<{
+                cumulative: "cumulative";
+                delta: "delta";
+            }>>;
             providerEvent: z.ZodOptional<z.ZodCustom<unknown, unknown>>;
         }, z.core.$strict>>>;
         contextTransferReceipt: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -640,6 +650,12 @@ export interface AgentEnvironmentEvent {
     id?: string;
     normalized?: StreamEvent;
     usage?: TokenUsage;
+    /**
+     * Delta is one new contribution; cumulative is the total so far for this turn.
+     * Cumulative totals include earlier deltas and may repeat during replay.
+     * Omission means the provider has not established the aggregation semantics.
+     */
+    usageMode?: "delta" | "cumulative";
     providerEvent?: unknown;
 }
 export interface AgentSession {
@@ -844,9 +860,8 @@ export interface AgentEnvironmentCapabilities {
         egress: readonly AgentExactProcessEgressMode[];
     };
     /**
-     * Present only when create honors {@link CreateAgentEnvironmentInput.egress} or
-     * {@link CreateAgentEnvironmentInput.billingOwner}. Absent means neither field is read, so a
-     * caller that needs either must not send it and call the result a policy.
+     * Present only when create honors at least one optional field below.
+     * Callers must check each requested field; an absent capability cannot satisfy it.
      *
      * Each member is present only when that field is honored, and the block carries at least one of
      * them. A provider that takes a billing owner but no caller-controlled egress therefore states
@@ -864,6 +879,10 @@ export interface AgentEnvironmentCapabilities {
          * authorizes the caller for that account; this flag states only that the field is not dropped.
          */
         billingOwner?: boolean;
+        /** Runtime-owned MCP bindings applied without changing the authored profile. */
+        runtimeAttachments?: {
+            mcp: true;
+        };
     };
     /** Per-surface flags for the normalized environment observation. */
     observation?: {
@@ -1007,6 +1026,9 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
             strict: "strict";
         }>>>;
         billingOwner: z.ZodOptional<z.ZodBoolean>;
+        runtimeAttachments: z.ZodOptional<z.ZodObject<{
+            mcp: z.ZodLiteral<true>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     observation: z.ZodOptional<z.ZodObject<{
         identity: z.ZodBoolean;
@@ -1039,6 +1061,13 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
 }, z.core.$strict>;
 export interface CreateAgentEnvironmentInput {
     profile: AgentProfileRef;
+    /**
+     * Runtime-owned execution inputs, separate from authored profile identity.
+     * Providers must refuse unsupported attachments and authored MCP alias collisions.
+     * Credentials are sensitive transport input; never include them in receipts or logs.
+     * Attachments participate in keyed create identity and cannot be refreshed by replay.
+     */
+    runtimeAttachments?: AgentRuntimeAttachments;
     /** Exact caller-owned id required by an accepted destination contract. */
     requestedId?: string;
     /** Agent backend inside the provider, for example "opencode" or "codex". */
@@ -1158,6 +1187,7 @@ export interface AgentEnvironmentProvider {
      *
      * With `input.idempotencyKey`, the provider must return the same environment
      * for the same canonical input and reject any changed input before creating.
+     * A provider without durable keyed admission must reject a keyed request before provisioning.
      * Without a key, each call may create a fresh environment.
      */
     create(input: CreateAgentEnvironmentInput): Promise<AgentEnvironment>;

package/dist/environment-runtime.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export { AgentRuntimeAttachmentsSchema } from "./runtime-attachments.js";
 import { canonicalCandidateDigest, canonicalCandidateJson, } from "./agent-candidate-schema-common.js";
 import { InteractionCapabilitiesSchema, RequestedInteractionsSchema } from "./interaction.js";
 import { ContextTransferReceiptSchema, ContextTransferRequestSchema, NativeContextBoundaryProofSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches } from "./portable-context.js";
@@ -40,6 +41,7 @@ const AgentEnvironmentEventSchema = z.strictObject({
     id: boundedIdentifierSchema.optional(),
     normalized: CanonicalStreamEventSchema.optional(),
     usage: TokenUsageSchema.optional(),
+    usageMode: z.enum(["delta", "cumulative"]).optional(),
     providerEvent: boundedJsonSchema.optional(),
 });
 /** Runtime validator for a provider turn returned from durable continuation. */
@@ -240,6 +242,7 @@ export const AgentEnvironmentCapabilitiesSchema = z
             .max(CONTRACT_MAX_ARRAY_LENGTH)
             .optional(),
         billingOwner: z.boolean().optional(),
+        runtimeAttachments: z.strictObject({ mcp: z.literal(true) }).optional(),
     })
         .optional(),
     observation: z
@@ -346,7 +349,7 @@ export const AgentEnvironmentCapabilitiesSchema = z
     }
     const create = capabilities.create;
     if (create !== undefined) {
-        if (create.egress === undefined && create.billingOwner === undefined) {
+        if (create.egress === undefined && create.billingOwner === undefined && create.runtimeAttachments === undefined) {
             refinement.addIssue({
                 code: "custom",
                 path: ["create"],

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
 export type * from "./environment-provider.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationAdmissionSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationAdmissionMatchesRequest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, canonicalWorkspaceCwd, MAX_WORKSPACE_CWD_LENGTH, workspaceCwdSchema, workspaceCwdPathForBase, WorkspaceRequestSchema, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentRuntimeAttachmentsSchema, AgentNativeContextContinuationAdmissionSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationAdmissionMatchesRequest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, canonicalWorkspaceCwd, MAX_WORKSPACE_CWD_LENGTH, workspaceCwdSchema, workspaceCwdPathForBase, WorkspaceRequestSchema, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export * from "./provider-config.js";
 export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationAdmissionSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationAdmissionMatchesRequest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, canonicalWorkspaceCwd, MAX_WORKSPACE_CWD_LENGTH, workspaceCwdSchema, workspaceCwdPathForBase, WorkspaceRequestSchema, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentRuntimeAttachmentsSchema, AgentNativeContextContinuationAdmissionSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationAdmissionMatchesRequest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, canonicalWorkspaceCwd, MAX_WORKSPACE_CWD_LENGTH, workspaceCwdSchema, workspaceCwdPathForBase, WorkspaceRequestSchema, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/runtime-attachments.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import type { AgentProfileMcpServer } from "./agent-profile.js";
+/** Runtime-owned bindings do not alter the authored AgentProfile or candidate identity. */
+export interface AgentRuntimeAttachments {
+    mcp: Record<string, AgentProfileMcpServer>;
+}
+export declare const AgentRuntimeAttachmentsSchema: z.ZodType<AgentRuntimeAttachments>;

package/dist/runtime-attachments.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { agentProfileSchema } from "./profile-schema.js";
+import { boundedIdentifierSchema, boundedJsonSchema } from "./contract-limits.js";
+export const AgentRuntimeAttachmentsSchema = boundedJsonSchema.pipe(z.strictObject({
+    mcp: agentProfileSchema.shape.mcp.unwrap().superRefine((servers, context) => {
+        for (const alias of Object.keys(servers)) {
+            const result = boundedIdentifierSchema.safeParse(alias);
+            if (!result.success) {
+                for (const issue of result.error.issues) {
+                    context.addIssue({ ...issue, path: [alias, ...issue.path] });
+                }
+            }
+        }
+    }),
+}));

package/package.json

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