@tangle-network/sandbox 0.60.16 → 0.60.17-develop.20261006080745.649508b

package/README.md

@@ -134,6 +134,26 @@ With `{ until: "removed" }`, a destroyed sandbox counts as confirmed only when i
 If the removal wait runs out, the sandbox reports `removal: "pending"` and `confirmed: false`, and `result.complete` is `false`.
 That sandbox is already gone for every read, so a later call does not list it again.
 
+## Run a profile without choosing where
+
+`client.run()` runs an AgentProfile on a prompt in the environment its needs require. It returns when the run settles.
+
+```typescript
+const result = await client.run({
+  profile: { name: "support", prompt: { systemPrompt: "Answer billing questions." } },
+  prompt: "Which plan includes priority support?",
+  // placement: "auto" (default) | "inference" | "worker" | "sandbox"
+});
+console.log(result.placement?.chosen, result.placement?.reason, result.text, result.costUsd);
+```
+
+`auto` chooses among three placements:
+- one Router call, when nothing needs a tool, a file or a session;
+- Tangle's sandbox-free agent loop, when the only tools are Hub `connections`, owner `objects` or `http` reads;
+- a sandbox, when the profile needs a harness, files, a shell or MCP servers.
+
+A run that cannot be honoured is refused before anything is spent. `client.runs.create()`, `get()` and `wait()` start a run and follow it separately. Runs are served by Platform at `platformUrl`.
+
 ## Create a sandbox
 
 Omit `environment` to use the server's default image. No image choice is
@@ -855,6 +875,7 @@ The root entrypoint exports the primary client, instance, session, fleet, image,
 | Coordinated environments | `SandboxFleetClient`, `SandboxFleet` |
 | Reusable images | `Image`, `ImageBuilder` |
 | Phone and messaging lines | `client.lines`, `box.lines` |
+| Run a profile where its needs require | `client.run()`, `client.runs` |
 | Failures | `SandboxError` and its specific subclasses |
 
 The main client provides `create`, `list`, `get`, `usage`, `subscription`, and `health`.

package/dist/agent/index.d.ts

@@ -1,7 +1,7 @@
 import { _ as SandboxSession, h as SandboxTaskSession, r as SandboxInstance } from "../sandbox-DalvAflZ.js";
 import { D as CodeExecutionResult, E as CodeExecutionOptions, Ji as SessionListOptions, Ki as SessionInfo, Kr as SandboxFleetParent, O as CodeLanguage, d as BackendConfig, io as BackendType, k as CodeResultPart } from "../types-CdT-paBK.js";
-import { i as Sandbox } from "../client-CbOQtx9b.js";
-import { u as PreviewAuthorizer } from "../preview-T96_mF5c.js";
+import { i as Sandbox } from "../client-6u7a1HMx.js";
+import { u as PreviewAuthorizer } from "../preview-BXglWD2M.js";
 import * as _$_modelcontextprotocol_sdk_server_index_js0 from "@modelcontextprotocol/sdk/server/index.js";
 import { JSONSchema } from "zod/v4/core";
 import { ToolSet } from "ai";

package/dist/agent/index.js

@@ -1,7 +1,7 @@
 import { a as TOOL_SPECS, i as ALL_TOOL_SPECS, o as serializeToolResult, r as bindToolSpecs, t as createMcpServer } from "../mcp-local-DY1CnWBn.js";
 import { k as assertCurrentBackendType } from "../interactive-controller-5_ixpFnR.js";
 import { c as NotFoundError, g as ValidationError, m as StateError } from "../errors-D1JIX7Jm.js";
-import { n as Sandbox } from "../client-CT9Td-BV.js";
+import { n as Sandbox } from "../client-BtsaKP2y.js";
 import { t as SandboxInstance } from "../sandbox-D3VcDY8b.js";
 import { z } from "zod";
 //#region src/agent/instances.ts

package/dist/agent/preview.d.ts

