@tangle-network/agent-interface 1.0.0 → 1.1.0

package/README.md

@@ -1,10 +1,34 @@
 # @tangle-network/agent-interface
 
-Shared TypeScript types and zod schemas that define the contract between Tangle
+Shared TypeScript types and Zod schemas that define the contract between Tangle
 agents, the sidecar, and provider adapters: capabilities, agent profiles,
 message parts, and harness descriptors. This is the canonical home for those
 shapes; higher-level packages import from here rather than redefining them.
 
+## Agent instances
+
+`AgentProfile` describes behavior. `AgentInstanceSpec` describes one optional managed Agent inside an existing execution environment. The environment remains the computer and security boundary, so it may host zero, one, or many Agent instances.
+
+```ts
+import type { AgentInstanceSpec } from "@tangle-network/agent-interface/agent-instance";
+
+const planner = {
+  id: "planner",
+  profile: {
+    name: "planner",
+    harness: "opencode",
+    prompt: { systemPrompt: "Plan before editing." },
+  },
+  workspace: { mode: "shared" },
+} satisfies AgentInstanceSpec;
+```
+
+The portable contract owns only inline profile and harness selection, shared or isolated workspace intent, public lifecycle state, a provider-sanitized failure summary, and idempotent stop shapes. Credentials, HTTP routes, process identifiers, placement, billing, snapshots, local resource controls, grants, and fencing remain provider-private.
+
+`shared` means ordinary same-computer file visibility. It is not automatic merge behavior or tenant isolation. `isolated` asks the provider for a private writable view and explicit inspect or commit behavior. Providers must reject unsatisfied machine requirements rather than silently replacing or migrating a live environment.
+
+The public `AgentInstanceRecord` contains a credential-free profile identity, not the full profile or provider request. Existing session APIs can implement this contract without a new service: one instance maps to one managed session, compatible sessions may reuse a backend process, and stop maps to idempotent session deletion or process release.
+
 ## Durable runs, interactions, and context
 
 `AgentRunControlRef` identifies a retained run without depending on a live JavaScript object and may carry the provider's admission digest so reconstruction can reject changed-input reuse.
@@ -52,6 +76,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.
 
@@ -59,8 +90,6 @@ Omitting `interactions` and `nativeContinuation`, or leaving the three durable b
 `replace` means the provider deletes the harness's own system prompt and installs `prompt.systemPrompt`; `append` means it keeps that prompt and adds `prompt.appendSystemPrompt` to it.
 A provider that can only append must declare `replace: false` and refuse a profile carrying `systemPrompt`, because quietly appending a requested replacement leaves the instructions the caller asked to delete in force.
 
