@tangle-network/agent-interface 1.0.0 → 1.0.1

package/README.md

@@ -52,6 +52,13 @@ Every returned resource repeats and validates that identity, lookups recover rem
 A checkpoint with dependent forks returns `in_use` plus the blocking environment identifiers and remains recoverable until those forks are destroyed.
 The older `checkpoint()` and `fork()` methods remain source-compatible for providers that have not yet implemented recovery semantics, but clients must not present them as durable workspace branching.
 
+`CreateAgentEnvironmentInput.idempotencyKey` makes generic environment creation one retry-safe operation.
+When a caller repeats that key, the provider must canonicalize every create field except the key and attempt signal.
+The same canonical input must return or reconstruct the same environment, including after an ambiguous provider response.
+The same key with any changed create field must reject before a second create effect.
+Providers backed by a remote service must forward the key and retain its canonical input through environment reconstruction.
+The existing `AgentEnvironmentProvider.create()` method carries this contract; it does not add a second create method or capability flag.
+
 All new wire values have exported Zod schemas on the package root.
 Omitting `interactions` and `nativeContinuation`, or leaving the three durable branching flags false, is the compatible declaration for existing providers.
 

package/dist/environment-runtime.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+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";
@@ -917,15 +918,54 @@ export interface CreateAgentEnvironmentInput {
     secrets?: string[] | Record<string, string>;
     metadata?: Record<string, unknown>;
     name?: string;
+    /**
+     * Stable identity for one logical environment create.
+     *
+     * When present, the provider must use this key as one idempotent operation:
+     * the same key with canonically equal create input must return or reconstruct
+     * the same environment, while a different input must be rejected.
+     * `signal` controls one attempt and is not part of create identity.
+     */
     idempotencyKey?: string;
     signal?: AbortSignal;
     providerOptions?: Record<string, unknown>;
 }
+/**
+ * Compute the canonical identity of a generic environment create request.
+ *
+ * The operation key names the request and the abort signal controls one
+ * attempt, so neither belongs in the input identity. Every other field is
+ * canonicalized with the shared RFC 8785 JSON representation.
+ * @internal
+ */
+export declare function agentEnvironmentCreateInputDigest(input: CreateAgentEnvironmentInput): Sha256Digest;
+/** @internal State held by one provider adapter for keyed create retries. */
+export interface AgentEnvironmentCreateIdempotencyRecord<T> {
+    readonly digest: Sha256Digest;
+    readonly pending: Promise<T>;
+    environment?: T;
+}
+/**
+ * Apply the generic create contract to one provider adapter's keyed requests.
+ *
+ * The provider's backing service remains responsible for retaining the key
+ * across adapter reconstruction. This helper coalesces concurrent retries and
+ * rejects collisions before the provider performs another create effect.
+ * @internal
+ */
+export declare function createAgentEnvironmentWithIdempotency<T>(records: Map<string, AgentEnvironmentCreateIdempotencyRecord<T>>, input: CreateAgentEnvironmentInput, create: () => Promise<T>): Promise<T>;
 export interface AgentEnvironmentProvider {
     readonly name: string;
     readonly exactProcess?: AgentExactProcessProvider;
     capabilities(): AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>;
     validateProfile?(profile: AgentProfileRef): AgentProfileValidationResult | Promise<AgentProfileValidationResult>;
+    /**
+     * Create or reconstruct one environment.
+     *
+     * With `input.idempotencyKey`, the provider must return the same environment
+     * for the same canonical input and reject any changed input before creating.
+     * Without a key, each call may create a fresh environment.
+     */
     create(input: CreateAgentEnvironmentInput): Promise<AgentEnvironment>;
     get?(id: string, options?: {
         signal?: AbortSignal;

package/dist/environment-runtime.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { canonicalCandidateDigest } from "./agent-candidate-schema-common.js";
 import { InteractionCapabilitiesSchema, RequestedInteractionsSchema } from "./interaction.js";
 import { ContextTransferReceiptSchema, ContextTransferRequestSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches } from "./portable-context.js";
 import { AgentExactRunControlRefSchema, AgentRunControlRefSchema, CanonicalStreamEventSchema } from "./runtime-control.js";
@@ -309,3 +310,57 @@ export const AgentEnvironmentCapabilitiesSchema = z
         });
     }
 });
