feat(provider): add agent environment provider adapters

.changeset/provider-environment-contract.md

@@ -0,0 +1,11 @@
+---
+"@tangle-network/agent-interface": minor
+"@tangle-network/agent-provider-testkit": minor
+"@tangle-network/agent-provider-sandbox": minor
+"@tangle-network/agent-provider-cli-bridge": minor
+"@tangle-network/agent-provider-computesdk": minor
+"@tangle-network/agent-provider-e2b": minor
+"@tangle-network/agent-provider-daytona": minor
+---
+
+Add the provider-neutral agent environment contract plus provider packages for Tangle Sandbox, CLI bridge, ComputeSDK, E2B, Daytona, and shared provider conformance tests.

README.md

@@ -1,17 +1,25 @@
 # agent-sdk
 
 Public home of the TypeScript SDK for building against Tangle agents. This is a
-pnpm workspace containing two published packages:
+pnpm workspace containing the shared contracts, core client, and provider
+adapters:
 
 | Package | Description |
 | --- | --- |
 | [`@tangle-network/agent-interface`](packages/agent-interface) | Shared TypeScript types and zod schemas defining the agent/provider contract. Zero runtime beyond zod. |
 | [`@tangle-network/agent-core`](packages/agent-core) | Runtime primitives for talking to Tangle agents: auth token issue/verify, SSE stream parsing, transport interfaces, retries/resilience, and telemetry. Depends on `@tangle-network/agent-interface`. |
+| [`@tangle-network/agent-provider-testkit`](packages/agent-provider-testkit) | Conformance checks that any `AgentEnvironmentProvider` package can run before publishing. |
+| [`@tangle-network/agent-provider-sandbox`](packages/agent-provider-sandbox) | Adapter from `@tangle-network/sandbox` clients into the shared environment provider contract. |
+| [`@tangle-network/agent-provider-cli-bridge`](packages/agent-provider-cli-bridge) | Adapter for a CLI bridge OpenAI-compatible HTTP endpoint. |
+| [`@tangle-network/agent-provider-computesdk`](packages/agent-provider-computesdk) | Adapter for ComputeSDK-backed sandboxes. |
+| [`@tangle-network/agent-provider-e2b`](packages/agent-provider-e2b) | Direct E2B adapter. |
+| [`@tangle-network/agent-provider-daytona`](packages/agent-provider-daytona) | Direct Daytona adapter. |
 
 ## Install
 
 ```bash
 pnpm add @tangle-network/agent-core @tangle-network/agent-interface
+pnpm add @tangle-network/agent-provider-sandbox
 ```
 
 `@tangle-network/agent-core` uses `node:crypto` for token signing/verification,

packages/agent-interface/README.md

@@ -16,14 +16,50 @@ pnpm add @tangle-network/agent-interface
 ## Usage
 
 ```ts
-import type { BackendCapabilities, ProviderCapabilities } from "@tangle-network/agent-interface";
+import type {
+  AgentEnvironmentProvider,
+} from "@tangle-network/agent-interface/environment-provider";
+import type {
+  BackendCapabilities,
+  ProviderCapabilities,
+} from "@tangle-network/agent-interface";
 
 const caps: ProviderCapabilities = {
   supportsVision: true,
   supportsLogprobs: false,
   supportsToolCalls: true,
   supportsComputerUse: false,
 };
+
+const provider: AgentEnvironmentProvider = {
+  name: "example",
+  capabilities: () => ({
+    profile: {
+      namedProfiles: false,
+      systemPrompt: true,
+      instructions: true,
+      tools: true,
+      permissions: true,
+      mcp: true,
+      subagents: false,
+      resources: { files: true, instructions: true, tools: true },
+      hooks: false,
+      modes: false,
+      runtimeUpdate: false,
+      validation: true,
+    },
+    streaming: { live: true, replay: false, detach: false, turnIdempotency: false },
+    sessions: { continue: false, list: false, messages: false },
+    workspace: { read: true, write: true, exec: true, git: false, upload: false, download: false },
+    branching: { checkpoint: false, fork: false },
+    placement: false,
+    usage: true,
+    confidential: false,
+  }),
+  create: async () => {
+    throw new Error("implement provider create()");
+  },
+};
 ```
 
 ## License