@@ -1,2 +1,2 @@
-import { _ as publishAgentPreview, a as previewOperationTool, c as AgentPreviewOptions, d as PreviewExecutionContext, f as PublishAgentPreviewOptions, g as listAgentPreviews, h as getAgentPreview, i as PreviewTool, l as PreviewAuthorizationRequest, m as ensureAgentPreview, n as PREVIEW_MCP_ALIAS, o as previewToolsForProfile, p as assertPreviewId, r as PREVIEW_TOOLS, s as AgentPreviewError, t as servePreviewMcp, u as PreviewAuthorizer, v as removeAgentPreview, y as resolveSelfSandbox } from "../preview-T96_mF5c.js";
+import { _ as publishAgentPreview, a as previewOperationTool, c as AgentPreviewOptions, d as PreviewExecutionContext, f as PublishAgentPreviewOptions, g as listAgentPreviews, h as getAgentPreview, i as PreviewTool, l as PreviewAuthorizationRequest, m as ensureAgentPreview, n as PREVIEW_MCP_ALIAS, o as previewToolsForProfile, p as assertPreviewId, r as PREVIEW_TOOLS, s as AgentPreviewError, t as servePreviewMcp, u as PreviewAuthorizer, v as removeAgentPreview, y as resolveSelfSandbox } from "../preview-BXglWD2M.js";
 export { AgentPreviewError, AgentPreviewOptions, PREVIEW_MCP_ALIAS, PREVIEW_TOOLS, PreviewAuthorizationRequest, PreviewAuthorizer, PreviewExecutionContext, PreviewTool, PublishAgentPreviewOptions, assertPreviewId, ensureAgentPreview, getAgentPreview, listAgentPreviews, previewOperationTool, previewToolsForProfile, publishAgentPreview, removeAgentPreview, resolveSelfSandbox, servePreviewMcp };

package/dist/{client-CbOQtx9b.d.ts → client-6u7a1HMx.d.ts}