+/**
+ * Compute the canonical identity of a generic environment create request.
+ *
+ * The operation key names the request and the abort signal controls one
+ * attempt, so neither belongs in the input identity. Every other field is
+ * canonicalized with the shared RFC 8785 JSON representation.
+ * @internal
+ */
+export function agentEnvironmentCreateInputDigest(input) {
+    const { idempotencyKey: _idempotencyKey, signal: _signal, ...material } = input;
+    return canonicalCandidateDigest({
+        kind: "agent-environment-create.v1",
+        input: material,
+    });
+}
+/**
+ * Apply the generic create contract to one provider adapter's keyed requests.
+ *
+ * The provider's backing service remains responsible for retaining the key
+ * across adapter reconstruction. This helper coalesces concurrent retries and
+ * rejects collisions before the provider performs another create effect.
+ * @internal
+ */
+export async function createAgentEnvironmentWithIdempotency(records, input, create) {
+    input.signal?.throwIfAborted();
+    const key = input.idempotencyKey;
+    if (key === undefined)
+        return create();
+    const digest = agentEnvironmentCreateInputDigest(input);
+    const existing = records.get(key);
+    if (existing !== undefined) {
+        if (existing.digest !== digest) {
+            throw new Error("agent environment create idempotency key conflicts with a different create input");
+        }
+        return existing.environment ?? existing.pending;
+    }
+    const pending = Promise.resolve().then(create);
+    const record = {
+        digest,
+        pending,
+    };
+    records.set(key, record);
+    try {
+        const environment = await pending;
+        if (records.get(key) === record)
+            record.environment = environment;
+        return environment;
+    }
+    catch (error) {
+        if (records.get(key) === record)
+            records.delete(key);
+        throw error;
+    }
+}

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, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, 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, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, 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, createAgentEnvironmentWithIdempotency, 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, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, 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, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, 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, createAgentEnvironmentWithIdempotency, 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/provider-config.d.ts

@@ -47,7 +47,16 @@ export type ModelGatewayDefaults = {
     apiKeyEnvVar: string;
 };
 export declare const TANGLE_ROUTER_DEFAULT_ROOT_URL = "https://router.tangle.tools";
-export declare const TANGLE_ROUTER_DEFAULT_MODEL = "zai/glm-4.7";
+/**
+ * Model a managed run requests when nothing else names one.
+ *
+ * The router answers a Tangle-funded call only when it both routes the model
+ * AND holds a spend-authorizing price for it. A model that fails either test
+ * answers 503, which a CLI reads as transient and retries until its own
+ * timeout — so an unservable default hangs a run rather than failing it.
+ * Confirm both properties against the live router before changing this id.
+ */
+export declare const TANGLE_ROUTER_DEFAULT_MODEL = "zai/glm-5.2";
 export declare function normalizeOpenAiCompatibleBaseUrl(baseUrl: string): string;
 export declare function resolveTangleRouterDefaults(env?: Record<string, string | undefined>): ModelGatewayDefaults;
 export declare function withModelGatewayDefaults<T extends ProviderConfig["model"]>(model: T, defaults?: ModelGatewayDefaults): T;

package/dist/provider-config.js

@@ -1,5 +1,14 @@
 export const TANGLE_ROUTER_DEFAULT_ROOT_URL = "https://router.tangle.tools";
-export const TANGLE_ROUTER_DEFAULT_MODEL = "zai/glm-4.7";
+/**
+ * Model a managed run requests when nothing else names one.
+ *
+ * The router answers a Tangle-funded call only when it both routes the model
+ * AND holds a spend-authorizing price for it. A model that fails either test
+ * answers 503, which a CLI reads as transient and retries until its own
+ * timeout — so an unservable default hangs a run rather than failing it.
+ * Confirm both properties against the live router before changing this id.
+ */
+export const TANGLE_ROUTER_DEFAULT_MODEL = "zai/glm-5.2";
 export function normalizeOpenAiCompatibleBaseUrl(baseUrl) {
     const trimmed = baseUrl.replace(/\/+$/, "");
     return /\/v\d+$/.test(trimmed) ? trimmed : `${trimmed}/v1`;

package/package.json

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