@tangle-network/agent-provider-tangle 0.2.0

package/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.

package/README.md

@@ -0,0 +1,12 @@
+# @tangle-network/agent-provider-tangle
+
+Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
+
+```ts
+import { Sandbox } from '@tangle-network/sandbox'
+import { createTangleProvider } from '@tangle-network/agent-provider-tangle'
+
+const provider = createTangleProvider({
+  client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
+})
+```

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
+import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import type { InputPart } from "@tangle-network/agent-interface";
+export interface SandboxClientLike {
+    create(options?: CreateSandboxOptions): Promise<SandboxInstanceLike>;
+    get?(id: string): Promise<SandboxInstanceLike | null>;
+    list?(options?: unknown): Promise<SandboxInstanceLike[]>;
+    describePlacement?(box: SandboxInstanceLike): unknown;
+}
+export interface SandboxInstanceLike {
+    id: string;
+    name?: string;
+    status?: unknown;
+    metadata?: Record<string, unknown>;
+    streamPrompt(message: string | InputPart[], options?: PromptOptions): AsyncIterable<SandboxEvent>;
+    prompt?(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
+    dispatchPrompt?(message: string | InputPart[], options?: PromptOptions): Promise<unknown>;
+    session?(id: string): SandboxSessionLike;
+    read?(path: string, options?: {
+        sessionId?: string;
+    }): Promise<string>;
+    write?(path: string, content: string, options?: {
+        sessionId?: string;
+    }): Promise<void>;
+    exec?(command: string, options?: unknown): Promise<SandboxExecResult>;
+    checkpoint?(options?: unknown): Promise<unknown>;
+    fork?(checkpointId: string, options?: unknown): Promise<SandboxInstanceLike>;
+    refresh?(): Promise<void>;
+    delete?(): Promise<void>;
+}
+export interface SandboxSessionLike {
+    readonly id: string;
+    status(): Promise<unknown | null>;
+    events(options?: {
+        since?: string;
+        signal?: AbortSignal;
+    }): AsyncIterable<SandboxEvent>;
+    result(): Promise<PromptResult>;
+    prompt(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
+    cancel(): Promise<void>;
+}
+export interface TangleProviderOptions {
+    client: SandboxClientLike;
+    name?: string;
+    defaultBackend?: BackendType;
+    capabilities?: AgentEnvironmentCapabilities | (() => AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>);
+    validateProfile?: AgentEnvironmentProvider["validateProfile"];
+    mapCreateInput?: (input: CreateAgentEnvironmentInput) => CreateSandboxOptions;
+}
+export declare function createTangleProvider(options: TangleProviderOptions): AgentEnvironmentProvider;
+export declare function defaultTangleSandboxCapabilities(): AgentEnvironmentCapabilities;

package/dist/index.js

@@ -0,0 +1,321 @@
+export function createTangleProvider(options) {
+    const providerName = options.name ?? "tangle-sandbox";
+    return {
+        name: providerName,
+        capabilities: async () => {
+            if (!options.capabilities)
+                return defaultTangleSandboxCapabilities();
+            return typeof options.capabilities === "function" ? options.capabilities() : options.capabilities;
+        },
+        ...(options.validateProfile ? { validateProfile: options.validateProfile } : {}),
+        async create(input) {
+            const createOptions = options.mapCreateInput?.(input) ??
+                sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode");
+            const box = await options.client.create(createOptions);
+            return sandboxInstanceAsEnvironment(box, providerName, options.client);
+        },
+        ...(options.client.get
+            ? {
+                async get(id) {
+                    const box = await options.client.get?.(id);
+                    return box ? sandboxInstanceAsEnvironment(box, providerName, options.client) : null;
+                },
+            }
+            : {}),
+        ...(options.client.list
+            ? {
+                async list(query) {
+                    const boxes = await options.client.list?.(query?.providerOptions);
+                    return (boxes ?? []).map((box) => ({
+                        id: String(box.id),
+                        provider: providerName,
+                        ...(box.name ? { name: box.name } : {}),
+                        status: statusFromUnknown(box.status),
+                        ...(box.metadata ? { metadata: box.metadata } : {}),
+                    }));
+                },
+            }
+            : {}),
+    };
+}
+function sandboxInstanceAsEnvironment(box, providerName, client) {
+    return {
+        id: String(box.id),
+        provider: providerName,
+        ...(box.name ? { name: box.name } : {}),
+        async status() {
+            await box.refresh?.();
+            return statusFromUnknown(box.status);
+        },
+        async *stream(input) {
+            for await (const event of box.streamPrompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input))) {
+                yield environmentEventFromSandboxEvent(event);
+            }
+        },
+        ...(box.dispatchPrompt
+            ? {
+                async dispatch(input) {
+                    const dispatched = await box.dispatchPrompt?.(promptFromTurnInput(input), promptOptionsFromTurnInput(input));
+                    return sessionRefFromSandboxDispatch(dispatched, providerName);
+                },
+            }
+            : {}),
+        ...(box.session
+            ? {
+                session(id) {
+                    const session = box.session?.(id);
+                    if (!session)
+                        throw new Error("sandbox session(id) returned undefined");
+                    return sandboxSessionAsAgentSession(session);
+                },
+            }
+            : {}),
+        ...(box.read ? { read: box.read.bind(box) } : {}),
+        ...(box.write ? { write: box.write.bind(box) } : {}),
+        ...(box.exec
+            ? {
+                async exec(command, options) {
+                    return execResultFromSandboxExecResult(await box.exec?.(command, options));
+                },
+            }
+            : {}),
+        ...(box.checkpoint
+            ? {
+                async checkpoint(options) {
+                    const result = await box.checkpoint?.(options);
+                    return { id: checkpointIdFromResult(result), provider: providerName };
+                },
+            }
+            : {}),
+        ...(box.fork
+            ? {
+                async fork(checkpoint, options) {
+                    const forked = await box.fork?.(checkpoint.id, options);
+                    if (!forked)
+                        throw new Error("sandbox fork returned no environment");
+                    return sandboxInstanceAsEnvironment(forked, providerName, client);
+                },
+            }
+            : {}),
+        async placement() {
+            return placementInfoFromLoopPlacement(client.describePlacement?.(box), box);
+        },
+        async refresh() {
+            await box.refresh?.();
+        },
+        async destroy() {
+            await box.delete?.();
+        },
+    };
+}
+function sandboxSessionAsAgentSession(session) {
+    return {
+        id: session.id,
+        async status() {
+            const status = await session.status();
+            if (!status)
+                return null;
+            return sessionStatusFromUnknown(status.status);
+        },
+        async *events(options) {
+            for await (const event of session.events(options))
+                yield environmentEventFromSandboxEvent(event);
+        },
+        async result() {
+            return agentTurnResultFromPromptResult(await session.result());
+        },
+        async prompt(input) {
+            return agentTurnResultFromPromptResult(await session.prompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input)));
+        },
+        cancel: session.cancel.bind(session),
+    };
+}
+function sandboxOptionsFromCreateInput(input, defaultBackend) {
+    const workspace = input.workspace ?? {};
+    const providerOptions = input.providerOptions?.sandboxCreateOptions;
+    const base = providerOptions && typeof providerOptions === "object"
+        ? { ...providerOptions }
+        : {};
+    return {
+        ...base,
+        ...(workspace.environment ? { environment: workspace.environment } : {}),
+        ...(workspace.image ? { image: workspace.image } : {}),
+        ...(workspace.repoUrl ? { git: { url: workspace.repoUrl, ref: workspace.gitRef } } : {}),
+        ...(input.resources ? { resources: input.resources } : {}),
+        ...(input.env ? { env: input.env } : {}),
+        ...(Array.isArray(input.secrets) ? { secrets: input.secrets } : {}),
+        ...(input.metadata ? { metadata: input.metadata } : {}),
+        ...(input.name ? { name: input.name } : {}),
+        ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+        backend: {
+            ...(base.backend ?? {}),
+            type: (input.backend ?? defaultBackend),
+            profile: input.profile,
+        },
+    };
+}
+function environmentEventFromSandboxEvent(event) {
+    const data = event.data && typeof event.data === "object"
+        ? event.data
+        : {};
+    return {
+        type: String(event.type),
+        data,
+        ...(event.id ? { id: event.id } : {}),
+        usage: tokenUsageFromData(data),
+        providerEvent: event,
+    };
+}
+function promptFromTurnInput(input) {
+    if (input.parts)
+        return input.parts;
+    return input.prompt ?? "";
+}
+function promptOptionsFromTurnInput(input) {
+    return {
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.timeoutMs ? { timeoutMs: input.timeoutMs } : {}),
+        ...(input.context ? { context: input.context } : {}),
+        ...(input.signal ? { signal: input.signal } : {}),
+        ...(input.executionId ? { executionId: input.executionId } : {}),
+        ...(input.lastEventId ? { lastEventId: input.lastEventId } : {}),
+        ...(input.turnId ? { turnId: input.turnId } : {}),
+        ...(input.detach !== undefined ? { detach: input.detach } : {}),
+    };
+}
+function agentTurnResultFromPromptResult(result) {
+    const record = result;
+    const text = typeof record.response === "string"
+        ? record.response
+        : typeof record.text === "string"
+            ? record.text
+            : typeof record.finalText === "string"
+                ? record.finalText
+                : "";
+    const success = typeof record.success === "boolean" ? record.success : true;
+    return {
+        text,
+        success,
+        ...(typeof record.error === "string" ? { error: record.error } : {}),
+        usage: tokenUsageFromData(record),
+    };
+}
+function sessionRefFromSandboxDispatch(dispatched, providerName) {
+    const record = dispatched && typeof dispatched === "object"
+        ? dispatched
+        : undefined;
+    const id = record?.sessionId ?? record?.id;
+    if (typeof id !== "string" || id.length === 0 || !record) {
+        throw new Error("sandbox dispatch returned no session id");
+    }
+    return {
+        id,
+        provider: providerName,
+        metadata: {
+            ...(record.status ? { status: record.status } : {}),
+            ...(record.alreadyExisted !== undefined ? { alreadyExisted: record.alreadyExisted } : {}),
+        },
+    };
+}
+function execResultFromSandboxExecResult(result) {
+    const record = (result ?? {});
+    return {
+        exitCode: finiteNumber(record.exitCode) ?? finiteNumber(record.code) ?? 0,
+        stdout: typeof record.stdout === "string" ? record.stdout : "",
+        stderr: typeof record.stderr === "string" ? record.stderr : "",
+    };
+}
+function checkpointIdFromResult(result) {
+    const record = result && typeof result === "object" ? result : {};
+    const id = record.checkpointId ?? record.id;
+    if (typeof id !== "string" || id.length === 0) {
+        throw new Error("sandbox checkpoint returned no checkpoint id");
+    }
+    return id;
+}
+function placementInfoFromLoopPlacement(placement, box) {
+    if (!placement || typeof placement !== "object")
+        return { kind: "sandbox", sandboxId: String(box.id) };
+    const record = placement;
+    return {
+        kind: record.kind === "fleet" ? "fleet" : "sandbox",
+        sandboxId: typeof record.sandboxId === "string" ? record.sandboxId : String(box.id),
+        ...(typeof record.fleetId === "string" ? { fleetId: record.fleetId } : {}),
+        ...(typeof record.machineId === "string" ? { machineId: record.machineId } : {}),
+    };
+}
+function tokenUsageFromData(data) {
+    const usageRecord = data.usage && typeof data.usage === "object"
+        ? data.usage
+        : data.tokenUsage && typeof data.tokenUsage === "object"
+            ? data.tokenUsage
+            : data;
+    const inputTokens = finiteNumber(usageRecord.inputTokens) ??
+        finiteNumber(usageRecord.tokensIn) ??
+        finiteNumber(usageRecord.prompt_tokens);
+    const outputTokens = finiteNumber(usageRecord.outputTokens) ??
+        finiteNumber(usageRecord.tokensOut) ??
+        finiteNumber(usageRecord.completion_tokens);
+    const cost = finiteNumber(usageRecord.cost) ??
+        finiteNumber(usageRecord.costUsd) ??
+        finiteNumber(usageRecord.totalCostUsd) ??
+        finiteNumber(data.costUsd) ??
+        finiteNumber(data.totalCostUsd);
+    if (inputTokens === undefined && outputTokens === undefined && cost === undefined)
+        return undefined;
+    return {
+        inputTokens: inputTokens ?? 0,
+        outputTokens: outputTokens ?? 0,
+        ...(cost !== undefined ? { cost } : {}),
+    };
+}
+function statusFromUnknown(status) {
+    if (status === "pending" || status === "provisioning" || status === "running")
+        return status;
+    if (status === "stopped" || status === "failed" || status === "expired")
+        return status;
+    if (status === "completed" || status === "cancelled")
+        return "stopped";
+    return "unknown";
+}
+function sessionStatusFromUnknown(status) {
+    if (status === "completed" || status === "cancelled")
+        return status;
+    return statusFromUnknown(status);
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+export function defaultTangleSandboxCapabilities() {
+    return {
+        profile: {
+            namedProfiles: true,
+            systemPrompt: true,
+            instructions: true,
+            tools: true,
+            permissions: true,
+            mcp: true,
+            subagents: true,
+            resources: {
+                files: true,
+                instructions: true,
+                tools: true,
+                skills: true,
+                agents: true,
+                commands: true,
+            },
+            hooks: true,
+            modes: true,
+            runtimeUpdate: true,
+            validation: true,
+        },
+        streaming: { live: true, replay: true, detach: true, turnIdempotency: true },
+        sessions: { continue: true, list: true, messages: true },
+        workspace: { read: true, write: true, exec: true, git: true, upload: true, download: true },
+        branching: { checkpoint: true, fork: true },
+        placement: true,
+        usage: true,
+        confidential: true,
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@tangle-network/agent-provider-tangle",
+  "version": "0.2.0",
+  "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tangle-network/agent-sdk.git",
+    "directory": "packages/agent-provider-tangle"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "dist/index.d.ts",
+    "dist/index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@tangle-network/agent-interface": "0.14.0"
+  },
+  "peerDependencies": {
+    "@tangle-network/sandbox": ">=0.8.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tangle-network/sandbox": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@tangle-network/sandbox": "^0.8.2",
+    "@types/node": "25.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
+    "@tangle-network/agent-provider-testkit": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}