@@ -3,7 +3,7 @@ import { $a as BatchEvent, $n as PublicTemplateInfo, Ar as SandboxFleetArtifact,
 import { l as ScopedToken, s as MintInteractiveSessionTokenOptions } from "./terminal-stream-B6bUr0hj.js";
 import { I as LinesClient } from "./lines-BTZTbYDz.js";
 import { f as SandboxError } from "./errors-DS32ViPj.js";
-import { AgentInteractiveSessionRef } from "@tangle-network/agent-interface";
+import { AgentInteractiveSessionRef, AgentProfile } from "@tangle-network/agent-interface";
 import { z } from "zod";
 
 //#region src/backend-registry.d.ts
@@ -537,6 +537,89 @@ declare class InstancesClient {
   private write;
 }
 //#endregion
+//#region src/runs.d.ts
+/** Where a run executes. */
+type RunPlacement = "auto" | "inference" | "worker" | "sandbox";
+interface RunOptions {
+  /** The agent: an inline AgentProfile, or a built-in or catalog profile id. */
+  profile: AgentProfile | string;
+  /** What to do in this run. */
+  prompt: string;
+  /** Default `auto`. */
+  placement?: RunPlacement;
+  /** A Router model id, when the profile names none. */
+  model?: string;
+  /** Hub providers the run may use, by name (`slack`, `github`, …). */
+  connections?: string[];
+  /** Owner-object prefixes and mode the run may use (worker only). */
+  objects?: {
+    prefixes: string[];
+    mode: "read" | "readwrite";
+  };
+  /** Public HTTPS hosts the run may GET (worker only). */
+  http?: {
+    hosts: string[];
+  };
+  /** The run's own wall-clock budget, a duration (`"5m"`) or milliseconds. */
+  timeout?: string | number;
+  /** Spend cap for the run, in USD. */
+  maxCostUsd?: number;
+}
+interface RunWaitOptions {
+  /** How long to wait for the run to settle. Default 10 minutes. */
+  timeoutMs?: number;
+  /** Poll interval. Default 1 second. */
+  pollIntervalMs?: number;
+  signal?: AbortSignal;
+}
+/** Where the run went and why, as Platform recorded it. */
+interface RunPlacementRecord {
+  chosen: Exclude<RunPlacement, "auto">;
+  policy: string;
+  reason: string;
+  rejected: Array<{
+    placement: Exclude<RunPlacement, "auto">;
+    reason: string;
+  }>;
+}
+interface RunRecord {
+  id: string;
+  /** `queued`, `running`, `waiting`, `succeeded`, `failed` or `cancelled`. */
+  status: string;
+  placement: RunPlacementRecord | null;
+  text: string | null;
+  model: string | null;
+  usage: {
+    inputTokens?: number;
+    outputTokens?: number;
+  } | null;
+  /** What the run cost. `null` when Platform has no measured cost. */
+  costUsd: number | null;
+  error: string | null;
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+interface RunsHttpClient {
+  platformFetch(path: string, options?: RequestInit): Promise<Response>;
+}
+/** `client.runs`: start a run, read it, wait for it. */
+declare class RunsClient {
+  private readonly http;
+  constructor(http: RunsHttpClient);
+  /** Start a run. Returns at once with its id; it executes on Platform. */
+  create(options: RunOptions): Promise<{
+    id: string;
+    status: string;
+  }>;
+  /** Read a run: its status, placement, answer, cost and error. */
+  get(id: string): Promise<RunRecord>;
+  /** Poll a run until it settles. */
+  wait(id: string, options?: RunWaitOptions): Promise<RunRecord>;
+  /** Start a run and wait for it to settle. */
+  run(options: RunOptions, wait?: RunWaitOptions): Promise<RunRecord>;
+}
+//#endregion
 //#region src/scoped-token.d.ts
 interface ScopedTokenHttpClient {
   fetch(path: string, options?: RequestInit, fetchOptions?: {
@@ -575,6 +658,7 @@ declare class Sandbox implements HttpClient, ScopedTokenHttpClient {
   private _instances;
   private _intelligence;
   private _lines;
+  private _runs;
   constructor(config: SandboxConfig);
   /**
    * Fleet operations for agent-managed groups of sandboxes.
@@ -596,6 +680,25 @@ declare class Sandbox implements HttpClient, ScopedTokenHttpClient {
    * sandbox with `sandbox.lines.attach()`.
    */
   get lines(): LinesClient;
+  /**
+   * Runs: run an AgentProfile on a prompt in the environment its needs
+   * require — one inference call, Tangle's sandbox-free agent loop, or a
+   * sandbox. `placement: "auto"` (the default) chooses and records why.
+   */
+  get runs(): RunsClient;
+  /**
+   * Run an AgentProfile on a prompt and wait for the result.
+   *
+   * @example
+   * ```ts
+   * const result = await client.run({
+   *   profile: { name: "support", prompt: { systemPrompt: "Answer billing questions." } },
+   *   prompt: "Which plan am I on?",
+   * });
+   * console.log(result.placement?.chosen, result.text, result.costUsd);
+   * ```
+   */
+  run(options: RunOptions, wait?: RunWaitOptions): Promise<RunRecord>;
   get intelligence(): IntelligenceClient;
   getApiKey(): string;
   /** A client with this one's settings that authenticates with `apiKey`. */
@@ -1138,4 +1241,4 @@ declare class TeamsClient {
   deleteTemplate(teamId: string, templateId: string): Promise<void>;
 }
 //#endregion
-export { isBackendRegistryInteractionKind as A, BackendRegistryEntry as C, backendRegistryEntrySchema as D, backendRegistryCapabilitiesSchema as E, parseBackendRegistryResponseBody as M, backendRegistryInteractionKindSchema as O, BackendRegistryCapabilities as S, BackendRegistryResponse as T, SandboxFleet as _, Team as a, ParsedSSEEvent as b, SessionBroadcastEvent as c, HostedInstance as d, InstanceProfile as f, InstancesClient as g, InstanceStart as h, Sandbox as i, parseBackendRegistryResponse as j, backendRegistryResponseSchema as k, SessionBroadcastResult as l, InstanceRestartingError as m, IntelligenceClient as n, TeamInvitation as o, InstanceRecord as p, InviteTeamMemberOptions as r, TeamMember as s, CreateTeamOptions as t, EnsureInstanceOptions as u, SandboxFleetClient as v, BackendRegistryInteractionKind as w, parseSSEStream as x, ParseSSEStreamOptions as y };
+export { BackendRegistryInteractionKind as A, SandboxFleet as C, parseSSEStream as D, ParsedSSEEvent as E, backendRegistryResponseSchema as F, isBackendRegistryInteractionKind as I, parseBackendRegistryResponse as L, backendRegistryCapabilitiesSchema as M, backendRegistryEntrySchema as N, BackendRegistryCapabilities as O, backendRegistryInteractionKindSchema as P, parseBackendRegistryResponseBody as R, InstancesClient as S, ParseSSEStreamOptions as T, HostedInstance as _, Team as a, InstanceRestartingError as b, SessionBroadcastEvent as c, RunPlacement as d, RunPlacementRecord as f, EnsureInstanceOptions as g, RunsClient as h, Sandbox as i, BackendRegistryResponse as j, BackendRegistryEntry as k, SessionBroadcastResult as l, RunWaitOptions as m, IntelligenceClient as n, TeamInvitation as o, RunRecord as p, InviteTeamMemberOptions as r, TeamMember as s, CreateTeamOptions as t, RunOptions as u, InstanceProfile as v, SandboxFleetClient as w, InstanceStart as x, InstanceRecord as y };

package/dist/{client-CT9Td-BV.js → client-BtsaKP2y.js}

@@ -3096,6 +3096,73 @@ async function read(response) {
 	return { instance: parsed.instance };
 }
 //#endregion
+//#region src/runs.ts
+const SETTLED = new Set([
+	"succeeded",
+	"failed",
+	"cancelled"
+]);
+async function platformData(response) {
+	const body = await response.text();
+	if (!response.ok) throw parseErrorResponse(response.status, body, void 0, response.headers);
+	const parsed = JSON.parse(body);
+	if (parsed.success !== true || parsed.data === void 0) throw parseErrorResponse(502, body, void 0, response.headers);
+	return parsed.data;
+}
+function abortableDelay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** `client.runs`: start a run, read it, wait for it. */
+var RunsClient = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/** Start a run. Returns at once with its id; it executes on Platform. */
+	async create(options) {
+		if (!options.prompt) throw new ValidationError("prompt is required", { prompt: "required" });
+		return platformData(await this.http.platformFetch("/v1/runs", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(options)
+		}));
+	}
+	/** Read a run: its status, placement, answer, cost and error. */
+	async get(id) {
+		return platformData(await this.http.platformFetch(`/v1/runs/${encodeURIComponent(id)}`));
+	}
+	/** Poll a run until it settles. */
+	async wait(id, options = {}) {
+		const timeoutMs = options.timeoutMs ?? 10 * 6e4;
+		const deadline = Date.now() + timeoutMs;
+		const interval = options.pollIntervalMs ?? 1e3;
+		for (;;) {
+			const record = await this.get(id);
+			if (SETTLED.has(record.status)) return record;
+			if (Date.now() + interval > deadline) throw new TimeoutError(timeoutMs, `run ${id} did not settle within ${timeoutMs}ms (last status ${record.status})`);
+			await abortableDelay(interval, options.signal);
+		}
+	}
+	/** Start a run and wait for it to settle. */
+	async run(options, wait = {}) {
+		const { id } = await this.create(options);
+		return this.wait(id, wait);
+	}
+};
+//#endregion
 //#region src/session-events.ts
 async function broadcastSessionEvent(client, sessionId, event) {
 	if (!sessionId.trim()) throw new ValidationError("Session ID is required");
@@ -3320,6 +3387,7 @@ var Sandbox = class Sandbox {
 	_instances = null;
 	_intelligence = null;
 	_lines = null;
+	_runs = null;
 	constructor(config) {
 		if (!config.apiKey) throw new AuthError("API key is required");
 		if (!config.baseUrl) throw new ValidationError("Base URL is required");
@@ -3359,6 +3427,30 @@ var Sandbox = class Sandbox {
 		if (!this._lines) this._lines = new LinesClient(this);
 		return this._lines;
 	}
+	/**
+	* Runs: run an AgentProfile on a prompt in the environment its needs
+	* require — one inference call, Tangle's sandbox-free agent loop, or a
+	* sandbox. `placement: "auto"` (the default) chooses and records why.
+	*/
+	get runs() {
+		if (!this._runs) this._runs = new RunsClient(this);
+		return this._runs;
+	}
+	/**
+	* Run an AgentProfile on a prompt and wait for the result.
+	*
+	* @example
+	* ```ts
+	* const result = await client.run({
+	*   profile: { name: "support", prompt: { systemPrompt: "Answer billing questions." } },
+	*   prompt: "Which plan am I on?",
+	* });
+	* console.log(result.placement?.chosen, result.text, result.costUsd);
+	* ```
+	*/
+	run(options, wait) {
+		return this.runs.run(options, wait);
+	}
 	get intelligence() {
 		if (!this._intelligence) this._intelligence = new IntelligenceClient(this);
 		return this._intelligence;
@@ -4527,4 +4619,4 @@ var TeamsClient = class {
 	}
 };
 //#endregion
-export { parseBackendRegistryResponseBody as _, InstancesClient as a, runtimeWorkspaceCwdSchema as c, backendRegistryCapabilitiesSchema as d, backendRegistryEntrySchema as f, parseBackendRegistryResponse as g, isBackendRegistryInteractionKind as h, InstanceRestartingError as i, createBatchResultAccumulator as l, backendRegistryResponseSchema as m, Sandbox as n, SandboxFleet as o, backendRegistryInteractionKindSchema as p, HostedInstance as r, SandboxFleetClient as s, IntelligenceClient as t, validateBatchRunRequest as u };
+export { parseBackendRegistryResponse as _, InstanceRestartingError as a, SandboxFleetClient as c, validateBatchRunRequest as d, backendRegistryCapabilitiesSchema as f, isBackendRegistryInteractionKind as g, backendRegistryResponseSchema as h, HostedInstance as i, runtimeWorkspaceCwdSchema as l, backendRegistryInteractionKindSchema as m, Sandbox as n, InstancesClient as o, backendRegistryEntrySchema as p, RunsClient as r, SandboxFleet as s, IntelligenceClient as t, createBatchResultAccumulator as u, parseBackendRegistryResponseBody as v };

package/dist/core.d.ts

@@ -1,7 +1,7 @@
 import { a as WorkspaceImagePublishRequestOptions, i as WorkspaceImagePublishInput, o as WorkspaceImagePublishResult, r as SandboxInstance, s as WorkspaceImages } from "./sandbox-DalvAflZ.js";
 import { An as NetworkConfig, B as CreateSandboxOptions, Ba as ManagedProcessState, Fa as ManagedProcessJobs, Fn as PreviewLinkInfo, Ha as SandboxEnvRecoveryView, Ia as ManagedProcessOptions, In as PreviewLinkManager, Kn as PromptInputPart, La as ManagedProcessRecord, Ln as PreviewLinkWaitOptions, M as ConversationTurnOptions, N as ConversationTurnResult, Pa as ManagedProcessClient, Ra as ManagedProcessResumeOptions, Va as SandboxEnvRecovery, Xi as SessionMessageAdmission, ci as SandboxInfo, vt as ExecOptions, xi as SandboxStatus, yr as SandboxConfig, yt as ExecResult, za as ManagedProcessSpec } from "./types-CdT-paBK.js";
 import { A as LineSenderVerification, B as profileChannelReference, C as LineReplyCodeInput, G as LineApplicationResult, H as LINE_APPLICATION_REQUEST_MAX_BYTES, I as LinesClient, J as parseLineApplicationRequest, K as LineApplicationState, O as LineSendInput, S as LineReplyCode, U as LineApplication, V as LINE_APPLICATION_REPLY_MAX_CHARS, W as LineApplicationRequest, Y as parseLineApplicationResult, a as LineApplicationAttachOptions, b as LineProvider, c as LineAttachmentReauthorization, d as LineInstanceAttachOptions, f as LineInstanceCreate, h as LineMemberInstance, j as LineSenderVerificationStart, k as LineSendReceipt, l as LineExecutionKey, m as LineMember, n as LineAgentRolePolicy, q as LineApplicationView, s as LineAttachment, t as Line, x as LineReminderPreferences, y as LineNumberInventory, z as lineInstanceKey } from "./lines-BTZTbYDz.js";
-import { A as isBackendRegistryInteractionKind, C as BackendRegistryEntry, D as backendRegistryEntrySchema, E as backendRegistryCapabilitiesSchema, M as parseBackendRegistryResponseBody, O as backendRegistryInteractionKindSchema, S as BackendRegistryCapabilities, T as BackendRegistryResponse, d as HostedInstance, f as InstanceProfile, g as InstancesClient, i as Sandbox, j as parseBackendRegistryResponse, k as backendRegistryResponseSchema, m as InstanceRestartingError, p as InstanceRecord, u as EnsureInstanceOptions, w as BackendRegistryInteractionKind } from "./client-CbOQtx9b.js";
+import { A as BackendRegistryInteractionKind, F as backendRegistryResponseSchema, I as isBackendRegistryInteractionKind, L as parseBackendRegistryResponse, M as backendRegistryCapabilitiesSchema, N as backendRegistryEntrySchema, O as BackendRegistryCapabilities, P as backendRegistryInteractionKindSchema, R as parseBackendRegistryResponseBody, S as InstancesClient, _ as HostedInstance, b as InstanceRestartingError, g as EnsureInstanceOptions, i as Sandbox, j as BackendRegistryResponse, k as BackendRegistryEntry, v as InstanceProfile, y as InstanceRecord } from "./client-6u7a1HMx.js";
 import { _ as TimeoutError, a as FileWriteConflictError, c as NotFoundError, f as SandboxError, g as StateError, h as ServerError, l as PartialFailureError, m as SandboxFailureDetail, n as CapabilityError, p as SandboxErrorJson, s as NetworkError, t as AuthError, u as QuotaError, v as ValidationError } from "./errors-DS32ViPj.js";
 
 //#region src/core.d.ts

package/dist/core.js

@@ -1,5 +1,5 @@
 import { a as FileWriteConflictError, c as NotFoundError, f as SandboxError, g as ValidationError, h as TimeoutError, l as PartialFailureError, m as StateError, n as CapabilityError, p as ServerError, s as NetworkError, t as AuthError, u as QuotaError } from "./errors-D1JIX7Jm.js";
-import { _ as parseBackendRegistryResponseBody, a as InstancesClient, d as backendRegistryCapabilitiesSchema, f as backendRegistryEntrySchema, g as parseBackendRegistryResponse, h as isBackendRegistryInteractionKind, i as InstanceRestartingError, m as backendRegistryResponseSchema, n as Sandbox, p as backendRegistryInteractionKindSchema, r as HostedInstance } from "./client-CT9Td-BV.js";
+import { _ as parseBackendRegistryResponse, a as InstanceRestartingError, f as backendRegistryCapabilitiesSchema, g as isBackendRegistryInteractionKind, h as backendRegistryResponseSchema, i as HostedInstance, m as backendRegistryInteractionKindSchema, n as Sandbox, o as InstancesClient, p as backendRegistryEntrySchema, v as parseBackendRegistryResponseBody } from "./client-BtsaKP2y.js";
 import { o as WorkspaceImages, t as SandboxInstance, x as ManagedProcessClient } from "./sandbox-D3VcDY8b.js";
 import { LinesClient, lineInstanceKey, profileChannelReference } from "./lines.js";
 import { i as parseLineApplicationResult, n as LINE_APPLICATION_REQUEST_MAX_BYTES, r as parseLineApplicationRequest, t as LINE_APPLICATION_REPLY_MAX_CHARS } from "./line-application-C2SuT1zK.js";