-
-
 ## Install
 
 ```bash

package/dist/agent-instance.d.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import type { Sha256Digest } from "./agent-candidate.js";
+import type { AgentProfile } from "./agent-profile.js";
+import type { HarnessType } from "./harness.js";
+/** Lifecycle state of one managed Agent inside an execution environment. */
+export declare const AGENT_INSTANCE_STATUSES: readonly ["starting", "ready", "busy", "failed", "stopped"];
+export type AgentInstanceStatus = (typeof AGENT_INSTANCE_STATUSES)[number];
+/**
+ * How one Agent sees the provider-owned workspace.
+ *
+ * `shared` is ordinary same-computer visibility. `isolated` requests a private
+ * writable view with provider-defined inspect or commit behavior. Neither mode
+ * is a security boundary between mutually untrusted Agents.
+ */
+export declare const AGENT_INSTANCE_WORKSPACE_MODES: readonly ["shared", "isolated"];
+export type AgentInstanceWorkspaceMode = (typeof AGENT_INSTANCE_WORKSPACE_MODES)[number];
+export interface AgentInstanceWorkspace {
+    mode: AgentInstanceWorkspaceMode;
+}
+/**
+ * Provider-neutral request to start one managed Agent inside an existing
+ * execution environment.
+ *
+ * Omitting `profile` asks the provider for its default Agent configuration.
+ * Omitting `workspace` selects the provider's documented default. A profile
+ * never implies another VM.
+ */
+export interface AgentInstanceSpec {
+    /** Stable caller-selected id or idempotency key, when supported. */
+    id?: string;
+    /** Human-readable label; not immutable identity. */
+    name?: string;
+    /** Exact portable profile for this Agent. */
+    profile?: AgentProfile;
+    /** Optional execution override; otherwise the profile or provider decides. */
+    harness?: HarnessType;
+    workspace?: AgentInstanceWorkspace;
+}
+/** Credential-free identity of the profile bound to an Agent instance. */
+export interface AgentInstanceProfileIdentity {
+    name?: string;
+    digest: Sha256Digest;
+}
+/**
+ * Public failure summary. Providers must remove credentials and private
+ * implementation details before publishing this value.
+ */
+export interface AgentInstanceFailure {
+    code?: string;
+    message: string;
+}
+/**
+ * Portable snapshot of one managed Agent.
+ *
+ * The record deliberately excludes the full profile, provider request,
+ * credentials, grants, process ids, placement, and fencing state.
+ */
+export interface AgentInstanceRecord {
+    kind: "agent-instance";
+    schemaVersion: 1;
+    id: string;
+    name?: string;
+    profile?: AgentInstanceProfileIdentity;
+    /** Effective harness after profile and caller override resolution. */
+    harness?: HarnessType;
+    workspace: AgentInstanceWorkspace;
+    status: AgentInstanceStatus;
+    failure?: AgentInstanceFailure;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+export interface AgentInstanceStopRequest {
+    agentId: string;
+    /** Provider-defined hard termination after graceful stop cannot complete. */
+    force?: boolean;
+}
+export interface AgentInstanceStopAcknowledgement {
+    agentId: string;
+    outcome: "stopped" | "already-stopped" | "not-found";
+}
+export declare const agentInstanceStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    starting: "starting";
+    ready: "ready";
+    busy: "busy";
+    stopped: "stopped";
+}>;
+export declare const agentInstanceWorkspaceModeSchema: z.ZodEnum<{
+    isolated: "isolated";
+    shared: "shared";
+}>;
+export declare const agentInstanceWorkspaceSchema: z.ZodType<AgentInstanceWorkspace>;
+export declare const agentInstanceSpecSchema: z.ZodType<AgentInstanceSpec>;
+export declare const agentInstanceProfileIdentitySchema: z.ZodType<AgentInstanceProfileIdentity>;
+export declare const agentInstanceFailureSchema: z.ZodType<AgentInstanceFailure>;
+export declare const agentInstanceRecordSchema: z.ZodType<AgentInstanceRecord>;
+export declare const agentInstanceStopRequestSchema: z.ZodType<AgentInstanceStopRequest>;
+export declare const agentInstanceStopAcknowledgementSchema: z.ZodType<AgentInstanceStopAcknowledgement>;

package/dist/agent-instance.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { isWellFormedUnicode, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { harnessTypeSchema } from "./harness.js";
+import { agentProfileSchema } from "./profile-schema.js";
+/** Lifecycle state of one managed Agent inside an execution environment. */
+export const AGENT_INSTANCE_STATUSES = [
+    "starting",
+    "ready",
+    "busy",
+    "failed",
+    "stopped",
+];
+/**
+ * How one Agent sees the provider-owned workspace.
+ *
+ * `shared` is ordinary same-computer visibility. `isolated` requests a private
+ * writable view with provider-defined inspect or commit behavior. Neither mode
+ * is a security boundary between mutually untrusted Agents.
+ */
+export const AGENT_INSTANCE_WORKSPACE_MODES = ["shared", "isolated"];
+const identifierSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9](?:[A-Za-z0-9._:-]*[A-Za-z0-9])?$/, "identifier must use visible alphanumeric, '.', '_', ':', or '-' characters");
+const labelSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .refine((value) => isWellFormedUnicode(value) && !/[\u0000-\u001f\u007f]/u.test(value), "label must be valid Unicode without control characters");
+const failureMessageSchema = z
+    .string()
+    .min(1)
+    .max(16_384)
+    .refine((value) => isWellFormedUnicode(value) && !value.includes("\0"), "failure message must be valid Unicode without NUL");
+const timestampSchema = z
+    .number()
+    .int()
+    .nonnegative()
+    .max(Number.MAX_SAFE_INTEGER);
+export const agentInstanceStatusSchema = z.enum(AGENT_INSTANCE_STATUSES);
+export const agentInstanceWorkspaceModeSchema = z.enum(AGENT_INSTANCE_WORKSPACE_MODES);
+export const agentInstanceWorkspaceSchema = z.strictObject({
+    mode: agentInstanceWorkspaceModeSchema,
+});
+export const agentInstanceSpecSchema = z.strictObject({
+    id: identifierSchema.optional(),
+    name: labelSchema.optional(),
+    profile: agentProfileSchema.optional(),
+    harness: harnessTypeSchema.optional(),
+    workspace: agentInstanceWorkspaceSchema.optional(),
+});
+export const agentInstanceProfileIdentitySchema = z.strictObject({
+    name: labelSchema.optional(),
+    digest: sha256DigestSchema,
+});
+export const agentInstanceFailureSchema = z.strictObject({
+    code: identifierSchema.optional(),
+    message: failureMessageSchema,
+});
+export const agentInstanceRecordSchema = z
+    .strictObject({
+    kind: z.literal("agent-instance"),
+    schemaVersion: z.literal(1),
+    id: identifierSchema,
+    name: labelSchema.optional(),
+    profile: agentInstanceProfileIdentitySchema.optional(),
+    harness: harnessTypeSchema.optional(),
+    workspace: agentInstanceWorkspaceSchema,
+    status: agentInstanceStatusSchema,
+    failure: agentInstanceFailureSchema.optional(),
+    createdAtMs: timestampSchema,
+    updatedAtMs: timestampSchema,
+})
+    .superRefine((record, context) => {
+    if (record.updatedAtMs < record.createdAtMs) {
+        context.addIssue({
+            code: "custom",
+            path: ["updatedAtMs"],
+            message: "agent instance update cannot precede creation",
+        });
+    }
+    if (record.status === "failed" && record.failure === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["failure"],
+            message: "failed agent instance requires a failure reason",
+        });
+    }
+    if (record.status !== "failed" && record.failure !== undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["failure"],
+            message: "failure reason is valid only for failed agent instances",
+        });
+    }
+});
+export const agentInstanceStopRequestSchema = z.strictObject({
+    agentId: identifierSchema,
+    force: z.boolean().optional(),
+});
+export const agentInstanceStopAcknowledgementSchema = z.strictObject({
+    agentId: identifierSchema,
+    outcome: z.enum(["stopped", "already-stopped", "not-found"]),
+});

package/dist/environment-interactive.d.ts

@@ -1050,8 +1050,8 @@ export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnio
     }, z.core.$strict>;
     endedAt: z.ZodISODateTime;
     reason: z.ZodEnum<{
-        exited: "exited";
         stopped: "stopped";
+        exited: "exited";
         lost: "lost";
     }>;
     exitCode: z.ZodOptional<z.ZodNumber>;
@@ -1541,8 +1541,8 @@ export declare const AgentInteractiveSessionStopAcknowledgementSchema: z.ZodObje
     }>;
     effect: z.ZodEnum<{
         unknown: "unknown";
-        not_live: "not_live";
         stopped: "stopped";
+        not_live: "not_live";
         stop_requested: "stop_requested";
     }>;
     message: z.ZodOptional<z.ZodString>;

package/dist/environment-observation.d.ts

@@ -105,9 +105,9 @@ export declare const AgentEnvironmentStatusSchema: z.ZodEnum<{
     unknown: "unknown";
     failed: "failed";
     expired: "expired";
+    stopped: "stopped";
     pending: "pending";
     running: "running";
-    stopped: "stopped";
     provisioning: "provisioning";
 }>;
 /** Lifecycle, cleanup, continuity, and persistence of one environment. */
@@ -116,9 +116,9 @@ export declare const EnvironmentLifecycleSchema: z.ZodObject<{
         unknown: "unknown";
         failed: "failed";
         expired: "expired";
+        stopped: "stopped";
         pending: "pending";
         running: "running";
-        stopped: "stopped";
         provisioning: "provisioning";
     }>;
     cleanup: z.ZodOptional<z.ZodObject<{
@@ -441,9 +441,9 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 unknown: "unknown";
                 failed: "failed";
                 expired: "expired";
+                stopped: "stopped";
                 pending: "pending";
                 running: "running";
-                stopped: "stopped";
                 provisioning: "provisioning";
             }>;
             cleanup: z.ZodOptional<z.ZodObject<{
@@ -489,9 +489,9 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 unknown: "unknown";
                 failed: "failed";
                 expired: "expired";
+                stopped: "stopped";
                 pending: "pending";
                 running: "running";
-                stopped: "stopped";
                 provisioning: "provisioning";
             }>;
             cleanup: z.ZodOptional<z.ZodObject<{

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";
@@ -26,6 +26,7 @@ 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 "./agent-instance.js";
 export * from "./agent-profile-snapshot.js";
 export * from "./agent-profile-activation.js";
 export * from "./agent-profile-materialization.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";
@@ -24,6 +24,7 @@ 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 "./agent-instance.js";
 export * from "./agent-profile-snapshot.js";
 export * from "./agent-profile-activation.js";
 export * from "./agent-profile-materialization.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.1.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -22,6 +22,11 @@
       "types": "./dist/agent-profile.d.ts",
       "default": "./dist/agent-profile.js"
     },
+    "./agent-instance": {
+      "import": "./dist/agent-instance.js",
+      "types": "./dist/agent-instance.d.ts",
+      "default": "./dist/agent-instance.js"
+    },
     "./profile-snapshot": {
       "import": "./dist/agent-profile-snapshot.js",
       "types": "./dist/agent-profile-snapshot.d.ts",