packages/agent-interface/package.json

@@ -9,6 +9,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./src/index.ts"
+    },
+    "./environment-provider": {
+      "import": "./dist/environment-provider.js",
+      "types": "./src/environment-provider.ts"
     }
   },
   "repository": {
@@ -26,6 +30,11 @@
         "import": "./dist/index.js",
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
+      },
+      "./environment-provider": {
+        "import": "./dist/environment-provider.js",
+        "types": "./dist/environment-provider.d.ts",
+        "default": "./dist/environment-provider.js"
       }
     }
   },

packages/agent-interface/src/environment-provider.ts

@@ -0,0 +1,233 @@
+import type {
+  AgentProfile,
+  AgentProfileCapabilities,
+  AgentProfileValidationResult,
+} from "./agent-profile.js";
+import type { InputPart, StreamEvent, TokenUsage } from "./index.js";
+
+/** Portable profile reference: inline profile or provider catalog id. */
+export type AgentProfileRef = AgentProfile | string;
+
+export type AgentEnvironmentStatus =
+  | "pending"
+  | "provisioning"
+  | "running"
+  | "stopped"
+  | "failed"
+  | "expired"
+  | "unknown";
+
+export type AgentSessionStatus =
+  | AgentEnvironmentStatus
+  | "completed"
+  | "cancelled";
+
+export interface WorkspaceRequest {
+  /** Provider-specific environment/template id, for example "universal". */
+  environment?: string;
+  /** Container image or image alias when the provider supports image-backed workspaces. */
+  image?: string;
+  /** Repository to clone or mount before the agent runs. */
+  repoUrl?: string;
+  /** Git ref for {@link repoUrl}. */
+  gitRef?: string;
+  /** Initial working directory inside the environment. */
+  cwd?: string;
+  /** Opaque provider-native workspace fields. */
+  providerOptions?: Record<string, unknown>;
+}
+
+export interface ResourceRequest {
+  cpu?: number;
+  memoryMb?: number;
+  diskMb?: number;
+  gpu?: string;
+  providerOptions?: Record<string, unknown>;
+}
+
+export interface AgentEnvironmentQuery {
+  name?: string;
+  metadata?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
+}
+
+export interface AgentEnvironmentSummary {
+  id: string;
+  provider: string;
+  name?: string;
+  status?: AgentEnvironmentStatus;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ExecRequest {
+  cwd?: string;
+  env?: Record<string, string>;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface ExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface CheckpointRequest {
+  name?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CheckpointRef {
+  id: string;
+  provider?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ForkRequest {
+  name?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PlacementInfo {
+  kind: "local" | "sandbox" | "fleet" | "provider";
+  sandboxId?: string;
+  fleetId?: string;
+  machineId?: string;
+  region?: string;
+  providerMetadata?: Record<string, unknown>;
+}
+
+export interface AgentTurnInput {
+  prompt?: string;
+  parts?: InputPart[];
+  sessionId?: string;
+  model?: string;
+  timeoutMs?: number;
+  executionId?: string;
+  lastEventId?: string;
+  turnId?: string;
+  detach?: boolean;
+  context?: Record<string, unknown>;
+  signal?: AbortSignal;
+  providerOptions?: Record<string, unknown>;
+}
+
+export interface AgentTurnResult {
+  text: string;
+  success: boolean;
+  error?: string;
+  sessionId?: string;
+  usage?: TokenUsage;
+  metadata?: Record<string, unknown>;
+  events?: AgentEnvironmentEvent[];
+}
+
+export interface AgentSessionRef {
+  id: string;
+  provider?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentEnvironmentEvent {
+  type: string;
+  data: Record<string, unknown>;
+  id?: string;
+  normalized?: StreamEvent;
+  usage?: TokenUsage;
+  providerEvent?: unknown;
+}
+
+export interface AgentSession {
+  readonly id: string;
+  status(): Promise<AgentSessionStatus | null>;
+  events(options?: {
+    since?: string;
+    signal?: AbortSignal;
+  }): AsyncIterable<AgentEnvironmentEvent>;
+  result(): Promise<AgentTurnResult>;
+  prompt(input: AgentTurnInput): Promise<AgentTurnResult>;
+  cancel(): Promise<void>;
+}
+
+export interface AgentEnvironment {
+  readonly id: string;
+  readonly provider: string;
+  readonly name?: string;
+  status(): Promise<AgentEnvironmentStatus>;
+  stream(input: AgentTurnInput): AsyncIterable<AgentEnvironmentEvent>;
+  dispatch?(input: AgentTurnInput): Promise<AgentSessionRef>;
+  session?(id: string): AgentSession;
+  read?(path: string, options?: { sessionId?: string }): Promise<string>;
+  write?(
+    path: string,
+    content: string,
+    options?: { sessionId?: string },
+  ): Promise<void>;
+  exec?(command: string, options?: ExecRequest): Promise<ExecResult>;
+  checkpoint?(options?: CheckpointRequest): Promise<CheckpointRef>;
+  fork?(
+    checkpoint: CheckpointRef,
+    options?: ForkRequest,
+  ): Promise<AgentEnvironment>;
+  placement?(): Promise<PlacementInfo>;
+  refresh?(): Promise<void>;
+  destroy?(): Promise<void>;
+}
+
+export interface AgentEnvironmentCapabilities {
+  profile: AgentProfileCapabilities;
+  streaming: {
+    live: boolean;
+    replay: boolean;
+    detach: boolean;
+    turnIdempotency: boolean;
+  };
+  sessions: {
+    continue: boolean;
+    list: boolean;
+    messages: boolean;
+  };
+  workspace: {
+    read: boolean;
+    write: boolean;
+    exec: boolean;
+    git: boolean;
+    upload: boolean;
+    download: boolean;
+  };
+  branching: {
+    checkpoint: boolean;
+    fork: boolean;
+  };
+  placement: boolean;
+  usage: boolean;
+  confidential: boolean;
+}
+
+export interface CreateAgentEnvironmentInput {
+  profile: AgentProfileRef;
+  /** Agent backend inside the provider, for example "opencode" or "codex". */
+  backend?: string;
+  workspace?: WorkspaceRequest;
+  resources?: ResourceRequest;
+  env?: Record<string, string>;
+  secrets?: string[] | Record<string, string>;
+  metadata?: Record<string, unknown>;
+  name?: string;
+  idempotencyKey?: string;
+  signal?: AbortSignal;
+  providerOptions?: Record<string, unknown>;
+}
+
+export interface AgentEnvironmentProvider {
+  readonly name: string;
+  capabilities():
+    | AgentEnvironmentCapabilities
+    | Promise<AgentEnvironmentCapabilities>;
+  validateProfile?(
+    profile: AgentProfileRef,
+  ): AgentProfileValidationResult | Promise<AgentProfileValidationResult>;
+  create(input: CreateAgentEnvironmentInput): Promise<AgentEnvironment>;
+  get?(id: string): Promise<AgentEnvironment | null>;
+  list?(query?: AgentEnvironmentQuery): Promise<AgentEnvironmentSummary[]>;
+}

packages/agent-interface/src/index.ts

@@ -6,6 +6,7 @@
  */
 
 import type { InteractionRequest, InteractionResponse } from "./interaction.js";
+export type * from "./environment-provider.js";
 
 // Capabilities describe what a provider supports
 export type BackendCapabilities = {

packages/agent-provider-cli-bridge/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tangle Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/agent-provider-cli-bridge/README.md

@@ -0,0 +1,13 @@
+# @tangle-network/agent-provider-cli-bridge
+
+Wraps a running `cli-bridge` server as an `AgentEnvironmentProvider`.
+
+```ts
+import { createCliBridgeProvider } from '@tangle-network/agent-provider-cli-bridge'
+
+const provider = createCliBridgeProvider({
+  baseUrl: 'http://127.0.0.1:8787',
+  bearerToken: process.env.CLI_BRIDGE_TOKEN,
+  defaultModel: 'codex',
+})
+```