Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

refactor: update versioning logic in sandbox environment handling (#919)

Sujai Kumar Guptab28f29152470
diff --git a/.changeset/default-sandbox-env-controller.md b/.changeset/default-sandbox-env-controller.md
new file mode 100644
index 000000000..72a65d694
--- /dev/null
+++ b/.changeset/default-sandbox-env-controller.md
@@ -0,0 +1,6 @@
+---
+'@truefoundry/trueforge': minor
+'@truefoundry/trueforge-core': minor
+---
+
+Default sandbox environment on provider configure (with provider status-column drop), capabilities/resolve via default env status, and a controller loop that builds the latest pending environment version per env. Core: generic SandboxProvider/Sandbox, HarnessSandbox, and Daytona build/getBuildStatus on the provider.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 25106ebac..5c99aad3f 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -962,22 +962,10 @@
"properties": {
"manifest": {
"$ref": "#/components/schemas/SandboxProviderManifest"
- },
- "status": {
- "$ref": "#/components/schemas/SandboxBuildStatus"
- },
- "status_reason": {
- "description": "Human-readable detail for the current status; null when ready.",
- "type": [
- "string",
- "null"
- ]
}
},
"required": [
- "manifest",
- "status",
- "status_reason"
+ "manifest"
],
"type": "object"
},
@@ -2387,6 +2375,21 @@
],
"type": "object"
},
+ "ListPendingSandboxEnvironmentVersionsResponse": {
+ "additionalProperties": false,
+ "properties": {
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/PendingSandboxEnvironmentVersion"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"ListPermissionsData": {
"properties": {
"permissions": {
@@ -3479,6 +3482,20 @@
],
"type": "object"
},
+ "PendingSandboxEnvironmentVersion": {
+ "additionalProperties": false,
+ "properties": {
+ "environment_version_id": {
+ "description": "Version row id to progress.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "environment_version_id"
+ ],
+ "type": "object"
+ },
"PermissionResourceType": {
"description": "Resource type to evaluate permissions for.",
"enum": [
@@ -3511,6 +3528,20 @@
"default": "auto",
"description": "Defaults to 'auto' (chain to session last turn). Use 'none' for a new root turn."
},
+ "ProgressSandboxEnvironmentVersionRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "environment_version_id": {
+ "description": "Version row id to progress.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "environment_version_id"
+ ],
+ "type": "object"
+ },
"RawToolCall": {
"allOf": [
{
@@ -3787,15 +3818,6 @@
},
"type": "object"
},
- "SandboxBuildStatus": {
- "description": "Current build status.",
- "enum": [
- "pending",
- "ready",
- "failed"
- ],
- "type": "string"
- },
"SandboxCapability": {
"properties": {
"enabled": {
@@ -3993,6 +4015,38 @@
],
"type": "object"
},
+ "SandboxEnvironmentManifestRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "Optional human-readable description.",
+ "maxLength": 1024,
+ "type": "string"
+ },
+ "environment_variables": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "image": {
+ "$ref": "#/components/schemas/SandboxEnvironmentImage"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ "networking": {
+ "$ref": "#/components/schemas/SandboxEnvironmentNetworking"
+ },
+ "resources": {
+ "$ref": "#/components/schemas/SandboxEnvironmentResources"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
"SandboxEnvironmentNetworking": {
"additionalProperties": false,
"properties": {
@@ -4077,7 +4131,7 @@
"description": "Readiness of the environment.",
"enum": [
"pending",
- "active",
+ "ready",
"failed"
],
"type": "string"
@@ -6063,7 +6117,7 @@
"additionalProperties": false,
"properties": {
"manifest": {
- "$ref": "#/components/schemas/SandboxEnvironmentManifest"
+ "$ref": "#/components/schemas/SandboxEnvironmentManifestRequest"
}
},
"required": [
@@ -6938,6 +6992,93 @@
"x-fern-sdk-method-name": "get_meters"
}
},
+ "/api/internal/sandbox-environments/pending": {
+ "get": {
+ "description": "Returns pending environment versions for the build controller.",
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListPendingSandboxEnvironmentVersionsResponse"
+ }
+ }
+ },
+ "description": "Pending versions oldest-first."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid service credential."
+ }
+ },
+ "summary": "List pending sandbox environment versions",
+ "tags": [
+ "Internal"
+ ],
+ "x-excluded": true,
+ "x-fern-sdk-group-name": [
+ "internal",
+ "sandbox_environments"
+ ],
+ "x-fern-sdk-method-name": "list_pending"
+ }
+ },
+ "/api/internal/sandbox-environments/progress": {
+ "post": {
+ "description": "Registers or polls the snapshot build and updates version status.",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ProgressSandboxEnvironmentVersionRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "Progressed (or left pending)."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid service credential."
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Version not found."
+ }
+ },
+ "summary": "Progress a pending sandbox environment version",
+ "tags": [
+ "Internal"
+ ],
+ "x-excluded": true,
+ "x-fern-sdk-group-name": [
+ "internal",
+ "sandbox_environments"
+ ],
+ "x-fern-sdk-method-name": "progress"
+ }
+ },
"/api/internal/schedules/runs/execute": {
"post": {
"description": "Execute a persisted schedule run using its saved schedule and agent.",
@@ -8287,17 +8428,17 @@
},
"/api/v1/sandbox-environments": {
"get": {
- "description": "List sandbox environments created by the authenticated subject, newest first.",
+ "description": "List the tenant default environment plus sandbox environments created by the authenticated subject.",
"parameters": [
{
- "description": "Page size. Defaults to 25",
+ "description": "Page size. Defaults to 25, max 1000.",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 25,
- "description": "Page size. Defaults to 25",
- "maximum": 25,
+ "description": "Page size. Defaults to 25, max 1000.",
+ "maximum": 1000,
"minimum": 1,
"type": "integer"
}
@@ -8360,7 +8501,7 @@
"x-fern-sdk-method-name": "list"
},
"put": {
- "description": "Create or replace by `manifest.name`. Requires a Daytona sandbox provider.",
+ "description": "Create or replace by `manifest.name`. Requires a configured sandbox provider.",
"requestBody": {
"content": {
"application/json": {
@@ -8420,7 +8561,7 @@
}
}
},
- "description": "No Daytona sandbox provider configured."
+ "description": "No sandbox provider configured."
}
},
"summary": "Create or update a sandbox environment",
@@ -8506,7 +8647,7 @@
"x-fern-sdk-method-name": "delete"
},
"get": {
- "description": "Get a sandbox environment by name for the authenticated subject.",
+ "description": "Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.",
"parameters": [
{
"description": "Sandbox environment name.",
@@ -10922,7 +11063,7 @@
}
}
},
- "description": "Daytona rejected the provided API key."
+ "description": "Sandbox provider rejected the provided API key."
}
},
"summary": "Create or replace the sandbox provider",
diff --git a/docs/openapi.json b/docs/openapi.json
index 25106ebac..5c99aad3f 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -962,22 +962,10 @@
"properties": {
"manifest": {
"$ref": "#/components/schemas/SandboxProviderManifest"
- },
- "status": {
- "$ref": "#/components/schemas/SandboxBuildStatus"
- },
- "status_reason": {
- "description": "Human-readable detail for the current status; null when ready.",
- "type": [
- "string",
- "null"
- ]
}
},
"required": [
- "manifest",
- "status",
- "status_reason"
+ "manifest"
],
"type": "object"
},
@@ -2387,6 +2375,21 @@
],
"type": "object"
},
+ "ListPendingSandboxEnvironmentVersionsResponse": {
+ "additionalProperties": false,
+ "properties": {
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/PendingSandboxEnvironmentVersion"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"ListPermissionsData": {
"properties": {
"permissions": {
@@ -3479,6 +3482,20 @@
],
"type": "object"
},
+ "PendingSandboxEnvironmentVersion": {
+ "additionalProperties": false,
+ "properties": {
+ "environment_version_id": {
+ "description": "Version row id to progress.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "environment_version_id"
+ ],
+ "type": "object"
+ },
"PermissionResourceType": {
"description": "Resource type to evaluate permissions for.",
"enum": [
@@ -3511,6 +3528,20 @@
"default": "auto",
"description": "Defaults to 'auto' (chain to session last turn). Use 'none' for a new root turn."
},
+ "ProgressSandboxEnvironmentVersionRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "environment_version_id": {
+ "description": "Version row id to progress.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "environment_version_id"
+ ],
+ "type": "object"
+ },
"RawToolCall": {
"allOf": [
{
@@ -3787,15 +3818,6 @@
},
"type": "object"
},
- "SandboxBuildStatus": {
- "description": "Current build status.",
- "enum": [
- "pending",
- "ready",
- "failed"
- ],
- "type": "string"
- },
"SandboxCapability": {
"properties": {
"enabled": {
@@ -3993,6 +4015,38 @@
],
"type": "object"
},
+ "SandboxEnvironmentManifestRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "Optional human-readable description.",
+ "maxLength": 1024,
+ "type": "string"
+ },
+ "environment_variables": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "image": {
+ "$ref": "#/components/schemas/SandboxEnvironmentImage"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ },
+ "networking": {
+ "$ref": "#/components/schemas/SandboxEnvironmentNetworking"
+ },
+ "resources": {
+ "$ref": "#/components/schemas/SandboxEnvironmentResources"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
"SandboxEnvironmentNetworking": {
"additionalProperties": false,
"properties": {
@@ -4077,7 +4131,7 @@
"description": "Readiness of the environment.",
"enum": [
"pending",
- "active",
+ "ready",
"failed"
],
"type": "string"
@@ -6063,7 +6117,7 @@
"additionalProperties": false,
"properties": {
"manifest": {
- "$ref": "#/components/schemas/SandboxEnvironmentManifest"
+ "$ref": "#/components/schemas/SandboxEnvironmentManifestRequest"
}
},
"required": [
@@ -6938,6 +6992,93 @@
"x-fern-sdk-method-name": "get_meters"
}
},
+ "/api/internal/sandbox-environments/pending": {
+ "get": {
+ "description": "Returns pending environment versions for the build controller.",
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListPendingSandboxEnvironmentVersionsResponse"
+ }
+ }
+ },
+ "description": "Pending versions oldest-first."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid service credential."
+ }
+ },
+ "summary": "List pending sandbox environment versions",
+ "tags": [
+ "Internal"
+ ],
+ "x-excluded": true,
+ "x-fern-sdk-group-name": [
+ "internal",
+ "sandbox_environments"
+ ],
+ "x-fern-sdk-method-name": "list_pending"
+ }
+ },
+ "/api/internal/sandbox-environments/progress": {
+ "post": {
+ "description": "Registers or polls the snapshot build and updates version status.",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ProgressSandboxEnvironmentVersionRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "Progressed (or left pending)."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid service credential."
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Version not found."
+ }
+ },
+ "summary": "Progress a pending sandbox environment version",
+ "tags": [
+ "Internal"
+ ],
+ "x-excluded": true,
+ "x-fern-sdk-group-name": [
+ "internal",
+ "sandbox_environments"
+ ],
+ "x-fern-sdk-method-name": "progress"
+ }
+ },
"/api/internal/schedules/runs/execute": {
"post": {
"description": "Execute a persisted schedule run using its saved schedule and agent.",
@@ -8287,17 +8428,17 @@
},
"/api/v1/sandbox-environments": {
"get": {
- "description": "List sandbox environments created by the authenticated subject, newest first.",
+ "description": "List the tenant default environment plus sandbox environments created by the authenticated subject.",
"parameters": [
{
- "description": "Page size. Defaults to 25",
+ "description": "Page size. Defaults to 25, max 1000.",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 25,
- "description": "Page size. Defaults to 25",
- "maximum": 25,
+ "description": "Page size. Defaults to 25, max 1000.",
+ "maximum": 1000,
"minimum": 1,
"type": "integer"
}
@@ -8360,7 +8501,7 @@
"x-fern-sdk-method-name": "list"
},
"put": {
- "description": "Create or replace by `manifest.name`. Requires a Daytona sandbox provider.",
+ "description": "Create or replace by `manifest.name`. Requires a configured sandbox provider.",
"requestBody": {
"content": {
"application/json": {
@@ -8420,7 +8561,7 @@
}
}
},
- "description": "No Daytona sandbox provider configured."
+ "description": "No sandbox provider configured."
}
},
"summary": "Create or update a sandbox environment",
@@ -8506,7 +8647,7 @@
"x-fern-sdk-method-name": "delete"
},
"get": {
- "description": "Get a sandbox environment by name for the authenticated subject.",
+ "description": "Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.",
"parameters": [
{
"description": "Sandbox environment name.",
@@ -10922,7 +11063,7 @@
}
}
},
- "description": "Daytona rejected the provided API key."
+ "description": "Sandbox provider rejected the provided API key."
}
},
"summary": "Create or replace the sandbox provider",
diff --git a/packages/assistant-ui-runtime/src/index.ts b/packages/assistant-ui-runtime/src/index.ts
index 0d15a0d31..669506f2b 100644
--- a/packages/assistant-ui-runtime/src/index.ts
+++ b/packages/assistant-ui-runtime/src/index.ts
@@ -171,8 +171,6 @@ export type {
SandboxCreatedEvent,
SandboxProviderBase,
SandboxProviderCatalogEntry,
- SandboxProviderListEntry,
- SandboxSnapshotSyncStatus,
SaveAgentRequest,
SaveAgentResult,
Schedule,
diff --git a/packages/assistant-ui-runtime/src/server/index.ts b/packages/assistant-ui-runtime/src/server/index.ts
index bf30d5ce9..6bc307338 100644
--- a/packages/assistant-ui-runtime/src/server/index.ts
+++ b/packages/assistant-ui-runtime/src/server/index.ts
@@ -94,8 +94,6 @@ export type {
SandboxCatalogServer,
SandboxProviderBase,
SandboxProviderCatalogEntry,
- SandboxProviderListEntry,
- SandboxSnapshotSyncStatus,
SaveAgentRequest,
SaveAgentResult,
Schedule,
diff --git a/packages/assistant-ui-runtime/src/server/types.ts b/packages/assistant-ui-runtime/src/server/types.ts
index 8777565be..83f6ed405 100644
--- a/packages/assistant-ui-runtime/src/server/types.ts
+++ b/packages/assistant-ui-runtime/src/server/types.ts
@@ -749,16 +749,6 @@ export interface SandboxBase {
isConnected: boolean;
}
-export interface SandboxSnapshotSyncStatus {
- status: 'pending' | 'ready' | 'failed';
- statusReason?: string | null;
-}
-
-export interface SandboxProviderListEntry<TSandbox extends SandboxBase = SandboxBase> {
- data: TSandbox;
- snapshotSyncStatus: SandboxSnapshotSyncStatus;
-}
-
export interface CreateSandboxRequest {
/** `SandboxCatalogEntry.id` used to create this sandbox provider. */
catalogId: string;
@@ -784,10 +774,9 @@ export interface SandboxCatalogServer<
TCatalogEntry extends SandboxCatalogEntry = SandboxCatalogEntry,
TCreate extends CreateSandboxRequest = CreateSandboxRequest,
TUpdate extends UpdateSandboxRequest = UpdateSandboxRequest,
- TListEntry extends SandboxProviderListEntry<TProvider> = SandboxProviderListEntry<TProvider>,
> {
getSandboxProviderCatalog(): Promise<TCatalogEntry[]>;
- listSandboxProviders(req?: { query?: string }): Promise<TListEntry[]>;
+ listSandboxProviders(req?: { query?: string }): Promise<TProvider[]>;
createSandboxProvider(req: TCreate): Promise<TProvider>;
updateSandboxProvider(req: TUpdate): Promise<TProvider>;
deleteSandboxProvider?(req: { id: string }): Promise<void>;
diff --git a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts
index 791ab963e..fd633908a 100644
--- a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts
+++ b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts
@@ -2,7 +2,7 @@ import type { Logger } from 'winston';
import type { AgentCapability } from '../core/capabilities/AgentCapability';
import type { AgentDefinition } from '../core/runtime/AgentDefinition';
import type { AgentInfo } from '../core/runtime/AgentThread.types';
-import type { Sandbox, SandboxInfo } from '../core/sandbox/Sandbox';
+import type { HarnessSandbox, SandboxInfo } from '../core/sandbox/Sandbox';
import type { AgentTracing } from '../core/tracing/AgentTracing';
import type { IWebSearchProvider } from '../core/web-search/WebSearchProvider';
import type { TurnRecord } from './models/TurnRecord';
@@ -45,7 +45,7 @@ export interface ITurnResourceResolver<TTurnCustom extends object = Record<strin
previousTurn?: TurnRecord<TTurnCustom> | undefined;
signal: AbortSignal;
tracing: AgentTracing;
- }): Promise<Sandbox | undefined>;
+ }): Promise<HarnessSandbox | undefined>;
/**
* Called once per thread (rebuild or live sub-agent spawn); calls for different
* threads may overlap, so implementations must be concurrency-safe.
diff --git a/packages/trueforge-core/src/agent-session/SessionHandle.ts b/packages/trueforge-core/src/agent-session/SessionHandle.ts
index ecaa2aeaa..e29e6f388 100644
--- a/packages/trueforge-core/src/agent-session/SessionHandle.ts
+++ b/packages/trueforge-core/src/agent-session/SessionHandle.ts
@@ -16,7 +16,7 @@ import {
isInputUserMessage,
} from '../core/runtime/contextUtils';
import type { CreateDynamicSubAgentThread } from '../core/runtime/CreateDynamicSubAgentThread';
-import type { Sandbox } from '../core/sandbox/Sandbox';
+import type { HarnessSandbox } from '../core/sandbox/Sandbox';
import type { AgentTracing } from '../core/tracing/AgentTracing';
import { builtinsFromSpec } from './builtinsFromSpec';
import type { ITurnResourceResolver, ResolvedAgentDefinition } from './ITurnResourceResolver';
@@ -424,7 +424,7 @@ export class SessionHandle<
previous: TurnRecord<TTurnCustom> | undefined;
resolver: ITurnResourceResolver<TTurnCustom>;
spec: AgentSpec;
- sandbox: Sandbox | undefined;
+ sandbox: HarnessSandbox | undefined;
tracing: AgentTracing;
definitionsByThreadId: ReadonlyMap<string, ResolvedAgentDefinition>;
}): Map<string, AgentThread> {
@@ -456,7 +456,7 @@ export class SessionHandle<
previousThreadSnapshot?: AgentThreadSnapshot | undefined;
resolver: ITurnResourceResolver<TTurnCustom>;
spec: AgentSpec;
- sandbox: Sandbox | undefined;
+ sandbox: HarnessSandbox | undefined;
tracing: AgentTracing;
resolvedDefinition: ResolvedAgentDefinition;
}): AgentThread {
@@ -495,7 +495,7 @@ export class SessionHandle<
resolver: ITurnResourceResolver<TTurnCustom>;
previous: TurnRecord<TTurnCustom> | undefined;
spec: AgentSpec;
- sandbox: Sandbox | undefined;
+ sandbox: HarnessSandbox | undefined;
tracing: AgentTracing;
}): CreateDynamicSubAgentThread {
return async params => {
diff --git a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
index 2f34b5d36..32c40606c 100644
--- a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
+++ b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
@@ -6,7 +6,7 @@ import type { ToolSelectorConfig } from '../core/mcp/ToolSelectorPolicy';
import { ToolSet } from '../core/mcp/ToolSet';
import type { AgentDefinition, ModelParams } from '../core/runtime/AgentDefinition';
import type { AgentInfo } from '../core/runtime/AgentThread.types';
-import type { Sandbox, SandboxInfo } from '../core/sandbox/Sandbox';
+import type { HarnessSandbox, SandboxInfo } from '../core/sandbox/Sandbox';
import type { AgentTracing } from '../core/tracing/AgentTracing';
import { NOOP_AGENT_TRACING } from '../core/tracing/NoopAgentTracing';
import type { IWebSearchProvider } from '../core/web-search/WebSearchProvider';
@@ -25,7 +25,7 @@ export type TurnSandboxFactory = (input: {
existingSandboxId?: string | undefined;
signal: AbortSignal;
tracing: AgentTracing;
-}) => Promise<Sandbox>;
+}) => Promise<HarnessSandbox>;
function specWantsSandbox(spec: AgentSpec): boolean {
return spec.config.sandbox.enabled;
@@ -61,7 +61,7 @@ export class TurnResourceResolver<
> implements ITurnResourceResolver<TTurnCustom> {
readonly #sources = new Map<string, Promise<ToolSource>>();
readonly #models = new Map<string, Promise<ResolvedModel>>();
- #sandbox?: Sandbox | undefined;
+ #sandbox?: HarnessSandbox | undefined;
constructor(
protected readonly deps: {
@@ -128,7 +128,7 @@ export class TurnResourceResolver<
previousTurn?: TurnRecord<TTurnCustom> | undefined;
signal: AbortSignal;
tracing: AgentTracing;
- }): Promise<Sandbox | undefined> {
+ }): Promise<HarnessSandbox | undefined> {
if (!this.deps.sandboxProvider || !specWantsSandbox(input.spec)) {
return undefined;
}
diff --git a/packages/trueforge-core/src/core/capabilities/AgentContextProcessor.ts b/packages/trueforge-core/src/core/capabilities/AgentContextProcessor.ts
index 24b37bf01..6aabe0043 100644
--- a/packages/trueforge-core/src/core/capabilities/AgentContextProcessor.ts
+++ b/packages/trueforge-core/src/core/capabilities/AgentContextProcessor.ts
@@ -7,12 +7,12 @@ import type {
InternalPassthroughEvent,
} from '../runtime/AgentThread.types';
import type { CurrentContextUsage } from '../runtime/contextUsage';
-import type { Sandbox } from '../sandbox/Sandbox';
+import type { HarnessSandbox } from '../sandbox/Sandbox';
/** Ambient thread snapshot passed Readonly to every capability processor hook. */
export interface AgentThreadExecutionContext {
threadId: string;
- sandbox?: Sandbox | undefined;
+ sandbox?: HarnessSandbox | undefined;
currentContextUsage: CurrentContextUsage;
context: ContextMessage[];
}
diff --git a/packages/trueforge-core/src/core/capabilities/builtins/LargeToolResponse.ts b/packages/trueforge-core/src/core/capabilities/builtins/LargeToolResponse.ts
index 1b51ad2b1..bdfcc88ea 100644
--- a/packages/trueforge-core/src/core/capabilities/builtins/LargeToolResponse.ts
+++ b/packages/trueforge-core/src/core/capabilities/builtins/LargeToolResponse.ts
@@ -2,7 +2,7 @@ import dedent from 'dedent';
import type { Logger } from 'winston';
import { estimateTokensForString } from '../../llm/usage';
import type { ToolCallResult } from '../../mcp/executeToolCalls';
-import type { Sandbox, SandboxInfo } from '../../sandbox/Sandbox';
+import type { HarnessSandbox, SandboxInfo } from '../../sandbox/Sandbox';
import { createSandboxLargeToolResponseGuidance, SANDBOX_SCHEMA_INFER_TAG } from '../../sandbox/Sandbox';
import { extractErrorLogFields } from '../../util/errorLogFields';
import type { AgentCapability } from '../AgentCapability';
@@ -24,7 +24,7 @@ interface ToolResultWithInfo {
category: ResultCategory;
}
-function categorize(result: ToolCallResult, sandbox: Sandbox | undefined): ResultCategory {
+function categorize(result: ToolCallResult, sandbox: HarnessSandbox | undefined): ResultCategory {
if (result.failure) {
return 'failure';
}
@@ -70,7 +70,7 @@ export class LargeToolResponseProcessor implements ToolResponseProcessor {
this.logger = param.logger.child({ module: 'LargeToolResponse' });
}
- private createLargeToolResponseGuidance(sandbox: Sandbox | undefined): string {
+ private createLargeToolResponseGuidance(sandbox: HarnessSandbox | undefined): string {
const steps = ['Check if some parameter can be passed in order to reduce the output size.'];
if (sandbox) {
@@ -106,7 +106,7 @@ export class LargeToolResponseProcessor implements ToolResponseProcessor {
return `Content too large. Result saved to: ${filePath}.\n\n${guidance}\n\nPreview (first and last ${String(this.previewNumberOfCharacters)} chars):\n${preview}`;
}
- private buildResultsWithInfo(results: ToolCallResult[], sandbox: Sandbox | undefined): ToolResultWithInfo[] {
+ private buildResultsWithInfo(results: ToolCallResult[], sandbox: HarnessSandbox | undefined): ToolResultWithInfo[] {
return results.map(toolCallResult => ({
toolCallResult,
originalContent: toolCallResult.message.content,
@@ -118,7 +118,7 @@ export class LargeToolResponseProcessor implements ToolResponseProcessor {
private blockResult(
entry: ToolResultWithInfo,
pendingSandboxDumps: ToolResultWithInfo[],
- sandbox: Sandbox | undefined,
+ sandbox: HarnessSandbox | undefined,
): number {
const preview = createContentPreview(entry.originalContent, this.previewNumberOfCharacters);
@@ -146,7 +146,7 @@ export class LargeToolResponseProcessor implements ToolResponseProcessor {
private async uploadToSandboxAndPrependFilePath(
entry: ToolResultWithInfo,
index: number,
- sandbox: Sandbox,
+ sandbox: HarnessSandbox,
): Promise<SandboxInfo | undefined> {
if (!entry.toolCallResult.info) {
throw new Error(`Unreachable`);
@@ -170,7 +170,10 @@ export class LargeToolResponseProcessor implements ToolResponseProcessor {
}
}
- private async executeSandboxDumps(entries: ToolResultWithInfo[], sandbox: Sandbox): Promise<SandboxInfo | undefined> {
+ private async executeSandboxDumps(
+ entries: ToolResultWithInfo[],
+ sandbox: HarnessSandbox,
+ ): Promise<SandboxInfo | undefined> {
const results = await Promise.all(
entries.map((entry, index) => this.uploadToSandboxAndPrependFilePath(entry, index, sandbox)),
);
diff --git a/packages/trueforge-core/src/core/index.ts b/packages/trueforge-core/src/core/index.ts
index cee913050..725aafd77 100644
--- a/packages/trueforge-core/src/core/index.ts
+++ b/packages/trueforge-core/src/core/index.ts
@@ -167,7 +167,15 @@ export type { CodeModeClientInstall, CodeModeTransport } from './sandbox/codeMod
export { CodeModeErrorSourceSchema, CodeModeReplySchema, CodeModeRequestSchema } from './sandbox/codeMode/types';
export type { CodeModeErrorSource, CodeModeReply, CodeModeRequest } from './sandbox/codeMode/types';
export { DaytonaSandboxProvider } from './sandbox/provider/DaytonaProvider';
-export type { DaytonaSandboxProviderOptions, SandboxEnvironment } from './sandbox/provider/DaytonaProvider';
+export type { DaytonaSandboxProviderOptions } from './sandbox/provider/DaytonaProvider';
+export {
+ DAYTONA_SNAPSHOT_NOT_STARTED_REASON,
+ createDaytonaSandboxEnvironment,
+} from './sandbox/provider/DaytonaSandboxEnvironment';
+export type {
+ DaytonaSandboxEnvironment,
+ DaytonaSandboxEnvironmentOptions,
+} from './sandbox/provider/DaytonaSandboxEnvironment';
export { absolutizeRelativeExecEnv } from './sandbox/provider/execEnv';
export { ensureExecSuccess, shellEscape } from './sandbox/provider/Provider';
export type {
@@ -183,7 +191,7 @@ export type {
} from './sandbox/provider/Provider';
export { TFYSandboxProvider } from './sandbox/provider/TFYSandboxProvider';
export { SKILL_DOWNLOAD_TIMEOUT_SECONDS, Sandbox, buildWriteAndRunScriptCommand } from './sandbox/Sandbox';
-export type { SandboxInfo } from './sandbox/Sandbox';
+export type { HarnessSandbox, SandboxInfo } from './sandbox/Sandbox';
export {
SandboxError,
SandboxFileNotFoundError,
diff --git a/packages/trueforge-core/src/core/runtime/AgentThread.ts b/packages/trueforge-core/src/core/runtime/AgentThread.ts
index 8f586f4fd..f01cf0f51 100644
--- a/packages/trueforge-core/src/core/runtime/AgentThread.ts
+++ b/packages/trueforge-core/src/core/runtime/AgentThread.ts
@@ -52,7 +52,7 @@ import { estimateTokensForString } from '../llm/usage';
import { convertMCPServersToTools, type ConvertToolsResult, type MappedMCPTool } from '../mcp/convertMCPServers';
import { executeToolCalls } from '../mcp/executeToolCalls';
import type { IToolSet, MCPAuthRequired } from '../mcp/IMCPServer';
-import type { Sandbox, SandboxInfo } from '../sandbox/Sandbox';
+import type { HarnessSandbox, SandboxInfo } from '../sandbox/Sandbox';
import type { AgentTracing } from '../tracing/AgentTracing';
import { describeUnknownError, extractErrorLogFields } from '../util/errorLogFields';
import type { AgentDefinition } from './AgentDefinition';
@@ -513,7 +513,7 @@ export class AgentThread {
private deferredTool?: DeferredTool | undefined;
private convertedTools: ConvertToolsResult | undefined;
private pendingSandboxCreatedEvents: SandboxCreatedEvent[] = [];
- private sandbox?: Sandbox | undefined;
+ private sandbox?: HarnessSandbox | undefined;
private readonly tracing: AgentTracing;
private readonly logger: Logger;
diff --git a/packages/trueforge-core/src/core/runtime/AgentThread.types.ts b/packages/trueforge-core/src/core/runtime/AgentThread.types.ts
index 5a5cf79f1..e0b7b12e8 100644
--- a/packages/trueforge-core/src/core/runtime/AgentThread.types.ts
+++ b/packages/trueforge-core/src/core/runtime/AgentThread.types.ts
@@ -26,7 +26,7 @@ import type {
UserToolResponseMessage,
} from '../events/schema';
import type { InternalEnrichedAssistantMessage, LLMToolMessage, LLMUserMessage } from '../llm/LLMTypes';
-import type { Sandbox } from '../sandbox/Sandbox';
+import type { HarnessSandbox } from '../sandbox/Sandbox';
import type { AgentTracing } from '../tracing/AgentTracing';
import type { AgentDefinition } from './AgentDefinition';
import type { CurrentContextUsage } from './contextUsage';
@@ -167,7 +167,7 @@ export interface AgentThreadConstructorInput {
context?: ContextMessage[] | undefined;
currentContextUsage?: CurrentContextUsage | undefined;
preComputedCompletion?: SubAgentCompletionMarker | undefined;
- sandbox?: Sandbox | undefined;
+ sandbox?: HarnessSandbox | undefined;
capabilities?: readonly AgentCapability[] | undefined;
/**
* Previous turn's capability_state for hydration. Optional — omit on first
diff --git a/packages/trueforge-core/src/core/runtime/UserInputMessage.ts b/packages/trueforge-core/src/core/runtime/UserInputMessage.ts
index 64c3a28db..31a37a351 100644
--- a/packages/trueforge-core/src/core/runtime/UserInputMessage.ts
+++ b/packages/trueforge-core/src/core/runtime/UserInputMessage.ts
@@ -8,7 +8,7 @@ import {
type UserContentPart,
} from '../events/schema';
import type { LLMUserMessage } from '../llm/LLMTypes';
-import type { Sandbox, SandboxInfo } from '../sandbox/Sandbox';
+import type { HarnessSandbox, SandboxInfo } from '../sandbox/Sandbox';
import type { AgentSendInput } from './AgentThread.types';
import { internalSystemTag } from './contextUtils';
@@ -113,7 +113,7 @@ export interface ProcessAgentUserInputResult {
export async function processAgentUserInput(
msg: AgentInputUserMessage,
- sandbox: Sandbox | undefined,
+ sandbox: HarnessSandbox | undefined,
): Promise<ProcessAgentUserInputResult> {
if (typeof msg.content === 'string') {
return { message: { role: 'user', content: msg.content }, sandboxCreated: undefined };
diff --git a/packages/trueforge-core/src/core/sandbox/Sandbox.ts b/packages/trueforge-core/src/core/sandbox/Sandbox.ts
index 47eac9169..9162eb1c6 100644
--- a/packages/trueforge-core/src/core/sandbox/Sandbox.ts
+++ b/packages/trueforge-core/src/core/sandbox/Sandbox.ts
@@ -84,8 +84,13 @@ export interface SandboxStoredFile {
sandboxCreated?: SandboxInfo | undefined;
}
-export interface SandboxOptions {
- provider: SandboxProvider;
+export interface SandboxOptions<TEnvironment = undefined> {
+ provider: SandboxProvider<TEnvironment>;
+ /**
+ * Optional create-time environment (snapshot + create params). Ignored when restoring
+ * an existing sandbox id.
+ */
+ environment?: TEnvironment | undefined;
existingSandboxId?: string | undefined;
skillMounter?: ISkillMounter | undefined;
fileDownloadEnabled?: boolean | undefined;
@@ -191,12 +196,20 @@ export function createSandboxLargeToolResponseGuidance(): string {
export const SANDBOX_MCP_SERVER_ID = 'sandbox';
type SandboxExecInput = z.infer<typeof sandboxExecSchema>;
-export class Sandbox extends LocalToolMCP {
+/**
+ * Environment-erased sandbox for the harness (Daytona tip / TFY / local share one handle type).
+ * `any` is intentional here only — callers must not spread it as a general escape hatch.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- harness erase across providers
+export type HarnessSandbox = Sandbox<any>;
+
+export class Sandbox<TEnvironment = undefined> extends LocalToolMCP {
readonly name = SANDBOX_MCP_SERVER_ID;
readonly displayName = 'Sandbox';
override readonly description = 'Persistent sandbox environment for code execution';
- private readonly provider: SandboxProvider;
+ private readonly provider: SandboxProvider<TEnvironment>;
+ private readonly environment: TEnvironment | undefined;
private readonly existingSandboxId?: string | undefined;
private existingSandboxInfo: SandboxInfo | undefined;
// Cached promise to prevent concurrent sub-agents from creating duplicate sandboxes.
@@ -224,9 +237,10 @@ export class Sandbox extends LocalToolMCP {
}),
];
- constructor(options: SandboxOptions) {
+ constructor(options: SandboxOptions<TEnvironment>) {
super({ tracing: options.tracing });
this.provider = options.provider;
+ this.environment = options.environment;
this.existingSandboxId = options.existingSandboxId;
this.skillMounter = options.skillMounter;
this.fileDownloadEnabled = options.fileDownloadEnabled ?? false;
@@ -461,7 +475,7 @@ export class Sandbox extends LocalToolMCP {
}
// Provider returns a raw id; persist the fancy `v1:type:raw` session id.
this.sandboxCreationPromise ??= this.provider
- .createSandbox()
+ .createSandbox(this.environment)
.then(({ sandboxId }) => ({
sandbox_id: formatSandboxId({ providerType: this.provider.type, rawId: sandboxId }),
}))
diff --git a/packages/trueforge-core/src/core/sandbox/provider/DaytonaProvider.ts b/packages/trueforge-core/src/core/sandbox/provider/DaytonaProvider.ts
index 638cbeeb1..1a5818a69 100644
--- a/packages/trueforge-core/src/core/sandbox/provider/DaytonaProvider.ts
+++ b/packages/trueforge-core/src/core/sandbox/provider/DaytonaProvider.ts
@@ -6,6 +6,7 @@ import { randomUUID } from 'node:crypto';
import { join } from 'node:path/posix';
import type { Logger } from 'winston';
import { extractErrorLogFields } from '../../util/errorLogFields';
+import { withTimeout } from '../../util/promiseUtils';
import {
SandboxFileNotFoundError,
SandboxFileTooLargeError,
@@ -16,19 +17,18 @@ import {
import type { CodeModeTransport } from '../codeMode/CodeModeTransport';
import { CodeModeNatsTransport } from '../codeMode/nats/CodeModeNatsTransport';
import { DEFAULT_PREVIEW_URL_EXPIRY_SECONDS, DEFAULT_SANDBOX_NATS_WS_PORT } from '../constants';
+import { DAYTONA_SNAPSHOT_NOT_STARTED_REASON, type DaytonaSandboxEnvironment } from './DaytonaSandboxEnvironment';
import type { ExecResult, SandboxBuild, SandboxExecParams, SandboxFileInfo, SandboxProvider } from './Provider';
const SANDBOX_NOT_FOUND_STATUS = 404;
+const SANDBOX_STATE_STARTED = 'started';
/** Another replica already registered this build name; its create is the one that counts. */
const SNAPSHOT_CONFLICT_STATUS = 409;
-const SANDBOX_STATE_STARTED = 'started';
const BUILD_STATE_ACTIVE = 'active';
-const BUILD_STATE_INACTIVE = 'inactive';
const BUILD_STATE_ERROR = 'error';
const BUILD_STATE_BUILD_FAILED = 'build_failed';
-const IMAGE_BUILD_NAME_PREFIX = 'trueforge-build-';
/** Same default the Daytona SDK applies when `DaytonaConfig.apiUrl` is omitted. */
const DEFAULT_DAYTONA_API_URL = 'https://app.daytona.io/api';
@@ -36,29 +36,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null;
}
-/**
- * Digest portion of a container image reference (the tag/digest after the final `:`)
- * The release image is always published with an explicit digest tag
- */
-function imageDigest(image: string): string {
- const lastSegment = image.slice(image.lastIndexOf('/') + 1);
- const colon = lastSegment.lastIndexOf(':');
- if (colon === -1) {
- throw new Error(`Sandbox image reference has no tag/digest: ${image}`);
- }
- return lastSegment.slice(colon + 1);
-}
-
-/** Deterministic build name per image digest so every server replica converges on one build. */
-function deriveImageBuildName(digest: string): string {
- return `${IMAGE_BUILD_NAME_PREFIX}${digest}`;
-}
-
-/** Terminal-failure build states: a build stuck here never becomes ready on its own. */
-function isFailedBuildState(state: Snapshot['state']): boolean {
- return state === BUILD_STATE_ERROR || state === BUILD_STATE_BUILD_FAILED;
-}
-
/** Convert Daytona https preview URLs to wss for the NATS client. */
function httpUrlToWsUrl(url: string): string {
const parsed = new URL(url);
@@ -70,39 +47,6 @@ function httpUrlToWsUrl(url: string): string {
return parsed.toString();
}
-/**
- * Daytona-only environment (subset of the host sandbox-environment manifest).
- * Fresh create applies env vars + networking only; other fields are accepted unused for now.
- * Daytona networking modes are mutually exclusive (`network_block_all` vs `domain_allow_list`).
- */
-export interface SandboxEnvironment {
- image?:
- | {
- type: 'build';
- build_script?: string | undefined;
- }
- | undefined;
- resources: {
- cpu: number;
- memory: number;
- disk: number;
- };
- environment_variables?: Record<string, string> | undefined;
- networking?:
- | {
- network_block_all?: boolean | undefined;
- domain_allow_list?: string | undefined;
- secrets?:
- | {
- env: string;
- value: string;
- hosts: string[];
- }[]
- | undefined;
- }
- | undefined;
-}
-
export interface DaytonaSandboxProviderOptions {
/** Caller-owned Daytona SDK client (credentials / lifetime). */
client: Daytona;
@@ -114,14 +58,6 @@ export interface DaytonaSandboxProviderOptions {
/** Daytona API base URL (including `/api`). Defaults to the SDK's public cloud endpoint. */
apiUrl?: string | undefined;
tenantName: string;
- /** Release-owned sandbox image reference; built into a Daytona snapshot and cloned per sandbox. */
- sandboxImage: string;
- /**
- * Daytona snapshot name to clone sandboxes from. When omitted it is derived from the image
- * digest. Callers that create sandboxes pass the persisted build_ref so cloning targets the
- * snapshot that was actually built, not a speculative name derived from the current image.
- */
- buildRef?: string | undefined;
timeoutMs: number;
autoStopIntervalInMinutes: number;
autoArchiveIntervalInMinutes: number;
@@ -131,18 +67,13 @@ export interface DaytonaSandboxProviderOptions {
natsBridgePort?: number;
/** Defaults to 1 hour (same as the gateway's max agent execution time). */
previewUrlExpirySeconds?: number;
- /** Optional sandbox environment; applied only on fresh create (not restore). */
- environment?: SandboxEnvironment;
logger: Logger;
}
-export class DaytonaSandboxProvider implements SandboxProvider {
+export class DaytonaSandboxProvider implements SandboxProvider<DaytonaSandboxEnvironment> {
readonly type = 'daytona';
+ readonly envSupported = true;
private readonly tenantName: string;
- /** Release-owned sandbox image reference; built into a Daytona snapshot and cloned per sandbox. */
- private readonly imageUri: string;
- /** Daytona snapshot name sandboxes are cloned from; the persisted build_ref, or derived from the image digest. */
- private readonly buildRef: string;
private readonly timeoutMs: number;
private readonly autoStopIntervalInMinutes: number;
private readonly autoArchiveIntervalInMinutes: number;
@@ -152,7 +83,6 @@ export class DaytonaSandboxProvider implements SandboxProvider {
private readonly previewUrlExpirySeconds: number;
private readonly apiKey: string;
private readonly apiUrl: string;
- private readonly environment: DaytonaSandboxProviderOptions['environment'];
private readonly logger: Logger;
private readonly daytona: Daytona;
private static readonly cachedSandboxes = new Map<string, { sandbox: Sandbox; defaultTimeoutMs: number }>();
@@ -164,8 +94,6 @@ export class DaytonaSandboxProvider implements SandboxProvider {
this.apiKey = options.apiKey;
this.apiUrl = options.apiUrl ?? DEFAULT_DAYTONA_API_URL;
this.tenantName = options.tenantName;
- this.imageUri = options.sandboxImage;
- this.buildRef = options.buildRef ?? deriveImageBuildName(imageDigest(options.sandboxImage));
this.timeoutMs = options.timeoutMs;
this.autoStopIntervalInMinutes = options.autoStopIntervalInMinutes;
this.autoArchiveIntervalInMinutes = options.autoArchiveIntervalInMinutes;
@@ -173,11 +101,196 @@ export class DaytonaSandboxProvider implements SandboxProvider {
this.fileMaxBytesForDownload = options.fileMaxBytesForDownload;
this.natsBridgePort = options.natsBridgePort ?? DEFAULT_SANDBOX_NATS_WS_PORT;
this.previewUrlExpirySeconds = options.previewUrlExpirySeconds ?? DEFAULT_PREVIEW_URL_EXPIRY_SECONDS;
- this.environment = options.environment;
this.logger = options.logger.child({ module: 'DaytonaProvider' });
}
- private async getOrCreateSandbox(sandboxId?: string): Promise<{ sandbox: Sandbox; defaultTimeoutMs: number }> {
+ /** Require a Daytona environment for fresh creates. */
+ private requireEnvironment(environment?: DaytonaSandboxEnvironment): DaytonaSandboxEnvironment {
+ if (environment === undefined) {
+ throw new Error('Daytona sandbox create requires a DaytonaSandboxEnvironment');
+ }
+ return environment;
+ }
+
+ /** Lightweight authz probe (list one snapshot page) — no snapshot build. */
+ async validateAccess(): Promise<void> {
+ await withTimeout(this.daytona.snapshot.list({ page: 1, limit: 1 }), 3_000, 'sandbox credentials check');
+ }
+
+ private runtimeCreateParams(environment: DaytonaSandboxEnvironment): {
+ envVars?: Record<string, string>;
+ networkBlockAll?: boolean;
+ domainAllowList?: string;
+ } {
+ const networking = environment.networking;
+ return {
+ ...(environment.environment_variables ? { envVars: environment.environment_variables } : {}),
+ ...(networking?.network_block_all ? { networkBlockAll: networking.network_block_all } : {}),
+ ...(networking?.domain_allow_list ? { domainAllowList: networking.domain_allow_list } : {}),
+ };
+ }
+
+ private toBuild({
+ environment,
+ state,
+ errorReason,
+ }: {
+ environment: DaytonaSandboxEnvironment;
+ state: string;
+ errorReason: string | null;
+ }): SandboxBuild {
+ const metadata = { build_ref: environment.snapshot_ref, image_uri: environment.image_uri };
+ switch (state) {
+ case BUILD_STATE_ACTIVE:
+ return { status: 'ready', reason: null, metadata };
+ case BUILD_STATE_ERROR:
+ case BUILD_STATE_BUILD_FAILED:
+ return { status: 'failed', reason: errorReason ?? `Sandbox image build failed (${state}).`, metadata };
+ default:
+ return { status: 'pending', reason: `Sandbox image build in progress (${state}).`, metadata };
+ }
+ }
+
+ /** Resolves undefined when no snapshot carries that name; auth/other failures throw. */
+ private async getSnapshot(snapshotRef: string): Promise<Snapshot | undefined> {
+ try {
+ return await this.daytona.snapshot.get(snapshotRef);
+ } catch (error) {
+ if (error instanceof DaytonaError && error.statusCode === SANDBOX_NOT_FOUND_STATUS) {
+ return undefined;
+ }
+ throw error;
+ }
+ }
+
+ /**
+ * Dockerfile that layers `build_script` onto the release base image.
+ * JSON-array RUN keeps the script bytes intact (newlines, quotes) without shell-escaping hell.
+ */
+ private dockerfileFromBuildScript({ imageUri, buildScript }: { imageUri: string; buildScript: string }): string {
+ return `FROM ${imageUri}\nRUN ["bash", "-lc", ${JSON.stringify(buildScript)}]`;
+ }
+
+ /** Body for POST /snapshots — imageName XOR buildInfo (Daytona mutual exclusion). */
+ private createSnapshotBody(environment: DaytonaSandboxEnvironment): {
+ name: string;
+ cpu: number;
+ memory: number;
+ disk: number;
+ imageName?: string;
+ buildInfo?: { dockerfileContent: string };
+ } {
+ const body: {
+ name: string;
+ cpu: number;
+ memory: number;
+ disk: number;
+ imageName?: string;
+ buildInfo?: { dockerfileContent: string };
+ } = {
+ name: environment.snapshot_ref,
+ cpu: environment.resources.cpu,
+ memory: environment.resources.memory,
+ disk: environment.resources.disk,
+ };
+ const buildScript = environment.image?.type === 'build' ? environment.image.build_script : undefined;
+ if (buildScript !== undefined && buildScript.length > 0) {
+ body.buildInfo = {
+ dockerfileContent: this.dockerfileFromBuildScript({
+ imageUri: environment.image_uri,
+ buildScript,
+ }),
+ };
+ } else {
+ body.imageName = environment.image_uri;
+ }
+ return body;
+ }
+
+ /**
+ * Registers the snapshot and returns its initial state without waiting for the build.
+ *
+ * The SDK's `snapshot.create` issues this same POST and then polls until the snapshot is active
+ * or failed (minutes on a cold image pull). Progress only needs the registration result, so
+ * credential errors surface on the request while build progress stays observable via get.
+ */
+ private async registerSnapshot(
+ environment: DaytonaSandboxEnvironment,
+ ): Promise<{ state: string; errorReason: string | null }> {
+ let response: Response;
+ try {
+ response = await fetch(`${this.apiUrl}/snapshots`, {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${this.apiKey}`,
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify(this.createSnapshotBody(environment)),
+ });
+ } catch (error) {
+ throw new Error('Daytona snapshot registration request failed.', { cause: error });
+ }
+
+ const body: unknown = await response.json().catch(() => null);
+ if (!response.ok) {
+ const message =
+ isRecord(body) && typeof body['message'] === 'string'
+ ? body['message']
+ : `Daytona snapshot registration failed (${String(response.status)})`;
+ throw new DaytonaError(message, response.status);
+ }
+ if (!isRecord(body) || typeof body['state'] !== 'string') {
+ throw new DaytonaError("Failed to register snapshot. Daytona didn't return a snapshot state.");
+ }
+ return {
+ state: body['state'],
+ errorReason: typeof body['errorReason'] === 'string' ? body['errorReason'] : null,
+ };
+ }
+
+ /**
+ * Registers this environment's snapshot. Does not wait for the build to finish.
+ * Callers that are polling should use getBuildStatus; only call build when not started.
+ */
+ async build(environment: DaytonaSandboxEnvironment): Promise<SandboxBuild> {
+ try {
+ const registered = await this.registerSnapshot(environment);
+ return this.toBuild({
+ environment,
+ state: registered.state,
+ errorReason: registered.errorReason,
+ });
+ } catch (error) {
+ // A losing concurrent create is not a build failure: read whatever the winner registered.
+ if (error instanceof DaytonaError && error.statusCode === SNAPSHOT_CONFLICT_STATUS) {
+ this.logger.info(`Daytona snapshot already created concurrently: name=${environment.snapshot_ref}`);
+ return this.getBuildStatus(environment);
+ }
+ throw error;
+ }
+ }
+
+ /** Current build status for this environment. Read-only: never kicks off a build. */
+ async getBuildStatus(environment: DaytonaSandboxEnvironment): Promise<SandboxBuild> {
+ const snapshot = await this.getSnapshot(environment.snapshot_ref);
+ if (!snapshot) {
+ return {
+ status: 'pending',
+ reason: DAYTONA_SNAPSHOT_NOT_STARTED_REASON,
+ metadata: { build_ref: environment.snapshot_ref, image_uri: environment.image_uri },
+ };
+ }
+ return this.toBuild({
+ environment,
+ state: snapshot.state,
+ errorReason: snapshot.errorReason,
+ });
+ }
+
+ private async getOrCreateSandbox(
+ sandboxId?: string,
+ environment?: DaytonaSandboxEnvironment,
+ ): Promise<{ sandbox: Sandbox; defaultTimeoutMs: number }> {
if (sandboxId) {
validateSandboxOwnedByTenant({ sandboxId, tenantName: this.tenantName });
const cached = DaytonaSandboxProvider.cachedSandboxes.get(sandboxId);
@@ -188,25 +301,22 @@ export class DaytonaSandboxProvider implements SandboxProvider {
const sandbox = sandboxId
? await this.restoreExistingSandbox(sandboxId)
- : await this.daytona.create(this.buildCreateParams());
+ : await this.daytona.create(this.buildCreateParams(environment));
const entry = { sandbox, defaultTimeoutMs: this.timeoutMs };
DaytonaSandboxProvider.cachedSandboxes.set(sandbox.name, entry);
return entry;
}
- private buildCreateParams(): CreateSandboxFromSnapshotParams {
- const environment = this.environment;
- const networking = environment?.networking;
+ private buildCreateParams(environment?: DaytonaSandboxEnvironment): CreateSandboxFromSnapshotParams {
+ const env = this.requireEnvironment(environment);
return {
name: `${this.tenantName}.${randomUUID()}`,
- snapshot: this.buildRef,
+ snapshot: env.snapshot_ref,
autoStopInterval: this.autoStopIntervalInMinutes,
autoArchiveInterval: this.autoArchiveIntervalInMinutes,
autoDeleteInterval: this.autoDeleteIntervalInMinutes,
- ...(environment?.environment_variables ? { envVars: environment.environment_variables } : {}),
- ...(networking?.network_block_all ? { networkBlockAll: networking.network_block_all } : {}),
- ...(networking?.domain_allow_list ? { domainAllowList: networking.domain_allow_list } : {}),
+ ...this.runtimeCreateParams(env),
};
}
@@ -291,143 +401,14 @@ export class DaytonaSandboxProvider implements SandboxProvider {
}
}
- async createSandbox(): Promise<{ sandboxId: string }> {
+ async createSandbox(environment?: DaytonaSandboxEnvironment): Promise<{ sandboxId: string }> {
return context.with(suppressTracing(context.active()), async () => {
- const { sandbox } = await this.getOrCreateSandbox();
+ const { sandbox } = await this.getOrCreateSandbox(undefined, environment);
this.logger.debug(`Sandbox created: name=${sandbox.name}`);
return { sandboxId: sandbox.name };
});
}
- /** Resolves undefined when no snapshot carries that name; auth/other failures throw. */
- private async getSnapshot(name: string): Promise<Snapshot | undefined> {
- try {
- return await this.daytona.snapshot.get(name);
- } catch (error) {
- if (error instanceof DaytonaError && error.statusCode === SANDBOX_NOT_FOUND_STATUS) {
- return undefined;
- }
- throw error;
- }
- }
-
- /**
- * Drops a build stuck in a terminal-failure state so a fresh create can reuse its
- * deterministic name. A concurrent replica may have deleted it already (404) — that
- * is fine and treated as success.
- */
- private async deleteFailedBuild(snapshot: Snapshot): Promise<void> {
- try {
- await this.daytona.snapshot.delete(snapshot);
- } catch (error) {
- if (error instanceof DaytonaError && error.statusCode === SANDBOX_NOT_FOUND_STATUS) {
- return;
- }
- throw error;
- }
- }
-
- private toBuild(state: string, errorReason: string | null): SandboxBuild {
- const metadata = { build_ref: this.buildRef, image_uri: this.imageUri };
- switch (state) {
- case BUILD_STATE_ACTIVE:
- return { status: 'ready', reason: null, metadata };
- case BUILD_STATE_ERROR:
- case BUILD_STATE_BUILD_FAILED:
- return { status: 'failed', reason: errorReason ?? `Sandbox image build failed (${state}).`, metadata };
- default:
- // pending / building / pulling / removing / future states: not ready yet.
- return { status: 'pending', reason: `Sandbox image build in progress (${state}).`, metadata };
- }
- }
-
- /**
- * Registers the snapshot and returns its initial state without waiting for the build.
- *
- * The SDK's `snapshot.create` issues this same POST and then polls until the snapshot is active
- * or failed (minutes on a cold image pull). Configure only needs the registration result, so
- * credential errors surface on the request while build progress stays observable via `getSnapshot`.
- */
- private async registerSnapshot(): Promise<{ state: string; errorReason: string | null }> {
- let response: Response;
- try {
- response = await fetch(`${this.apiUrl}/snapshots`, {
- method: 'POST',
- headers: {
- Authorization: `Bearer ${this.apiKey}`,
- 'Content-Type': 'application/json',
- },
- body: JSON.stringify({ name: this.buildRef, imageName: this.imageUri }),
- });
- } catch (error) {
- throw new Error('Daytona snapshot registration request failed.', { cause: error });
- }
-
- const body: unknown = await response.json().catch(() => null);
- if (!response.ok) {
- const message =
- isRecord(body) && typeof body['message'] === 'string'
- ? body['message']
- : `Daytona snapshot registration failed (${String(response.status)})`;
- throw new DaytonaError(message, response.status);
- }
- if (!isRecord(body) || typeof body['state'] !== 'string') {
- throw new DaytonaError("Failed to register snapshot. Daytona didn't return a snapshot state.");
- }
- return {
- state: body['state'],
- errorReason: typeof body['errorReason'] === 'string' ? body['errorReason'] : null,
- };
- }
-
- async buildImage(): Promise<SandboxBuild> {
- const existing = await this.getSnapshot(this.buildRef);
- if (existing) {
- // Daytona parks unused snapshots as 'inactive' after ~2 idle weeks; reactivate rather than rebuild.
- if (existing.state === BUILD_STATE_INACTIVE) {
- const activated = await this.daytona.snapshot.activate(existing);
- return this.toBuild(activated.state, activated.errorReason);
- }
- if (!isFailedBuildState(existing.state)) {
- return this.toBuild(existing.state, existing.errorReason);
- }
- // A failed build keeps the deterministic name occupied and never self-heals, so
- // re-saving settings (which calls buildImage) could never retry. Drop it, then recreate.
- await this.deleteFailedBuild(existing);
- }
-
- try {
- const registered = await this.registerSnapshot();
- // Registration returns pending almost always; map whatever Daytona sent so a fast
- // active/error still surfaces correctly without a follow-up GET.
- return this.toBuild(registered.state, registered.errorReason);
- } catch (error) {
- // A losing concurrent create is not a build failure: the winner owns the deterministic name.
- if (error instanceof DaytonaError && error.statusCode === SNAPSHOT_CONFLICT_STATUS) {
- this.logger.info(`Daytona snapshot already created concurrently: name=${this.buildRef}`);
- return {
- status: 'pending',
- reason: 'Sandbox image build started by another server replica.',
- metadata: { build_ref: this.buildRef, image_uri: this.imageUri },
- };
- }
- throw error;
- }
- }
-
- async getImageBuildStatus(): Promise<SandboxBuild> {
- const snapshot = await this.getSnapshot(this.buildRef);
- // Read-only: a missing build reports pending; PUT /settings/sandbox-providers starts the build.
- if (!snapshot) {
- return {
- status: 'pending',
- reason: 'Sandbox image build not started.',
- metadata: { build_ref: this.buildRef, image_uri: this.imageUri },
- };
- }
- return this.toBuild(snapshot.state, snapshot.errorReason);
- }
-
async exec(params: SandboxExecParams): Promise<ExecResult> {
return context.with(suppressTracing(context.active()), async (): Promise<ExecResult> => {
try {
diff --git a/packages/trueforge-core/src/core/sandbox/provider/DaytonaSandboxEnvironment.ts b/packages/trueforge-core/src/core/sandbox/provider/DaytonaSandboxEnvironment.ts
new file mode 100644
index 000000000..e8d6ff080
--- /dev/null
+++ b/packages/trueforge-core/src/core/sandbox/provider/DaytonaSandboxEnvironment.ts
@@ -0,0 +1,64 @@
+import { SANDBOX_IMAGE_URI } from '../sandboxImage';
+
+/** getBuildStatus reason when this environment has never been registered with Daytona. */
+export const DAYTONA_SNAPSHOT_NOT_STARTED_REASON = 'Sandbox image build not started.';
+
+export interface DaytonaSandboxEnvironmentOptions {
+ /** Daytona snapshot name to build or clone from (persisted env-version external_ref). */
+ snapshot_ref: string;
+ /**
+ * Base container image the snapshot is built from. Defaults to the release sandbox image.
+ */
+ image_uri?: string | undefined;
+ resources: {
+ cpu: number;
+ memory: number;
+ disk: number;
+ };
+ image?:
+ | {
+ type: 'build';
+ build_script?: string | undefined;
+ }
+ | undefined;
+ environment_variables?: Record<string, string> | undefined;
+ /**
+ * Daytona networking modes are mutually exclusive
+ * (`network_block_all` vs `domain_allow_list`).
+ */
+ networking?:
+ | {
+ network_block_all?: boolean | undefined;
+ domain_allow_list?: string | undefined;
+ secrets?:
+ | {
+ env: string;
+ value: string;
+ hosts: string[];
+ }[]
+ | undefined;
+ }
+ | undefined;
+}
+
+/** Plain Daytona create/build input (snapshot tip + create params). */
+export interface DaytonaSandboxEnvironment {
+ snapshot_ref: string;
+ image_uri: string;
+ resources: DaytonaSandboxEnvironmentOptions['resources'];
+ image?: DaytonaSandboxEnvironmentOptions['image'];
+ environment_variables?: DaytonaSandboxEnvironmentOptions['environment_variables'];
+ networking?: DaytonaSandboxEnvironmentOptions['networking'];
+}
+
+/** Apply defaults (e.g. release image) onto Daytona env options. */
+export function createDaytonaSandboxEnvironment(options: DaytonaSandboxEnvironmentOptions): DaytonaSandboxEnvironment {
+ return {
+ snapshot_ref: options.snapshot_ref,
+ image_uri: options.image_uri ?? SANDBOX_IMAGE_URI,
+ resources: options.resources,
+ ...(options.image !== undefined ? { image: options.image } : {}),
+ ...(options.environment_variables !== undefined ? { environment_variables: options.environment_variables } : {}),
+ ...(options.networking !== undefined ? { networking: options.networking } : {}),
+ };
+}
diff --git a/packages/trueforge-core/src/core/sandbox/provider/Provider.ts b/packages/trueforge-core/src/core/sandbox/provider/Provider.ts
index 0a46e5477..c0c54119c 100644
--- a/packages/trueforge-core/src/core/sandbox/provider/Provider.ts
+++ b/packages/trueforge-core/src/core/sandbox/provider/Provider.ts
@@ -80,18 +80,27 @@ export interface SandboxBuild {
metadata: SandboxBuildMetadata | null;
}
-export interface SandboxProvider {
+/**
+ * Sandbox backend. `TEnvironment` is provider-specific create/build input
+ * (`DaytonaSandboxEnvironment` for Daytona; `undefined` when the provider has none).
+ */
+export interface SandboxProvider<TEnvironment = undefined> {
/** Stable provider kind used in fancy sandbox ids and carry-forward (plain string). */
readonly type: string;
/**
- * Ensures the release image is being built into the provider's backing store and
- * returns its current status. Idempotent: an already-built image reports `ready`;
- * a fresh build starts in the background and reports `pending`.
+ * Whether this provider uses sandbox environments (snapshot tip / build).
+ * When false, env resolve and env-store builds are skipped.
+ */
+ readonly envSupported: boolean;
+ /**
+ * Optional credential/access probe. Providers that need none may omit or resolve immediately.
*/
- buildImage(): Promise<SandboxBuild>;
- /** Current build status of the release image. Read-only: never kicks off a build. */
- getImageBuildStatus(): Promise<SandboxBuild>;
- createSandbox(): Promise<{ sandboxId: string }>;
+ validateAccess?(): Promise<void>;
+ /** Fresh sandbox; optional environment pins snapshot + create params. */
+ createSandbox(environment?: TEnvironment): Promise<{ sandboxId: string }>;
+ /** Env snapshot/image build. Only providers that have environments implement these. */
+ build?(environment: TEnvironment): Promise<SandboxBuild>;
+ getBuildStatus?(environment: TEnvironment): Promise<SandboxBuild>;
exec(params: SandboxExecParams): Promise<ExecResult>;
/** Provider-specific instructions appended to the agent system prompt. */
getAdditionalInstructions(): string | undefined;
diff --git a/packages/trueforge-core/src/core/sandbox/provider/TFYSandboxProvider.ts b/packages/trueforge-core/src/core/sandbox/provider/TFYSandboxProvider.ts
index 8a1b09eeb..8fe228e1e 100644
--- a/packages/trueforge-core/src/core/sandbox/provider/TFYSandboxProvider.ts
+++ b/packages/trueforge-core/src/core/sandbox/provider/TFYSandboxProvider.ts
@@ -18,7 +18,6 @@ import { absolutizeRelativeExecEnv } from './execEnv';
import {
shellEscape,
type ExecResult,
- type SandboxBuild,
type SandboxExecParams,
type SandboxFileInfo,
type SandboxProvider,
@@ -64,6 +63,7 @@ interface StatResult {
export class TFYSandboxProvider implements SandboxProvider {
readonly type = 'truefoundry';
+ readonly envSupported = false;
private readonly serverUrl: string;
private readonly natsBridgeUrl: string;
private readonly tenantName: string;
@@ -82,19 +82,8 @@ export class TFYSandboxProvider implements SandboxProvider {
this.logger = options.logger.child({ module: 'TFYSandboxProvider' });
}
- // TFY sandboxes run a prebuilt server image with no per-image build step, so the image is always ready.
- private static readonly readyBuild: SandboxBuild = {
- status: 'ready',
- reason: null,
- metadata: null,
- };
-
- buildImage(): Promise<SandboxBuild> {
- return Promise.resolve(TFYSandboxProvider.readyBuild);
- }
-
- getImageBuildStatus(): Promise<SandboxBuild> {
- return Promise.resolve(TFYSandboxProvider.readyBuild);
+ validateAccess(): Promise<void> {
+ return Promise.resolve();
}
createSandbox(): Promise<{ sandboxId: string }> {
diff --git a/packages/trueforge-core/tests/core/harnessMocks.ts b/packages/trueforge-core/tests/core/harnessMocks.ts
index 89b81944c..81f6a869c 100644
--- a/packages/trueforge-core/tests/core/harnessMocks.ts
+++ b/packages/trueforge-core/tests/core/harnessMocks.ts
@@ -60,8 +60,7 @@ export function makeMockIMCPServer(params: {
export function makeStubPublicSandbox(): Sandbox {
const provider: SandboxProvider = {
type: 'test',
- buildImage: jest.fn(),
- getImageBuildStatus: jest.fn(),
+ envSupported: false,
createSandbox: jest.fn(),
exec: jest.fn(),
getAdditionalInstructions: () => undefined,
diff --git a/packages/trueforge-core/tests/core/sandbox/Sandbox.ids.test.ts b/packages/trueforge-core/tests/core/sandbox/Sandbox.ids.test.ts
index c9273ce30..417ff6e95 100644
--- a/packages/trueforge-core/tests/core/sandbox/Sandbox.ids.test.ts
+++ b/packages/trueforge-core/tests/core/sandbox/Sandbox.ids.test.ts
@@ -14,8 +14,7 @@ function makeProvider(
): SandboxProvider {
return {
type: 'local',
- buildImage: () => Promise.resolve({ status: 'ready', reason: null, metadata: null }),
- getImageBuildStatus: () => Promise.resolve({ status: 'ready', reason: null, metadata: null }),
+ envSupported: false,
getAdditionalInstructions: () => undefined,
getToolResultDumpDir: sandboxId => `${sandboxId}/tool-results`,
getGitCredentialsPath: sandboxId => `${sandboxId}/.git-credentials`,
diff --git a/packages/trueforge-core/tests/core/sandbox/Sandbox.paths.test.ts b/packages/trueforge-core/tests/core/sandbox/Sandbox.paths.test.ts
index 1449edd3c..874b34df9 100644
--- a/packages/trueforge-core/tests/core/sandbox/Sandbox.paths.test.ts
+++ b/packages/trueforge-core/tests/core/sandbox/Sandbox.paths.test.ts
@@ -13,8 +13,7 @@ function readyExec(): Promise<ExecResult> {
function makeProvider(overrides: Partial<SandboxProvider> = {}): SandboxProvider {
return {
type: 'test',
- buildImage: () => Promise.resolve({ status: 'ready', reason: null, metadata: null }),
- getImageBuildStatus: () => Promise.resolve({ status: 'ready', reason: null, metadata: null }),
+ envSupported: false,
createSandbox: () => Promise.resolve({ sandboxId: 'raw-1' }),
exec: () => readyExec(),
getAdditionalInstructions: () => undefined,
diff --git a/packages/trueforge-core/tests/core/sandbox/daytonaSnapshotRegistration.test.ts b/packages/trueforge-core/tests/core/sandbox/daytonaSnapshotRegistration.test.ts
index 2c94b868d..c7aa7f073 100644
--- a/packages/trueforge-core/tests/core/sandbox/daytonaSnapshotRegistration.test.ts
+++ b/packages/trueforge-core/tests/core/sandbox/daytonaSnapshotRegistration.test.ts
@@ -1,5 +1,6 @@
import { Daytona, DaytonaError } from '@daytona/sdk';
import { DaytonaSandboxProvider } from '../../../src/core/sandbox/provider/DaytonaProvider';
+import { createDaytonaSandboxEnvironment } from '../../../src/core/sandbox/provider/DaytonaSandboxEnvironment';
import { SandboxNotAvailableError } from '../../../src/core/sandbox/SandboxErrors';
import { makeSilentLogger } from '../harnessMocks';
@@ -8,9 +9,15 @@ const CONFLICT_STATUS = 409;
const FORBIDDEN_STATUS = 403;
const API_URL = 'https://daytona.test/api';
+const DEFAULT_TEST_ENVIRONMENT = createDaytonaSandboxEnvironment({
+ snapshot_ref: 'trueforge-build-029ea5ff',
+ image_uri: 'registry.example.com/sandbox:029ea5ff',
+ resources: { cpu: 1, memory: 1, disk: 3 },
+});
+
/**
- * Builds a provider whose snapshot lookup reports "not built yet" so `buildImage` always reaches
- * the register-only POST.
+ * Builds a provider whose snapshot lookup reports "not built yet" so provider.build
+ * always reaches the register-only POST.
*/
function makeProvider(): DaytonaSandboxProvider {
// useDeprecatedPolling keeps the constructor from opening the event-stream WebSocket.
@@ -22,7 +29,6 @@ function makeProvider(): DaytonaSandboxProvider {
apiKey: 'dtn-test',
apiUrl: API_URL,
tenantName: 'test-tenant',
- sandboxImage: 'registry.example.com/sandbox:029ea5ff',
timeoutMs: 1000,
autoStopIntervalInMinutes: 5,
autoArchiveIntervalInMinutes: 60,
@@ -49,7 +55,7 @@ describe('DaytonaSandboxProvider register-only snapshot create', () => {
body: { id: 'snap-1', name: 'trueforge-build-029ea5ff', state: 'pending', errorReason: null },
});
- const build = await makeProvider().buildImage();
+ const build = await makeProvider().build(DEFAULT_TEST_ENVIRONMENT);
expect(build.status).toBe('pending');
expect(fetchMock).toHaveBeenCalledTimes(1);
@@ -59,13 +65,42 @@ describe('DaytonaSandboxProvider register-only snapshot create', () => {
expect(JSON.parse(String(init?.body))).toEqual({
name: 'trueforge-build-029ea5ff',
imageName: 'registry.example.com/sandbox:029ea5ff',
+ cpu: 1,
+ memory: 1,
+ disk: 3,
+ });
+ });
+
+ it('sends build_script as Dockerfile buildInfo layered on the base image', async () => {
+ const fetchMock = mockFetch({
+ status: 200,
+ body: { id: 'snap-2', name: 'env-with-script', state: 'pending', errorReason: null },
+ });
+ const buildScript = 'set -ex\npip install httpx\n';
+ const environment = createDaytonaSandboxEnvironment({
+ snapshot_ref: 'env-with-script',
+ image_uri: 'registry.example.com/sandbox:029ea5ff',
+ resources: { cpu: 2, memory: 4, disk: 10 },
+ image: { type: 'build', build_script: buildScript },
+ });
+
+ await makeProvider().build(environment);
+
+ expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+ name: 'env-with-script',
+ cpu: 2,
+ memory: 4,
+ disk: 10,
+ buildInfo: {
+ dockerfileContent: `FROM registry.example.com/sandbox:029ea5ff\nRUN ["bash", "-lc", ${JSON.stringify(buildScript)}]`,
+ },
});
});
it('treats a concurrent-create conflict as pending, not a thrown failure', async () => {
mockFetch({ status: CONFLICT_STATUS, body: { statusCode: CONFLICT_STATUS, message: 'Conflict' } });
- const build = await makeProvider().buildImage();
+ const build = await makeProvider().build(DEFAULT_TEST_ENVIRONMENT);
expect(build.status).toBe('pending');
});
@@ -73,7 +108,7 @@ describe('DaytonaSandboxProvider register-only snapshot create', () => {
it('throws on Access denied so PUT can map it to 422', async () => {
mockFetch({ status: FORBIDDEN_STATUS, body: { statusCode: FORBIDDEN_STATUS, message: 'Access denied' } });
- await expect(makeProvider().buildImage()).rejects.toMatchObject({
+ await expect(makeProvider().build(DEFAULT_TEST_ENVIRONMENT)).rejects.toMatchObject({
message: 'Access denied',
statusCode: FORBIDDEN_STATUS,
});
@@ -89,7 +124,6 @@ describe('DaytonaSandboxProvider exec', () => {
apiKey: 'dtn-test',
apiUrl: API_URL,
tenantName: 'test-tenant',
- sandboxImage: 'registry.example.com/sandbox:029ea5ff',
timeoutMs: 1000,
autoStopIntervalInMinutes: 5,
autoArchiveIntervalInMinutes: 60,
diff --git a/packages/trueforge-core/tests/core/sandbox/sandboxBridgeTimeout.test.ts b/packages/trueforge-core/tests/core/sandbox/sandboxBridgeTimeout.test.ts
index 1418e6b46..aee71db01 100644
--- a/packages/trueforge-core/tests/core/sandbox/sandboxBridgeTimeout.test.ts
+++ b/packages/trueforge-core/tests/core/sandbox/sandboxBridgeTimeout.test.ts
@@ -18,8 +18,7 @@ function makeSandbox(options: {
const transport = options.transport;
const provider: SandboxProvider = {
type: 'test',
- buildImage: () => Promise.resolve({ status: 'ready', reason: null, metadata: null }),
- getImageBuildStatus: () => Promise.resolve({ status: 'ready', reason: null, metadata: null }),
+ envSupported: false,
createSandbox: () => Promise.resolve({ sandboxId: 'test-tenant.sandbox-1' }),
exec: (params): Promise<ExecResult> => {
execCalls.push(params);
diff --git a/packages/trueforge-sdk/package.json b/packages/trueforge-sdk/package.json
index 21cc2d885..5b75d6f84 100644
--- a/packages/trueforge-sdk/package.json
+++ b/packages/trueforge-sdk/package.json
@@ -220,6 +220,17 @@
},
"default": "./dist/cjs/api/resources/internal/resources/metrics/exports.js"
},
+ "./internal/sandboxEnvironments": {
+ "import": {
+ "types": "./dist/esm/api/resources/internal/resources/sandboxEnvironments/exports.d.mts",
+ "default": "./dist/esm/api/resources/internal/resources/sandboxEnvironments/exports.mjs"
+ },
+ "require": {
+ "types": "./dist/cjs/api/resources/internal/resources/sandboxEnvironments/exports.d.ts",
+ "default": "./dist/cjs/api/resources/internal/resources/sandboxEnvironments/exports.js"
+ },
+ "default": "./dist/cjs/api/resources/internal/resources/sandboxEnvironments/exports.js"
+ },
"./internal/schedules": {
"import": {
"types": "./dist/esm/api/resources/internal/resources/schedules/exports.d.mts",
diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.md
index 2c4cad6ed..915278f14 100644
--- a/packages/trueforge-sdk/reference.md
+++ b/packages/trueforge-sdk/reference.md
@@ -913,7 +913,7 @@ await client.models.list();
<dl>
<dd>
-List sandbox environments created by the authenticated subject, newest first.
+List the tenant default environment plus sandbox environments created by the authenticated subject.
</dd>
</dl>
</dd>
@@ -988,7 +988,7 @@ const response = page.response;
<dl>
<dd>
-Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+Create or replace by `manifest.name`. Requires a configured sandbox provider.
</dd>
</dl>
</dd>
@@ -1055,7 +1055,7 @@ await client.sandboxEnvironments.createOrUpdate({
<dl>
<dd>
-Get a sandbox environment by name for the authenticated subject.
+Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.
</dd>
</dl>
</dd>
@@ -3392,6 +3392,127 @@ await client.internal.metrics.getMeters({
</dl>
+</dd>
+</dl>
+</details>
+
+## Internal SandboxEnvironments
+<details><summary><code>client.internal.sandboxEnvironments.<a href="/src/api/resources/internal/resources/sandboxEnvironments/client/Client.ts">listPending</a>() -> TrueForge.ListPendingSandboxEnvironmentVersionsResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Returns pending environment versions for the build controller.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.internal.sandboxEnvironments.listPending();
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**requestOptions:** `SandboxEnvironmentsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.internal.sandboxEnvironments.<a href="/src/api/resources/internal/resources/sandboxEnvironments/client/Client.ts">progress</a>({ ...params }) -> void</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Registers or polls the snapshot build and updates version status.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.internal.sandboxEnvironments.progress({
+ environmentVersionId: "environment_version_id"
+});
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**request:** `TrueForge.internal.ProgressSandboxEnvironmentVersionRequest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `SandboxEnvironmentsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
</dd>
</dl>
</details>
diff --git a/packages/trueforge-sdk/src/api/resources/internal/client/Client.ts b/packages/trueforge-sdk/src/api/resources/internal/client/Client.ts
index 0faf09f27..a80d41722 100644
--- a/packages/trueforge-sdk/src/api/resources/internal/client/Client.ts
+++ b/packages/trueforge-sdk/src/api/resources/internal/client/Client.ts
@@ -11,6 +11,7 @@ import * as serializers from "../../../../serialization/index.js";
import * as TrueForge from "../../../index.js";
import { AgentsClient } from "../resources/agents/client/Client.js";
import { MetricsClient } from "../resources/metrics/client/Client.js";
+import { SandboxEnvironmentsClient } from "../resources/sandboxEnvironments/client/Client.js";
import { SchedulesClient } from "../resources/schedules/client/Client.js";
import { SessionsClient } from "../resources/sessions/client/Client.js";
@@ -23,6 +24,7 @@ export declare namespace InternalClient {
export class InternalClient {
protected readonly _options: NormalizedClientOptionsWithAuth<InternalClient.Options>;
protected _metrics: MetricsClient | undefined;
+ protected _sandboxEnvironments: SandboxEnvironmentsClient | undefined;
protected _schedules: SchedulesClient | undefined;
protected _sessions: SessionsClient | undefined;
protected _agents: AgentsClient | undefined;
@@ -35,6 +37,10 @@ export class InternalClient {
return (this._metrics ??= new MetricsClient(this._options));
}
+ public get sandboxEnvironments(): SandboxEnvironmentsClient {
+ return (this._sandboxEnvironments ??= new SandboxEnvironmentsClient(this._options));
+ }
+
public get schedules(): SchedulesClient {
return (this._schedules ??= new SchedulesClient(this._options));
}
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
index 3482fad64..3c1662cf9 100644
--- a/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
@@ -2,6 +2,8 @@ export * from "./agents/client/requests/index.js";
export * as agents from "./agents/index.js";
export * from "./metrics/client/requests/index.js";
export * as metrics from "./metrics/index.js";
+export * from "./sandboxEnvironments/client/requests/index.js";
+export * as sandboxEnvironments from "./sandboxEnvironments/index.js";
export * from "./schedules/client/requests/index.js";
export * as schedules from "./schedules/index.js";
export * from "./sessions/client/requests/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/Client.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/Client.ts
new file mode 100644
index 000000000..3c4cd9a11
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/Client.ts
@@ -0,0 +1,214 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../../../BaseClient.js";
+import { type NormalizedClientOptionsWithAuth, normalizeClientOptionsWithAuth } from "../../../../../../BaseClient.js";
+import { mergeHeaders } from "../../../../../../core/headers.js";
+import * as core from "../../../../../../core/index.js";
+import { mergeAdditionalBodyParameters } from "../../../../../../core/requestBody.js";
+import { handleNonStatusCodeError } from "../../../../../../errors/handleNonStatusCodeError.js";
+import * as errors from "../../../../../../errors/index.js";
+import * as serializers from "../../../../../../serialization/index.js";
+import * as TrueForge from "../../../../../index.js";
+
+export declare namespace SandboxEnvironmentsClient {
+ export type Options = BaseClientOptions;
+
+ export interface RequestOptions extends BaseRequestOptions {}
+}
+
+export class SandboxEnvironmentsClient {
+ protected readonly _options: NormalizedClientOptionsWithAuth<SandboxEnvironmentsClient.Options>;
+
+ constructor(options: SandboxEnvironmentsClient.Options) {
+ this._options = normalizeClientOptionsWithAuth(options);
+ }
+
+ /**
+ * Returns pending environment versions for the build controller.
+ *
+ * @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.internal.sandboxEnvironments.listPending()
+ */
+ public listPending(
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): core.HttpResponsePromise<TrueForge.ListPendingSandboxEnvironmentVersionsResponse> {
+ return core.HttpResponsePromise.fromPromise(this.__listPending(requestOptions));
+ }
+
+ private async __listPending(
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): Promise<core.WithRawResponse<TrueForge.ListPendingSandboxEnvironmentVersionsResponse>> {
+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+ _authRequest.headers,
+ this._options?.headers,
+ requestOptions?.headers,
+ );
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ "api/internal/sandbox-environments/pending",
+ ),
+ method: "GET",
+ headers: _headers,
+ queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+ abortSignal: requestOptions?.abortSignal,
+ fetchFn: this._options?.fetch,
+ logging: this._options.logging,
+ });
+ if (_response.ok) {
+ return {
+ data: serializers.ListPendingSandboxEnvironmentVersionsResponse.parseOrThrow(_response.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ rawResponse: _response.rawResponse,
+ };
+ }
+
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+
+ return handleNonStatusCodeError(
+ _response.error,
+ _response.rawResponse,
+ "GET",
+ "/api/internal/sandbox-environments/pending",
+ );
+ }
+
+ /**
+ * Registers or polls the snapshot build and updates version status.
+ *
+ * @param {TrueForge.internal.ProgressSandboxEnvironmentVersionRequest} request
+ * @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.NotFoundError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.internal.sandboxEnvironments.progress({
+ * environmentVersionId: "environment_version_id"
+ * })
+ */
+ public progress(
+ request: TrueForge.internal.ProgressSandboxEnvironmentVersionRequest,
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): core.HttpResponsePromise<void> {
+ return core.HttpResponsePromise.fromPromise(this.__progress(request, requestOptions));
+ }
+
+ private async __progress(
+ request: TrueForge.internal.ProgressSandboxEnvironmentVersionRequest,
+ requestOptions?: SandboxEnvironmentsClient.RequestOptions,
+ ): Promise<core.WithRawResponse<void>> {
+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+ _authRequest.headers,
+ this._options?.headers,
+ requestOptions?.headers,
+ );
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ "api/internal/sandbox-environments/progress",
+ ),
+ method: "POST",
+ headers: _headers,
+ contentType: "application/json",
+ queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+ requestType: "json",
+ body: mergeAdditionalBodyParameters(
+ serializers.internal.ProgressSandboxEnvironmentVersionRequest.jsonOrThrow(request, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ omitUndefined: true,
+ }),
+ requestOptions?.additionalBodyParameters,
+ ),
+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+ abortSignal: requestOptions?.abortSignal,
+ fetchFn: this._options?.fetch,
+ logging: this._options.logging,
+ });
+ if (_response.ok) {
+ return { data: undefined, rawResponse: _response.rawResponse };
+ }
+
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 404:
+ throw new TrueForge.NotFoundError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+
+ return handleNonStatusCodeError(
+ _response.error,
+ _response.rawResponse,
+ "POST",
+ "/api/internal/sandbox-environments/progress",
+ );
+ }
+}
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/index.ts
new file mode 100644
index 000000000..195f9aa8a
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/index.ts
@@ -0,0 +1 @@
+export * from "./requests/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/requests/ProgressSandboxEnvironmentVersionRequest.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/requests/ProgressSandboxEnvironmentVersionRequest.ts
new file mode 100644
index 000000000..5ffc6314c
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/requests/ProgressSandboxEnvironmentVersionRequest.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ * {
+ * environmentVersionId: "environment_version_id"
+ * }
+ */
+export interface ProgressSandboxEnvironmentVersionRequest {
+ /** Version row id to progress. */
+ environmentVersionId: string;
+}
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/requests/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/requests/index.ts
new file mode 100644
index 000000000..ece9d78dc
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/client/requests/index.ts
@@ -0,0 +1 @@
+export type { ProgressSandboxEnvironmentVersionRequest } from "./ProgressSandboxEnvironmentVersionRequest.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/exports.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/exports.ts
new file mode 100644
index 000000000..fc58f1b3e
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/exports.ts
@@ -0,0 +1,4 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export { SandboxEnvironmentsClient } from "./client/Client.js";
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/index.ts
new file mode 100644
index 000000000..914b8c3c7
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sandboxEnvironments/index.ts
@@ -0,0 +1 @@
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/Client.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/Client.ts
index d94dd9b52..8eabc7088 100644
--- a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/Client.ts
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/Client.ts
@@ -24,7 +24,7 @@ export class SandboxEnvironmentsClient {
}
/**
- * List sandbox environments created by the authenticated subject, newest first.
+ * List the tenant default environment plus sandbox environments created by the authenticated subject.
*
* @param {TrueForge.ListSandboxEnvironmentsRequest} request
* @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -142,7 +142,7 @@ export class SandboxEnvironmentsClient {
}
/**
- * Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+ * Create or replace by `manifest.name`. Requires a configured sandbox provider.
*
* @param {TrueForge.UpdateSandboxEnvironmentRequest} request
* @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -276,7 +276,7 @@ export class SandboxEnvironmentsClient {
}
/**
- * Get a sandbox environment by name for the authenticated subject.
+ * Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.
*
* @param {string} name - Sandbox environment name.
* @param {SandboxEnvironmentsClient.RequestOptions} requestOptions - Request-specific configuration.
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/ListSandboxEnvironmentsRequest.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/ListSandboxEnvironmentsRequest.ts
index 2efd1793b..7f7a49449 100644
--- a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/ListSandboxEnvironmentsRequest.ts
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/ListSandboxEnvironmentsRequest.ts
@@ -5,7 +5,7 @@
* {}
*/
export interface ListSandboxEnvironmentsRequest {
- /** Page size. Defaults to 25 */
+ /** Page size. Defaults to 25, max 1000. */
limit?: number;
/** Opaque token from a previous response `next_page_token`. */
pageToken?: string;
diff --git a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
index f24eb88bd..3760cbf2d 100644
--- a/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
+++ b/packages/trueforge-sdk/src/api/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
@@ -11,5 +11,5 @@ import type * as TrueForge from "../../../../index.js";
* }
*/
export interface UpdateSandboxEnvironmentRequest {
- manifest: TrueForge.SandboxEnvironmentManifest;
+ manifest: TrueForge.SandboxEnvironmentManifestRequest;
}
diff --git a/packages/trueforge-sdk/src/api/types/ConfiguredSandboxProvider.ts b/packages/trueforge-sdk/src/api/types/ConfiguredSandboxProvider.ts
index d766d8e2d..df3aa216d 100644
--- a/packages/trueforge-sdk/src/api/types/ConfiguredSandboxProvider.ts
+++ b/packages/trueforge-sdk/src/api/types/ConfiguredSandboxProvider.ts
@@ -4,7 +4,4 @@ import type * as TrueForge from "../index.js";
export interface ConfiguredSandboxProvider {
manifest: TrueForge.SandboxProviderManifest;
- status: TrueForge.SandboxBuildStatus;
- /** Human-readable detail for the current status; null when ready. */
- statusReason: string | null;
}
diff --git a/packages/trueforge-sdk/src/api/types/ListPendingSandboxEnvironmentVersionsResponse.ts b/packages/trueforge-sdk/src/api/types/ListPendingSandboxEnvironmentVersionsResponse.ts
new file mode 100644
index 000000000..1da0a8b0b
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/ListPendingSandboxEnvironmentVersionsResponse.ts
@@ -0,0 +1,7 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface ListPendingSandboxEnvironmentVersionsResponse {
+ data: TrueForge.PendingSandboxEnvironmentVersion[];
+}
diff --git a/packages/trueforge-sdk/src/api/types/PendingSandboxEnvironmentVersion.ts b/packages/trueforge-sdk/src/api/types/PendingSandboxEnvironmentVersion.ts
new file mode 100644
index 000000000..c83c81203
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/PendingSandboxEnvironmentVersion.ts
@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface PendingSandboxEnvironmentVersion {
+ /** Version row id to progress. */
+ environmentVersionId: string;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxBuildStatus.ts b/packages/trueforge-sdk/src/api/types/SandboxBuildStatus.ts
deleted file mode 100644
index 96db6994a..000000000
--- a/packages/trueforge-sdk/src/api/types/SandboxBuildStatus.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-// This file was auto-generated by Fern from our API Definition.
-
-/** Current build status. */
-export const SandboxBuildStatus = {
- Pending: "pending",
- Ready: "ready",
- Failed: "failed",
-} as const;
-export type SandboxBuildStatus = (typeof SandboxBuildStatus)[keyof typeof SandboxBuildStatus];
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentManifestRequest.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentManifestRequest.ts
new file mode 100644
index 000000000..e97016b56
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentManifestRequest.ts
@@ -0,0 +1,13 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface SandboxEnvironmentManifestRequest {
+ /** Optional human-readable description. */
+ description?: string;
+ environmentVariables?: Record<string, string>;
+ image?: TrueForge.SandboxEnvironmentImage;
+ name: TrueForge.ResourceName;
+ networking?: TrueForge.SandboxEnvironmentNetworking;
+ resources?: TrueForge.SandboxEnvironmentResources;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentVersionStatus.ts b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentVersionStatus.ts
index 15c0b430c..6336416c0 100644
--- a/packages/trueforge-sdk/src/api/types/SandboxEnvironmentVersionStatus.ts
+++ b/packages/trueforge-sdk/src/api/types/SandboxEnvironmentVersionStatus.ts
@@ -3,7 +3,7 @@
/** Readiness of the environment. */
export const SandboxEnvironmentVersionStatus = {
Pending: "pending",
- Active: "active",
+ Ready: "ready",
Failed: "failed",
} as const;
export type SandboxEnvironmentVersionStatus =
diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.ts
index cbbaeca3b..5730217c7 100644
--- a/packages/trueforge-sdk/src/api/types/index.ts
+++ b/packages/trueforge-sdk/src/api/types/index.ts
@@ -99,6 +99,7 @@ export * from "./ListAvailableSkillsResponse.js";
export * from "./ListMcpServersResponse.js";
export * from "./ListMcpServerToolsResponse.js";
export * from "./ListModelProvidersResponse.js";
+export * from "./ListPendingSandboxEnvironmentVersionsResponse.js";
export * from "./ListPermissionsData.js";
export * from "./ListPermissionsResponse.js";
export * from "./ListSandboxEnvironmentsResponse.js";
@@ -147,6 +148,7 @@ export * from "./ModelProviderManifest.js";
export * from "./MoonshotModelProvider.js";
export * from "./OpenAiModelProvider.js";
export * from "./ParallelWebSearchProviderAuth.js";
+export * from "./PendingSandboxEnvironmentVersion.js";
export * from "./PermissionResourceType.js";
export * from "./PreviousTurnIdInput.js";
export * from "./RawToolCall.js";
@@ -162,7 +164,6 @@ export * from "./ResponseFormatJsonSchema.js";
export * from "./ResponseFormatJsonSchemaJsonSchema.js";
export * from "./ResponseFormatText.js";
export * from "./RuntimeConfig.js";
-export * from "./SandboxBuildStatus.js";
export * from "./SandboxCapability.js";
export * from "./SandboxConfig.js";
export * from "./SandboxCreatedEvent.js";
@@ -170,6 +171,7 @@ export * from "./SandboxEnvironment.js";
export * from "./SandboxEnvironmentImage.js";
export * from "./SandboxEnvironmentLifecycleStage.js";
export * from "./SandboxEnvironmentManifest.js";
+export * from "./SandboxEnvironmentManifestRequest.js";
export * from "./SandboxEnvironmentNetworking.js";
export * from "./SandboxEnvironmentResources.js";
export * from "./SandboxEnvironmentSecret.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/index.ts
index 8a1a831cb..0c87d3959 100644
--- a/packages/trueforge-sdk/src/serialization/resources/internal/resources/index.ts
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/index.ts
@@ -1,3 +1,5 @@
+export * from "./sandboxEnvironments/client/requests/index.js";
+export * as sandboxEnvironments from "./sandboxEnvironments/index.js";
export * from "./schedules/client/requests/index.js";
export * as schedules from "./schedules/index.js";
export * from "./sessions/client/requests/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/index.ts
new file mode 100644
index 000000000..195f9aa8a
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/index.ts
@@ -0,0 +1 @@
+export * from "./requests/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/requests/ProgressSandboxEnvironmentVersionRequest.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/requests/ProgressSandboxEnvironmentVersionRequest.ts
new file mode 100644
index 000000000..922530dd5
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/requests/ProgressSandboxEnvironmentVersionRequest.ts
@@ -0,0 +1,18 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../../../../../../api/index.js";
+import * as core from "../../../../../../../core/index.js";
+import type * as serializers from "../../../../../../index.js";
+
+export const ProgressSandboxEnvironmentVersionRequest: core.serialization.Schema<
+ serializers.internal.ProgressSandboxEnvironmentVersionRequest.Raw,
+ TrueForge.internal.ProgressSandboxEnvironmentVersionRequest
+> = core.serialization.object({
+ environmentVersionId: core.serialization.property("environment_version_id", core.serialization.string()),
+});
+
+export declare namespace ProgressSandboxEnvironmentVersionRequest {
+ export interface Raw {
+ environment_version_id: string;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/requests/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/requests/index.ts
new file mode 100644
index 000000000..209b2d15f
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/client/requests/index.ts
@@ -0,0 +1 @@
+export { ProgressSandboxEnvironmentVersionRequest } from "./ProgressSandboxEnvironmentVersionRequest.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/index.ts
new file mode 100644
index 000000000..914b8c3c7
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sandboxEnvironments/index.ts
@@ -0,0 +1 @@
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
index cc1001878..e83b77e13 100644
--- a/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
+++ b/packages/trueforge-sdk/src/serialization/resources/sandboxEnvironments/client/requests/UpdateSandboxEnvironmentRequest.ts
@@ -3,17 +3,17 @@
import type * as TrueForge from "../../../../../api/index.js";
import * as core from "../../../../../core/index.js";
import type * as serializers from "../../../../index.js";
-import { SandboxEnvironmentManifest } from "../../../../types/SandboxEnvironmentManifest.js";
+import { SandboxEnvironmentManifestRequest } from "../../../../types/SandboxEnvironmentManifestRequest.js";
export const UpdateSandboxEnvironmentRequest: core.serialization.Schema<
serializers.UpdateSandboxEnvironmentRequest.Raw,
TrueForge.UpdateSandboxEnvironmentRequest
> = core.serialization.object({
- manifest: SandboxEnvironmentManifest,
+ manifest: SandboxEnvironmentManifestRequest,
});
export declare namespace UpdateSandboxEnvironmentRequest {
export interface Raw {
- manifest: SandboxEnvironmentManifest.Raw;
+ manifest: SandboxEnvironmentManifestRequest.Raw;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/ConfiguredSandboxProvider.ts b/packages/trueforge-sdk/src/serialization/types/ConfiguredSandboxProvider.ts
index 6bdb0087d..c34bc3a58 100644
--- a/packages/trueforge-sdk/src/serialization/types/ConfiguredSandboxProvider.ts
+++ b/packages/trueforge-sdk/src/serialization/types/ConfiguredSandboxProvider.ts
@@ -3,7 +3,6 @@
import type * as TrueForge from "../../api/index.js";
import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
-import { SandboxBuildStatus } from "./SandboxBuildStatus.js";
import { SandboxProviderManifest } from "./SandboxProviderManifest.js";
export const ConfiguredSandboxProvider: core.serialization.ObjectSchema<
@@ -11,14 +10,10 @@ export const ConfiguredSandboxProvider: core.serialization.ObjectSchema<
TrueForge.ConfiguredSandboxProvider
> = core.serialization.object({
manifest: SandboxProviderManifest,
- status: SandboxBuildStatus,
- statusReason: core.serialization.property("status_reason", core.serialization.string().nullable()),
});
export declare namespace ConfiguredSandboxProvider {
export interface Raw {
manifest: SandboxProviderManifest.Raw;
- status: SandboxBuildStatus.Raw;
- status_reason?: string | null;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/ListPendingSandboxEnvironmentVersionsResponse.ts b/packages/trueforge-sdk/src/serialization/types/ListPendingSandboxEnvironmentVersionsResponse.ts
new file mode 100644
index 000000000..a8418b40e
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/ListPendingSandboxEnvironmentVersionsResponse.ts
@@ -0,0 +1,19 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { PendingSandboxEnvironmentVersion } from "./PendingSandboxEnvironmentVersion.js";
+
+export const ListPendingSandboxEnvironmentVersionsResponse: core.serialization.ObjectSchema<
+ serializers.ListPendingSandboxEnvironmentVersionsResponse.Raw,
+ TrueForge.ListPendingSandboxEnvironmentVersionsResponse
+> = core.serialization.object({
+ data: core.serialization.list(PendingSandboxEnvironmentVersion),
+});
+
+export declare namespace ListPendingSandboxEnvironmentVersionsResponse {
+ export interface Raw {
+ data: PendingSandboxEnvironmentVersion.Raw[];
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/PendingSandboxEnvironmentVersion.ts b/packages/trueforge-sdk/src/serialization/types/PendingSandboxEnvironmentVersion.ts
new file mode 100644
index 000000000..ab7bf547a
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/PendingSandboxEnvironmentVersion.ts
@@ -0,0 +1,18 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const PendingSandboxEnvironmentVersion: core.serialization.ObjectSchema<
+ serializers.PendingSandboxEnvironmentVersion.Raw,
+ TrueForge.PendingSandboxEnvironmentVersion
+> = core.serialization.object({
+ environmentVersionId: core.serialization.property("environment_version_id", core.serialization.string()),
+});
+
+export declare namespace PendingSandboxEnvironmentVersion {
+ export interface Raw {
+ environment_version_id: string;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxBuildStatus.ts b/packages/trueforge-sdk/src/serialization/types/SandboxBuildStatus.ts
deleted file mode 100644
index 2c49382f1..000000000
--- a/packages/trueforge-sdk/src/serialization/types/SandboxBuildStatus.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-// This file was auto-generated by Fern from our API Definition.
-
-import type * as TrueForge from "../../api/index.js";
-import * as core from "../../core/index.js";
-import type * as serializers from "../index.js";
-
-export const SandboxBuildStatus: core.serialization.Schema<
- serializers.SandboxBuildStatus.Raw,
- TrueForge.SandboxBuildStatus
-> = core.serialization.enum_(["pending", "ready", "failed"]);
-
-export declare namespace SandboxBuildStatus {
- export type Raw = "pending" | "ready" | "failed";
-}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentManifestRequest.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentManifestRequest.ts
new file mode 100644
index 000000000..8bc34e5d2
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentManifestRequest.ts
@@ -0,0 +1,35 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { ResourceName } from "./ResourceName.js";
+import { SandboxEnvironmentImage } from "./SandboxEnvironmentImage.js";
+import { SandboxEnvironmentNetworking } from "./SandboxEnvironmentNetworking.js";
+import { SandboxEnvironmentResources } from "./SandboxEnvironmentResources.js";
+
+export const SandboxEnvironmentManifestRequest: core.serialization.ObjectSchema<
+ serializers.SandboxEnvironmentManifestRequest.Raw,
+ TrueForge.SandboxEnvironmentManifestRequest
+> = core.serialization.object({
+ description: core.serialization.string().optional(),
+ environmentVariables: core.serialization.property(
+ "environment_variables",
+ core.serialization.record(core.serialization.string(), core.serialization.string()).optional(),
+ ),
+ image: SandboxEnvironmentImage.optional(),
+ name: ResourceName,
+ networking: SandboxEnvironmentNetworking.optional(),
+ resources: SandboxEnvironmentResources.optional(),
+});
+
+export declare namespace SandboxEnvironmentManifestRequest {
+ export interface Raw {
+ description?: string | null;
+ environment_variables?: Record<string, string> | null;
+ image?: SandboxEnvironmentImage.Raw | null;
+ name: ResourceName.Raw;
+ networking?: SandboxEnvironmentNetworking.Raw | null;
+ resources?: SandboxEnvironmentResources.Raw | null;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentVersionStatus.ts b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentVersionStatus.ts
index 56c9013f5..ba75703f6 100644
--- a/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentVersionStatus.ts
+++ b/packages/trueforge-sdk/src/serialization/types/SandboxEnvironmentVersionStatus.ts
@@ -7,8 +7,8 @@ import type * as serializers from "../index.js";
export const SandboxEnvironmentVersionStatus: core.serialization.Schema<
serializers.SandboxEnvironmentVersionStatus.Raw,
TrueForge.SandboxEnvironmentVersionStatus
-> = core.serialization.enum_(["pending", "active", "failed"]);
+> = core.serialization.enum_(["pending", "ready", "failed"]);
export declare namespace SandboxEnvironmentVersionStatus {
- export type Raw = "pending" | "active" | "failed";
+ export type Raw = "pending" | "ready" | "failed";
}
diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.ts
index cbbaeca3b..5730217c7 100644
--- a/packages/trueforge-sdk/src/serialization/types/index.ts
+++ b/packages/trueforge-sdk/src/serialization/types/index.ts
@@ -99,6 +99,7 @@ export * from "./ListAvailableSkillsResponse.js";
export * from "./ListMcpServersResponse.js";
export * from "./ListMcpServerToolsResponse.js";
export * from "./ListModelProvidersResponse.js";
+export * from "./ListPendingSandboxEnvironmentVersionsResponse.js";
export * from "./ListPermissionsData.js";
export * from "./ListPermissionsResponse.js";
export * from "./ListSandboxEnvironmentsResponse.js";
@@ -147,6 +148,7 @@ export * from "./ModelProviderManifest.js";
export * from "./MoonshotModelProvider.js";
export * from "./OpenAiModelProvider.js";
export * from "./ParallelWebSearchProviderAuth.js";
+export * from "./PendingSandboxEnvironmentVersion.js";
export * from "./PermissionResourceType.js";
export * from "./PreviousTurnIdInput.js";
export * from "./RawToolCall.js";
@@ -162,7 +164,6 @@ export * from "./ResponseFormatJsonSchema.js";
export * from "./ResponseFormatJsonSchemaJsonSchema.js";
export * from "./ResponseFormatText.js";
export * from "./RuntimeConfig.js";
-export * from "./SandboxBuildStatus.js";
export * from "./SandboxCapability.js";
export * from "./SandboxConfig.js";
export * from "./SandboxCreatedEvent.js";
@@ -170,6 +171,7 @@ export * from "./SandboxEnvironment.js";
export * from "./SandboxEnvironmentImage.js";
export * from "./SandboxEnvironmentLifecycleStage.js";
export * from "./SandboxEnvironmentManifest.js";
+export * from "./SandboxEnvironmentManifestRequest.js";
export * from "./SandboxEnvironmentNetworking.js";
export * from "./SandboxEnvironmentResources.js";
export * from "./SandboxEnvironmentSecret.js";
diff --git a/packages/trueforge-sdk/tests/wire/internal/sandboxEnvironments.test.ts b/packages/trueforge-sdk/tests/wire/internal/sandboxEnvironments.test.ts
new file mode 100644
index 000000000..ca27c9a6b
--- /dev/null
+++ b/packages/trueforge-sdk/tests/wire/internal/sandboxEnvironments.test.ts
@@ -0,0 +1,113 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import * as TrueForgeTypes from "../../../src/api/index";
+import { TrueForge } from "../../../src/Client";
+import { mockServerPool } from "../../mock-server/MockServerPool";
+
+describe("SandboxEnvironmentsClient", () => {
+ test("list_pending (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { data: [{ environment_version_id: "environment_version_id" }] };
+
+ server
+ .mockEndpoint()
+ .get("/api/internal/sandbox-environments/pending")
+ .respondWith()
+ .statusCode(200)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ const response = await client.internal.sandboxEnvironments.listPending();
+ expect(response).toEqual({
+ data: [
+ {
+ environmentVersionId: "environment_version_id",
+ },
+ ],
+ });
+ });
+
+ test("list_pending (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/internal/sandbox-environments/pending")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.internal.sandboxEnvironments.listPending();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("progress (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { environment_version_id: "environment_version_id" };
+
+ server
+ .mockEndpoint()
+ .post("/api/internal/sandbox-environments/progress")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(200)
+ .build();
+
+ const response = await client.internal.sandboxEnvironments.progress({
+ environmentVersionId: "environment_version_id",
+ });
+ expect(response).toEqual(undefined);
+ });
+
+ test("progress (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { environment_version_id: "x" };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/api/internal/sandbox-environments/progress")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.internal.sandboxEnvironments.progress({
+ environmentVersionId: "x",
+ });
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("progress (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { environment_version_id: "x" };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/api/internal/sandbox-environments/progress")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(404)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.internal.sandboxEnvironments.progress({
+ environmentVersionId: "x",
+ });
+ }).rejects.toThrow(TrueForgeTypes.NotFoundError);
+ });
+});
diff --git a/packages/trueforge-sdk/tests/wire/settings/sandboxProviders.test.ts b/packages/trueforge-sdk/tests/wire/settings/sandboxProviders.test.ts
index 0edb2ac60..5140dbaf4 100644
--- a/packages/trueforge-sdk/tests/wire/settings/sandboxProviders.test.ts
+++ b/packages/trueforge-sdk/tests/wire/settings/sandboxProviders.test.ts
@@ -19,8 +19,6 @@ describe("SandboxProvidersClient", () => {
exec_timeout_ms: 1,
type: "daytona",
},
- status: "pending",
- status_reason: "status_reason",
},
};
@@ -45,8 +43,6 @@ describe("SandboxProvidersClient", () => {
execTimeoutMs: 1,
type: "daytona",
},
- status: "pending",
- statusReason: "status_reason",
},
});
});
@@ -93,8 +89,6 @@ describe("SandboxProvidersClient", () => {
exec_timeout_ms: 1,
type: "daytona",
},
- status: "pending",
- status_reason: "status_reason",
},
};
@@ -131,8 +125,6 @@ describe("SandboxProvidersClient", () => {
execTimeoutMs: 1,
type: "daytona",
},
- status: "pending",
- statusReason: "status_reason",
},
});
});
diff --git a/packages/trueforge-ui/src/containers/SettingsBuilder/SandboxSettings.tsx b/packages/trueforge-ui/src/containers/SettingsBuilder/SandboxSettings.tsx
index b3c947807..495f8a60e 100644
--- a/packages/trueforge-ui/src/containers/SettingsBuilder/SandboxSettings.tsx
+++ b/packages/trueforge-ui/src/containers/SettingsBuilder/SandboxSettings.tsx
@@ -2,27 +2,18 @@
import { useCallback, useEffect, useMemo, useState } from 'react';
-import { Spinner } from '@/atoms/primitives/Spinner.js';
import { Button } from '../../atoms/primitives/Button.js';
-import { Tooltip } from '../../atoms/primitives/Tooltip.js';
import { Icon } from '../../icons/Icon.js';
import {
isDaytonaSandboxConfig,
type DaytonaSandboxConfig,
} from '../../plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.js';
import { useCatalogServer } from '../../server/ServerContext.js';
-import type {
- SandboxProviderBase,
- SandboxProviderCatalogEntry,
- SandboxProviderListEntry,
- SandboxSnapshotSyncStatus,
-} from '../../server/types.js';
+import type { SandboxProviderBase, SandboxProviderCatalogEntry } from '../../server/types.js';
import { getErrorMessage } from '../../utils/getErrorMessage.js';
import { useToasterOptional } from '../ToasterContainer.js';
import ConfigureSandboxForm, { type SandboxConfigDraft } from './ConfigureSandboxForm.js';
-const SNAPSHOT_STATUS_POLL_INTERVAL_MS = 10000;
-
const configFrom = ({
execTimeoutMs,
autoStopIntervalInMinutes,
@@ -35,36 +26,11 @@ const configFrom = ({
autoDeleteIntervalInMinutes,
});
-const statusPresentation = (status: SandboxSnapshotSyncStatus['status']): { label: string; className: string } => {
- switch (status) {
- case 'pending':
- return {
- label: 'Syncing image...',
- className: 'text-warning-bg',
- };
- case 'ready':
- return {
- label: 'Connected',
- className: 'text-success-bg',
- };
- case 'failed':
- return {
- label: 'Sync failed',
- className: 'text-failure-bg',
- };
- default:
- return {
- label: status,
- className: 'text-text-secondary',
- };
- }
-};
-
const SandboxSettings = () => {
const { sandboxCatalog } = useCatalogServer();
const toaster = useToasterOptional();
- const [providers, setProviders] = useState<SandboxProviderListEntry[]>([]);
+ const [providers, setProviders] = useState<SandboxProviderBase[]>([]);
const [catalog, setCatalog] = useState<SandboxProviderCatalogEntry[]>([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
@@ -99,51 +65,11 @@ const SandboxSettings = () => {
void refresh();
}, [refresh]);
- const hasPendingProvider = providers.some(entry => entry.snapshotSyncStatus.status === 'pending');
-
- useEffect(() => {
- if (!sandboxCatalog || !hasPendingProvider) return;
- const activeSandboxCatalog = sandboxCatalog;
-
- let cancelled = false;
- let timeoutId: number | undefined;
-
- function schedulePoll() {
- timeoutId = window.setTimeout(() => {
- void poll();
- }, SNAPSHOT_STATUS_POLL_INTERVAL_MS);
- }
-
- async function poll() {
- try {
- const listed = await activeSandboxCatalog.listSandboxProviders();
- if (cancelled) return;
- setProviders(listed);
- setError(null);
- if (listed.some(entry => entry.snapshotSyncStatus.status === 'pending')) {
- schedulePoll();
- }
- } catch (err) {
- if (cancelled) return;
- setError(getErrorMessage(err, 'Failed to refresh sandbox providers'));
- schedulePoll();
- }
- }
-
- schedulePoll();
- return () => {
- cancelled = true;
- if (timeoutId !== undefined) {
- window.clearTimeout(timeoutId);
- }
- };
- }, [sandboxCatalog, hasPendingProvider]);
-
// Tenant/UI-wide: only one sandbox provider may be configured at a time.
const hasConfiguredProvider = providers.length > 0;
const availableEntries = useMemo(() => {
if (hasConfiguredProvider) return [];
- const connectedCatalogIds = new Set(providers.map(provider => provider.data.catalogId));
+ const connectedCatalogIds = new Set(providers.map(provider => provider.catalogId));
return catalog.filter(entry => !connectedCatalogIds.has(entry.id));
}, [catalog, providers, hasConfiguredProvider]);
@@ -205,16 +131,6 @@ const SandboxSettings = () => {
}, 0);
};
- const handleRetry = (provider: SandboxProviderBase) => {
- if (!isDaytonaSandboxConfig(provider)) return;
- void runMutation(async () => {
- await sandboxCatalog.updateSandboxProvider({
- id: provider.id,
- ...configFrom(provider),
- });
- }).catch(() => {});
- };
-
const handleRemove = (provider: SandboxProviderBase) => {
const deleteSandboxProvider = sandboxCatalog.deleteSandboxProvider;
if (!deleteSandboxProvider) return;
@@ -255,94 +171,57 @@ const SandboxSettings = () => {
Configured · {providers.length}
</h4>
<div className="overflow-hidden rounded-xl border border-border bg-card-bg">
- {providers.map(entry => {
- const provider = entry.data;
- const status = statusPresentation(entry.snapshotSyncStatus.status);
- const statusReason = entry.snapshotSyncStatus.statusReason;
- const statusIndicator = (
- <span className={`inline-flex items-center gap-1.5 text-sm font-medium ${status.className}`}>
- {entry.snapshotSyncStatus.status === 'pending' ? (
- <Spinner size={16} aria-label="Syncing snapshot image" />
- ) : entry.snapshotSyncStatus.status === 'ready' ? (
- <span className="size-2 rounded-full bg-success-bg" aria-hidden />
- ) : entry.snapshotSyncStatus.status === 'failed' ? (
- <Icon name="triangle-exclamation" className="size-4" />
- ) : null}
- {status.label}
- </span>
- );
- return (
- <article
- key={provider.id}
- className="flex flex-col gap-3 border-b border-border p-3 last:border-b-0 sm:flex-row sm:items-center"
- >
- <div className="flex min-w-0 flex-1 items-center gap-3">
- <span
- className="flex size-9 shrink-0 items-center justify-center rounded-lg border border-border bg-secondary-bg text-text-primary"
- aria-hidden
- >
- <Icon name="cube" className="size-4.5" />
- </span>
- <div className="min-w-0">
- <h5 className="truncate text-sm font-medium text-text-primary">{provider.name}</h5>
- </div>
+ {providers.map(provider => (
+ <article
+ key={provider.id}
+ className="flex flex-col gap-3 border-b border-border p-3 last:border-b-0 sm:flex-row sm:items-center"
+ >
+ <div className="flex min-w-0 flex-1 items-center gap-3">
+ <span
+ className="flex size-9 shrink-0 items-center justify-center rounded-lg border border-border bg-secondary-bg text-text-primary"
+ aria-hidden
+ >
+ <Icon name="cube" className="size-4.5" />
+ </span>
+ <div className="min-w-0">
+ <h5 className="truncate text-sm font-medium text-text-primary">{provider.name}</h5>
</div>
+ </div>
- <div className="flex flex-wrap items-center gap-2.5 sm:justify-end">
- {statusIndicator}
- {statusReason ? (
- <Tooltip content={statusReason}>
- <button
- type="button"
- aria-label="Snapshot sync status details"
- className="inline-flex text-text-secondary transition-colors hover:text-text-primary"
- >
- <Icon name="info" className="size-4" />
- </button>
- </Tooltip>
- ) : null}
- {entry.snapshotSyncStatus.status === 'failed' ? (
- <Button.Ghost
- size="small"
- type="button"
- disabled={busy}
- onClick={() => {
- handleRetry(provider);
- }}
- >
- Retry
- </Button.Ghost>
- ) : null}
- <Button.Secondary
+ <div className="flex flex-wrap items-center gap-2.5 sm:justify-end">
+ <span className="inline-flex items-center gap-1.5 text-sm font-medium text-success-bg">
+ <span className="size-2 rounded-full bg-success-bg" aria-hidden />
+ Connected
+ </span>
+ <Button.Secondary
+ size="small"
+ type="button"
+ disabled={busy}
+ onClick={() => {
+ setFormError(null);
+ setCreateEntry(null);
+ setUpdateProvider(provider);
+ }}
+ >
+ Update
+ </Button.Secondary>
+
+ {sandboxCatalog.deleteSandboxProvider ? (
+ <Button.Ghost
size="small"
+ className="text-text-secondary"
type="button"
disabled={busy}
onClick={() => {
- setFormError(null);
- setCreateEntry(null);
- setUpdateProvider(provider);
+ handleRemove(provider);
}}
>
- Update
- </Button.Secondary>
-
- {sandboxCatalog.deleteSandboxProvider ? (
- <Button.Ghost
- size="small"
- className="text-text-secondary"
- type="button"
- disabled={busy}
- onClick={() => {
- handleRemove(provider);
- }}
- >
- Remove
- </Button.Ghost>
- ) : null}
- </div>
- </article>
- );
- })}
+ Remove
+ </Button.Ghost>
+ ) : null}
+ </div>
+ </article>
+ ))}
</div>
</section>
) : null}
diff --git a/packages/trueforge-ui/src/index.ts b/packages/trueforge-ui/src/index.ts
index 04a3ccc6b..b83f7f12f 100644
--- a/packages/trueforge-ui/src/index.ts
+++ b/packages/trueforge-ui/src/index.ts
@@ -407,8 +407,6 @@ export type {
SandboxCatalogServer,
SandboxProviderBase,
SandboxProviderCatalogEntry,
- SandboxProviderListEntry,
- SandboxSnapshotSyncStatus,
SaveAgentRequest,
SaveAgentResult,
SearchAgentsParams,
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.ts
index fb3958aaf..4352179cb 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.ts
@@ -16,7 +16,6 @@ import type {
SandboxCatalogServer,
SandboxProviderBase,
SandboxProviderCatalogEntry,
- SandboxProviderListEntry,
UpdateSandboxProviderRequest,
} from '../../../server/types.js';
@@ -30,7 +29,6 @@ export interface DaytonaSandboxConfig {
export type UiSandboxProvider = SandboxProviderBase & DaytonaSandboxConfig;
export type UiSandboxProviderCatalogEntry = SandboxProviderCatalogEntry & DaytonaSandboxConfig;
-export type UiSandboxProviderListEntry = SandboxProviderListEntry<UiSandboxProvider>;
export type UiCreateSandboxProviderRequest = CreateSandboxProviderRequest & DaytonaSandboxConfig;
export type UiUpdateSandboxProviderRequest = UpdateSandboxProviderRequest & DaytonaSandboxConfig;
@@ -38,8 +36,7 @@ export type DaytonaSandboxCatalogServer = SandboxCatalogServer<
UiSandboxProvider,
UiSandboxProviderCatalogEntry,
UiCreateSandboxProviderRequest,
- UiUpdateSandboxProviderRequest,
- UiSandboxProviderListEntry
+ UiUpdateSandboxProviderRequest
>;
const DAYTONA_TYPE = 'daytona';
@@ -95,33 +92,20 @@ export function toUiSandboxProvider(provider: TrueForgeApi.SandboxProviderManife
};
}
-export function toUiSandboxProviderListEntry(
- response: TrueForgeApi.GetSandboxProviderResponse['data'],
-): UiSandboxProviderListEntry {
- return {
- data: toUiSandboxProvider(response.manifest),
- snapshotSyncStatus: {
- status: response.status,
- ...(response.statusReason ? { statusReason: response.statusReason } : {}),
- },
- };
-}
-
export function filterUiSandboxProviders({
providers,
query,
}: {
- providers: UiSandboxProviderListEntry[];
+ providers: UiSandboxProvider[];
query?: string;
-}): UiSandboxProviderListEntry[] {
+}): UiSandboxProvider[] {
const normalizedQuery = query?.trim().toLowerCase();
if (normalizedQuery === undefined || normalizedQuery === '') {
return providers;
}
return providers.filter(
provider =>
- provider.data.name.toLowerCase().includes(normalizedQuery) ||
- provider.data.id.toLowerCase().includes(normalizedQuery),
+ provider.name.toLowerCase().includes(normalizedQuery) || provider.id.toLowerCase().includes(normalizedQuery),
);
}
@@ -161,10 +145,10 @@ export function createSandboxProviderCatalog(client: TrueForge): DaytonaSandboxC
return body.data.map(toUiCatalogEntry);
},
listSandboxProviders: async req => {
- let providers: UiSandboxProviderListEntry[];
+ let providers: UiSandboxProvider[];
try {
const body = await client.settings.sandboxProviders.get();
- providers = [toUiSandboxProviderListEntry(body.data)];
+ providers = [toUiSandboxProvider(body.data.manifest)];
} catch (err) {
if (err instanceof TrueForgeApi.NotFoundError) {
providers = [];
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
index f1673c1bd..1cc6f07d0 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
@@ -49,13 +49,11 @@ export {
toHarnessManifest as toHarnessSandboxManifest,
toUiCatalogEntry as toUiSandboxCatalogEntry,
toUiSandboxProvider,
- toUiSandboxProviderListEntry,
type DaytonaSandboxCatalogServer,
type DaytonaSandboxConfig,
type UiCreateSandboxProviderRequest,
type UiSandboxProvider,
type UiSandboxProviderCatalogEntry,
- type UiSandboxProviderListEntry,
type UiUpdateSandboxProviderRequest,
} from './catalogs/sandboxProviderCatalog.js';
export { createSkillCatalog, toHarnessManifest as toHarnessSkillManifest, toUiSkill } from './catalogs/skillCatalog.js';
diff --git a/packages/trueforge-ui/src/server/types.ts b/packages/trueforge-ui/src/server/types.ts
index 2b3a7f3d8..0b25157b7 100644
--- a/packages/trueforge-ui/src/server/types.ts
+++ b/packages/trueforge-ui/src/server/types.ts
@@ -94,8 +94,6 @@ export type {
SandboxCatalogServer,
SandboxProviderBase,
SandboxProviderCatalogEntry,
- SandboxProviderListEntry,
- SandboxSnapshotSyncStatus,
SaveAgentRequest,
SaveAgentResult,
Schedule,
diff --git a/packages/trueforge-ui/test/containers/SettingsBuilder/SandboxSettings.test.tsx b/packages/trueforge-ui/test/containers/SettingsBuilder/SandboxSettings.test.tsx
index 958ab757e..9ac7d577c 100644
--- a/packages/trueforge-ui/test/containers/SettingsBuilder/SandboxSettings.test.tsx
+++ b/packages/trueforge-ui/test/containers/SettingsBuilder/SandboxSettings.test.tsx
@@ -1,18 +1,16 @@
// @vitest-environment jsdom
-import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import type { ReactNode } from 'react';
-import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
import SandboxSettings from '@/containers/SettingsBuilder/SandboxSettings.js';
import type {
UiCreateSandboxProviderRequest,
UiSandboxProvider,
UiSandboxProviderCatalogEntry,
- UiSandboxProviderListEntry,
UiUpdateSandboxProviderRequest,
} from '@/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.js';
import { ServerProvider } from '@/server/ServerContext.js';
-import type { SandboxSnapshotSyncStatus } from '@/server/types.js';
import { createMockAgentUIServer, createMockCatalog } from '../../server/mockServer.js';
beforeAll(() => {
@@ -24,10 +22,6 @@ beforeAll(() => {
};
});
-afterEach(() => {
- vi.useRealTimers();
-});
-
const catalogEntry: UiSandboxProviderCatalogEntry = {
id: 'cat-daytona',
name: 'Daytona',
@@ -38,36 +32,14 @@ const catalogEntry: UiSandboxProviderCatalogEntry = {
autoDeleteIntervalInMinutes: 43200,
};
-function sandboxEntry({
- provider,
- status = 'ready',
- statusReason,
-}: {
- provider: UiSandboxProvider;
- status?: SandboxSnapshotSyncStatus['status'];
- statusReason?: string;
-}): UiSandboxProviderListEntry {
- return {
- data: provider,
- snapshotSyncStatus: {
- status,
- ...(statusReason ? { statusReason } : {}),
- },
- };
-}
-
-function createFakeHost(initial: UiSandboxProviderListEntry[] = []) {
+function createFakeHost(initial: UiSandboxProvider[] = []) {
let providers = [...initial];
- let listCalls = 0;
const created: UiCreateSandboxProviderRequest[] = [];
const updated: UiUpdateSandboxProviderRequest[] = [];
const sandboxCatalog = {
getSandboxProviderCatalog: async () => [catalogEntry],
- listSandboxProviders: async () => {
- listCalls += 1;
- return providers;
- },
+ listSandboxProviders: async () => providers,
createSandboxProvider: async (req: UiCreateSandboxProviderRequest) => {
created.push(req);
const provider: UiSandboxProvider = {
@@ -80,30 +52,27 @@ function createFakeHost(initial: UiSandboxProviderListEntry[] = []) {
autoArchiveIntervalInMinutes: req.autoArchiveIntervalInMinutes,
autoDeleteIntervalInMinutes: req.autoDeleteIntervalInMinutes,
};
- providers = [...providers, sandboxEntry({ provider, status: 'pending' })];
+ providers = [...providers, provider];
return provider;
},
updateSandboxProvider: async (req: UiUpdateSandboxProviderRequest) => {
updated.push(req);
- providers = providers.map(entry =>
- entry.data.id === req.id
+ providers = providers.map(provider =>
+ provider.id === req.id
? {
- ...entry,
- data: {
- ...entry.data,
- execTimeoutMs: req.execTimeoutMs,
- autoStopIntervalInMinutes: req.autoStopIntervalInMinutes,
- autoArchiveIntervalInMinutes: req.autoArchiveIntervalInMinutes,
- autoDeleteIntervalInMinutes: req.autoDeleteIntervalInMinutes,
- },
+ ...provider,
+ execTimeoutMs: req.execTimeoutMs,
+ autoStopIntervalInMinutes: req.autoStopIntervalInMinutes,
+ autoArchiveIntervalInMinutes: req.autoArchiveIntervalInMinutes,
+ autoDeleteIntervalInMinutes: req.autoDeleteIntervalInMinutes,
}
- : entry,
+ : provider,
);
- const next = providers.find(entry => entry.data.id === req.id);
+ const next = providers.find(provider => provider.id === req.id);
if (next === undefined) {
throw new Error(`Sandbox provider "${req.id}" not found`);
}
- return next.data;
+ return next;
},
};
@@ -114,11 +83,6 @@ function createFakeHost(initial: UiSandboxProviderListEntry[] = []) {
return {
created,
updated,
- getListCalls: () => listCalls,
- getProviders: () => providers,
- setProviders: (next: UiSandboxProviderListEntry[]) => {
- providers = next;
- },
wrapper: ({ children }: { children: ReactNode }) => <ServerProvider server={server}>{children}</ServerProvider>,
};
}
@@ -180,7 +144,7 @@ describe('SandboxSettings', () => {
autoArchiveIntervalInMinutes: 1440,
autoDeleteIntervalInMinutes: 10080,
};
- const host = createFakeHost([sandboxEntry({ provider: existing })]);
+ const host = createFakeHost([existing]);
const { wrapper: Wrapper } = host;
render(
<Wrapper>
@@ -192,6 +156,7 @@ describe('SandboxSettings', () => {
expect(screen.getByRole('button', { name: 'Update' })).toBeTruthy();
});
expect(screen.queryByRole('button', { name: 'Remove' })).toBeNull();
+ expect(screen.getByText('Connected')).toBeTruthy();
fireEvent.click(screen.getByRole('button', { name: 'Update' }));
@@ -229,7 +194,7 @@ describe('SandboxSettings', () => {
autoArchiveIntervalInMinutes: 1440,
autoDeleteIntervalInMinutes: 10080,
};
- const host = createFakeHost([sandboxEntry({ provider: existing })]);
+ const host = createFakeHost([existing]);
const { wrapper: Wrapper } = host;
render(
<Wrapper>
@@ -241,141 +206,7 @@ describe('SandboxSettings', () => {
expect(screen.getByText('Sandbox providers')).toBeTruthy();
});
expect(screen.queryByRole('button', { name: 'Configure' })).toBeNull();
- // Once a provider is configured, the whole "Available" section is hidden (heading + message).
expect(screen.queryByText(/^Available ·/)).toBeNull();
expect(screen.queryByText('One provider is set up. Update it or remove it to switch.')).toBeNull();
});
-
- it('renders pending and ready snapshot status badges', async () => {
- const provider: UiSandboxProvider = {
- id: 'sb-1',
- name: 'Daytona',
- catalogId: 'cat-daytona',
- isConnected: true,
- execTimeoutMs: 60000,
- autoStopIntervalInMinutes: 30,
- autoArchiveIntervalInMinutes: 1440,
- autoDeleteIntervalInMinutes: 10080,
- };
- const host = createFakeHost([
- sandboxEntry({
- provider,
- status: 'pending',
- statusReason: 'Snapshot build is queued',
- }),
- sandboxEntry({
- provider: { ...provider, id: 'sb-2', name: 'Daytona ready' },
- status: 'ready',
- }),
- ]);
- const { wrapper: Wrapper } = host;
- render(
- <Wrapper>
- <SandboxSettings />
- </Wrapper>,
- );
-
- await waitFor(() => {
- expect(screen.getByText('Syncing image...')).toBeTruthy();
- expect(screen.getByText('Connected')).toBeTruthy();
- });
- expect(screen.queryByRole('button', { name: 'Retry' })).toBeNull();
-
- fireEvent.mouseEnter(screen.getByLabelText('Snapshot sync status details'));
- await waitFor(() => {
- expect(screen.getByRole('tooltip')).toHaveTextContent('Snapshot build is queued');
- });
- });
-
- it('polls pending snapshot status every ten seconds until it changes', async () => {
- vi.useFakeTimers();
- const provider: UiSandboxProvider = {
- id: 'sb-1',
- name: 'Daytona',
- catalogId: 'cat-daytona',
- isConnected: true,
- execTimeoutMs: 60000,
- autoStopIntervalInMinutes: 30,
- autoArchiveIntervalInMinutes: 1440,
- autoDeleteIntervalInMinutes: 10080,
- };
- const host = createFakeHost([sandboxEntry({ provider, status: 'pending' })]);
- const { wrapper: Wrapper } = host;
- render(
- <Wrapper>
- <SandboxSettings />
- </Wrapper>,
- );
-
- await act(async () => {
- await vi.advanceTimersByTimeAsync(0);
- });
- expect(host.getListCalls()).toBe(1);
-
- host.setProviders([sandboxEntry({ provider, status: 'ready' })]);
- await act(async () => {
- await vi.advanceTimersByTimeAsync(9_999);
- });
- expect(host.getListCalls()).toBe(1);
-
- await act(async () => {
- await vi.advanceTimersByTimeAsync(1);
- });
- expect(host.getListCalls()).toBe(2);
- expect(screen.getByText('Connected')).toBeTruthy();
-
- await act(async () => {
- await vi.advanceTimersByTimeAsync(20_000);
- });
- expect(host.getListCalls()).toBe(2);
- });
-
- it('renders snapshot status badges and exposes failed status reason in a tooltip', async () => {
- const provider: UiSandboxProvider = {
- id: 'sb-1',
- name: 'Daytona',
- catalogId: 'cat-daytona',
- isConnected: true,
- execTimeoutMs: 60000,
- autoStopIntervalInMinutes: 30,
- autoArchiveIntervalInMinutes: 1440,
- autoDeleteIntervalInMinutes: 10080,
- };
- const host = createFakeHost([
- sandboxEntry({
- provider,
- status: 'failed',
- statusReason: 'Snapshot image could not be built',
- }),
- ]);
- const { wrapper: Wrapper } = host;
- render(
- <Wrapper>
- <SandboxSettings />
- </Wrapper>,
- );
-
- await waitFor(() => {
- expect(screen.getByText('Sync failed')).toBeTruthy();
- });
- expect(screen.queryByText('Connected')).toBeNull();
-
- fireEvent.mouseEnter(screen.getByLabelText('Snapshot sync status details'));
- await waitFor(() => {
- expect(screen.getByRole('tooltip')).toHaveTextContent('Snapshot image could not be built');
- });
-
- fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
- await waitFor(() => {
- expect(host.updated).toHaveLength(1);
- });
- expect(host.updated[0]).toEqual({
- id: 'sb-1',
- execTimeoutMs: 60000,
- autoStopIntervalInMinutes: 30,
- autoArchiveIntervalInMinutes: 1440,
- autoDeleteIntervalInMinutes: 10080,
- });
- expect(host.updated[0]).not.toHaveProperty('apiKey');
- });
});
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.test.ts
index 5bbdecc32..4dfde77fd 100644
--- a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.test.ts
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.test.ts
@@ -1,4 +1,3 @@
-import { TrueForgeApi } from '@truefoundry/trueforge-sdk';
import assert from 'node:assert/strict';
import { describe, it } from 'vitest';
@@ -9,7 +8,6 @@ import {
toHarnessManifest,
toUiCatalogEntry,
toUiSandboxProvider,
- toUiSandboxProviderListEntry,
} from '@/plugins/trueforge-agent-server-adapter/catalogs/sandboxProviderCatalog.js';
describe('sandboxProviderCatalog mappers', () => {
@@ -26,20 +24,6 @@ describe('sandboxProviderCatalog mappers', () => {
auth: { apiKey: 'dtn_secret' },
};
- function configuredResponse({
- status,
- statusReason,
- }: {
- status: TrueForgeApi.SandboxBuildStatus;
- statusReason: string | null;
- }): TrueForgeApi.GetSandboxProviderResponse['data'] {
- return {
- manifest: harnessConfigured,
- status,
- statusReason,
- };
- }
-
it('stamps catalog identity from type and strips auth', () => {
assert.deepEqual(toUiCatalogEntry(harnessCatalog), {
id: 'daytona',
@@ -67,32 +51,8 @@ describe('sandboxProviderCatalog mappers', () => {
assert.equal('apiKey' in toUiSandboxProvider(harnessConfigured), false);
});
- it('wraps configured providers with snapshot sync status', () => {
- for (const status of [
- TrueForgeApi.SandboxBuildStatus.Pending,
- TrueForgeApi.SandboxBuildStatus.Ready,
- TrueForgeApi.SandboxBuildStatus.Failed,
- ]) {
- const statusReason = status === TrueForgeApi.SandboxBuildStatus.Failed ? 'Snapshot build failed' : null;
- const entry = toUiSandboxProviderListEntry(configuredResponse({ status, statusReason }));
-
- assert.equal(entry.snapshotSyncStatus.status, status);
- assert.deepEqual(entry.data, toUiSandboxProvider(harnessConfigured));
- if (statusReason) {
- assert.equal(entry.snapshotSyncStatus.statusReason, statusReason);
- } else {
- assert.equal('statusReason' in entry.snapshotSyncStatus, false);
- }
- }
- });
-
- it('filters wrapped providers by provider identity', () => {
- const provider = toUiSandboxProviderListEntry(
- configuredResponse({
- status: TrueForgeApi.SandboxBuildStatus.Ready,
- statusReason: null,
- }),
- );
+ it('filters providers by provider identity', () => {
+ const provider = toUiSandboxProvider(harnessConfigured);
assert.deepEqual(filterUiSandboxProviders({ providers: [provider], query: ' DAYT ' }), [provider]);
assert.deepEqual(filterUiSandboxProviders({ providers: [provider], query: 'missing' }), []);
diff --git a/packages/trueforge/scripts/write-openapi.ts b/packages/trueforge/scripts/write-openapi.ts
index f07bfdec3..69a280743 100644
--- a/packages/trueforge/scripts/write-openapi.ts
+++ b/packages/trueforge/scripts/write-openapi.ts
@@ -89,6 +89,7 @@ const app = createServerApp({
resolveImportAgentStore: () => agentStore,
agentStore,
sandboxEnvironmentStore,
+ sandboxProviderStore,
turnSkillsResolverStore: skillStore,
withTransaction: callback => db.transaction().execute(callback),
scheduleStore: new SqliteScheduleStore(db),
diff --git a/packages/trueforge/src/apis/capabilities.ts b/packages/trueforge/src/apis/capabilities.ts
index fdabd8906..acb4c10b1 100644
--- a/packages/trueforge/src/apis/capabilities.ts
+++ b/packages/trueforge/src/apis/capabilities.ts
@@ -1,22 +1,21 @@
import { OpenAPIHono } from '@hono/zod-openapi';
-import { extractErrorLogFields } from '@truefoundry/trueforge-core/core';
import type { Context } from 'hono';
import type { Logger } from 'winston';
import { hasAdminRole, type ResolveRequestContext } from '../auth/identity';
-import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
import type { WithTransaction } from '../db/transaction';
import type { IWebSearchProviderStore } from '../db/webSearchProviderStore';
import { getCapabilitiesRoute } from '../routes/capabilityRoutes';
import { isLocalSandboxFallbackEnabled } from '../sandbox/localRuntime';
-import { checkSnapshotStatus } from '../sandbox/providerUtils';
-import type { SandboxBuildStatus } from '../schemas/sandboxProvider';
+import { DEFAULT_SANDBOX_ENVIRONMENT_NAME, type SandboxEnvironmentVersionStatus } from '../schemas/sandboxEnvironment';
+import { hasTrueFoundrySandboxProviderConfig } from '../truefoundry/resolveTrueFoundrySandboxProviderConfig';
import { hasConfiguredWebSearchProvider } from '../websearch/providers';
/**
- * Why skills are unavailable, keyed off the sandbox build status.
- * `pending` is transient (retry); everything else (no provider / failed / unknown) reads as not configured.
+ * Why skills are unavailable, keyed off the default sandbox environment status.
+ * `pending` is transient (retry); everything else (missing / failed) reads as not configured.
*/
-function skillDisabledReason(status: SandboxBuildStatus | undefined): string {
+function skillDisabledReason(status: SandboxEnvironmentVersionStatus | undefined): string {
if (status === 'pending') {
return 'Skills run in a sandbox whose image is still being prepared — retry shortly.';
}
@@ -24,7 +23,7 @@ function skillDisabledReason(status: SandboxBuildStatus | undefined): string {
}
export function createCapabilitiesRouter<TTransaction>(deps: {
- resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
resolveWebSearchProviderStore: (c: Context) => IWebSearchProviderStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
logger: Logger;
@@ -33,20 +32,17 @@ export function createCapabilitiesRouter<TTransaction>(deps: {
const router = new OpenAPIHono();
router.openapi(getCapabilitiesRoute, async c => {
const requestContext = deps.resolveRequestContext(c);
- // Sandbox is usable only when a provider is configured AND its image build reports ready.
- // Refresh the persisted status (and re-activate an idle snapshot); fail closed (disabled) if it throws.
- let status: SandboxBuildStatus | undefined;
- try {
- const refreshed = await checkSnapshotStatus({
- store: deps.resolveSandboxProviderStore(c),
- tenant_id: requestContext.tenant_id,
- logger: deps.logger,
- });
- status = refreshed?.status;
- } catch (error) {
- deps.logger.warn('Sandbox image status check failed; reporting sandbox disabled', extractErrorLogFields(error));
- }
- const sandboxEnabled = status === 'ready' || (status === undefined && isLocalSandboxFallbackEnabled());
+ const defaultEnv = await deps.sandboxEnvironmentStore.getEnvironment({
+ tenant_id: requestContext.tenant_id,
+ name: DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ });
+ const status = defaultEnv?.version.status;
+ // Shared TFY provider (incl. on-prem with no env tip), ready default env, or local fallback.
+ // hasTrueFoundrySandboxProviderConfig never throws — incomplete TFY settings stay "disabled".
+ const sandboxEnabled =
+ hasTrueFoundrySandboxProviderConfig() ||
+ status === 'ready' ||
+ (defaultEnv === undefined && isLocalSandboxFallbackEnabled());
const settingsEnabled = hasAdminRole(requestContext);
const webSearchEnabled = await hasConfiguredWebSearchProvider({
tenant_id: requestContext.tenant_id,
diff --git a/packages/trueforge/src/apis/sandboxEnvironmentBuild.ts b/packages/trueforge/src/apis/sandboxEnvironmentBuild.ts
new file mode 100644
index 000000000..943933186
--- /dev/null
+++ b/packages/trueforge/src/apis/sandboxEnvironmentBuild.ts
@@ -0,0 +1,54 @@
+/**
+ * Internal API for the sandbox-environment build controller.
+ */
+import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
+import { HTTPException } from 'hono/http-exception';
+import type { Logger } from 'winston';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
+import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
+import {
+ listPendingSandboxEnvironmentVersionsRoute,
+ progressSandboxEnvironmentVersionRoute,
+} from '../routes/sandboxEnvironmentBuildRoutes';
+import { progressSandboxEnvironmentVersion } from '../sandbox/progressSandboxEnvironmentVersion';
+
+export interface SandboxEnvironmentBuildRouterDeps {
+ sandboxEnvironmentStore: ISandboxEnvironmentStore;
+ sandboxProviderStore: ISandboxProviderStore;
+ logger: Logger;
+}
+
+export function createSandboxEnvironmentBuildRouter(deps: SandboxEnvironmentBuildRouterDeps) {
+ const listHandler: RouteHandler<typeof listPendingSandboxEnvironmentVersionsRoute> = async c => {
+ const pending = await deps.sandboxEnvironmentStore.listLatestPendingVersions();
+ return c.json(
+ {
+ data: pending.map(environment_version_id => ({ environment_version_id })),
+ },
+ 200,
+ );
+ };
+
+ const progressHandler: RouteHandler<typeof progressSandboxEnvironmentVersionRoute> = async c => {
+ const body = c.req.valid('json');
+ try {
+ await progressSandboxEnvironmentVersion({
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
+ sandboxProviderStore: deps.sandboxProviderStore,
+ environment_version_id: body.environment_version_id,
+ logger: deps.logger,
+ });
+ return c.body(null, 204);
+ } catch (error) {
+ if (error instanceof HTTPException && error.status === 404) {
+ return c.json({ error: { message: 'Sandbox environment version not found' } }, 404);
+ }
+ throw error;
+ }
+ };
+
+ const router = new OpenAPIHono();
+ router.openapi(listPendingSandboxEnvironmentVersionsRoute, listHandler);
+ router.openapi(progressSandboxEnvironmentVersionRoute, progressHandler);
+ return router;
+}
diff --git a/packages/trueforge/src/apis/sandboxEnvironments.ts b/packages/trueforge/src/apis/sandboxEnvironments.ts
index 74685ffcc..e735d485f 100644
--- a/packages/trueforge/src/apis/sandboxEnvironments.ts
+++ b/packages/trueforge/src/apis/sandboxEnvironments.ts
@@ -23,7 +23,11 @@ import {
putSandboxEnvironmentRoute,
} from '../routes/sandboxEnvironmentRoutes';
import { buildNextVersion, redactManifestSecrets } from '../sandbox/sandboxEnvironmentVersion';
-import type { SandboxEnvironment, SandboxEnvironmentManifest } from '../schemas/sandboxEnvironment';
+import {
+ DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ type SandboxEnvironment,
+ type SandboxEnvironmentManifest,
+} from '../schemas/sandboxEnvironment';
import { MissingStoredSecretError } from '../utils/secretRedaction';
export interface SandboxEnvironmentsRouterDeps<TTransaction> {
@@ -113,10 +117,11 @@ export function createSandboxEnvironmentsRouter<TTransaction>(
const getHandler: RouteHandler<typeof getSandboxEnvironmentRoute> = async c => {
const { tenant_id, subject } = resolveRequestContext(c);
const { name } = c.req.valid('param');
+ // System default is tenant-wide; custom envs stay owner-scoped.
const loaded = await store.getEnvironment({
tenant_id,
name,
- created_by_subject_id: subject.id,
+ ...(name === DEFAULT_SANDBOX_ENVIRONMENT_NAME ? {} : { created_by_subject_id: subject.id }),
});
if (!loaded) {
return c.json({ error: { message: `Sandbox environment not found: ${name}` } }, 404);
@@ -129,8 +134,8 @@ export function createSandboxEnvironmentsRouter<TTransaction>(
const body = c.req.valid('json');
const requestContext = resolveRequestContext(c);
const provider = await resolveSandboxProviderRecord(deps.resolveSandboxProviderStore(c), requestContext.tenant_id);
- if (provider?.manifest.type !== 'daytona') {
- return c.json({ error: { message: 'Sandbox environments require a Daytona sandbox provider' } }, 422);
+ if (provider === undefined) {
+ return c.json({ error: { message: 'No sandbox provider configured' } }, 422);
}
const created_by_subject = createdBySubjectFromRequestContext(requestContext);
@@ -167,6 +172,9 @@ export function createSandboxEnvironmentsRouter<TTransaction>(
const deleteHandler: RouteHandler<typeof deleteSandboxEnvironmentRoute> = async c => {
const { tenant_id, subject } = resolveRequestContext(c);
const { name } = c.req.valid('param');
+ if (name === DEFAULT_SANDBOX_ENVIRONMENT_NAME) {
+ return c.json({ error: { message: 'Sandbox environment "default" cannot be deleted' } }, 409);
+ }
const existing = await store.getEnvironment({
tenant_id,
name,
diff --git a/packages/trueforge/src/apis/sandboxProviders.ts b/packages/trueforge/src/apis/sandboxProviders.ts
index 3b713ca02..70f911630 100644
--- a/packages/trueforge/src/apis/sandboxProviders.ts
+++ b/packages/trueforge/src/apis/sandboxProviders.ts
@@ -1,26 +1,19 @@
import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
-import { withTimeout } from '@truefoundry/trueforge-core/core';
import type { Context } from 'hono';
import type { Logger } from 'winston';
-import type { ResolveRequestContext } from '../auth/identity';
+import { createdBySubjectFromRequestContext, type ResolveRequestContext } from '../auth/identity';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
import type { ISandboxProviderStore, SandboxProviderRecord } from '../db/sandboxProviderStore';
import type { WithTransaction } from '../db/transaction';
import { getSandboxProviderRoute, putSandboxProviderRoute } from '../routes/sandboxProviderRoutes';
-import {
- checkSnapshotStatus,
- isDaytonaAuthError,
- isDaytonaPermissionError,
- toDaytonaSandboxProvider,
- toSandboxStatus,
-} from '../sandbox/providerUtils';
+import { ensureDefaultSandboxEnvironment } from '../sandbox/ensureDefaultSandboxEnvironment';
+import { isDaytonaAuthError, isDaytonaPermissionError, validateSandboxProviderAccess } from '../sandbox/providerUtils';
import type { SandboxProviderManifest, UpdateSandboxProviderRequest } from '../schemas/sandboxProvider';
import { MissingStoredSecretError, resolveStoredSecretValue, toRedactedSecretValue } from '../utils/secretRedaction';
-/** Cap the Daytona register round-trip so a slow/unreachable provider can't hold the request (or DB txn) open. */
-const BUILD_REQUEST_TIMEOUT_MS = 3_000;
-
export interface SandboxProvidersRouterDeps<TTransaction> {
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
logger: Logger;
resolveRequestContext: ResolveRequestContext;
@@ -33,6 +26,15 @@ function redactSandboxProvider(manifest: SandboxProviderManifest): SandboxProvid
};
}
+/** Settings API is Daytona-only; TFY may synthesize a `truefoundry` row without `auth`. */
+function storedApiKey(record: SandboxProviderRecord | undefined): string | undefined {
+ const manifest = record?.manifest;
+ if (manifest?.type !== 'daytona') {
+ return undefined;
+ }
+ return manifest.auth.api_key;
+}
+
/** Admin/settings sandbox provider surface (mounted at /api/v1/settings/sandbox-providers). */
export function createSandboxProvidersRouter<TTransaction>(deps: SandboxProvidersRouterDeps<TTransaction>) {
const getHandler: RouteHandler<typeof getSandboxProviderRoute> = async c => {
@@ -42,18 +44,10 @@ export function createSandboxProvidersRouter<TTransaction>(deps: SandboxProvider
if (record?.manifest.type !== 'daytona') {
return c.json({ error: { message: 'No sandbox provider configured' } }, 404);
}
- // Refresh the persisted build status (and re-activate an idle snapshot) on every GET.
- const status = await checkSnapshotStatus({
- store,
- tenant_id: requestContext.tenant_id,
- logger: deps.logger,
- });
return c.json(
{
data: {
manifest: redactSandboxProvider(record.manifest),
- status: status?.status ?? record.status,
- status_reason: status?.status_reason ?? record.status_reason,
},
},
200,
@@ -70,38 +64,48 @@ export function createSandboxProvidersRouter<TTransaction>(deps: SandboxProvider
auth: {
api_key: resolveStoredSecretValue({
incoming: incoming.auth.api_key,
- existing: existing?.manifest.type === 'daytona' ? existing.manifest.auth.api_key : undefined,
+ existing: storedApiKey(existing),
}),
},
});
try {
- // NOTE: build (Daytona network I/O) runs inside the transaction for now; the design is being revisited.
- const { manifest, status } = await deps.withTransaction(async transaction => {
+ const existing = await store.getSandboxProvider(requestContext.tenant_id);
+ const resolved = resolveManifest(existing);
+ await validateSandboxProviderAccess({
+ manifest: resolved,
+ tenant_id: requestContext.tenant_id,
+ logger: deps.logger,
+ });
+
+ const manifest = await deps.withTransaction(async transaction => {
const locked = await store.getSandboxProviderForUpdate(requestContext.tenant_id, transaction);
- const resolved = resolveManifest(locked);
- // Pass persisted build_metadata so a settings re-save does not start a new snapshot for a
- // bumped SANDBOX_IMAGE_URI (upgrades are unsupported — first configure has no metadata).
- const provider = toDaytonaSandboxProvider({
- manifest: resolved,
- tenant_id: requestContext.tenant_id,
- logger: deps.logger,
- ...(locked ? { build_metadata: locked.build_metadata } : {}),
- });
- const built = toSandboxStatus(
- await withTimeout(provider.buildImage(), BUILD_REQUEST_TIMEOUT_MS, 'sandbox buildImage'),
- );
+ const lockedResolved = resolveManifest(locked);
+ const previousKey = storedApiKey(locked);
+ const keyChanged = previousKey !== undefined && previousKey !== lockedResolved.auth.api_key;
+
await store.upsertSandboxProvider(
- { tenant_id: requestContext.tenant_id, manifest: resolved, ...built },
+ {
+ tenant_id: requestContext.tenant_id,
+ manifest: lockedResolved,
+ },
transaction,
);
- return { manifest: resolved, status: built };
+
+ await ensureDefaultSandboxEnvironment({
+ store: deps.sandboxEnvironmentStore,
+ tenant_id: requestContext.tenant_id,
+ created_by_subject: createdBySubjectFromRequestContext(requestContext),
+ provider_type: lockedResolved.type,
+ resetPending: keyChanged,
+ transaction,
+ });
+
+ return lockedResolved;
});
return c.json(
{
data: {
manifest: redactSandboxProvider(manifest),
- status: status.status,
- status_reason: status.status_reason,
},
},
200,
@@ -111,14 +115,14 @@ export function createSandboxProvidersRouter<TTransaction>(deps: SandboxProvider
return c.json({ error: { message: 'API key is required' } }, 400);
}
if (isDaytonaAuthError(error)) {
- return c.json({ error: { message: 'Daytona rejected the API key — check the credentials' } }, 422);
+ return c.json({ error: { message: 'Sandbox provider rejected the API key — check the credentials' } }, 422);
}
if (isDaytonaPermissionError(error)) {
return c.json(
{
error: {
message:
- 'Daytona denied access: the API key is missing required permissions. Grant write:sandboxes, write:snapshots, and delete:snapshots on the key in the Daytona dashboard, then try again.',
+ 'Sandbox provider denied access: the API key is missing required permissions. Grant write:sandboxes, write:snapshots, and delete:snapshots on the key, then try again.',
},
},
422,
diff --git a/packages/trueforge/src/apis/settings.ts b/packages/trueforge/src/apis/settings.ts
index e6e9e4667..2fa3e87e3 100644
--- a/packages/trueforge/src/apis/settings.ts
+++ b/packages/trueforge/src/apis/settings.ts
@@ -9,6 +9,7 @@ import type { Logger } from 'winston';
import type { ResolveRequestContext } from '../auth/identity';
import type { IMcpServerWithAuthStore } from '../db/mcpServerStore';
import type { IModelProviderStore } from '../db/modelProviderStore';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
import type { WithTransaction } from '../db/transaction';
import type { IWebSearchProviderStore } from '../db/webSearchProviderStore';
@@ -25,6 +26,7 @@ export interface SettingsRouterDeps<TTransaction> {
tokenStore: IOAuthTokenStore<TTransaction>;
resolveSkillStore: ResolveSkillStore<TTransaction>;
resolveSandboxProviderStore: (c: Context) => ISandboxProviderStore<TTransaction>;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
resolveWebSearchProviderStore: (c: Context) => IWebSearchProviderStore<TTransaction>;
withTransaction: WithTransaction<TTransaction>;
logger: Logger;
@@ -63,6 +65,7 @@ export function createSettingsRouter<TTransaction>(deps: SettingsRouterDeps<TTra
'/sandbox-providers',
createSandboxProvidersRouter({
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
withTransaction: deps.withTransaction,
logger: deps.logger,
resolveRequestContext: deps.resolveRequestContext,
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index efeb23427..8b6e1a2c7 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -59,9 +59,10 @@ import {
buildTurnSandbox,
getMcpConnection,
getModelDetails,
+ resolveSandboxEnvironment,
resolveSandboxProvider,
} from '../runtime/sessionResources';
-import { checkSnapshotStatus } from '../sandbox/providerUtils';
+import { DEFAULT_SANDBOX_ENVIRONMENT_NAME } from '../schemas/sandboxEnvironment';
import { MAX_SESSION_TITLE_LENGTH } from '../schemas/session';
import { assertGatewayMetadataRequestHeaders } from '../truefoundry/gatewayMetadata';
import { newId } from '../utils/id';
@@ -230,38 +231,17 @@ function createTurnResolver(deps: {
mcpConnectTimeoutMs: configuration.MCP_CONNECT_TIMEOUT_MS,
mcpMaxResponseBytes: configuration.MCP_TOOL_CALL_MAX_RESPONSE_BYTES,
sandboxProvider: async ({ spec, existingSandboxId, tracing }) => {
- const environment_name = spec.config.sandbox.environment_name;
- const resolved = await resolveSandboxProvider({
+ const provider = await resolveSandboxProvider({
tenant_id,
store: sandboxProviderStore,
logger,
sessionId,
- sandboxEnvironmentStore,
- environment_name,
});
- if (resolved === undefined) {
+ if (provider === undefined) {
throw new HTTPException(422, {
message: 'no sandbox provider configured — PUT /settings/sandbox-providers',
});
}
- const { provider, usesEnvironmentSnapshot } = resolved;
- const carriedSandboxId = existingSandboxIdForProvider({
- existingSandboxId,
- currentProviderType: provider.type,
- });
- // Fresh non-local create: env snapshot readiness is gated in resolveSandboxProvider;
- // release snapshot still needs tenant provider status when not using an env build.
- if (carriedSandboxId === undefined && provider.type !== 'local' && !usesEnvironmentSnapshot) {
- const status = await checkSnapshotStatus({ store: sandboxProviderStore, tenant_id, logger });
- if (status?.status !== 'ready') {
- throw new HTTPException(422, {
- message:
- status?.status === 'failed'
- ? `sandbox image build failed (${status.status_reason ?? 'unknown error'})`
- : 'sandbox image is activating — retry shortly',
- });
- }
- }
const skills = spec.skills ?? [];
const mountSkills =
skills.length === 0
@@ -270,13 +250,34 @@ function createTurnResolver(deps: {
tenant_id,
skills,
});
- return buildTurnSandbox({
- provider,
+ const carriedSandboxId = existingSandboxIdForProvider({
+ existingSandboxId,
+ currentProviderType: provider.type,
+ });
+ const turnSandboxBase = {
logger,
skills: mountSkills,
fileDownloadEnabled: spec.config.sandbox.file_downloads,
existingSandboxId: carriedSandboxId,
tracing,
+ };
+ // Env-capable providers (Daytona): resolve env. Others skip (no snapshot concept).
+ if (provider.envSupported) {
+ const environment = await resolveSandboxEnvironment({
+ tenant_id,
+ name: spec.config.sandbox.environment_name ?? DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ sandboxEnvironmentStore,
+ optional: spec.config.sandbox.environment_name === undefined,
+ });
+ return buildTurnSandbox({
+ provider,
+ ...(environment !== undefined ? { environment } : {}),
+ ...turnSandboxBase,
+ });
+ }
+ return buildTurnSandbox({
+ provider,
+ ...turnSandboxBase,
});
},
agent: async agentId => {
@@ -677,20 +678,18 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
return c.json({ error: { message: `Turn has no sandbox: ${turnId}` } }, 412);
}
- const resolved = await resolveSandboxProvider({
+ const provider = await resolveSandboxProvider({
tenant_id: requestContext.tenant_id,
store: deps.resolveSandboxProviderStore(c),
logger: deps.logger,
sessionId,
- sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
- environment_name: undefined,
});
- if (resolved === undefined) {
+ if (provider === undefined) {
return c.json({ error: { message: 'No sandbox provider configured' } }, 412);
}
// TODO: stream the body instead of buffering the whole file in memory.
- const content = await resolved.provider.downloadFile({ sandboxId: rawSandboxId(sandboxId), path });
+ const content = await provider.downloadFile({ sandboxId: rawSandboxId(sandboxId), path });
return c.body(toArrayBuffer(content), 200, {
'Content-Type': 'application/octet-stream',
'Content-Length': String(content.byteLength),
diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.ts
index 0f9897263..c1bbdef16 100644
--- a/packages/trueforge/src/app.ts
+++ b/packages/trueforge/src/app.ts
@@ -18,6 +18,7 @@ import { createMcpOAuthRouter } from './apis/mcpOAuth';
import { createMcpServersRouter } from './apis/mcpServers';
import { createModelsRouter } from './apis/models';
import { createPermissionsRouter } from './apis/permissions';
+import { createSandboxEnvironmentBuildRouter } from './apis/sandboxEnvironmentBuild';
import { createSandboxEnvironmentsRouter } from './apis/sandboxEnvironments';
import { createScheduleExecutionRouter, createSchedulesRouter } from './apis/schedules';
import { createInternalMetricsRouter } from './apis/sessionMetrics';
@@ -210,6 +211,11 @@ export interface ServerDeps<TTransaction> {
agentStore: IAgentStore<TTransaction>;
/** Sandbox environment parent + version persistence (no TrueFoundry dual-write). */
sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
+ /**
+ * Context-free sandbox provider store for internal build progress (persistence or TFY).
+ * Same backing store as resolveSandboxProviderStore, without request context.
+ */
+ sandboxProviderStore: ISandboxProviderStore<TTransaction>;
/** Resolve turn skills - persistence store or TrueFoundry resolve with Service API key (schedule runs do have any caller token). */
turnSkillsResolverStore: Pick<ISkillStore<TTransaction>, 'resolveTurnSkills'>;
sessions: Sessions;
@@ -272,7 +278,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
'/api/v1/capabilities',
withAuth(
createCapabilitiesRouter({
- resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
resolveWebSearchProviderStore: deps.resolveWebSearchProviderStore,
withTransaction: deps.withTransaction,
logger: deps.logger,
@@ -374,6 +380,17 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
'/api/internal/schedules',
withAuth(createScheduleExecutionRouter(scheduleTurnDeps), scheduleExecutionAuthMiddleware),
);
+ app.route(
+ '/api/internal/sandbox-environments',
+ withAuth(
+ createSandboxEnvironmentBuildRouter({
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
+ sandboxProviderStore: deps.sandboxProviderStore,
+ logger: deps.logger,
+ }),
+ scheduleExecutionAuthMiddleware,
+ ),
+ );
app.route(
'/api/v1/schedules',
withAuth(
@@ -396,6 +413,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
tokenStore: deps.tokenStore,
resolveSkillStore: deps.resolveSkillStore,
resolveSandboxProviderStore: deps.resolveSandboxProviderStore,
+ sandboxEnvironmentStore: deps.sandboxEnvironmentStore,
resolveWebSearchProviderStore: deps.resolveWebSearchProviderStore,
withTransaction: deps.withTransaction,
logger: deps.logger,
diff --git a/packages/trueforge/src/controller.ts b/packages/trueforge/src/controller.ts
index 61c13c8ee..21e5958f6 100644
--- a/packages/trueforge/src/controller.ts
+++ b/packages/trueforge/src/controller.ts
@@ -1,5 +1,6 @@
import type { Logger } from 'winston';
import { Controller } from './controller/Controller';
+import { sandboxEnvBuildLoop } from './controller/sandboxEnvBuild';
import { scheduleDispatchLoop } from './controller/scheduleDispatch';
import type { IScheduleStore } from './db/scheduleStore';
import type { WithTransaction } from './db/transaction';
@@ -8,6 +9,7 @@ import type { WithTransaction } from './db/transaction';
* Controller whose schedule loop hands runs to the server over HTTP
* (`SERVER_URL` + `TRUEFORGE_API_KEY` from process config). Standalone uses
* loopback; distributed uses the dedicated controller against the server Service.
+ * Sandbox-env build loop lists/progresses pending versions over the same HTTP path.
*/
export function createController<TTransaction>(params: {
scheduleStore: IScheduleStore<TTransaction>;
@@ -21,6 +23,7 @@ export function createController<TTransaction>(params: {
withTransaction: params.withTransaction,
logger: params.logger,
}),
+ sandboxEnvBuildLoop({ logger: params.logger }),
],
logger: params.logger,
});
diff --git a/packages/trueforge/src/controller/internalTrueForgeClient.ts b/packages/trueforge/src/controller/internalTrueForgeClient.ts
new file mode 100644
index 000000000..36570085f
--- /dev/null
+++ b/packages/trueforge/src/controller/internalTrueForgeClient.ts
@@ -0,0 +1,38 @@
+/**
+ * Shared TrueForge SDK client for controller → server HTTP handoff (mTLS + API key).
+ */
+import { TrueForge } from '@truefoundry/trueforge-sdk';
+import configuration from '../config';
+import { createTlsFetch, normalizeTlsUrl } from '../http/tls';
+
+function createClient(): TrueForge {
+ const tls = {
+ enabled: configuration.MTLS_ENABLED,
+ dir: configuration.MTLS_CERTS_DIR,
+ };
+ const tlsFetch = createTlsFetch(tls);
+ return new TrueForge({
+ baseUrl: normalizeTlsUrl({ url: configuration.SERVER_URL, enabled: tls.enabled }),
+ token: configuration.TRUEFORGE_API_KEY,
+ timeoutInSeconds: 60,
+ ...(tlsFetch === undefined ? {} : { fetch: tlsFetch }),
+ });
+}
+
+const client = createClient();
+
+/** Controller loops share this client for all internal HTTP handoffs. */
+export const internalTrueForgeClient = {
+ async executeScheduleRun(scheduleRunId: string): Promise<void> {
+ await client.internal.schedules.executeRun({ scheduleRunId });
+ },
+
+ async listPendingSandboxEnvironmentVersions(): Promise<string[]> {
+ const response = await client.internal.sandboxEnvironments.listPending();
+ return response.data.map(row => row.environmentVersionId);
+ },
+
+ async progressSandboxEnvironmentVersion(environmentVersionId: string): Promise<void> {
+ await client.internal.sandboxEnvironments.progress({ environmentVersionId });
+ },
+};
diff --git a/packages/trueforge/src/controller/sandboxEnvBuild.ts b/packages/trueforge/src/controller/sandboxEnvBuild.ts
new file mode 100644
index 000000000..3c0973e84
--- /dev/null
+++ b/packages/trueforge/src/controller/sandboxEnvBuild.ts
@@ -0,0 +1,57 @@
+/**
+ * Control loop: list pending sandbox-env versions and hand each to the server over HTTP.
+ */
+import { TrueForgeApi } from '@truefoundry/trueforge-sdk';
+import type { Logger } from 'winston';
+import { captureCriticalException } from '../sentry';
+import type { ControlLoop } from './Controller';
+import { internalTrueForgeClient } from './internalTrueForgeClient';
+
+const SANDBOX_ENV_BUILD_INTERVAL_MS = 5_000;
+const SANDBOX_ENV_BUILD_LOOP_NAME = 'sandbox-env-build';
+
+export async function dispatchSandboxEnvBuilds({ logger }: { logger: Logger }): Promise<void> {
+ const pending = await internalTrueForgeClient.listPendingSandboxEnvironmentVersions();
+ logger.info('Sandbox environment build tick', { pending_count: pending.length });
+ for (const environmentVersionId of pending) {
+ logger.info('Progressing sandbox environment version', { environment_version_id: environmentVersionId });
+ try {
+ await internalTrueForgeClient.progressSandboxEnvironmentVersion(environmentVersionId);
+ logger.info('Sandbox environment version progress completed', {
+ environment_version_id: environmentVersionId,
+ });
+ } catch (error) {
+ if (error instanceof TrueForgeApi.NotFoundError) {
+ logger.warn('Sandbox environment version not found; skipping', {
+ environment_version_id: environmentVersionId,
+ });
+ captureCriticalException(error, {
+ tags: { module: 'sandboxEnvBuild', operation: 'progressNotFound' },
+ extra: { environment_version_id: environmentVersionId },
+ });
+ continue;
+ }
+ logger.error('Sandbox environment version progress failed', {
+ environment_version_id: environmentVersionId,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ captureCriticalException(error, {
+ tags: { module: 'sandboxEnvBuild', operation: 'progress' },
+ extra: { environment_version_id: environmentVersionId },
+ });
+ }
+ }
+}
+
+export function sandboxEnvBuildLoop(params: { logger: Logger }): ControlLoop {
+ return {
+ name: SANDBOX_ENV_BUILD_LOOP_NAME,
+ intervalMs: SANDBOX_ENV_BUILD_INTERVAL_MS,
+ async tick(signal) {
+ if (signal.aborted) {
+ return;
+ }
+ await dispatchSandboxEnvBuilds({ logger: params.logger });
+ },
+ };
+}
diff --git a/packages/trueforge/src/controller/scheduleDispatch.ts b/packages/trueforge/src/controller/scheduleDispatch.ts
index 3a8c11d83..7407d097f 100644
--- a/packages/trueforge/src/controller/scheduleDispatch.ts
+++ b/packages/trueforge/src/controller/scheduleDispatch.ts
@@ -1,7 +1,5 @@
import type { SessionHandle, Sessions, TurnInputItem } from '@truefoundry/trueforge-core/agent-session';
-import { TrueForge } from '@truefoundry/trueforge-sdk';
import type { Logger } from 'winston';
-import configuration from '../config';
import type { AgentRecord, IAgentStore } from '../db/agentStore';
import {
cronRunName,
@@ -10,11 +8,11 @@ import {
type ScheduleRunRecord,
} from '../db/scheduleStore';
import type { WithTransaction } from '../db/transaction';
-import { createTlsFetch, normalizeTlsUrl } from '../http/tls';
import { nextTriggerAfter } from '../runtime/cron';
import { InvalidCronError, type ScheduleRunStatus } from '../schemas/schedule';
import { captureCriticalException } from '../sentry';
import type { ControlLoop } from './Controller';
+import { internalTrueForgeClient } from './internalTrueForgeClient';
/**
* Rows examined per pass.
@@ -44,22 +42,6 @@ const SCHEDULE_DISPATCH_LOOP_NAME = 'schedule-dispatch';
export type ScheduleRunExecutor = (scheduleRunId: string) => Promise<void>;
-/** HTTP handoff to `POST /api/internal/schedules/runs/execute` (dedicated controller or standalone loopback). */
-export function createHttpScheduleRunExecutor(): ScheduleRunExecutor {
- const tls = {
- enabled: configuration.MTLS_ENABLED,
- dir: configuration.MTLS_CERTS_DIR,
- };
- const tlsFetch = createTlsFetch(tls);
- const client = new TrueForge({
- baseUrl: normalizeTlsUrl({ url: configuration.SERVER_URL, enabled: tls.enabled }),
- token: configuration.TRUEFORGE_API_KEY,
- timeoutInSeconds: 60,
- ...(tlsFetch === undefined ? {} : { fetch: tlsFetch }),
- });
- return scheduleRunId => client.internal.schedules.executeRun({ scheduleRunId });
-}
-
/** Schedule's bound agent name is missing from the agent store. */
export class ScheduleAgentNotFoundError extends Error {
readonly agent_name: string;
@@ -358,14 +340,13 @@ export function scheduleDispatchLoop<TTransaction>(params: {
withTransaction: WithTransaction<TTransaction>;
}): ControlLoop {
const { scheduleStore, withTransaction, logger } = params;
- const executeRun = createHttpScheduleRunExecutor();
return {
name: SCHEDULE_DISPATCH_LOOP_NAME,
intervalMs: SCHEDULE_DISPATCH_INTERVAL_MS,
async tick(signal: AbortSignal): Promise<void> {
const result = await dispatchScheduledRuns({
store: scheduleStore,
- onTriggered: item => executeRun(item.run.id),
+ onTriggered: item => internalTrueForgeClient.executeScheduleRun(item.run.id),
logger,
withTransaction,
signal,
diff --git a/packages/trueforge/src/db/postgres/migrations/20260929_000001_sandbox_environment_default_backfill.ts b/packages/trueforge/src/db/postgres/migrations/20260929_000001_sandbox_environment_default_backfill.ts
new file mode 100644
index 000000000..594a6706c
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20260929_000001_sandbox_environment_default_backfill.ts
@@ -0,0 +1,126 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Backfill the tenant `"default"` sandbox environment for existing Daytona providers.
+ * New providers already create it on PUT; this covers tenants that configured a provider
+ * before sandbox environments existed.
+ *
+ * Version lands as `pending` so the build controller can activate the snapshot.
+ *
+ * Also drops provider-level build status columns — snapshot readiness lives on
+ * sandbox environment versions now.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+
+ await sql`
+ WITH providers AS (
+ SELECT tenant_id
+ FROM sandbox_provider
+ WHERE manifest->>'type' = 'daytona'
+ ),
+ missing AS (
+ SELECT p.tenant_id
+ FROM providers p
+ WHERE NOT EXISTS (
+ SELECT 1
+ FROM sandbox_environment e
+ WHERE e.tenant_id = p.tenant_id
+ AND e.name = 'default'
+ AND e.lifecycle_stage = 'active'
+ )
+ ),
+ inserted_env AS (
+ INSERT INTO sandbox_environment (
+ id,
+ tenant_id,
+ name,
+ description,
+ active_version,
+ lifecycle_stage,
+ created_by_subject,
+ created_at,
+ updated_at
+ )
+ SELECT
+ 'se_default_' || m.tenant_id,
+ m.tenant_id,
+ 'default',
+ '',
+ 1,
+ 'active',
+ jsonb_build_object(
+ 'subject_id', 'trueforge-system',
+ 'subject_type', 'user',
+ 'subject_display_name', 'TrueForge'
+ ),
+ NOW(),
+ NOW()
+ FROM missing m
+ RETURNING id, tenant_id
+ )
+ INSERT INTO sandbox_environment_version (
+ id,
+ environment_id,
+ version,
+ manifest,
+ status,
+ status_reason,
+ external_ref,
+ internal_metadata,
+ created_by_subject,
+ created_at,
+ updated_at
+ )
+ SELECT
+ ie.id || '_v1',
+ ie.id,
+ 1,
+ jsonb_build_object(
+ 'name', 'default',
+ 'resources', jsonb_build_object('cpu', 1, 'memory', 1, 'disk', 3),
+ 'type', 'daytona',
+ 'sandbox_provider', 'daytona'
+ ),
+ 'pending',
+ NULL,
+ 'trueforge-default-' || replace(ie.tenant_id, '/', '-'),
+ '{"secrets":[]}'::jsonb,
+ jsonb_build_object(
+ 'subject_id', 'trueforge-system',
+ 'subject_type', 'user',
+ 'subject_display_name', 'TrueForge'
+ ),
+ NOW(),
+ NOW()
+ FROM inserted_env ie
+ `.execute(db);
+
+ await db.schema
+ .alterTable('sandbox_provider')
+ .dropColumn('build_metadata')
+ .dropColumn('status_reason')
+ .dropColumn('status')
+ .execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+
+ await db.schema
+ .alterTable('sandbox_provider')
+ .addColumn('status', 'text', col => col.notNull().defaultTo('ready'))
+ .addColumn('status_reason', 'text')
+ .addColumn('build_metadata', 'jsonb')
+ .execute();
+
+ // Remove only rows this migration inserted (id prefix).
+ await sql`
+ DELETE FROM sandbox_environment_version
+ WHERE environment_id LIKE 'se_default_%'
+ `.execute(db);
+ await sql`
+ DELETE FROM sandbox_environment
+ WHERE id LIKE 'se_default_%'
+ `.execute(db);
+}
diff --git a/packages/trueforge/src/db/postgres/sandbox-environment-store/PostgresSandboxEnvironmentStore.ts b/packages/trueforge/src/db/postgres/sandbox-environment-store/PostgresSandboxEnvironmentStore.ts
index dd2ca7591..6a5c7bf3c 100644
--- a/packages/trueforge/src/db/postgres/sandbox-environment-store/PostgresSandboxEnvironmentStore.ts
+++ b/packages/trueforge/src/db/postgres/sandbox-environment-store/PostgresSandboxEnvironmentStore.ts
@@ -6,7 +6,10 @@ import {
import type { Kysely, Selectable, Transaction } from 'kysely';
import { sql } from 'kysely';
import { NameSchema } from '../../../schemas/common';
-import { SandboxEnvironmentVersionInternalMetadataSchema } from '../../../schemas/sandboxEnvironment';
+import {
+ DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ SandboxEnvironmentVersionInternalMetadataSchema,
+} from '../../../schemas/sandboxEnvironment';
import { newId } from '../../../utils/id';
import { SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ, SANDBOX_ENVIRONMENT_VERSION_UQ } from '../../indexes';
import {
@@ -16,11 +19,13 @@ import {
toUpsertSandboxEnvironmentVersionWrite,
type DeleteSandboxEnvironmentInput,
type GetSandboxEnvironmentInput,
+ type GetSandboxEnvironmentVersionInput,
type ISandboxEnvironmentStore,
type ListSandboxEnvironmentsInput,
- type MarkSandboxEnvironmentVersionActiveInput,
type MarkSandboxEnvironmentVersionFailedInput,
+ type MarkSandboxEnvironmentVersionReadyInput,
type SandboxEnvironmentRecord,
+ type SandboxEnvironmentVersionForProgress,
type SandboxEnvironmentVersionRecord,
type SandboxEnvironmentWithVersion,
type UpsertSandboxEnvironmentInput,
@@ -130,7 +135,15 @@ export class PostgresSandboxEnvironmentStore implements ISandboxEnvironmentStore
const query = activeVersionJoin(db)
.where('env.tenant_id', '=', input.tenant_id)
.where('env.lifecycle_stage', '=', 'active')
- .where(sql`env.created_by_subject->>'subject_id'`, '=', input.created_by_subject_id)
+ .where(eb =>
+ eb.or([
+ eb('env.name', '=', DEFAULT_SANDBOX_ENVIRONMENT_NAME),
+ eb.and([
+ eb('env.name', '!=', DEFAULT_SANDBOX_ENVIRONMENT_NAME),
+ eb(sql`env.created_by_subject->>'subject_id'`, '=', input.created_by_subject_id),
+ ]),
+ ]),
+ )
.orderBy('env.name');
if (!input.limit) {
const rows = await query.execute();
@@ -154,13 +167,70 @@ export class PostgresSandboxEnvironmentStore implements ISandboxEnvironmentStore
.where('env.tenant_id', '=', input.tenant_id)
.where('env.name', '=', input.name)
.where('env.lifecycle_stage', '=', 'active');
- if (input.created_by_subject_id) {
+ if (input.created_by_subject_id && input.name !== DEFAULT_SANDBOX_ENVIRONMENT_NAME) {
query = query.where(sql`env.created_by_subject->>'subject_id'`, '=', input.created_by_subject_id);
}
const row = await query.executeTakeFirst();
return row ? toWithVersion(row) : undefined;
}
+ async listLatestPendingVersions(transaction?: Transaction<Database>): Promise<string[]> {
+ const db = transaction ?? this.#db;
+ // One pending tip per environment.
+ const rows = await sql<{ id: string }>`
+ SELECT version.id
+ FROM sandbox_environment_version AS version
+ INNER JOIN sandbox_environment AS environment
+ ON environment.id = version.environment_id
+ INNER JOIN (
+ SELECT environment_id, MAX(version) AS version
+ FROM sandbox_environment_version
+ WHERE status = 'pending'
+ GROUP BY environment_id
+ ) AS tip
+ ON tip.environment_id = version.environment_id
+ AND tip.version = version.version
+ WHERE version.status = 'pending'
+ AND environment.lifecycle_stage = 'active'
+ ORDER BY version.created_at ASC
+ `.execute(db);
+ return rows.rows.map(row => row.id);
+ }
+
+ async getSandboxEnvironmentVersion(
+ input: GetSandboxEnvironmentVersionInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentVersionForProgress | undefined> {
+ const db = transaction ?? this.#db;
+ const row = await db
+ .selectFrom('sandbox_environment_version as ver')
+ .innerJoin('sandbox_environment as env', 'env.id', 'ver.environment_id')
+ .select([
+ 'ver.id',
+ 'env.tenant_id',
+ 'env.name as environment_name',
+ 'ver.environment_id',
+ 'ver.version',
+ 'ver.external_ref',
+ 'ver.manifest',
+ ])
+ .where('ver.id', '=', input.environment_version_id)
+ .where('env.lifecycle_stage', '=', 'active')
+ .executeTakeFirst();
+ if (!row) {
+ return undefined;
+ }
+ return {
+ id: row.id,
+ tenant_id: row.tenant_id,
+ environment_id: row.environment_id,
+ environment_name: row.environment_name,
+ version: row.version,
+ external_ref: row.external_ref,
+ manifest: parseStoredSandboxEnvironmentManifest(row.manifest),
+ };
+ }
+
async upsertEnvironment(
input: UpsertSandboxEnvironmentInput,
transaction?: Transaction<Database>,
@@ -175,21 +245,27 @@ export class PostgresSandboxEnvironmentStore implements ISandboxEnvironmentStore
input: UpsertSandboxEnvironmentInput,
db: Transaction<Database>,
): Promise<SandboxEnvironmentWithVersion> {
- const environmentRow = await db
+ const isDefault = input.name === DEFAULT_SANDBOX_ENVIRONMENT_NAME;
+ let environmentQuery = db
.selectFrom('sandbox_environment')
.selectAll()
.where('tenant_id', '=', input.tenant_id)
.where('name', '=', input.name)
- .where('lifecycle_stage', '=', 'active')
- .where(sql`created_by_subject->>'subject_id'`, '=', input.created_by_subject.subject_id)
- .forUpdate()
- .executeTakeFirst();
+ .where('lifecycle_stage', '=', 'active');
+ if (!isDefault) {
+ environmentQuery = environmentQuery.where(
+ sql`created_by_subject->>'subject_id'`,
+ '=',
+ input.created_by_subject.subject_id,
+ );
+ }
+ const environmentRow = await environmentQuery.forUpdate().executeTakeFirst();
if (!environmentRow) {
const environment_id = newId();
const versionWrite = toUpsertSandboxEnvironmentVersionWrite(input.buildVersion());
// First version: point here so get/list join works; later versions only move the
- // pointer when their status is (or becomes) active.
+ // pointer when their status is (or becomes) ready.
const active_version = versionWrite.version;
try {
const created = await db
@@ -207,10 +283,8 @@ export class PostgresSandboxEnvironmentStore implements ISandboxEnvironmentStore
})
.returningAll()
.executeTakeFirstOrThrow();
- return {
- environment: toEnvironmentRecord(created),
- version: await this.#insertVersionRow(db, environment_id, versionWrite),
- };
+ const version = await this.#insertVersionRow(db, environment_id, versionWrite);
+ return { environment: toEnvironmentRecord(created), version };
} catch (error) {
if (isUniqueViolation(error) || isPgConstraint(error, SANDBOX_ENVIRONMENT_TENANT_NAME_ACTIVE_UQ)) {
throw new SandboxEnvironmentNameConflictError(
@@ -235,11 +309,12 @@ export class PostgresSandboxEnvironmentStore implements ISandboxEnvironmentStore
previous_external_ref: previousVersion.external_ref,
}),
);
+
const version = await this.#insertVersionRow(db, environmentRow.id, versionWrite);
const updated = await db
.updateTable('sandbox_environment')
.set({
- ...(versionWrite.status === 'active' ? { active_version: versionWrite.version } : {}),
+ ...(versionWrite.status === 'ready' ? { active_version: versionWrite.version } : {}),
description: input.description,
updated_at: now(),
})
@@ -257,47 +332,50 @@ export class PostgresSandboxEnvironmentStore implements ISandboxEnvironmentStore
return { environment: toEnvironmentRecord(updated), version };
}
- async markVersionActive(
- input: MarkSandboxEnvironmentVersionActiveInput,
+ async markVersionReady(
+ input: MarkSandboxEnvironmentVersionReadyInput,
transaction?: Transaction<Database>,
): Promise<SandboxEnvironmentWithVersion | undefined> {
if (transaction) {
- return this.#markVersionActive(input, transaction);
+ return this.#markVersionReady(input, transaction);
}
- return this.#db.transaction().execute(db => this.#markVersionActive(input, db));
+ return this.#db.transaction().execute(db => this.#markVersionReady(input, db));
}
- async #markVersionActive(
- input: MarkSandboxEnvironmentVersionActiveInput,
+ async #markVersionReady(
+ input: MarkSandboxEnvironmentVersionReadyInput,
db: Transaction<Database>,
): Promise<SandboxEnvironmentWithVersion | undefined> {
const versionRow = await db
.updateTable('sandbox_environment_version')
.set({
- status: 'active',
+ status: 'ready',
status_reason: null,
updated_at: now(),
})
- .where('environment_id', '=', input.environment_id)
- .where('version', '=', input.version)
+ .where('id', '=', input.environment_version_id)
.returningAll()
.executeTakeFirst();
if (!versionRow) {
return undefined;
}
+ // Only advance the parent pointer forward (never roll back to an older tip).
const parentUpdated = await db
.updateTable('sandbox_environment')
.set({
- active_version: input.version,
+ active_version: versionRow.version,
updated_at: now(),
})
- .where('id', '=', input.environment_id)
+ .where('id', '=', versionRow.environment_id)
.where('lifecycle_stage', '=', 'active')
+ .where('active_version', '<=', versionRow.version)
.executeTakeFirst();
if (!Number(parentUpdated.numUpdatedRows)) {
- return undefined;
+ // Version marked ready but pointer already ahead — still return the join on current tip.
+ const row = await activeVersionJoin(db).where('env.id', '=', versionRow.environment_id).executeTakeFirst();
+ return row ? toWithVersion(row) : undefined;
}
- const row = await activeVersionJoin(db).where('env.id', '=', input.environment_id).executeTakeFirst();
+ const row = await activeVersionJoin(db).where('env.id', '=', versionRow.environment_id).executeTakeFirst();
return row ? toWithVersion(row) : undefined;
}
@@ -313,8 +391,7 @@ export class PostgresSandboxEnvironmentStore implements ISandboxEnvironmentStore
status_reason: input.status_reason,
updated_at: now(),
})
- .where('environment_id', '=', input.environment_id)
- .where('version', '=', input.version)
+ .where('id', '=', input.environment_version_id)
.returningAll()
.executeTakeFirst();
return row ? toVersionRecord(row) : undefined;
diff --git a/packages/trueforge/src/db/postgres/sandbox-provider-store/PostgresSandboxProviderStore.ts b/packages/trueforge/src/db/postgres/sandbox-provider-store/PostgresSandboxProviderStore.ts
index c0ca35dfb..a4d7bde78 100644
--- a/packages/trueforge/src/db/postgres/sandbox-provider-store/PostgresSandboxProviderStore.ts
+++ b/packages/trueforge/src/db/postgres/sandbox-provider-store/PostgresSandboxProviderStore.ts
@@ -2,7 +2,6 @@ import type { Kysely, Selectable, Transaction } from 'kysely';
import {
type ISandboxProviderStore,
type SandboxProviderRecord,
- type UpdateSandboxStatusInput,
type UpsertSandboxProviderInput,
} from '../../sandboxProviderStore';
import { json, now } from '../sqlExpressions';
@@ -12,9 +11,6 @@ function toRecord(row: Selectable<SandboxProviderTable>): SandboxProviderRecord
return {
tenant_id: row.tenant_id,
manifest: row.manifest,
- status: row.status,
- status_reason: row.status_reason,
- build_metadata: row.build_metadata,
created_at: row.created_at.toISOString(),
updated_at: row.updated_at.toISOString(),
};
@@ -63,18 +59,12 @@ export class PostgresSandboxProviderStore implements ISandboxProviderStore<Trans
.values({
tenant_id: input.tenant_id,
manifest: json(input.manifest),
- status: input.status,
- status_reason: input.status_reason,
- build_metadata: input.build_metadata !== null ? json(input.build_metadata) : null,
created_at: now(),
updated_at: now(),
})
.onConflict(oc =>
oc.columns(['tenant_id']).doUpdateSet({
manifest: json(input.manifest),
- status: input.status,
- status_reason: input.status_reason,
- build_metadata: input.build_metadata !== null ? json(input.build_metadata) : null,
updated_at: now(),
}),
)
@@ -82,23 +72,4 @@ export class PostgresSandboxProviderStore implements ISandboxProviderStore<Trans
.executeTakeFirstOrThrow();
return toRecord(row);
}
-
- async updateSandboxStatus(
- input: UpdateSandboxStatusInput,
- transaction?: Transaction<Database>,
- ): Promise<SandboxProviderRecord | undefined> {
- const db = transaction ?? this.#db;
- const row = await db
- .updateTable('sandbox_provider')
- .set({
- status: input.status,
- status_reason: input.status_reason,
- build_metadata: input.build_metadata !== null ? json(input.build_metadata) : null,
- updated_at: now(),
- })
- .where('tenant_id', '=', input.tenant_id)
- .returningAll()
- .executeTakeFirst();
- return row === undefined ? undefined : toRecord(row);
- }
}
diff --git a/packages/trueforge/src/db/postgres/types.ts b/packages/trueforge/src/db/postgres/types.ts
index 2946c9737..121565b6a 100644
--- a/packages/trueforge/src/db/postgres/types.ts
+++ b/packages/trueforge/src/db/postgres/types.ts
@@ -32,11 +32,7 @@ import type {
SandboxEnvironmentVersionStatus,
StoredSandboxEnvironmentManifest,
} from '../../schemas/sandboxEnvironment';
-import type {
- SandboxBuildMetadata,
- SandboxBuildStatus,
- StoredSandboxProviderManifest,
-} from '../../schemas/sandboxProvider';
+import type { StoredSandboxProviderManifest } from '../../schemas/sandboxProvider';
import type { ScheduleManifest, ScheduleRunStatus, ScheduleStatus } from '../../schemas/schedule';
import type { SkillManifest } from '../../schemas/skill';
import type { WebSearchProviderManifest } from '../../schemas/webSearchProvider';
@@ -399,12 +395,6 @@ export interface SandboxProviderTable {
tenant_id: string;
/** StoredSandboxProviderManifest document; replaced whole on every upsert */
manifest: JSONColumnType<StoredSandboxProviderManifest, StoredSandboxProviderManifest, StoredSandboxProviderManifest>;
- /** Last persisted build status of the release sandbox image. */
- status: SandboxBuildStatus;
- /** Human-readable detail for `status`; null when ready. */
- status_reason: string | null;
- /** SandboxBuildMetadata document (opaque string map); null when the provider has none. */
- build_metadata: JSONColumnType<SandboxBuildMetadata | null, SandboxBuildMetadata | null, SandboxBuildMetadata | null>;
created_at: Date;
updated_at: Date;
}
diff --git a/packages/trueforge/src/db/sandboxEnvironmentStore.ts b/packages/trueforge/src/db/sandboxEnvironmentStore.ts
index 5726c23d7..8add362d5 100644
--- a/packages/trueforge/src/db/sandboxEnvironmentStore.ts
+++ b/packages/trueforge/src/db/sandboxEnvironmentStore.ts
@@ -55,7 +55,7 @@ export function parseStoredSandboxEnvironmentManifest(manifest: unknown): Stored
export interface ListSandboxEnvironmentsInput {
tenant_id: string;
- /** Only environments created by this subject. */
+ /** Only environments created by this subject (tenant `"default"` is always included). */
created_by_subject_id: string;
limit: number | undefined;
page_token: string | undefined;
@@ -66,12 +66,26 @@ export interface GetSandboxEnvironmentInput {
name: string;
/**
* When set (CRUD / agent attach), only return if this subject created the environment.
- * Omit when resolving an env during agent execution: running the agent already
- * implies access to its referenced sandbox environment, so ownership is not checked.
+ * Ignored for the tenant `"default"`. Omit when resolving an env during agent execution.
*/
created_by_subject_id?: string;
}
+/** Version + parent fields needed to progress a build. */
+export interface SandboxEnvironmentVersionForProgress {
+ id: string;
+ tenant_id: string;
+ environment_id: string;
+ environment_name: string;
+ version: number;
+ external_ref: string;
+ manifest: StoredSandboxEnvironmentManifest;
+}
+
+export interface GetSandboxEnvironmentVersionInput {
+ environment_version_id: string;
+}
+
/**
* Result of `buildVersion` during upsert — {@link NextSandboxEnvironmentVersion} plus subject.
*/
@@ -108,14 +122,12 @@ export interface UpsertSandboxEnvironmentInput {
buildVersion: (previous?: UpsertSandboxEnvironmentPrevious) => UpsertSandboxEnvironmentVersion;
}
-export interface MarkSandboxEnvironmentVersionActiveInput {
- environment_id: string;
- version: number;
+export interface MarkSandboxEnvironmentVersionReadyInput {
+ environment_version_id: string;
}
export interface MarkSandboxEnvironmentVersionFailedInput {
- environment_id: string;
- version: number;
+ environment_version_id: string;
status_reason: string;
}
@@ -153,36 +165,43 @@ export class SandboxEnvironmentVersionConflictError extends Error {
}
export interface ISandboxEnvironmentStore<TTransaction = never> {
- /** Active environments joined to the version pointed at by `active_version`. */
+ /** Active environments joined to `active_version` (includes tenant `"default"`). */
listEnvironments(
input: ListSandboxEnvironmentsInput,
transaction?: TTransaction,
): Promise<{ data: SandboxEnvironmentWithVersion[]; pagination: TokenPagination }>;
/**
* Active environment by name, joined to its active version.
- * Pass `created_by_subject_id` for owner-scoped CRUD/attach; omit it when an agent
- * run resolves the env by name (caller already has access via the agent).
+ * Pass `created_by_subject_id` for owner-scoped CRUD/attach on custom envs; the tenant
+ * `"default"` ignores ownership. Omit the subject filter when an agent run resolves an env.
*/
getEnvironment(
input: GetSandboxEnvironmentInput,
transaction?: TTransaction,
): Promise<SandboxEnvironmentWithVersion | undefined>;
/**
- * Create or replace by `(tenant_id, name)` for this subject — parent + new version row.
- * On update, parent `active_version` advances only when the new version's status is
- * `active` (otherwise use markVersionActive). Uses `transaction` when passed;
- * otherwise opens its own (multi-write).
+ * Create or replace by `(tenant_id, name)` — parent + version row.
+ * Updates insert a new version; parent `active_version` advances only when status is
+ * `ready` (otherwise use markVersionReady). Uses `transaction` when passed; otherwise
+ * opens its own.
*/
upsertEnvironment(
input: UpsertSandboxEnvironmentInput,
transaction?: TTransaction,
): Promise<SandboxEnvironmentWithVersion>;
+ /** Latest pending version id per environment across tenants (oldest first). */
+ listLatestPendingVersions(transaction?: TTransaction): Promise<string[]>;
+ /** Version row + parent fields for controller progress. */
+ getSandboxEnvironmentVersion(
+ input: GetSandboxEnvironmentVersionInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentVersionForProgress | undefined>;
/**
- * Set version status to `active` and point the parent `active_version` at it.
- * No-op (returns undefined) if the version row is missing.
+ * Set version status to `ready` and point the parent `active_version` at it when
+ * `version >= active_version`. No-op (returns undefined) if the version row is missing.
*/
- markVersionActive(
- input: MarkSandboxEnvironmentVersionActiveInput,
+ markVersionReady(
+ input: MarkSandboxEnvironmentVersionReadyInput,
transaction?: TTransaction,
): Promise<SandboxEnvironmentWithVersion | undefined>;
markVersionFailed(
diff --git a/packages/trueforge/src/db/sandboxProviderStore.ts b/packages/trueforge/src/db/sandboxProviderStore.ts
index 55d25942f..140ef41f2 100644
--- a/packages/trueforge/src/db/sandboxProviderStore.ts
+++ b/packages/trueforge/src/db/sandboxProviderStore.ts
@@ -1,24 +1,14 @@
/**
* DB-backed configured sandbox provider: at most one row per tenant. Persists the
- * Zod-validated `StoredSandboxProviderManifest` jsonb document plus the last-known build
- * status (`status` / `status_reason` / `build_metadata`), refreshed on read.
+ * Zod-validated `StoredSandboxProviderManifest` jsonb document.
+ * Snapshot readiness lives on sandbox environment versions, not this row.
* Implementations: PostgresSandboxProviderStore and SqliteSandboxProviderStore.
*/
-import type {
- SandboxBuildMetadata,
- SandboxBuildStatus,
- StoredSandboxProviderManifest,
-} from '../schemas/sandboxProvider';
+import type { StoredSandboxProviderManifest } from '../schemas/sandboxProvider';
export interface SandboxProviderRecord {
tenant_id: string;
manifest: StoredSandboxProviderManifest;
- /** Last persisted build status of the release sandbox image. */
- status: SandboxBuildStatus;
- /** Human-readable detail for `status`; null when ready. */
- status_reason: string | null;
- /** Provider-specific build metadata; null when the provider has none. */
- build_metadata: SandboxBuildMetadata | null;
/** ISO-8601 UTC instant. */
created_at: string;
/** ISO-8601 UTC instant. */
@@ -28,16 +18,6 @@ export interface SandboxProviderRecord {
export interface UpsertSandboxProviderInput {
tenant_id: string;
manifest: StoredSandboxProviderManifest;
- status: SandboxBuildStatus;
- status_reason: string | null;
- build_metadata: SandboxBuildMetadata | null;
-}
-
-export interface UpdateSandboxStatusInput {
- tenant_id: string;
- status: SandboxBuildStatus;
- status_reason: string | null;
- build_metadata: SandboxBuildMetadata | null;
}
export interface ISandboxProviderStore<TTransaction = never> {
@@ -48,14 +28,6 @@ export interface ISandboxProviderStore<TTransaction = never> {
* Required before read-modify-write of secrets so concurrent keep/rotate cannot interleave.
*/
getSandboxProviderForUpdate(tenantId: string, transaction: TTransaction): Promise<SandboxProviderRecord | undefined>;
- /** Single-row write: creates the provider or replaces the whole manifest + build status. */
+ /** Single-row write: creates the provider or replaces the whole manifest. */
upsertSandboxProvider(input: UpsertSandboxProviderInput, transaction?: TTransaction): Promise<SandboxProviderRecord>;
- /**
- * Refresh only the build status columns (status / status_reason / build_metadata) of the
- * existing row, leaving the manifest untouched. Returns undefined when no row exists.
- */
- updateSandboxStatus(
- input: UpdateSandboxStatusInput,
- transaction?: TTransaction,
- ): Promise<SandboxProviderRecord | undefined>;
}
diff --git a/packages/trueforge/src/db/sqlite/client.ts b/packages/trueforge/src/db/sqlite/client.ts
index ca5e07dd3..9e95da431 100644
--- a/packages/trueforge/src/db/sqlite/client.ts
+++ b/packages/trueforge/src/db/sqlite/client.ts
@@ -145,7 +145,6 @@ const JSON_RESULT_COLUMNS = new Set([
'manifest',
'metadata',
'internal_metadata',
- 'build_metadata',
'oauth_server',
'oauth_client',
'token',
diff --git a/packages/trueforge/src/db/sqlite/migrations/20260929_000001_sandbox_environment_default_backfill.ts b/packages/trueforge/src/db/sqlite/migrations/20260929_000001_sandbox_environment_default_backfill.ts
new file mode 100644
index 000000000..d6b1ea14e
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20260929_000001_sandbox_environment_default_backfill.ts
@@ -0,0 +1,104 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Backfill the tenant `"default"` sandbox environment for existing Daytona providers.
+ * Mirrors postgres/20260929_000001_sandbox_environment_default_backfill.ts.
+ *
+ * Kysely does not wrap SQLite migrations — keep inserts + column drops in one transaction.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ const providers = await sql<{ tenant_id: string }>`
+ SELECT tenant_id
+ FROM sandbox_provider
+ WHERE json_extract(manifest, '$.type') = 'daytona'
+ `.execute(trx);
+
+ for (const row of providers.rows) {
+ const existing = await sql<{ id: string }>`
+ SELECT id
+ FROM sandbox_environment
+ WHERE tenant_id = ${row.tenant_id}
+ AND name = 'default'
+ AND lifecycle_stage = 'active'
+ LIMIT 1
+ `.execute(trx);
+ if (existing.rows.length > 0) {
+ continue;
+ }
+
+ const environmentId = `se_default_${row.tenant_id}`;
+ const now = new Date().toISOString();
+ const subject = {
+ subject_id: 'trueforge-system',
+ subject_type: 'user',
+ subject_display_name: 'TrueForge',
+ };
+ const manifest = {
+ name: 'default',
+ resources: { cpu: 1, memory: 1, disk: 3 },
+ type: 'daytona',
+ sandbox_provider: 'daytona',
+ };
+ const internalMetadata = { secrets: [] };
+ const externalRef = `trueforge-default-${row.tenant_id.replaceAll('/', '-')}`;
+
+ await sql`
+ INSERT INTO sandbox_environment (
+ id, tenant_id, name, description, active_version, lifecycle_stage,
+ created_by_subject, created_at, updated_at
+ ) VALUES (
+ ${environmentId},
+ ${row.tenant_id},
+ 'default',
+ '',
+ 1,
+ 'active',
+ jsonb(${JSON.stringify(subject)}),
+ ${now},
+ ${now}
+ )
+ `.execute(trx);
+
+ await sql`
+ INSERT INTO sandbox_environment_version (
+ id, environment_id, version, manifest, status, status_reason,
+ external_ref, internal_metadata, created_by_subject, created_at, updated_at
+ ) VALUES (
+ ${`${environmentId}_v1`},
+ ${environmentId},
+ 1,
+ jsonb(${JSON.stringify(manifest)}),
+ 'pending',
+ NULL,
+ ${externalRef},
+ jsonb(${JSON.stringify(internalMetadata)}),
+ jsonb(${JSON.stringify(subject)}),
+ ${now},
+ ${now}
+ )
+ `.execute(trx);
+ }
+
+ await sql`ALTER TABLE sandbox_provider DROP COLUMN build_metadata`.execute(trx);
+ await sql`ALTER TABLE sandbox_provider DROP COLUMN status_reason`.execute(trx);
+ await sql`ALTER TABLE sandbox_provider DROP COLUMN status`.execute(trx);
+ });
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`ALTER TABLE sandbox_provider ADD COLUMN status TEXT NOT NULL DEFAULT 'ready'`.execute(trx);
+ await sql`ALTER TABLE sandbox_provider ADD COLUMN status_reason TEXT`.execute(trx);
+ await sql`ALTER TABLE sandbox_provider ADD COLUMN build_metadata BLOB`.execute(trx);
+
+ await sql`
+ DELETE FROM sandbox_environment_version
+ WHERE environment_id LIKE 'se_default_%'
+ `.execute(trx);
+ await sql`
+ DELETE FROM sandbox_environment
+ WHERE id LIKE 'se_default_%'
+ `.execute(trx);
+ });
+}
diff --git a/packages/trueforge/src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore.ts b/packages/trueforge/src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore.ts
index dc057fd2b..036805e00 100644
--- a/packages/trueforge/src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore.ts
+++ b/packages/trueforge/src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore.ts
@@ -9,8 +9,10 @@ import {
} from '@truefoundry/trueforge-core/agent-session/store/OffsetPageToken';
import type { Kysely, Transaction } from 'kysely';
import { sql } from 'kysely';
+import {} from '../../../sandbox/sandboxEnvironmentVersion';
import { NameSchema } from '../../../schemas/common';
import {
+ DEFAULT_SANDBOX_ENVIRONMENT_NAME,
SandboxEnvironmentVersionInternalMetadataSchema,
type SandboxEnvironmentVersionInternalMetadata,
type StoredSandboxEnvironmentManifest,
@@ -23,11 +25,13 @@ import {
toUpsertSandboxEnvironmentVersionWrite,
type DeleteSandboxEnvironmentInput,
type GetSandboxEnvironmentInput,
+ type GetSandboxEnvironmentVersionInput,
type ISandboxEnvironmentStore,
type ListSandboxEnvironmentsInput,
- type MarkSandboxEnvironmentVersionActiveInput,
type MarkSandboxEnvironmentVersionFailedInput,
+ type MarkSandboxEnvironmentVersionReadyInput,
type SandboxEnvironmentRecord,
+ type SandboxEnvironmentVersionForProgress,
type SandboxEnvironmentVersionRecord,
type SandboxEnvironmentWithVersion,
type UpsertSandboxEnvironmentInput,
@@ -190,7 +194,15 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
const query = activeVersionJoin(db)
.where('env.tenant_id', '=', input.tenant_id)
.where('env.lifecycle_stage', '=', 'active')
- .where(sql`json_extract(env.created_by_subject, '$.subject_id')`, '=', input.created_by_subject_id)
+ .where(eb =>
+ eb.or([
+ eb('env.name', '=', DEFAULT_SANDBOX_ENVIRONMENT_NAME),
+ eb.and([
+ eb('env.name', '!=', DEFAULT_SANDBOX_ENVIRONMENT_NAME),
+ eb(sql`json_extract(env.created_by_subject, '$.subject_id')`, '=', input.created_by_subject_id),
+ ]),
+ ]),
+ )
.orderBy('env.name');
if (!input.limit) {
const rows = await query.execute();
@@ -214,13 +226,69 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
.where('env.tenant_id', '=', input.tenant_id)
.where('env.name', '=', input.name)
.where('env.lifecycle_stage', '=', 'active');
- if (input.created_by_subject_id) {
+ if (input.created_by_subject_id && input.name !== DEFAULT_SANDBOX_ENVIRONMENT_NAME) {
query = query.where(sql`json_extract(env.created_by_subject, '$.subject_id')`, '=', input.created_by_subject_id);
}
const row = await query.executeTakeFirst();
return row ? toWithVersion(row) : undefined;
}
+ async listLatestPendingVersions(transaction?: Transaction<Database>): Promise<string[]> {
+ const db = transaction ?? this.#db;
+ const rows = await sql<{ id: string }>`
+ SELECT version.id
+ FROM sandbox_environment_version AS version
+ INNER JOIN sandbox_environment AS environment
+ ON environment.id = version.environment_id
+ INNER JOIN (
+ SELECT environment_id, MAX(version) AS version
+ FROM sandbox_environment_version
+ WHERE status = 'pending'
+ GROUP BY environment_id
+ ) AS tip
+ ON tip.environment_id = version.environment_id
+ AND tip.version = version.version
+ WHERE version.status = 'pending'
+ AND environment.lifecycle_stage = 'active'
+ ORDER BY version.created_at ASC
+ `.execute(db);
+ return rows.rows.map(row => row.id);
+ }
+
+ async getSandboxEnvironmentVersion(
+ input: GetSandboxEnvironmentVersionInput,
+ transaction?: Transaction<Database>,
+ ): Promise<SandboxEnvironmentVersionForProgress | undefined> {
+ const db = transaction ?? this.#db;
+ const row = await db
+ .selectFrom('sandbox_environment_version as ver')
+ .innerJoin('sandbox_environment as env', 'env.id', 'ver.environment_id')
+ .select([
+ 'ver.id',
+ 'env.tenant_id',
+ 'env.name as environment_name',
+ 'ver.environment_id',
+ 'ver.version',
+ 'ver.external_ref',
+ jsonText<StoredSandboxEnvironmentManifest>(sql.ref('ver.manifest')).as('manifest'),
+ ])
+ .where('ver.id', '=', input.environment_version_id)
+ .where('env.lifecycle_stage', '=', 'active')
+ .executeTakeFirst();
+ if (!row) {
+ return undefined;
+ }
+ return {
+ id: row.id,
+ tenant_id: row.tenant_id,
+ environment_id: row.environment_id,
+ environment_name: row.environment_name,
+ version: row.version,
+ external_ref: row.external_ref,
+ manifest: parseStoredSandboxEnvironmentManifest(row.manifest),
+ };
+ }
+
async upsertEnvironment(
input: UpsertSandboxEnvironmentInput,
transaction?: Transaction<Database>,
@@ -235,7 +303,8 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
input: UpsertSandboxEnvironmentInput,
db: Transaction<Database>,
): Promise<SandboxEnvironmentWithVersion> {
- const environmentRow = await db
+ const isDefault = input.name === DEFAULT_SANDBOX_ENVIRONMENT_NAME;
+ let environmentQuery = db
.selectFrom('sandbox_environment')
.select([
'id',
@@ -250,16 +319,22 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
])
.where('tenant_id', '=', input.tenant_id)
.where('name', '=', input.name)
- .where('lifecycle_stage', '=', 'active')
- .where(sql`json_extract(created_by_subject, '$.subject_id')`, '=', input.created_by_subject.subject_id)
- .executeTakeFirst();
+ .where('lifecycle_stage', '=', 'active');
+ if (!isDefault) {
+ environmentQuery = environmentQuery.where(
+ sql`json_extract(created_by_subject, '$.subject_id')`,
+ '=',
+ input.created_by_subject.subject_id,
+ );
+ }
+ const environmentRow = await environmentQuery.executeTakeFirst();
if (!environmentRow) {
const environment_id = newId();
const versionWrite = toUpsertSandboxEnvironmentVersionWrite(input.buildVersion());
const created_at = nowIso();
// First version: point here so get/list join works; later versions only move the
- // pointer when their status is (or becomes) active.
+ // pointer when their status is (or becomes) ready.
const active_version = versionWrite.version;
try {
await db
@@ -315,13 +390,13 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
previous_external_ref: previousVersion.external_ref,
}),
);
- const version = await this.#insertVersionRow(db, environmentRow.id, versionWrite);
const updated_at = nowIso();
- const nextActiveVersion = versionWrite.status === 'active' ? versionWrite.version : environmentRow.active_version;
+
+ const version = await this.#insertVersionRow(db, environmentRow.id, versionWrite);
const result = await db
.updateTable('sandbox_environment')
.set({
- ...(versionWrite.status === 'active' ? { active_version: versionWrite.version } : {}),
+ ...(versionWrite.status === 'ready' ? { active_version: versionWrite.version } : {}),
description: input.description,
updated_at,
})
@@ -335,6 +410,7 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
{ cause: new Error('Sandbox environment disappeared during upsert') },
);
}
+ const nextActiveVersion = versionWrite.status === 'ready' ? versionWrite.version : environmentRow.active_version;
return {
environment: toEnvironmentRecord({
...environmentRow,
@@ -346,47 +422,52 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
};
}
- async markVersionActive(
- input: MarkSandboxEnvironmentVersionActiveInput,
+ async markVersionReady(
+ input: MarkSandboxEnvironmentVersionReadyInput,
transaction?: Transaction<Database>,
): Promise<SandboxEnvironmentWithVersion | undefined> {
if (transaction) {
- return this.#markVersionActive(input, transaction);
+ return this.#markVersionReady(input, transaction);
}
- return this.#db.transaction().execute(db => this.#markVersionActive(input, db));
+ return this.#db.transaction().execute(db => this.#markVersionReady(input, db));
}
- async #markVersionActive(
- input: MarkSandboxEnvironmentVersionActiveInput,
+ async #markVersionReady(
+ input: MarkSandboxEnvironmentVersionReadyInput,
db: Transaction<Database>,
): Promise<SandboxEnvironmentWithVersion | undefined> {
const updated_at = nowIso();
+ const versionRow = await db
+ .selectFrom('sandbox_environment_version')
+ .select(['id', 'environment_id', 'version'])
+ .where('id', '=', input.environment_version_id)
+ .executeTakeFirst();
+ if (!versionRow) {
+ return undefined;
+ }
const versionResult = await db
.updateTable('sandbox_environment_version')
.set({
- status: 'active',
+ status: 'ready',
status_reason: null,
updated_at,
})
- .where('environment_id', '=', input.environment_id)
- .where('version', '=', input.version)
+ .where('id', '=', input.environment_version_id)
.executeTakeFirst();
if (!Number(versionResult.numUpdatedRows)) {
return undefined;
}
- const parentResult = await db
+ await db
.updateTable('sandbox_environment')
.set({
- active_version: input.version,
+ active_version: versionRow.version,
updated_at,
})
- .where('id', '=', input.environment_id)
+ .where('id', '=', versionRow.environment_id)
.where('lifecycle_stage', '=', 'active')
+ .where('active_version', '<=', versionRow.version)
.executeTakeFirst();
- if (!Number(parentResult.numUpdatedRows)) {
- return undefined;
- }
- const row = await activeVersionJoin(db).where('env.id', '=', input.environment_id).executeTakeFirst();
+ const row = await activeVersionJoin(db).where('env.id', '=', versionRow.environment_id).executeTakeFirst();
return row ? toWithVersion(row) : undefined;
}
@@ -402,8 +483,7 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
status_reason: input.status_reason,
updated_at: nowIso(),
})
- .where('environment_id', '=', input.environment_id)
- .where('version', '=', input.version)
+ .where('id', '=', input.environment_version_id)
.executeTakeFirst();
if (!Number(result.numUpdatedRows)) {
return undefined;
@@ -411,8 +491,7 @@ export class SqliteSandboxEnvironmentStore implements ISandboxEnvironmentStore<T
const row = await db
.selectFrom('sandbox_environment_version')
.select(versionSelect())
- .where('environment_id', '=', input.environment_id)
- .where('version', '=', input.version)
+ .where('id', '=', input.environment_version_id)
.executeTakeFirst();
return row ? toVersionRecord(row) : undefined;
}
diff --git a/packages/trueforge/src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore.ts b/packages/trueforge/src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore.ts
index a52acd5d8..07f4ddad5 100644
--- a/packages/trueforge/src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore.ts
+++ b/packages/trueforge/src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore.ts
@@ -1,22 +1,18 @@
import type { ExpressionBuilder, Kysely, Transaction } from 'kysely';
-import type { SandboxBuildMetadata, StoredSandboxProviderManifest } from '../../../schemas/sandboxProvider';
+import type { StoredSandboxProviderManifest } from '../../../schemas/sandboxProvider';
import {
type ISandboxProviderStore,
type SandboxProviderRecord,
- type UpdateSandboxStatusInput,
type UpsertSandboxProviderInput,
} from '../../sandboxProviderStore';
import { jsonbBind, jsonText, nowIso } from '../sqlExpressions';
import type { Database } from '../types';
-/** Column list projecting the JSONB manifest/build_metadata as parsed JSON (see JSON_RESULT_COLUMNS). */
+/** Column list projecting the JSONB manifest as parsed JSON (see JSON_RESULT_COLUMNS). */
function recordColumns(eb: ExpressionBuilder<Database, 'sandbox_provider'>) {
return [
'tenant_id' as const,
jsonText<StoredSandboxProviderManifest>(eb.ref('manifest')).as('manifest'),
- 'status' as const,
- 'status_reason' as const,
- jsonText<SandboxBuildMetadata>(eb.ref('build_metadata')).as('build_metadata'),
'created_at' as const,
'updated_at' as const,
];
@@ -67,40 +63,16 @@ export class SqliteSandboxProviderStore implements ISandboxProviderStore<Transac
.values({
tenant_id: input.tenant_id,
manifest: jsonbBind(input.manifest),
- status: input.status,
- status_reason: input.status_reason,
- build_metadata: input.build_metadata !== null ? jsonbBind(input.build_metadata) : null,
created_at: timestamp,
updated_at: timestamp,
})
.onConflict(oc =>
oc.columns(['tenant_id']).doUpdateSet({
manifest: jsonbBind(input.manifest),
- status: input.status,
- status_reason: input.status_reason,
- build_metadata: input.build_metadata !== null ? jsonbBind(input.build_metadata) : null,
updated_at: timestamp,
}),
)
.returning(recordColumns)
.executeTakeFirstOrThrow();
}
-
- async updateSandboxStatus(
- input: UpdateSandboxStatusInput,
- transaction?: Transaction<Database>,
- ): Promise<SandboxProviderRecord | undefined> {
- const db = transaction ?? this.#db;
- return await db
- .updateTable('sandbox_provider')
- .set({
- status: input.status,
- status_reason: input.status_reason,
- build_metadata: input.build_metadata !== null ? jsonbBind(input.build_metadata) : null,
- updated_at: nowIso(),
- })
- .where('tenant_id', '=', input.tenant_id)
- .returning(recordColumns)
- .executeTakeFirst();
- }
}
diff --git a/packages/trueforge/src/db/sqlite/types.ts b/packages/trueforge/src/db/sqlite/types.ts
index e413e25ae..60dac6bf0 100644
--- a/packages/trueforge/src/db/sqlite/types.ts
+++ b/packages/trueforge/src/db/sqlite/types.ts
@@ -35,11 +35,7 @@ import type {
SandboxEnvironmentVersionStatus,
StoredSandboxEnvironmentManifest,
} from '../../schemas/sandboxEnvironment';
-import type {
- SandboxBuildMetadata,
- SandboxBuildStatus,
- StoredSandboxProviderManifest,
-} from '../../schemas/sandboxProvider';
+import type { StoredSandboxProviderManifest } from '../../schemas/sandboxProvider';
import type { ScheduleManifest, ScheduleRunStatus, ScheduleStatus } from '../../schemas/schedule';
import type { SkillManifest } from '../../schemas/skill';
import type { WebSearchProviderManifest } from '../../schemas/webSearchProvider';
@@ -244,12 +240,6 @@ export interface SandboxProviderTable {
tenant_id: string;
/** StoredSandboxProviderManifest document; replaced whole on every upsert */
manifest: JsonbColumn<StoredSandboxProviderManifest>;
- /** Last persisted build status of the release sandbox image. */
- status: SandboxBuildStatus;
- /** Human-readable detail for `status`; null when ready. */
- status_reason: string | null;
- /** SandboxBuildMetadata document (opaque string map); null when the provider has none. */
- build_metadata: JsonbColumn<SandboxBuildMetadata> | null;
created_at: string;
updated_at: string;
}
diff --git a/packages/trueforge/src/main.ts b/packages/trueforge/src/main.ts
index 56ca1acfb..3ac3f06d5 100644
--- a/packages/trueforge/src/main.ts
+++ b/packages/trueforge/src/main.ts
@@ -63,7 +63,7 @@ import type { Logger } from 'winston';
import { createServerApp } from './app';
import { TrueForgeAuthorizer, type Authorizer } from './auth/authorizer';
import { createAuthenticator } from './auth/createAuthenticator';
-import { resolveRequestContext, type RequestContext } from './auth/identity';
+import { resolveRequestContext, STANDALONE_REQUEST_CONTEXT, type RequestContext } from './auth/identity';
import { initOidc } from './auth/oidc';
import { McpCatalog } from './catalog/McpCatalog';
import { ModelCatalog } from './catalog/ModelCatalog';
@@ -116,6 +116,7 @@ import { TrueFoundryAgentStore } from './truefoundry/TrueFoundryAgentStore';
import { TrueFoundryAuthorizer } from './truefoundry/TrueFoundryAuthorizer';
import { TrueFoundryMcpServerStore } from './truefoundry/TrueFoundryMcpServerStore';
import { TrueFoundryModelProviderStore } from './truefoundry/TrueFoundryModelProviderStore';
+import { TrueFoundrySandboxEnvironmentStore } from './truefoundry/TrueFoundrySandboxEnvironmentStore';
import { TrueFoundrySandboxProviderStore } from './truefoundry/TrueFoundrySandboxProviderStore';
import { TrueFoundryServiceFoundryServerClient } from './truefoundry/TrueFoundryServiceFoundryServerClient';
import { TrueFoundryAdminSkillStore, TrueFoundrySkillStore } from './truefoundry/TrueFoundrySkillStore';
@@ -145,6 +146,8 @@ interface ServerPersistence<TTransaction> {
/** extra pre-resolved stores for scheduled runs */
agentStore: IAgentStore<TTransaction>;
sandboxEnvironmentStore: ISandboxEnvironmentStore<TTransaction>;
+ /** Context-free provider store for internal sandbox-env build progress. */
+ sandboxProviderStore: ISandboxProviderStore<TTransaction>;
turnSkillsResolverStore: Pick<ISkillStore<TTransaction>, 'resolveTurnSkills'>;
destroyDb: () => Promise<void>;
/** Connected Redis (client + mode) for distributed peering; undefined in standalone. */
@@ -295,6 +298,18 @@ function buildResolveSandboxProviderStore<TTransaction>(options: {
return () => persistenceStore;
}
+function wrapSandboxEnvironmentStore<TTransaction>(
+ persistenceStore: ISandboxEnvironmentStore<TTransaction>,
+): ISandboxEnvironmentStore<TTransaction> {
+ if (isTrueFoundryModeEnabled(configuration)) {
+ // Discriminator only — full resolve validates secrets/settings used elsewhere.
+ return new TrueFoundrySandboxEnvironmentStore(persistenceStore, {
+ envSupported: configuration.TRUEFOUNDRY_SANDBOX_PROVIDER === 'daytona',
+ });
+ }
+ return persistenceStore;
+}
+
function buildResolveWebSearchProviderStore<TTransaction>(options: {
persistenceStore: IWebSearchProviderStore<TTransaction>;
}): (rc: RequestContext) => IWebSearchProviderStore<TTransaction> {
@@ -350,7 +365,7 @@ async function createStandalonePersistence(options: {
const tokenStore = new SqliteOAuthTokenStore(db);
const agentStore = new SqliteAgentStore(db);
- const sandboxEnvironmentStore = new SqliteSandboxEnvironmentStore(db);
+ const sandboxEnvironmentStore = wrapSandboxEnvironmentStore(new SqliteSandboxEnvironmentStore(db));
const modelProviderStore = new SqliteModelProviderStore(db);
const mcpServerStore = new McpServerWithAuthStore({
store: new SqliteMcpServerStore(db),
@@ -376,6 +391,7 @@ async function createStandalonePersistence(options: {
resolveImportAgentStore: () => agentStore,
agentStore,
sandboxEnvironmentStore,
+ sandboxProviderStore,
turnSkillsResolverStore: skillStore,
destroyDb: () => db.destroy(),
redis: undefined,
@@ -469,7 +485,7 @@ async function createDistributedPersistence(options: {
const webSearchProviderStore = new PostgresWebSearchProviderStore(db);
const skillStore = new PostgresSkillStore(db);
const agentStore = new PostgresAgentStore(db);
- const sandboxEnvironmentStore = new PostgresSandboxEnvironmentStore(db);
+ const sandboxEnvironmentStore = wrapSandboxEnvironmentStore(new PostgresSandboxEnvironmentStore(db));
const turnSkillsResolverStore = buildTurnSkillsResolverStore({
persistenceStore: skillStore,
client: serviceFoundryClient,
@@ -535,6 +551,7 @@ async function createDistributedPersistence(options: {
resolveImportAgentStore,
agentStore,
sandboxEnvironmentStore,
+ sandboxProviderStore: resolveSandboxProviderStore(STANDALONE_REQUEST_CONTEXT),
turnSkillsResolverStore,
destroyDb: () => db.destroy(),
redis: await connectRedis({
@@ -681,6 +698,7 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
scheduleStore,
agentStore,
sandboxEnvironmentStore,
+ sandboxProviderStore: persistence.sandboxProviderStore,
turnSkillsResolverStore,
sessionStore,
sessionMetricsStore,
diff --git a/packages/trueforge/src/routes/sandboxEnvironmentBuildRoutes.ts b/packages/trueforge/src/routes/sandboxEnvironmentBuildRoutes.ts
new file mode 100644
index 000000000..d1c3fe5b6
--- /dev/null
+++ b/packages/trueforge/src/routes/sandboxEnvironmentBuildRoutes.ts
@@ -0,0 +1,77 @@
+/**
+ * Internal sandbox-environment build routes (API-key auth).
+ * Mounted at /api/internal/sandbox-environments.
+ */
+import { createRoute, z } from '@hono/zod-openapi';
+import { RequestErrorResponseSchema } from '../schemas/errors';
+import { OpenApiTag } from './openapiTags';
+
+export const PendingSandboxEnvironmentVersionSchema = z
+ .object({
+ environment_version_id: z.string().min(1).describe('Version row id to progress.'),
+ })
+ .strict()
+ .openapi('PendingSandboxEnvironmentVersion');
+
+export const ListPendingSandboxEnvironmentVersionsResponseSchema = z
+ .object({
+ data: z.array(PendingSandboxEnvironmentVersionSchema),
+ })
+ .strict()
+ .openapi('ListPendingSandboxEnvironmentVersionsResponse');
+
+export const ProgressSandboxEnvironmentVersionRequestSchema = z
+ .object({
+ environment_version_id: z.string().min(1).describe('Version row id to progress.'),
+ })
+ .strict()
+ .openapi('ProgressSandboxEnvironmentVersionRequest');
+
+export const listPendingSandboxEnvironmentVersionsRoute = createRoute({
+ method: 'get',
+ path: '/pending',
+ tags: [OpenApiTag.INTERNAL],
+ summary: 'List pending sandbox environment versions',
+ description: 'Returns pending environment versions for the build controller.',
+ 'x-fern-sdk-group-name': ['internal', 'sandbox_environments'],
+ 'x-fern-sdk-method-name': 'list_pending',
+ 'x-excluded': true,
+ responses: {
+ 200: {
+ content: { 'application/json': { schema: ListPendingSandboxEnvironmentVersionsResponseSchema } },
+ description: 'Pending versions oldest-first.',
+ },
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Invalid service credential.',
+ },
+ },
+});
+
+export const progressSandboxEnvironmentVersionRoute = createRoute({
+ method: 'post',
+ path: '/progress',
+ tags: [OpenApiTag.INTERNAL],
+ summary: 'Progress a pending sandbox environment version',
+ description: 'Registers or polls the snapshot build and updates version status.',
+ 'x-fern-sdk-group-name': ['internal', 'sandbox_environments'],
+ 'x-fern-sdk-method-name': 'progress',
+ 'x-excluded': true,
+ request: {
+ body: {
+ content: { 'application/json': { schema: ProgressSandboxEnvironmentVersionRequestSchema } },
+ required: true,
+ },
+ },
+ responses: {
+ 204: { description: 'Progressed (or left pending).' },
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Invalid service credential.',
+ },
+ 404: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Version not found.',
+ },
+ },
+});
diff --git a/packages/trueforge/src/routes/sandboxEnvironmentRoutes.ts b/packages/trueforge/src/routes/sandboxEnvironmentRoutes.ts
index 48a930c3a..197fa9e3d 100644
--- a/packages/trueforge/src/routes/sandboxEnvironmentRoutes.ts
+++ b/packages/trueforge/src/routes/sandboxEnvironmentRoutes.ts
@@ -14,6 +14,8 @@ import {
import { TOKEN_PAGINATION } from './fernExtensions';
import { OpenApiTag } from './openapiTags';
+const SANDBOX_ENVIRONMENTS_PAGE_LIMIT = 1000;
+
const SandboxEnvironmentNameParamsSchema = z.object({
name: NameSchema.describe('Sandbox environment name.'),
});
@@ -24,10 +26,10 @@ export const ListSandboxEnvironmentsQuerySchema = z
.number()
.int()
.min(1)
- .max(PAGE_LIMIT)
+ .max(SANDBOX_ENVIRONMENTS_PAGE_LIMIT)
.optional()
.default(PAGE_LIMIT)
- .describe(`Page size. Defaults to ${String(PAGE_LIMIT)}`),
+ .describe(`Page size. Defaults to ${String(PAGE_LIMIT)}, max ${String(SANDBOX_ENVIRONMENTS_PAGE_LIMIT)}.`),
page_token: z.string().optional().describe('Opaque token from a previous response `next_page_token`.'),
})
.openapi('ListSandboxEnvironmentsQuery');
@@ -37,7 +39,7 @@ export const listSandboxEnvironmentsRoute = createRoute({
path: '/',
tags: [OpenApiTag.SANDBOXES],
summary: 'List sandbox environments',
- description: 'List sandbox environments created by the authenticated subject, newest first.',
+ description: 'List the tenant default environment plus sandbox environments created by the authenticated subject.',
'x-fern-sdk-group-name': ['sandboxEnvironments'],
'x-fern-sdk-method-name': 'list',
'x-fern-pagination': TOKEN_PAGINATION,
@@ -65,7 +67,8 @@ export const getSandboxEnvironmentRoute = createRoute({
path: '/{name}',
tags: [OpenApiTag.SANDBOXES],
summary: 'Get a sandbox environment',
- description: 'Get a sandbox environment by name for the authenticated subject.',
+ description:
+ 'Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.',
'x-fern-sdk-group-name': ['sandboxEnvironments'],
'x-fern-sdk-method-name': 'get',
request: {
@@ -92,7 +95,7 @@ export const putSandboxEnvironmentRoute = createRoute({
path: '/',
tags: [OpenApiTag.SANDBOXES],
summary: 'Create or update a sandbox environment',
- description: 'Create or replace by `manifest.name`. Requires a Daytona sandbox provider.',
+ description: 'Create or replace by `manifest.name`. Requires a configured sandbox provider.',
'x-fern-sdk-group-name': ['sandboxEnvironments'],
'x-fern-sdk-method-name': 'create_or_update',
request: {
@@ -120,7 +123,7 @@ export const putSandboxEnvironmentRoute = createRoute({
},
422: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
- description: 'No Daytona sandbox provider configured.',
+ description: 'No sandbox provider configured.',
},
},
});
diff --git a/packages/trueforge/src/routes/sandboxProviderRoutes.ts b/packages/trueforge/src/routes/sandboxProviderRoutes.ts
index c1be8d052..bf9da4be9 100644
--- a/packages/trueforge/src/routes/sandboxProviderRoutes.ts
+++ b/packages/trueforge/src/routes/sandboxProviderRoutes.ts
@@ -55,7 +55,7 @@ export const putSandboxProviderRoute = createRoute({
},
422: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
- description: 'Daytona rejected the provided API key.',
+ description: 'Sandbox provider rejected the provided API key.',
},
},
});
diff --git a/packages/trueforge/src/runtime/sessionResources.ts b/packages/trueforge/src/runtime/sessionResources.ts
index 1ee7b9fc7..9a8244077 100644
--- a/packages/trueforge/src/runtime/sessionResources.ts
+++ b/packages/trueforge/src/runtime/sessionResources.ts
@@ -4,6 +4,7 @@ import {
SkillMounter,
type AgentDefinition,
type AgentTracing,
+ type DaytonaSandboxEnvironment,
type ModelParams,
type RemoteMcpHeaders,
type SandboxProvider,
@@ -23,8 +24,13 @@ import type { TurnMetadata } from '../db/turnMetadata';
import type { IWebSearchProviderStore } from '../db/webSearchProviderStore';
import { LocalSandboxProvider } from '../sandbox/local/provider/LocalSandboxProvider';
import { getCachedLocalSandboxSupport, isLocalSandboxFallbackEnabled } from '../sandbox/localRuntime';
-import { toDaytonaSandboxProvider, toSandboxProviderFromRecord } from '../sandbox/providerUtils';
+import {
+ toSandboxEnvironment,
+ toSandboxProviderFromRecord,
+ type ResolvedSandboxProvider,
+} from '../sandbox/providerUtils';
import type { ReasoningEffort } from '../schemas/modelProvider';
+import { DEFAULT_SANDBOX_ENVIRONMENT_NAME } from '../schemas/sandboxEnvironment';
import { hasConfiguredWebSearchProvider } from '../websearch/providers';
export interface McpConnection {
@@ -137,18 +143,6 @@ export async function getMcpConnection({
};
}
-/**
- * Build a runtime SandboxProvider from the configured store row, or the
- * in-memory local fallback when standalone + the cached probe is supported.
- * Builds a fresh provider client per call (no network I/O).
- *
- * When `environment_name` is set (and not the reserved `default`), loads that
- * sandbox environment by tenant + name (must be `active`) — no subject ownership
- * check so anyone who can run the agent can use its env. `default` falls through
- * to the tenant provider. Env create overlays use Daytona only (switch on
- * provider type). For `image.type === 'build'` pins the snapshot to the
- * environment version `external_ref`.
- */
/** Single path segment under the sandboxes parent (`_` when sessionId is missing or unsafe). */
export function localSandboxSessionSegment(sessionId: string | undefined): string {
if (sessionId === undefined || sessionId.length === 0 || sessionId.includes('/') || sessionId.includes('..')) {
@@ -157,83 +151,25 @@ export function localSandboxSessionSegment(sessionId: string | undefined): strin
return sessionId;
}
-export interface ResolvedSandboxProvider {
- provider: SandboxProvider;
- /**
- * True when cloning an environment's built snapshot (`external_ref`).
- * Callers should skip the tenant provider release-snapshot readiness check.
- */
- usesEnvironmentSnapshot: boolean;
-}
-
+/**
+ * Configured provider client, or standalone local fallback.
+ * Fresh client per call (no network I/O until a provider method runs).
+ * Environment is resolved separately via resolveSandboxEnvironment.
+ */
export async function resolveSandboxProvider({
tenant_id,
store,
logger,
sessionId,
- environment_name,
- sandboxEnvironmentStore,
}: {
tenant_id: string;
store: ISandboxProviderStore;
logger: Logger;
sessionId: string;
- environment_name: string | undefined;
- sandboxEnvironmentStore: ISandboxEnvironmentStore;
-}): Promise<ResolvedSandboxProvider | undefined> {
+}): Promise<ResolvedSandboxProvider | LocalSandboxProvider | undefined> {
const record = await store.getSandboxProvider(tenant_id);
-
- // Reserved `default` means the tenant sandbox provider (no env overlay).
- if (environment_name && environment_name !== 'default') {
- const loaded = await sandboxEnvironmentStore.getEnvironment({
- tenant_id,
- name: environment_name,
- });
- if (loaded === undefined) {
- throw new HTTPException(422, {
- message: `Unknown sandbox environment "${environment_name}" — not configured`,
- });
- }
- if (loaded.version.status !== 'active') {
- throw new HTTPException(422, {
- message:
- loaded.version.status === 'failed'
- ? `Sandbox environment "${environment_name}" build failed (${loaded.version.status_reason ?? 'unknown error'})`
- : `Sandbox environment "${environment_name}" is not ready (status: ${loaded.version.status}) — retry shortly`,
- });
- }
- if (record === undefined) {
- throw new HTTPException(422, {
- message: `Sandbox environment "${environment_name}" requires a sandbox provider — configure via PUT /settings/sandbox-providers`,
- });
- }
- const usesEnvironmentSnapshot = loaded.version.manifest.image?.type === 'build';
- switch (record.manifest.type) {
- case 'daytona':
- return {
- provider: toDaytonaSandboxProvider({
- manifest: record.manifest,
- tenant_id,
- logger,
- build_metadata: usesEnvironmentSnapshot
- ? { build_ref: loaded.version.external_ref }
- : record.build_metadata,
- environment: loaded.version.manifest,
- }),
- usesEnvironmentSnapshot,
- };
- default:
- throw new HTTPException(422, {
- message: `Sandbox environment "${environment_name}" requires a Daytona sandbox provider (configured provider type: "${record.manifest.type}")`,
- });
- }
- }
-
if (record !== undefined) {
- return {
- provider: toSandboxProviderFromRecord({ record, tenant_id, logger }),
- usesEnvironmentSnapshot: false,
- };
+ return toSandboxProviderFromRecord({ record, tenant_id, logger });
}
if (!configuration.STANDALONE) {
return undefined;
@@ -242,32 +178,72 @@ export async function resolveSandboxProvider({
if (support?.supported !== true) {
return undefined;
}
- return {
- provider: new LocalSandboxProvider({
- sandboxRootPathParent: join(configuration.LOCAL_SANDBOX_ROOT_PARENT, localSandboxSessionSegment(sessionId)),
- codeModeSocketParentPath: configuration.CODE_MODE_SOCKET_PARENT,
- support,
- fileMaxBytesForDownload: configuration.SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD,
- logger,
- }),
- usesEnvironmentSnapshot: false,
- };
+ return new LocalSandboxProvider({
+ sandboxRootPathParent: join(configuration.LOCAL_SANDBOX_ROOT_PARENT, localSandboxSessionSegment(sessionId)),
+ codeModeSocketParentPath: configuration.CODE_MODE_SOCKET_PARENT,
+ support,
+ fileMaxBytesForDownload: configuration.SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD,
+ logger,
+ });
+}
+
+/**
+ * Load a ready sandbox environment for create. Throws 422 when missing or not ready.
+ * When `optional` is true, a missing environment returns undefined instead of 422.
+ */
+export async function resolveSandboxEnvironment({
+ tenant_id,
+ name,
+ sandboxEnvironmentStore,
+ optional = false,
+}: {
+ tenant_id: string;
+ name: string;
+ sandboxEnvironmentStore: ISandboxEnvironmentStore;
+ optional?: boolean;
+}): Promise<DaytonaSandboxEnvironment | undefined> {
+ const loaded = await sandboxEnvironmentStore.getEnvironment({
+ tenant_id,
+ name,
+ });
+ if (loaded === undefined) {
+ if (optional) {
+ return undefined;
+ }
+ throw new HTTPException(422, {
+ message: `Unknown sandbox environment "${name}" — not configured`,
+ });
+ }
+ if (loaded.version.status !== 'ready') {
+ throw new HTTPException(422, {
+ message:
+ loaded.version.status === 'failed'
+ ? `Sandbox environment "${name}" build failed (${loaded.version.status_reason ?? 'unknown error'})`
+ : `Sandbox environment "${name}" is not ready (status: ${loaded.version.status}) — retry shortly`,
+ });
+ }
+ return toSandboxEnvironment({
+ external_ref: loaded.version.external_ref,
+ manifest: loaded.version.manifest,
+ });
}
/**
- * Builds a Sandbox for one turn from a resolved provider and skill mounts.
+ * Builds a Sandbox for one turn from a resolved provider, optional environment, and skill mounts.
*/
-export function buildTurnSandbox(input: {
- provider: SandboxProvider;
+export function buildTurnSandbox<TEnvironment = undefined>(input: {
+ provider: SandboxProvider<TEnvironment>;
+ environment?: TEnvironment | undefined;
logger: Logger;
skills?: readonly Skill[];
fileDownloadEnabled: boolean;
existingSandboxId?: string | undefined;
tracing: AgentTracing;
-}): Sandbox {
+}): Sandbox<TEnvironment> {
// Empty mounter still uploads requested-skills file so existing skills are cleaned up.
return new Sandbox({
provider: input.provider,
+ ...(input.environment !== undefined ? { environment: input.environment } : {}),
existingSandboxId: input.existingSandboxId,
fileDownloadEnabled: input.fileDownloadEnabled,
blockDestructiveToolsInCodeMode: true,
@@ -360,7 +336,7 @@ export async function validateAgentSpec({
}
const environmentName = spec.config.sandbox.environment_name;
- if (environmentName) {
+ if (environmentName && environmentName !== DEFAULT_SANDBOX_ENVIRONMENT_NAME) {
const environment = await sandboxEnvironmentStore.getEnvironment({
tenant_id,
name: environmentName,
diff --git a/packages/trueforge/src/sandbox/ensureDefaultSandboxEnvironment.ts b/packages/trueforge/src/sandbox/ensureDefaultSandboxEnvironment.ts
new file mode 100644
index 000000000..7c3232b65
--- /dev/null
+++ b/packages/trueforge/src/sandbox/ensureDefaultSandboxEnvironment.ts
@@ -0,0 +1,61 @@
+/**
+ * Ensure the tenant `"default"` sandbox environment exists for a configured provider.
+ */
+import type { CreatedBySubject } from '@truefoundry/trueforge-core/agent-session';
+import type { ISandboxEnvironmentStore, SandboxEnvironmentWithVersion } from '../db/sandboxEnvironmentStore';
+import { NameSchema } from '../schemas/common';
+import {
+ DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ SandboxEnvironmentVersionInternalMetadataSchema,
+} from '../schemas/sandboxEnvironment';
+import {
+ defaultSandboxEnvironmentStoredManifest,
+ newExternalRef,
+ type SandboxEnvironmentProviderType,
+} from './sandboxEnvironmentVersion';
+
+const DEFAULT_NAME = NameSchema.parse(DEFAULT_SANDBOX_ENVIRONMENT_NAME);
+const EMPTY_INTERNAL_METADATA = SandboxEnvironmentVersionInternalMetadataSchema.parse({});
+
+/**
+ * Returns the existing default env, or creates it / appends a new pending version.
+ * Pass `resetPending` when the provider API key rotated.
+ */
+export async function ensureDefaultSandboxEnvironment<TTransaction>({
+ store,
+ tenant_id,
+ created_by_subject,
+ provider_type,
+ resetPending,
+ transaction,
+}: {
+ store: ISandboxEnvironmentStore<TTransaction>;
+ tenant_id: string;
+ created_by_subject: CreatedBySubject;
+ provider_type: SandboxEnvironmentProviderType;
+ resetPending: boolean;
+ transaction?: TTransaction;
+}): Promise<SandboxEnvironmentWithVersion> {
+ const existing = await store.getEnvironment({ tenant_id, name: DEFAULT_SANDBOX_ENVIRONMENT_NAME }, transaction);
+ if (existing !== undefined && !resetPending) {
+ return existing;
+ }
+ return store.upsertEnvironment(
+ {
+ tenant_id,
+ name: DEFAULT_NAME,
+ description: '',
+ created_by_subject,
+ buildVersion: previous => ({
+ version: previous ? previous.latest_version + 1 : 1,
+ manifest: defaultSandboxEnvironmentStoredManifest(provider_type),
+ status: 'pending',
+ status_reason: null,
+ external_ref: newExternalRef(),
+ internal_metadata: EMPTY_INTERNAL_METADATA,
+ created_by_subject,
+ }),
+ },
+ transaction,
+ );
+}
diff --git a/packages/trueforge/src/sandbox/local/provider/LocalSandboxProvider.ts b/packages/trueforge/src/sandbox/local/provider/LocalSandboxProvider.ts
index b69625010..e04c3ed85 100644
--- a/packages/trueforge/src/sandbox/local/provider/LocalSandboxProvider.ts
+++ b/packages/trueforge/src/sandbox/local/provider/LocalSandboxProvider.ts
@@ -4,7 +4,6 @@
import type {
CodeModeTransport,
ExecResult,
- SandboxBuild,
SandboxExecParams,
SandboxProvider,
} from '@truefoundry/trueforge-core/core';
@@ -223,6 +222,7 @@ export function localSandboxUploadCommand(remotePath: string): string {
export class LocalSandboxProvider implements SandboxProvider {
readonly type = 'local';
+ readonly envSupported = false;
private readonly sandboxRootPathParent: string;
private readonly codeModeSocketParentPath: string;
private readonly support: LocalSandboxSupported;
@@ -231,12 +231,9 @@ export class LocalSandboxProvider implements SandboxProvider {
private srtInitialized = false;
private readonly logger: Logger;
- /** Local SRT has no image build step — always ready. */
- private static readonly readyBuild: SandboxBuild = {
- status: 'ready',
- reason: null,
- metadata: null,
- };
+ validateAccess(): Promise<void> {
+ return Promise.resolve();
+ }
/**
* Probe whether this host can run LocalSandboxProvider
@@ -461,14 +458,6 @@ export class LocalSandboxProvider implements SandboxProvider {
return this.pythonC(code, relPath);
}
- buildImage(): Promise<SandboxBuild> {
- return Promise.resolve(LocalSandboxProvider.readyBuild);
- }
-
- getImageBuildStatus(): Promise<SandboxBuild> {
- return Promise.resolve(LocalSandboxProvider.readyBuild);
- }
-
private async ensureSrt(): Promise<void> {
if (this.srtInitialized) {
return;
diff --git a/packages/trueforge/src/sandbox/progressSandboxEnvironmentVersion.ts b/packages/trueforge/src/sandbox/progressSandboxEnvironmentVersion.ts
new file mode 100644
index 000000000..732f264f8
--- /dev/null
+++ b/packages/trueforge/src/sandbox/progressSandboxEnvironmentVersion.ts
@@ -0,0 +1,103 @@
+/**
+ * Progress a pending sandbox-environment version: get/create snapshot, update DB.
+ */
+import { DAYTONA_SNAPSHOT_NOT_STARTED_REASON, withTimeout } from '@truefoundry/trueforge-core/core';
+import { HTTPException } from 'hono/http-exception';
+import type { Logger } from 'winston';
+import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';
+import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
+import {
+ isDaytonaAuthError,
+ isDaytonaPermissionError,
+ toDaytonaSandboxProvider,
+ toSandboxEnvironment,
+ toSandboxStatus,
+} from '../sandbox/providerUtils';
+import { captureCriticalException } from '../sentry';
+
+/** Bound hung Daytona GET/POST so the sandbox-env-build tick can move on. */
+const DAYTONA_SNAPSHOT_RPC_TIMEOUT_MS = 30_000;
+
+export async function progressSandboxEnvironmentVersion({
+ sandboxEnvironmentStore,
+ sandboxProviderStore,
+ environment_version_id,
+ logger,
+}: {
+ sandboxEnvironmentStore: ISandboxEnvironmentStore;
+ sandboxProviderStore: ISandboxProviderStore;
+ environment_version_id: string;
+ logger: Logger;
+}): Promise<void> {
+ const pending = await sandboxEnvironmentStore.getSandboxEnvironmentVersion({ environment_version_id });
+ if (pending === undefined) {
+ const error = new HTTPException(404, { message: 'Sandbox environment version not found' });
+ captureCriticalException(error, {
+ tags: { module: 'progressSandboxEnvironmentVersion', operation: 'notFound' },
+ extra: { environment_version_id },
+ });
+ throw error;
+ }
+
+ const providerRecord = await sandboxProviderStore.getSandboxProvider(pending.tenant_id);
+ if (providerRecord === undefined) {
+ throw new Error('Sandbox environment build requires a configured Daytona sandbox provider');
+ }
+
+ const provider = toDaytonaSandboxProvider({
+ manifest: providerRecord.manifest,
+ tenant_id: pending.tenant_id,
+ logger,
+ });
+ const environment = toSandboxEnvironment({
+ external_ref: pending.external_ref,
+ manifest: pending.manifest,
+ });
+
+ try {
+ const status = await withTimeout(
+ provider.getBuildStatus(environment),
+ DAYTONA_SNAPSHOT_RPC_TIMEOUT_MS,
+ 'sandbox environment getBuildStatus',
+ );
+ const built = toSandboxStatus(
+ status.reason === DAYTONA_SNAPSHOT_NOT_STARTED_REASON
+ ? await withTimeout(provider.build(environment), DAYTONA_SNAPSHOT_RPC_TIMEOUT_MS, 'sandbox environment build')
+ : status,
+ );
+ if (built.status === 'ready') {
+ await sandboxEnvironmentStore.markVersionReady({ environment_version_id });
+ return;
+ }
+ if (built.status === 'failed') {
+ await sandboxEnvironmentStore.markVersionFailed({
+ environment_version_id,
+ status_reason: built.status_reason ?? 'Sandbox environment snapshot build failed',
+ });
+ return;
+ }
+ // pending / building — leave as pending for the next tick.
+ return;
+ } catch (error) {
+ if (isDaytonaAuthError(error) || isDaytonaPermissionError(error)) {
+ const status_reason = isDaytonaAuthError(error)
+ ? 'Sandbox provider rejected the API key — check the credentials'
+ : 'Sandbox provider denied access: the API key is missing required permissions';
+ await sandboxEnvironmentStore.markVersionFailed({ environment_version_id, status_reason });
+ logger.warn('Sandbox environment build failed authz', {
+ environment_version_id,
+ status_reason,
+ });
+ captureCriticalException(error, {
+ tags: { module: 'progressSandboxEnvironmentVersion', operation: 'authz' },
+ extra: { environment_version_id, tenant_id: pending.tenant_id, status_reason },
+ });
+ return;
+ }
+ captureCriticalException(error, {
+ tags: { module: 'progressSandboxEnvironmentVersion', operation: 'build' },
+ extra: { environment_version_id, tenant_id: pending.tenant_id },
+ });
+ throw error;
+ }
+}
diff --git a/packages/trueforge/src/sandbox/providerUtils.ts b/packages/trueforge/src/sandbox/providerUtils.ts
index a75b2a0a4..bb1bfb3c8 100644
--- a/packages/trueforge/src/sandbox/providerUtils.ts
+++ b/packages/trueforge/src/sandbox/providerUtils.ts
@@ -1,26 +1,23 @@
-/** Sandbox provider construction + Daytona snapshot status refresh. */
+/** Sandbox provider construction + credential validation. */
import { Daytona, DaytonaError } from '@daytona/sdk';
import {
+ createDaytonaSandboxEnvironment,
DaytonaSandboxProvider,
- SANDBOX_IMAGE_URI,
TFYSandboxProvider,
- withTimeout,
+ type DaytonaSandboxEnvironment,
type SandboxBuild,
- type SandboxEnvironment,
- type SandboxProvider,
} from '@truefoundry/trueforge-core/core';
import type { Logger } from 'winston';
import configuration from '../config';
-import type { ISandboxProviderStore, SandboxProviderRecord } from '../db/sandboxProviderStore';
-import type { SandboxEnvironmentManifest } from '../schemas/sandboxEnvironment';
+import type { SandboxProviderRecord } from '../db/sandboxProviderStore';
+import type { StoredSandboxEnvironmentManifest } from '../schemas/sandboxEnvironment';
import {
toDaytonaSandboxProviderInput,
- type SandboxBuildMetadata,
- type SandboxProviderManifest,
type SandboxStatus,
+ type StoredSandboxProviderManifest,
} from '../schemas/sandboxProvider';
-/** Daytona rejected the credentials (401 unauthorized); retrying the same key cannot succeed. */
+/** Provider rejected the credentials (401 unauthorized); retrying the same key cannot succeed. */
export function isDaytonaAuthError(error: unknown): boolean {
return error instanceof DaytonaError && error.statusCode === 401;
}
@@ -29,9 +26,19 @@ export function isDaytonaPermissionError(error: unknown): boolean {
return error instanceof DaytonaError && error.statusCode === 403;
}
-/** Map host sandbox-environment manifest onto the Daytona provider environment. */
-export function toDaytonaSandboxEnvironment(manifest: SandboxEnvironmentManifest): SandboxEnvironment {
- return {
+/** Configured tenant sandbox backends (not local fallback). */
+export type ResolvedSandboxProvider = DaytonaSandboxProvider | TFYSandboxProvider;
+
+/** Map a ready env (external_ref + stored manifest) onto Daytona create/build input data. */
+export function toSandboxEnvironment({
+ external_ref,
+ manifest,
+}: {
+ external_ref: string;
+ manifest: StoredSandboxEnvironmentManifest;
+}): DaytonaSandboxEnvironment {
+ return createDaytonaSandboxEnvironment({
+ snapshot_ref: external_ref,
resources: manifest.resources,
...(manifest.image ? { image: manifest.image } : {}),
...(manifest.environment_variables ? { environment_variables: manifest.environment_variables } : {}),
@@ -48,40 +55,32 @@ export function toDaytonaSandboxEnvironment(manifest: SandboxEnvironmentManifest
},
}
: {}),
- };
+ });
}
/**
* Builds the Daytona runtime provider for a stored Daytona manifest. No network I/O until a method is called.
- *
- * When `build_metadata` is present, pin both `sandboxImage` and `buildRef` to what was actually
- * built — image bumps in the running binary must not rewrite an existing tenant onto a new
- * snapshot (upgrades are not supported yet). First-time configure omits metadata and uses
- * {@link SANDBOX_IMAGE_URI}.
+ * Snapshot tips (ref + image) are create/build input data, not provider config.
*/
export function toDaytonaSandboxProvider({
manifest,
tenant_id,
logger,
- build_metadata,
- environment,
}: {
- manifest: SandboxProviderManifest;
+ manifest: StoredSandboxProviderManifest;
tenant_id: string;
logger: Logger;
- build_metadata?: SandboxBuildMetadata | null;
- environment?: SandboxEnvironmentManifest;
}): DaytonaSandboxProvider {
+ if (manifest.type !== 'daytona') {
+ throw new Error('Daytona sandbox provider required');
+ }
const { apiKey, ...settings } = toDaytonaSandboxProviderInput(manifest);
return new DaytonaSandboxProvider({
client: new Daytona({ apiKey }),
apiKey,
...settings,
tenantName: tenant_id,
- sandboxImage: build_metadata?.['image_uri'] ?? SANDBOX_IMAGE_URI,
- buildRef: build_metadata?.['build_ref'],
fileMaxBytesForDownload: configuration.SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD,
- ...(environment ? { environment: toDaytonaSandboxEnvironment(environment) } : {}),
logger,
});
}
@@ -89,28 +88,22 @@ export function toDaytonaSandboxProvider({
/**
* Builds the runtime SandboxProvider for a store record. One switch on `manifest.type`.
* No network I/O until a provider method is called.
- *
- * Optional `build_metadata` overrides the record's persisted metadata (e.g. env-version
- * snapshot `build_ref`); ignored for non-Daytona providers.
*/
export function toSandboxProviderFromRecord({
record,
tenant_id,
logger,
- build_metadata,
}: {
record: SandboxProviderRecord;
tenant_id: string;
- build_metadata?: SandboxBuildMetadata | null;
logger: Logger;
-}): SandboxProvider {
+}): ResolvedSandboxProvider {
switch (record.manifest.type) {
case 'daytona':
return toDaytonaSandboxProvider({
manifest: record.manifest,
tenant_id,
logger,
- build_metadata: build_metadata ?? record.build_metadata,
});
case 'truefoundry':
return new TFYSandboxProvider({
@@ -124,70 +117,34 @@ export function toSandboxProviderFromRecord({
}
}
-/** Maps a core `SandboxBuild` onto the persisted/wire status shape (metadata passes through). */
-export function toSandboxStatus(build: SandboxBuild): SandboxStatus {
- return {
- status: build.status,
- status_reason: build.reason,
- build_metadata: build.metadata,
- };
-}
-
-function sandboxStatusFromRecord(record: SandboxProviderRecord): SandboxStatus {
- return {
- status: record.status,
- status_reason: record.status_reason,
- build_metadata: record.build_metadata,
- };
-}
-
-// Daytona deactivates idle snapshots after 14 days; revalidate at 13 to stay a day ahead.
-const READY_REVALIDATE_INTERVAL_MS = 13 * 24 * 60 * 60 * 1000;
-
-/** Cap the Daytona round-trip for the refresh, which runs outside a transaction. */
-const STATUS_REFRESH_TIMEOUT_MS = 60_000;
-
-export async function checkSnapshotStatus({
- store,
+/**
+ * Credential/access probe via the provider's `validateAccess` (no-op when unimplemented).
+ */
+export async function validateSandboxProviderAccess({
+ manifest,
tenant_id,
logger,
}: {
- store: ISandboxProviderStore;
+ manifest: StoredSandboxProviderManifest;
tenant_id: string;
logger: Logger;
-}): Promise<SandboxStatus | undefined> {
- const record = await store.getSandboxProvider(tenant_id);
- if (!record) {
- return undefined;
- }
-
- const persisted = sandboxStatusFromRecord(record);
-
- // Prebuilt image — no snapshot registration or refresh.
- if (record.manifest.type === 'truefoundry') {
- return persisted;
- }
-
- const readyIsFresh =
- record.status === 'ready' && Date.now() - Date.parse(record.updated_at) < READY_REVALIDATE_INTERVAL_MS;
- if (record.status === 'failed' || readyIsFresh) {
- return persisted;
+}): Promise<void> {
+ switch (manifest.type) {
+ case 'daytona': {
+ const provider = toDaytonaSandboxProvider({ manifest, tenant_id, logger });
+ await provider.validateAccess();
+ return;
+ }
+ case 'truefoundry':
+ return;
}
+}
- const provider = toDaytonaSandboxProvider({
- manifest: record.manifest,
- tenant_id,
- logger,
- build_metadata: record.build_metadata,
- });
- let build: SandboxBuild;
- if (record.status === 'ready') {
- // this is because image may have deactivated
- build = await withTimeout(provider.buildImage(), STATUS_REFRESH_TIMEOUT_MS, 'sandbox buildImage');
- } else {
- build = await withTimeout(provider.getImageBuildStatus(), STATUS_REFRESH_TIMEOUT_MS, 'sandbox getImageBuildStatus');
- }
- const next = toSandboxStatus(build);
- const updated = await store.updateSandboxStatus({ tenant_id, ...next });
- return updated ? sandboxStatusFromRecord(updated) : next;
+/** Maps a core `SandboxBuild` onto the persisted/wire status shape (metadata passes through). */
+export function toSandboxStatus(build: SandboxBuild): SandboxStatus {
+ return {
+ status: build.status,
+ status_reason: build.reason,
+ build_metadata: build.metadata,
+ };
}
diff --git a/packages/trueforge/src/sandbox/sandboxEnvironmentVersion.ts b/packages/trueforge/src/sandbox/sandboxEnvironmentVersion.ts
index 472b898b5..ace7b4ea0 100644
--- a/packages/trueforge/src/sandbox/sandboxEnvironmentVersion.ts
+++ b/packages/trueforge/src/sandbox/sandboxEnvironmentVersion.ts
@@ -5,7 +5,10 @@
import { randomUUID } from 'node:crypto';
import { isDeepStrictEqual } from 'node:util';
import {
+ DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ DEFAULT_SANDBOX_ENVIRONMENT_RESOURCES,
SandboxEnvironmentVersionInternalMetadataSchema,
+ StoredSandboxEnvironmentManifestSchema,
type SandboxEnvironmentManifest,
type SandboxEnvironmentVersionInternalMetadata,
type SandboxEnvironmentVersionStatus,
@@ -32,6 +35,18 @@ export interface NextSandboxEnvironmentVersion {
internal_metadata: SandboxEnvironmentVersionInternalMetadata;
}
+/** System default env stored jsonb (platform image; no networking/secrets). */
+export function defaultSandboxEnvironmentStoredManifest(
+ provider_type: SandboxEnvironmentProviderType,
+): StoredSandboxEnvironmentManifest {
+ return StoredSandboxEnvironmentManifestSchema.parse({
+ name: DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ resources: DEFAULT_SANDBOX_ENVIRONMENT_RESOURCES,
+ type: provider_type,
+ sandbox_provider: provider_type,
+ });
+}
+
/** Merge redacted keep-as-is stand-ins with previously stored secret values (sandbox-provider style). */
export function resolveManifestSecrets({
manifest,
@@ -127,9 +142,9 @@ export function buildNextVersion({
provider_type: SandboxEnvironmentProviderType;
}): NextSandboxEnvironmentVersion {
const diff = diffManifest({ previous: previous_manifest, next: manifest });
- // Detect only — do NOT call Daytona secrets/build APIs here.
- const needs_snapshot =
- manifest.image?.type === 'build' && (diff.build_changed || diff.resources_changed || !previous_external_ref);
+ // Daytona bakes cpu/memory/disk into the snapshot; resource or build changes need a new ref.
+ // Env vars / networking apply at create time and can reuse previous_external_ref.
+ const needs_snapshot = !previous_external_ref || diff.build_changed || diff.resources_changed;
const resolved = resolveManifestSecrets({
manifest,
@@ -142,7 +157,7 @@ export function buildNextVersion({
manifest: toStoredManifest({ manifest: resolved, provider_type }),
status: 'pending',
status_reason: null,
- external_ref: needs_snapshot || !previous_external_ref ? newExternalRef() : previous_external_ref,
+ external_ref: needs_snapshot ? newExternalRef() : previous_external_ref,
internal_metadata: SandboxEnvironmentVersionInternalMetadataSchema.parse({}),
};
}
diff --git a/packages/trueforge/src/schemas/sandboxEnvironment.ts b/packages/trueforge/src/schemas/sandboxEnvironment.ts
index c7acdab7b..55f8ef9b4 100644
--- a/packages/trueforge/src/schemas/sandboxEnvironment.ts
+++ b/packages/trueforge/src/schemas/sandboxEnvironment.ts
@@ -11,6 +11,11 @@ import { NameSchema } from './common';
export const SANDBOX_ENVIRONMENT_DESCRIPTION_MAX_LENGTH = 1024;
+/** Reserved system environment name (tenant default; not creatable via public CRUD). */
+export const DEFAULT_SANDBOX_ENVIRONMENT_NAME = 'default';
+
+export const DEFAULT_SANDBOX_ENVIRONMENT_RESOURCES = { cpu: 1, memory: 1, disk: 3 } as const;
+
const BUILD_SCRIPT_EXAMPLE = 'set -ex\npip install httpx\n';
export const SandboxEnvironmentDescriptionSchema = z
@@ -25,8 +30,8 @@ export const SandboxEnvironmentLifecycleStageSchema = z
.openapi('SandboxEnvironmentLifecycleStage');
export const SandboxEnvironmentVersionStatusSchema = z
- .enum(['pending', 'active', 'failed'])
- .describe('Build/activation status of the environment (active version under the hood).')
+ .enum(['pending', 'ready', 'failed'])
+ .describe('Build readiness of the environment version.')
.openapi('SandboxEnvironmentVersionStatus');
/** Single image variant today; widen with discriminatedUnion when another type lands. */
@@ -90,29 +95,39 @@ export const SandboxEnvironmentNetworkingSchema = z
})
.openapi('SandboxEnvironmentNetworking');
-/** Wire + request/response document — no `type` / `sandbox_provider`. */
-export const SandboxEnvironmentManifestSchema = z
+/**
+ * Manifest fields shared by wire and storage. Responses may use name `"default"`;
+ * create/update requests reject it (reserved system env).
+ */
+const SandboxEnvironmentManifestFieldsSchema = z
.object({
- name: NameSchema.refine(name => name !== 'default', {
- message: 'name "default" is reserved',
- }),
+ name: NameSchema,
description: SandboxEnvironmentDescriptionSchema.optional(),
image: SandboxEnvironmentImageSchema.optional(),
- resources: SandboxEnvironmentResourcesSchema.default({ cpu: 1, memory: 1, disk: 3 }),
+ resources: SandboxEnvironmentResourcesSchema.default(DEFAULT_SANDBOX_ENVIRONMENT_RESOURCES),
environment_variables: z.record(z.string().min(1), z.string()).optional(),
networking: SandboxEnvironmentNetworkingSchema.optional(),
})
- .strict()
- .openapi('SandboxEnvironmentManifest');
+ .strict();
+
+/** Wire document (list/get/response) — no `type` / `sandbox_provider`; name `"default"` allowed. */
+export const SandboxEnvironmentManifestSchema =
+ SandboxEnvironmentManifestFieldsSchema.openapi('SandboxEnvironmentManifest');
+
+/** PUT body manifest — rejects reserved name `"default"`. */
+const SandboxEnvironmentManifestRequestSchema = SandboxEnvironmentManifestFieldsSchema.refine(
+ manifest => manifest.name !== DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ { message: 'name "default" is reserved', path: ['name'] },
+).openapi('SandboxEnvironmentManifestRequest');
/**
* Persisted version jsonb — wire fields plus backend-resolved provider identity.
* `truefoundry` = TrueFoundry platform mode label; runtime still uses Daytona for envs.
- * Not exposed on request/response wire types.
+ * Not exposed on request/response wire types. Allows name `"default"`.
*/
export const StoredSandboxEnvironmentManifestSchema = z
.object({
- ...SandboxEnvironmentManifestSchema.shape,
+ ...SandboxEnvironmentManifestFieldsSchema.shape,
type: z.enum(['daytona', 'truefoundry']),
sandbox_provider: z.enum(['daytona', 'truefoundry']),
})
@@ -138,7 +153,7 @@ export const SandboxEnvironmentVersionInternalMetadataSchema = z
/** PUT create-or-update body (single write API). */
export const UpdateSandboxEnvironmentRequestSchema = z
.object({
- manifest: SandboxEnvironmentManifestSchema,
+ manifest: SandboxEnvironmentManifestRequestSchema,
})
.strict()
.openapi('UpdateSandboxEnvironmentRequest');
diff --git a/packages/trueforge/src/schemas/sandboxProvider.ts b/packages/trueforge/src/schemas/sandboxProvider.ts
index 380ed8c6d..9673e34d0 100644
--- a/packages/trueforge/src/schemas/sandboxProvider.ts
+++ b/packages/trueforge/src/schemas/sandboxProvider.ts
@@ -94,12 +94,10 @@ export const SandboxStatusSchema = z
})
.strict();
-/** Settings wire item: nested Daytona manifest plus build status (no build_metadata). */
+/** Settings wire item: nested Daytona manifest (build readiness lives on the default sandbox environment). */
export const ConfiguredSandboxProviderSchema = z
.object({
manifest: SandboxProviderManifestSchema,
- status: SandboxBuildStatusSchema,
- status_reason: z.string().nullable().describe('Human-readable detail for the current status; null when ready.'),
})
.strict()
.openapi('ConfiguredSandboxProvider');
diff --git a/packages/trueforge/src/truefoundry/TrueFoundrySandboxEnvironmentStore.ts b/packages/trueforge/src/truefoundry/TrueFoundrySandboxEnvironmentStore.ts
new file mode 100644
index 000000000..2c93933f8
--- /dev/null
+++ b/packages/trueforge/src/truefoundry/TrueFoundrySandboxEnvironmentStore.ts
@@ -0,0 +1,184 @@
+/**
+ * TrueFoundry-mode sandbox environments: in-memory always-ready `"default"` when the
+ * shared provider supports environments (Daytona); custom env CRUD delegated to persistence.
+ *
+ * When the shared provider does not support environments (TFY on-prem sandbox) there is no
+ * env/snapshot concept — get/upsert/list-inject no-op (list still returns persistence leftovers).
+ */
+import type { TokenPagination } from '@truefoundry/trueforge-core/agent-session';
+import { encodeOffsetPageToken } from '@truefoundry/trueforge-core/agent-session/store/OffsetPageToken';
+import { createLogger } from 'winston';
+import type {
+ DeleteSandboxEnvironmentInput,
+ GetSandboxEnvironmentInput,
+ GetSandboxEnvironmentVersionInput,
+ ISandboxEnvironmentStore,
+ ListSandboxEnvironmentsInput,
+ MarkSandboxEnvironmentVersionFailedInput,
+ MarkSandboxEnvironmentVersionReadyInput,
+ SandboxEnvironmentVersionForProgress,
+ SandboxEnvironmentVersionRecord,
+ SandboxEnvironmentWithVersion,
+ UpsertSandboxEnvironmentInput,
+} from '../db/sandboxEnvironmentStore';
+import { DEFAULT_SANDBOX_ENVIRONMENT_NAME } from '../schemas/sandboxEnvironment';
+import { trueFoundryManaged } from './errors';
+import { synthesizeTrueFoundryDefaultSandboxEnvironment } from './synthesizeTrueFoundryDefaultSandboxEnvironment';
+
+const logger = createLogger({ defaultMeta: { module: 'TrueFoundrySandboxEnvironmentStore' } });
+
+export interface TrueFoundrySandboxEnvironmentStoreOptions {
+ /**
+ * From the shared sandbox provider's `envSupported` (Daytona true; TFY on-prem false).
+ * When false, env CRUD/progress no-ops. Default tip comes from provider config via synthesize.
+ */
+ envSupported: boolean;
+}
+
+/**
+ * Wraps persistence for custom envs; `"default"` is always in-memory when env is supported.
+ */
+export class TrueFoundrySandboxEnvironmentStore<
+ TTransaction = never,
+> implements ISandboxEnvironmentStore<TTransaction> {
+ readonly #persistence: ISandboxEnvironmentStore<TTransaction>;
+ readonly #envSupported: boolean;
+
+ constructor(persistence: ISandboxEnvironmentStore<TTransaction>, options: TrueFoundrySandboxEnvironmentStoreOptions) {
+ this.#persistence = persistence;
+ this.#envSupported = options.envSupported;
+ }
+
+ async listEnvironments(
+ input: ListSandboxEnvironmentsInput,
+ transaction?: TTransaction,
+ ): Promise<{ data: SandboxEnvironmentWithVersion[]; pagination: TokenPagination }> {
+ // No env/snapshot concept — persistence only (e.g. leftovers after a flip).
+ if (!this.#envSupported || input.page_token) {
+ return this.#persistence.listEnvironments(input, transaction);
+ }
+
+ const synthesized = synthesizeTrueFoundryDefaultSandboxEnvironment(input.tenant_id);
+ const withoutDefault = (rows: SandboxEnvironmentWithVersion[]) =>
+ rows.filter(row => row.environment.name !== DEFAULT_SANDBOX_ENVIRONMENT_NAME);
+
+ // First page: inject default; when limited, reserve one slot for it.
+ const customLimit = input.limit === undefined ? undefined : Math.max(input.limit - 1, 0);
+ if (customLimit === 0) {
+ const peek = await this.#persistence.listEnvironments({ ...input, limit: 1 }, transaction);
+ const hasMore = withoutDefault(peek.data).length > 0 || peek.pagination.next_page_token !== undefined;
+ return {
+ data: [synthesized],
+ pagination: {
+ limit: input.limit ?? 1,
+ ...(hasMore ? { next_page_token: peek.pagination.next_page_token ?? encodeOffsetPageToken(0) } : {}),
+ },
+ };
+ }
+
+ const listed = await this.#persistence.listEnvironments(
+ customLimit === undefined ? input : { ...input, limit: customLimit },
+ transaction,
+ );
+ const customs = withoutDefault(listed.data);
+ return {
+ data: [synthesized, ...customs],
+ pagination: customLimit === undefined ? { limit: customs.length + 1 } : listed.pagination,
+ };
+ }
+
+ getEnvironment(
+ input: GetSandboxEnvironmentInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentWithVersion | undefined> {
+ if (!this.#envSupported) {
+ logger.info('Skipping sandbox environment get (provider does not support environments)', {
+ name: input.name,
+ tenant_id: input.tenant_id,
+ });
+ return Promise.resolve(undefined);
+ }
+ if (input.name === DEFAULT_SANDBOX_ENVIRONMENT_NAME) {
+ return Promise.resolve(synthesizeTrueFoundryDefaultSandboxEnvironment(input.tenant_id));
+ }
+ return this.#persistence.getEnvironment(input, transaction);
+ }
+
+ upsertEnvironment(
+ input: UpsertSandboxEnvironmentInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentWithVersion> {
+ if (!this.#envSupported) {
+ logger.info('Skipping sandbox environment upsert (provider does not support environments)', {
+ name: input.name,
+ tenant_id: input.tenant_id,
+ });
+ return trueFoundryManaged();
+ }
+ if (input.name === DEFAULT_SANDBOX_ENVIRONMENT_NAME) {
+ return Promise.resolve(synthesizeTrueFoundryDefaultSandboxEnvironment(input.tenant_id));
+ }
+ return this.#persistence.upsertEnvironment(input, transaction);
+ }
+
+ listLatestPendingVersions(transaction?: TTransaction): Promise<string[]> {
+ if (!this.#envSupported) {
+ logger.info('Skipping pending sandbox environment list (provider does not support environments)');
+ return Promise.resolve([]);
+ }
+ return this.#persistence.listLatestPendingVersions(transaction);
+ }
+
+ getSandboxEnvironmentVersion(
+ input: GetSandboxEnvironmentVersionInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentVersionForProgress | undefined> {
+ if (!this.#envSupported) {
+ logger.info('Skipping sandbox environment version get (provider does not support environments)', {
+ environment_version_id: input.environment_version_id,
+ });
+ return Promise.resolve(undefined);
+ }
+ return this.#persistence.getSandboxEnvironmentVersion(input, transaction);
+ }
+
+ markVersionReady(
+ input: MarkSandboxEnvironmentVersionReadyInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentWithVersion | undefined> {
+ if (!this.#envSupported) {
+ logger.info('Skipping sandbox environment mark ready (provider does not support environments)', {
+ environment_version_id: input.environment_version_id,
+ });
+ return Promise.resolve(undefined);
+ }
+ return this.#persistence.markVersionReady(input, transaction);
+ }
+
+ markVersionFailed(
+ input: MarkSandboxEnvironmentVersionFailedInput,
+ transaction?: TTransaction,
+ ): Promise<SandboxEnvironmentVersionRecord | undefined> {
+ if (!this.#envSupported) {
+ logger.info('Skipping sandbox environment mark failed (provider does not support environments)', {
+ environment_version_id: input.environment_version_id,
+ });
+ return Promise.resolve(undefined);
+ }
+ return this.#persistence.markVersionFailed(input, transaction);
+ }
+
+ deleteEnvironment(input: DeleteSandboxEnvironmentInput, transaction?: TTransaction): Promise<void> {
+ if (!this.#envSupported) {
+ logger.info('Skipping sandbox environment delete (provider does not support environments)', {
+ name: input.name,
+ tenant_id: input.tenant_id,
+ });
+ return Promise.resolve();
+ }
+ if (input.name === DEFAULT_SANDBOX_ENVIRONMENT_NAME) {
+ return trueFoundryManaged();
+ }
+ return this.#persistence.deleteEnvironment(input, transaction);
+ }
+}
diff --git a/packages/trueforge/src/truefoundry/TrueFoundrySandboxProviderStore.ts b/packages/trueforge/src/truefoundry/TrueFoundrySandboxProviderStore.ts
index e309f0e41..107bbb0e9 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundrySandboxProviderStore.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundrySandboxProviderStore.ts
@@ -1,7 +1,6 @@
import type {
ISandboxProviderStore,
SandboxProviderRecord,
- UpdateSandboxStatusInput,
UpsertSandboxProviderInput,
} from '../db/sandboxProviderStore';
import { trueFoundryManaged } from './errors';
@@ -30,12 +29,7 @@ function synthesizeDaytonaRecord({
auto_archive_interval_in_minutes: settings.autoArchiveIntervalInMinutes,
auto_delete_interval_in_minutes: settings.autoDeleteIntervalInMinutes,
},
- status: 'ready',
- status_reason: null,
- // Snapshot name only — no image_uri; TrueFoundry mode never registers a snapshot.
- build_metadata: { build_ref: settings.snapshotName },
created_at: now,
- // Fresh on every get so checkSnapshotStatus short-circuits without Daytona.
updated_at: now,
};
}
@@ -56,9 +50,6 @@ function synthesizeTrueFoundryRecord({
nats_bridge_url: providerConfig.natsBridgeUrl,
exec_timeout_ms: SANDBOX_DEFAULT_SETTINGS.timeoutMs,
},
- status: 'ready',
- status_reason: null,
- build_metadata: null,
created_at: now,
updated_at: now,
};
@@ -91,13 +82,4 @@ export class TrueFoundrySandboxProviderStore<TTransaction = never> implements IS
void transaction;
return trueFoundryManaged();
}
-
- updateSandboxStatus(
- input: UpdateSandboxStatusInput,
- transaction?: TTransaction,
- ): Promise<SandboxProviderRecord | undefined> {
- void input;
- void transaction;
- return trueFoundryManaged();
- }
}
diff --git a/packages/trueforge/src/truefoundry/resolveTrueFoundrySandboxProviderConfig.ts b/packages/trueforge/src/truefoundry/resolveTrueFoundrySandboxProviderConfig.ts
index fd4c1d2b8..3a4948e3c 100644
--- a/packages/trueforge/src/truefoundry/resolveTrueFoundrySandboxProviderConfig.ts
+++ b/packages/trueforge/src/truefoundry/resolveTrueFoundrySandboxProviderConfig.ts
@@ -88,3 +88,18 @@ export function resolveTrueFoundrySandboxProviderConfig(
}
return undefined;
}
+
+/**
+ * Capability/probe check: true when shared sandbox env resolves.
+ * Standalone, disabled, or incomplete/invalid settings → false (never throws).
+ */
+export function hasTrueFoundrySandboxProviderConfig(config: ServerConfiguration = configuration): boolean {
+ if (config.STANDALONE) {
+ return false;
+ }
+ try {
+ return resolveTrueFoundrySandboxProviderConfig(config) !== undefined;
+ } catch {
+ return false;
+ }
+}
diff --git a/packages/trueforge/src/truefoundry/synthesizeTrueFoundryDefaultSandboxEnvironment.ts b/packages/trueforge/src/truefoundry/synthesizeTrueFoundryDefaultSandboxEnvironment.ts
new file mode 100644
index 000000000..f942116cb
--- /dev/null
+++ b/packages/trueforge/src/truefoundry/synthesizeTrueFoundryDefaultSandboxEnvironment.ts
@@ -0,0 +1,57 @@
+/**
+ * In-memory always-ready `"default"` sandbox environment for TFY+Daytona.
+ * Tip (snapshot name) comes from shared provider config — not from the env store.
+ */
+import type { SandboxEnvironmentWithVersion } from '../db/sandboxEnvironmentStore';
+import { defaultSandboxEnvironmentStoredManifest } from '../sandbox/sandboxEnvironmentVersion';
+import { NameSchema } from '../schemas/common';
+import {
+ DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ SandboxEnvironmentVersionInternalMetadataSchema,
+} from '../schemas/sandboxEnvironment';
+import { resolveTrueFoundrySandboxProviderConfig } from './resolveTrueFoundrySandboxProviderConfig';
+
+const DEFAULT_ENVIRONMENT_ID = 'tfy-default-sandbox-environment';
+const DEFAULT_VERSION_ID = 'tfy-default-sandbox-environment-v1';
+const DEFAULT_NAME = NameSchema.parse(DEFAULT_SANDBOX_ENVIRONMENT_NAME);
+const SYSTEM_SUBJECT = {
+ subject_id: 'truefoundry',
+ subject_type: 'user' as const,
+ subject_display_name: 'TrueFoundry',
+};
+const EMPTY_INTERNAL_METADATA = SandboxEnvironmentVersionInternalMetadataSchema.parse({});
+
+/** Synthesize the platform default env row from Daytona shared-provider config. */
+export function synthesizeTrueFoundryDefaultSandboxEnvironment(tenant_id: string): SandboxEnvironmentWithVersion {
+ const provider = resolveTrueFoundrySandboxProviderConfig();
+ if (provider?.type !== 'daytona') {
+ throw new Error('TrueFoundry Daytona sandbox provider is not configured');
+ }
+ const now = new Date().toISOString();
+ return {
+ environment: {
+ id: DEFAULT_ENVIRONMENT_ID,
+ tenant_id,
+ name: DEFAULT_NAME,
+ description: '',
+ active_version: 1,
+ lifecycle_stage: 'active',
+ created_by_subject: SYSTEM_SUBJECT,
+ created_at: now,
+ updated_at: now,
+ },
+ version: {
+ id: DEFAULT_VERSION_ID,
+ environment_id: DEFAULT_ENVIRONMENT_ID,
+ version: 1,
+ manifest: defaultSandboxEnvironmentStoredManifest('daytona'),
+ status: 'ready',
+ status_reason: null,
+ external_ref: provider.settings.snapshotName,
+ internal_metadata: EMPTY_INTERNAL_METADATA,
+ created_by_subject: SYSTEM_SUBJECT,
+ created_at: now,
+ updated_at: now,
+ },
+ };
+}
diff --git a/packages/trueforge/tests/db/sandboxProviderStoreContractSuite.ts b/packages/trueforge/tests/db/sandboxProviderStoreContractSuite.ts
index a337d1c0c..91db3eff9 100644
--- a/packages/trueforge/tests/db/sandboxProviderStoreContractSuite.ts
+++ b/packages/trueforge/tests/db/sandboxProviderStoreContractSuite.ts
@@ -3,15 +3,10 @@
* Runs under jest against a fresh store per test (see backend test files).
*/
import type { ISandboxProviderStore, UpsertSandboxProviderInput } from '../../src/db/sandboxProviderStore';
-import type { SandboxBuildMetadata, SandboxProviderManifest } from '../../src/schemas/sandboxProvider';
+import type { SandboxProviderManifest } from '../../src/schemas/sandboxProvider';
const TENANT = 'default';
-const BUILD_METADATA: SandboxBuildMetadata = {
- build_ref: 'trueforge-build-029ea5ff',
- image_uri: 'tfy.jfrog.io/tfy-images/sandbox:029ea5ff',
-};
-
function manifest(overrides: Partial<SandboxProviderManifest> = {}): SandboxProviderManifest {
return {
type: 'daytona',
@@ -28,9 +23,6 @@ function upsertInput(overrides: Partial<UpsertSandboxProviderInput> = {}): Upser
return {
tenant_id: TENANT,
manifest: manifest(),
- status: 'pending',
- status_reason: 'Sandbox image build started.',
- build_metadata: BUILD_METADATA,
...overrides,
};
}
@@ -38,15 +30,12 @@ function upsertInput(overrides: Partial<UpsertSandboxProviderInput> = {}): Upser
const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
export function runSandboxProviderStoreContractSuite(getStore: () => ISandboxProviderStore): void {
- it('upsert creates a provider and round-trips the manifest + build status', async () => {
+ it('upsert creates a provider and round-trips the manifest', async () => {
const store = getStore();
const created = await store.upsertSandboxProvider(upsertInput());
expect(created.tenant_id).toBe(TENANT);
expect(created.manifest).toEqual(manifest());
- expect(created.status).toBe('pending');
- expect(created.status_reason).toBe('Sandbox image build started.');
- expect(created.build_metadata).toEqual(BUILD_METADATA);
expect(created.created_at).toMatch(ISO_UTC);
expect(created.updated_at).toBe(created.created_at);
@@ -85,32 +74,4 @@ export function runSandboxProviderStoreContractSuite(getStore: () => ISandboxPro
expect(forDefault?.manifest.exec_timeout_ms).toBe(60000);
expect(forOther?.manifest.exec_timeout_ms).toBe(120000);
});
-
- it('updateSandboxStatus refreshes only the build status, keeping the manifest', async () => {
- const store = getStore();
- const created = await store.upsertSandboxProvider(upsertInput());
-
- const updated = await store.updateSandboxStatus({
- tenant_id: TENANT,
- status: 'ready',
- status_reason: null,
- build_metadata: BUILD_METADATA,
- });
-
- expect(updated?.status).toBe('ready');
- expect(updated?.status_reason).toBeNull();
- expect(updated?.manifest).toEqual(created.manifest);
- });
-
- it('updateSandboxStatus returns undefined when no provider exists', async () => {
- const store = getStore();
- expect(
- await store.updateSandboxStatus({
- tenant_id: TENANT,
- status: 'ready',
- status_reason: null,
- build_metadata: BUILD_METADATA,
- }),
- ).toBeUndefined();
- });
}
diff --git a/packages/trueforge/tests/unit/apis/capabilities.test.ts b/packages/trueforge/tests/unit/apis/capabilities.test.ts
index 7f95232fe..3b1c37906 100644
--- a/packages/trueforge/tests/unit/apis/capabilities.test.ts
+++ b/packages/trueforge/tests/unit/apis/capabilities.test.ts
@@ -1,6 +1,3 @@
-// Sandbox capability is driven by the refreshed image status; stub it so tests never touch Daytona.
-jest.mock('../../../src/sandbox/providerUtils', () => ({ checkSnapshotStatus: jest.fn() }));
-
import { OpenAPIHono } from '@hono/zod-openapi';
import { exportJWK, generateKeyPair, SignJWT } from 'jose';
import type { Configuration } from 'openid-client';
@@ -13,22 +10,26 @@ import { disableOidcAuth, enableOidcAuth, initOidc } from '../../../src/auth/oid
import { OidcAuthenticator } from '../../../src/auth/oidcAuthenticator';
import { StandaloneAuthenticator } from '../../../src/auth/standaloneAuthenticator';
import type { OIDCConfig } from '../../../src/config';
-import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
+import type { ISandboxEnvironmentStore, SandboxEnvironmentWithVersion } from '../../../src/db/sandboxEnvironmentStore';
import { createSqliteDb } from '../../../src/db/sqlite/client';
-import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import type { IWebSearchProviderStore } from '../../../src/db/webSearchProviderStore';
import { setCachedLocalSandboxSupport } from '../../../src/sandbox/localRuntime';
-import { checkSnapshotStatus } from '../../../src/sandbox/providerUtils';
-import type { SandboxBuildStatus, SandboxStatus } from '../../../src/schemas/sandboxProvider';
+import type { SandboxEnvironmentVersionStatus } from '../../../src/schemas/sandboxEnvironment';
-const mockStatus = checkSnapshotStatus as jest.Mock;
const silentLogger = createLogger({ silent: true });
-const buildWithStatus = (status: SandboxBuildStatus): SandboxStatus => ({
- status,
- status_reason: status === 'failed' ? 'Sandbox image build failed (build_failed).' : null,
- build_metadata: { build_ref: 'trueforge-build-029ea5ff', image_uri: 'tfy.jfrog.io/tfy-images/sandbox:029ea5ff' },
-});
+let mockDefaultStatus: SandboxEnvironmentVersionStatus | undefined;
+
+function mockDefaultEnvStore(): ISandboxEnvironmentStore {
+ return {
+ getEnvironment: () =>
+ Promise.resolve(
+ mockDefaultStatus === undefined
+ ? undefined
+ : ({ version: { status: mockDefaultStatus } } as unknown as SandboxEnvironmentWithVersion),
+ ),
+ } as unknown as ISandboxEnvironmentStore;
+}
const ISSUER = 'https://issuer.example.com';
const AUDIENCE = 'harness-client';
@@ -61,8 +62,7 @@ function withAuth(router: OpenAPIHono, authenticator: Authenticator): OpenAPIHon
describe('capabilities routers', () => {
beforeEach(() => {
- mockStatus.mockReset();
- mockStatus.mockResolvedValue(undefined);
+ mockDefaultStatus = undefined;
setCachedLocalSandboxSupport(undefined);
});
@@ -84,9 +84,13 @@ describe('capabilities routers', () => {
};
return withAuth(
createCapabilitiesRouter({
- resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: mockDefaultEnvStore(),
resolveWebSearchProviderStore: () => webSearchStore ?? emptyWebSearchStore,
- withTransaction: callback => db.transaction().execute(callback),
+ withTransaction: (() => {
+ const run = <T>(callback: (trx: never) => Promise<T>): Promise<T> =>
+ db.transaction().execute(callback as never);
+ return run;
+ })() as never,
logger: silentLogger,
resolveRequestContext,
}),
@@ -96,7 +100,7 @@ describe('capabilities routers', () => {
it('reports sandbox + skill disabled when no image status is available', async () => {
disableOidcAuth();
- mockStatus.mockResolvedValue(undefined);
+ mockDefaultStatus = undefined;
const router = makeRouter();
const response = await router.request('/');
@@ -116,7 +120,7 @@ describe('capabilities routers', () => {
it('reports web_search enabled when a provider is configured', async () => {
disableOidcAuth();
- mockStatus.mockResolvedValue(undefined);
+ mockDefaultStatus = undefined;
const configuredStore: IWebSearchProviderStore = {
getProvider: () =>
Promise.resolve({
@@ -138,7 +142,7 @@ describe('capabilities routers', () => {
it('reports sandbox + skill enabled when local fallback is cached and no image status exists', async () => {
disableOidcAuth();
- mockStatus.mockResolvedValue(undefined);
+ mockDefaultStatus = undefined;
setCachedLocalSandboxSupport({
supported: true,
platform: 'darwin',
@@ -161,7 +165,7 @@ describe('capabilities routers', () => {
it('reports sandbox + skill enabled only when the image is ready', async () => {
disableOidcAuth();
- mockStatus.mockResolvedValue(buildWithStatus('ready'));
+ mockDefaultStatus = 'ready';
const router = makeRouter();
const response = await router.request('/');
@@ -178,7 +182,7 @@ describe('capabilities routers', () => {
it('reports sandbox disabled with a "being prepared" skill reason while the image is still pending', async () => {
disableOidcAuth();
- mockStatus.mockResolvedValue(buildWithStatus('pending'));
+ mockDefaultStatus = 'pending';
const router = makeRouter();
const response = await router.request('/');
@@ -196,7 +200,7 @@ describe('capabilities routers', () => {
it('reports "not configured" skill reason when the image build failed', async () => {
disableOidcAuth();
- mockStatus.mockResolvedValue(buildWithStatus('failed'));
+ mockDefaultStatus = 'failed';
const router = makeRouter();
const response = await router.request('/');
@@ -209,16 +213,6 @@ describe('capabilities routers', () => {
});
});
- it('fails closed (sandbox disabled) when the status check throws', async () => {
- disableOidcAuth();
- mockStatus.mockRejectedValue(new Error('daytona unreachable'));
- const router = makeRouter();
-
- const response = await router.request('/');
- expect(response.status).toBe(200);
- expect(await response.json()).toMatchObject({ data: { sandbox: { enabled: false } } });
- });
-
describe('when auth is enabled', () => {
const realFetch = globalThis.fetch;
let privateKey: Awaited<ReturnType<typeof generateKeyPair>>['privateKey'];
@@ -280,16 +274,19 @@ describe('capabilities routers', () => {
it('marks settings enabled for admin callers and disabled for non-admin callers', async () => {
const db = createSqliteDb(':memory:');
- await migrateSqliteToLatest(db);
const emptyWebSearchStore: IWebSearchProviderStore = {
getProvider: () => Promise.resolve(undefined),
upsertProvider: () => Promise.reject(new Error('not used')),
};
const router = withAuth(
createCapabilitiesRouter({
- resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: mockDefaultEnvStore(),
resolveWebSearchProviderStore: () => emptyWebSearchStore,
- withTransaction: callback => db.transaction().execute(callback),
+ withTransaction: (() => {
+ const run = <T>(callback: (trx: never) => Promise<T>): Promise<T> =>
+ db.transaction().execute(callback as never);
+ return run;
+ })() as never,
logger: silentLogger,
resolveRequestContext,
}),
diff --git a/packages/trueforge/tests/unit/apis/modelProviders.test.ts b/packages/trueforge/tests/unit/apis/modelProviders.test.ts
index 23d5ec809..bddd3dedb 100644
--- a/packages/trueforge/tests/unit/apis/modelProviders.test.ts
+++ b/packages/trueforge/tests/unit/apis/modelProviders.test.ts
@@ -16,6 +16,7 @@ import type { IModelProviderStore } from '../../../src/db/modelProviderStore';
import { createSqliteDb } from '../../../src/db/sqlite/client';
import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
import { SqliteOAuthTokenStore } from '../../../src/db/sqlite/token-store/SqliteOAuthTokenStore';
@@ -132,6 +133,7 @@ async function createRouters(): Promise<{
tokenStore,
resolveSkillStore: () => new SqliteSkillStore(db),
resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),
withTransaction: callback => db.transaction().execute(callback),
logger: winston.createLogger({ silent: true }),
diff --git a/packages/trueforge/tests/unit/apis/sandboxEnvironments.test.ts b/packages/trueforge/tests/unit/apis/sandboxEnvironments.test.ts
new file mode 100644
index 000000000..62218b339
--- /dev/null
+++ b/packages/trueforge/tests/unit/apis/sandboxEnvironments.test.ts
@@ -0,0 +1,138 @@
+import { DAYTONA_SNAPSHOT_NOT_STARTED_REASON } from '@truefoundry/trueforge-core/core';
+import { createLogger } from 'winston';
+import { createSandboxEnvironmentBuildRouter } from '../../../src/apis/sandboxEnvironmentBuild';
+import { createSandboxEnvironmentsRouter } from '../../../src/apis/sandboxEnvironments';
+import { STANDALONE_REQUEST_CONTEXT } from '../../../src/auth/identity';
+import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
+import { createSqliteDb } from '../../../src/db/sqlite/client';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
+import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
+import * as providerUtils from '../../../src/sandbox/providerUtils';
+
+jest.mock('../../../src/sandbox/providerUtils', () => {
+ const actual = jest.requireActual<typeof import('../../../src/sandbox/providerUtils')>(
+ '../../../src/sandbox/providerUtils',
+ );
+ return {
+ ...actual,
+ toDaytonaSandboxProvider: jest.fn(),
+ };
+});
+
+const logger = createLogger({ silent: true });
+
+const daytonaManifest = {
+ type: 'daytona' as const,
+ auth: { api_key: 'dtn-test-secret' },
+ exec_timeout_ms: 60_000,
+ auto_stop_interval_in_minutes: 5,
+ auto_archive_interval_in_minutes: 60,
+ auto_delete_interval_in_minutes: 7200,
+};
+
+describe('sandbox environments API → build controller path', () => {
+ afterEach(() => {
+ jest.restoreAllMocks();
+ });
+
+ async function setup() {
+ const db = createSqliteDb(':memory:');
+ await migrateSqliteToLatest(db);
+ const sandboxEnvironmentStore = new SqliteSandboxEnvironmentStore(db);
+ const sandboxProviderStore = new SqliteSandboxProviderStore(db);
+ await sandboxProviderStore.upsertSandboxProvider({
+ tenant_id: STANDALONE_REQUEST_CONTEXT.tenant_id,
+ manifest: daytonaManifest,
+ });
+
+ const publicRouter = createSandboxEnvironmentsRouter({
+ sandboxEnvironmentStore,
+ resolveAgentStore: () =>
+ ({
+ listAgentNamesUsingSandboxEnvironment: jest.fn().mockResolvedValue([]),
+ }) as never,
+ resolveSandboxProviderStore: () => sandboxProviderStore,
+ resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
+ });
+ const buildRouter = createSandboxEnvironmentBuildRouter({
+ sandboxEnvironmentStore,
+ sandboxProviderStore,
+ logger,
+ });
+ return { publicRouter, buildRouter, sandboxEnvironmentStore };
+ }
+
+ it('PUT custom env lands pending; internal progress marks ready after build', async () => {
+ const { publicRouter, buildRouter, sandboxEnvironmentStore } = await setup();
+
+ const putRes = await publicRouter.request('/', {
+ method: 'PUT',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ manifest: {
+ name: 'pyjokes-env',
+ description: 'has pyjokes',
+ image: { type: 'build', build_script: 'pip install pyjokes' },
+ },
+ }),
+ });
+ expect(putRes.status).toBe(200);
+ const putBody = (await putRes.json()) as { data: { status: string; name: string } };
+ expect(putBody.data).toMatchObject({ name: 'pyjokes-env', status: 'pending' });
+
+ const pendingRes = await buildRouter.request('/pending');
+ expect(pendingRes.status).toBe(200);
+ const pendingBody = (await pendingRes.json()) as { data: { environment_version_id: string }[] };
+ expect(pendingBody.data).toHaveLength(1);
+ const versionId = pendingBody.data[0]?.environment_version_id;
+ expect(versionId).toBeDefined();
+
+ jest.mocked(providerUtils.toDaytonaSandboxProvider).mockReturnValue({
+ getBuildStatus: jest.fn().mockResolvedValue({
+ status: 'pending',
+ reason: DAYTONA_SNAPSHOT_NOT_STARTED_REASON,
+ metadata: null,
+ }),
+ build: jest.fn().mockResolvedValue({
+ status: 'ready',
+ reason: null,
+ metadata: null,
+ }),
+ } as never);
+
+ const progressRes = await buildRouter.request('/progress', {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ environment_version_id: versionId }),
+ });
+ expect(progressRes.status).toBe(204);
+
+ const getRes = await publicRouter.request('/pyjokes-env');
+ expect(getRes.status).toBe(200);
+ const getBody = (await getRes.json()) as { data: { status: string } };
+ expect(getBody.data.status).toBe('ready');
+
+ const pendingAfter = await sandboxEnvironmentStore.listLatestPendingVersions();
+ expect(pendingAfter).toEqual([]);
+ });
+
+ it('rejects creating the reserved default name', async () => {
+ const { publicRouter } = await setup();
+ const putRes = await publicRouter.request('/', {
+ method: 'PUT',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ manifest: { name: 'default' },
+ }),
+ });
+ expect(putRes.status).toBe(400);
+ });
+
+ it('lists environments for the caller without error when none exist yet', async () => {
+ const { publicRouter } = await setup();
+ const listRes = await publicRouter.request('/');
+ expect(listRes.status).toBe(200);
+ const listBody = (await listRes.json()) as { data: unknown[] };
+ expect(Array.isArray(listBody.data)).toBe(true);
+ });
+});
diff --git a/packages/trueforge/tests/unit/apis/sandboxProviders.test.ts b/packages/trueforge/tests/unit/apis/sandboxProviders.test.ts
index 0be8b1c9a..e3ff236cb 100644
--- a/packages/trueforge/tests/unit/apis/sandboxProviders.test.ts
+++ b/packages/trueforge/tests/unit/apis/sandboxProviders.test.ts
@@ -1,14 +1,3 @@
-// Stub the Daytona-touching helpers so the router never talks to Daytona: the PUT path builds via
-// toDaytonaSandboxProvider, and the GET path refreshes via checkSnapshotStatus. isDaytonaAuthError,
-// isDaytonaPermissionError and toSandboxStatus stay real so the error mapping and PUT wire shape are
-// exercised.
-jest.mock('../../../src/sandbox/providerUtils', () => {
- const actual = jest.requireActual('../../../src/sandbox/providerUtils');
- return { ...actual, toDaytonaSandboxProvider: jest.fn(), checkSnapshotStatus: jest.fn() };
-});
-
-import { DaytonaError } from '@daytona/sdk';
-import type { SandboxBuild } from '@truefoundry/trueforge-core/core';
import { createLogger } from 'winston';
import { createCatalogRouter } from '../../../src/apis/catalog';
import { createSandboxProvidersRouter } from '../../../src/apis/sandboxProviders';
@@ -21,13 +10,21 @@ import { WebSearchCatalog } from '../../../src/catalog/WebSearchCatalog';
import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
import type { ISandboxProviderStore } from '../../../src/db/sandboxProviderStore';
import { createSqliteDb } from '../../../src/db/sqlite/client';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
-import { checkSnapshotStatus, toDaytonaSandboxProvider } from '../../../src/sandbox/providerUtils';
import { toRedactedSecretValue } from '../../../src/utils/secretRedaction';
-const mockProviderFactory = toDaytonaSandboxProvider as jest.Mock;
-const mockCheckStatus = checkSnapshotStatus as jest.Mock;
-const silentLogger = createLogger({ silent: true });
+jest.mock('../../../src/sandbox/providerUtils', () => {
+ const actual = jest.requireActual<typeof import('../../../src/sandbox/providerUtils')>(
+ '../../../src/sandbox/providerUtils',
+ );
+ return {
+ ...actual,
+ validateSandboxProviderAccess: jest.fn(async () => undefined),
+ };
+});
+
+const logger = createLogger({ silent: true });
const putBody = {
type: 'daytona' as const,
@@ -38,33 +35,12 @@ const putBody = {
auto_delete_interval_in_minutes: 7200,
};
-const IMAGE_URI = 'tfy.jfrog.io/tfy-images/truefoundry-utils-core-sandbox:029ea5ff';
-const readyBuild: SandboxBuild = {
- status: 'ready',
- reason: null,
- metadata: { build_ref: 'trueforge-build-029ea5ff', image_uri: IMAGE_URI },
+const putBodyWire = {
+ manifest: {
+ ...putBody,
+ auth: { api_key: toRedactedSecretValue(putBody.auth.api_key) },
+ },
};
-const expectedStatus = {
- status: 'ready' as const,
- status_reason: null,
-};
-
-/** Wire GET/PUT response: the (redacted) manifest nested under `manifest`, plus the build status. */
-function wireResponse(manifest: Record<string, unknown>) {
- return { manifest, ...expectedStatus };
-}
-
-const putBodyWire = wireResponse({
- ...putBody,
- auth: { api_key: toRedactedSecretValue(putBody.auth.api_key) },
-});
-
-function stubProvider(overrides: { buildImage?: jest.Mock; getImageBuildStatus?: jest.Mock } = {}) {
- return {
- buildImage: overrides.buildImage ?? jest.fn().mockResolvedValue(readyBuild),
- getImageBuildStatus: overrides.getImageBuildStatus ?? jest.fn().mockResolvedValue(readyBuild),
- };
-}
function wrapManifest(manifest: unknown) {
return { manifest };
@@ -88,25 +64,18 @@ async function createRouters(): Promise<{
return {
settingsRouter: createSandboxProvidersRouter({
resolveSandboxProviderStore: () => sandboxProviderStore,
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
withTransaction: callback => db.transaction().execute(callback),
- logger: silentLogger,
+ logger,
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
}),
sandboxProviderStore,
};
}
-beforeEach(() => {
- mockProviderFactory.mockReset();
- mockProviderFactory.mockReturnValue(stubProvider());
- mockCheckStatus.mockReset();
- mockCheckStatus.mockResolvedValue(expectedStatus);
-});
-
describe('sandboxProviders router', () => {
let settingsRouter: ReturnType<typeof createSandboxProvidersRouter>;
let catalogRouter: ReturnType<typeof createCatalogRouter>;
- // Concrete store keeps TTransaction as Transaction<Database>; the interface default is `never`.
let sandboxProviderStore: SqliteSandboxProviderStore;
beforeAll(async () => {
@@ -115,8 +84,9 @@ describe('sandboxProviders router', () => {
sandboxProviderStore = new SqliteSandboxProviderStore(db);
settingsRouter = createSandboxProvidersRouter({
resolveSandboxProviderStore: () => sandboxProviderStore,
+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),
withTransaction: callback => db.transaction().execute(callback),
- logger: silentLogger,
+ logger,
resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,
});
catalogRouter = createCatalogRouter({
@@ -150,18 +120,14 @@ describe('sandboxProviders router', () => {
nats_bridge_url: 'ws://nats-bridge',
exec_timeout_ms: 60_000,
},
- status: 'ready',
- status_reason: null,
- build_metadata: null,
});
const response = await router.request('/');
expect(response.status).toBe(404);
expect(await response.json()).toEqual({ error: { message: 'No sandbox provider configured' } });
- expect(mockCheckStatus).not.toHaveBeenCalled();
});
- it('PUT builds the image + upserts, GET returns redacted auth plus live image status', async () => {
+ it('PUT upserts credentials + default env, GET returns redacted auth', async () => {
const put = await settingsRouter.request('/', putInit(putBody));
expect(put.status).toBe(200);
expect(await put.json()).toEqual({ data: putBodyWire });
@@ -174,138 +140,9 @@ describe('sandboxProviders router', () => {
expect(stored?.manifest).toEqual(putBody);
});
- it('GET surfaces an error (500) when the status refresh throws', async () => {
- const { settingsRouter: router } = await createRouters();
- expect((await router.request('/', putInit(putBody))).status).toBe(200);
-
- mockCheckStatus.mockRejectedValue(new DaytonaError('unreachable', 500));
- const get = await router.request('/');
- expect(get.status).toBe(500);
- });
-
- it('PUT returns 422 when Daytona rejects the API key', async () => {
- mockProviderFactory.mockReturnValue(
- stubProvider({ buildImage: jest.fn().mockRejectedValue(new DaytonaError('unauthorized', 401)) }),
- );
- const response = await settingsRouter.request('/', putInit(putBody));
- expect(response.status).toBe(422);
- });
-
- it('PUT returns 422 naming the permissions when the key cannot register snapshots', async () => {
- mockProviderFactory.mockReturnValue(
- stubProvider({ buildImage: jest.fn().mockRejectedValue(new DaytonaError('Access denied', 403)) }),
- );
- const response = await settingsRouter.request('/', putInit(putBody));
- expect(response.status).toBe(422);
- expect(await response.json()).toEqual({
- error: {
- message:
- 'Daytona denied access: the API key is missing required permissions. Grant write:sandboxes, write:snapshots, and delete:snapshots on the key in the Daytona dashboard, then try again.',
- },
- });
- });
-
- it('PUT does not persist config when the build call fails auth', async () => {
- const { settingsRouter: router } = await createRouters();
- mockProviderFactory.mockReturnValue(
- stubProvider({ buildImage: jest.fn().mockRejectedValue(new DaytonaError('forbidden', 403)) }),
- );
- expect((await router.request('/', putInit(putBody))).status).toBe(422);
- expect((await router.request('/')).status).toBe(404);
- });
-
it('PUT rejects invalid bodies at the Zod layer', async () => {
const { auth: _auth, ...withoutAuth } = putBody;
const missingAuth = await settingsRouter.request('/', putInit(withoutAuth));
expect(missingAuth.status).toBe(400);
-
- const badType = await settingsRouter.request('/', putInit({ ...putBody, type: 'unknown' }));
- expect(badType.status).toBe(400);
-
- const withSnapshotName = await settingsRouter.request('/', putInit({ ...putBody, snapshot_name: 'legacy' }));
- expect(withSnapshotName.status).toBe(400);
- });
-});
-
-describe('sandbox-provider secret redaction and strict PUT', () => {
- it('PUT create with a redacted api_key returns 400', async () => {
- const { settingsRouter } = await createRouters();
- const response = await settingsRouter.request(
- '/',
- putInit({
- ...putBody,
- auth: { api_key: toRedactedSecretValue(putBody.auth.api_key) },
- }),
- );
- expect(response.status).toBe(400);
- expect(await response.json()).toEqual({ error: { message: 'API key is required' } });
- });
-
- it('PUT with a redacted api_key keeps the stored secret', async () => {
- const { settingsRouter, sandboxProviderStore } = await createRouters();
- expect((await settingsRouter.request('/', putInit(putBody))).status).toBe(200);
-
- const redactedKeep = {
- ...putBody,
- exec_timeout_ms: 120000,
- auth: { api_key: toRedactedSecretValue(putBody.auth.api_key) },
- };
- const update = await settingsRouter.request('/', putInit(redactedKeep));
- expect(update.status).toBe(200);
- expect(await update.json()).toEqual({ data: wireResponse(redactedKeep) });
-
- const stored = await sandboxProviderStore.getSandboxProvider('default');
- expect(stored?.manifest).toEqual({ ...putBody, exec_timeout_ms: 120000 });
- });
-
- it('PUT with a different redacted api_key still keeps the stored secret', async () => {
- const { settingsRouter, sandboxProviderStore } = await createRouters();
- expect((await settingsRouter.request('/', putInit(putBody))).status).toBe(200);
-
- const keep = {
- ...putBody,
- auth: { api_key: 'oth-***REDACTED***-xxx' },
- };
- const response = await settingsRouter.request('/', putInit(keep));
- expect(response.status).toBe(200);
- expect(await response.json()).toEqual({
- data: wireResponse({ ...keep, auth: { api_key: toRedactedSecretValue(putBody.auth.api_key) } }),
- });
-
- const stored = await sandboxProviderStore.getSandboxProvider('default');
- expect(stored?.manifest).toEqual(putBody);
- });
-
- it('PUT with a real api_key rotates the stored secret', async () => {
- const { settingsRouter, sandboxProviderStore } = await createRouters();
- expect((await settingsRouter.request('/', putInit(putBody))).status).toBe(200);
-
- const rotatedKey = 'dtn-rotated-key';
- const rotated = { ...putBody, auth: { api_key: rotatedKey } };
- const update = await settingsRouter.request('/', putInit(rotated));
- expect(update.status).toBe(200);
- expect(await update.json()).toEqual({
- data: wireResponse({ ...rotated, auth: { api_key: toRedactedSecretValue(rotatedKey) } }),
- });
-
- const stored = await sandboxProviderStore.getSandboxProvider('default');
- expect(stored?.manifest.type).toBe('daytona');
- if (stored?.manifest.type === 'daytona') {
- expect(stored.manifest.auth.api_key).toBe(rotatedKey);
- }
- });
-
- it('PUT update reuses persisted build_metadata (no image upgrade on re-save)', async () => {
- const { settingsRouter } = await createRouters();
- expect((await settingsRouter.request('/', putInit(putBody))).status).toBe(200);
- expect(mockProviderFactory.mock.calls[0]?.[0]).not.toHaveProperty('build_metadata');
-
- mockProviderFactory.mockClear();
- expect((await settingsRouter.request('/', putInit(putBody))).status).toBe(200);
- expect(mockProviderFactory).toHaveBeenCalledWith(
- expect.objectContaining({
- build_metadata: readyBuild.metadata,
- }),
- );
});
});
diff --git a/packages/trueforge/tests/unit/config/config.test.ts b/packages/trueforge/tests/unit/config/config.test.ts
index deb701b62..54b067058 100644
--- a/packages/trueforge/tests/unit/config/config.test.ts
+++ b/packages/trueforge/tests/unit/config/config.test.ts
@@ -1,6 +1,9 @@
import type { ServerConfiguration } from '../../../src/config';
import { buildRedisStandaloneUrl, getPublicUiBasePath } from '../../../src/config';
-import { resolveTrueFoundrySandboxProviderConfig } from '../../../src/truefoundry/resolveTrueFoundrySandboxProviderConfig';
+import {
+ hasTrueFoundrySandboxProviderConfig,
+ resolveTrueFoundrySandboxProviderConfig,
+} from '../../../src/truefoundry/resolveTrueFoundrySandboxProviderConfig';
/** Minimal distributed config slice for resolve tests (unused fields are irrelevant). */
function distributed(overrides: {
@@ -108,6 +111,50 @@ describe('resolveTrueFoundrySandboxProviderConfig', () => {
});
});
+describe('hasTrueFoundrySandboxProviderConfig', () => {
+ it('returns true when shared provider config resolves', () => {
+ expect(
+ hasTrueFoundrySandboxProviderConfig(
+ distributed({
+ TRUEFOUNDRY_SANDBOX_ENABLED: true,
+ TRUEFOUNDRY_SANDBOX_PROVIDER: 'truefoundry',
+ TRUEFOUNDRY_SANDBOX_SERVER_URL: 'http://sandbox-server',
+ TRUEFOUNDRY_SANDBOX_SETTINGS: JSON.stringify({ nats_bridge_url: 'ws://nats-bridge' }),
+ }),
+ ),
+ ).toBe(true);
+ });
+
+ it('returns false when sandbox is disabled', () => {
+ expect(hasTrueFoundrySandboxProviderConfig(distributed({}))).toBe(false);
+ });
+
+ it('returns false instead of throwing when settings are incomplete', () => {
+ expect(
+ hasTrueFoundrySandboxProviderConfig(
+ distributed({
+ TRUEFOUNDRY_SANDBOX_ENABLED: true,
+ TRUEFOUNDRY_SANDBOX_PROVIDER: 'truefoundry',
+ TRUEFOUNDRY_SANDBOX_SETTINGS: JSON.stringify({ nats_bridge_url: 'ws://nats-bridge' }),
+ }),
+ ),
+ ).toBe(false);
+ });
+
+ it('returns false instead of throwing when settings JSON is invalid', () => {
+ expect(
+ hasTrueFoundrySandboxProviderConfig(
+ distributed({
+ TRUEFOUNDRY_SANDBOX_ENABLED: true,
+ TRUEFOUNDRY_SANDBOX_PROVIDER: 'daytona',
+ TRUEFOUNDRY_SANDBOX_API_KEY: 'dtn-key',
+ TRUEFOUNDRY_SANDBOX_SETTINGS: '{not-json',
+ }),
+ ),
+ ).toBe(false);
+ });
+});
+
describe('getPublicUiBasePath', () => {
it('ignores a path-bearing PUBLIC_BASE_URL in standalone non-development', () => {
expect(
diff --git a/packages/trueforge/tests/unit/controller/sandboxEnvBuild.test.ts b/packages/trueforge/tests/unit/controller/sandboxEnvBuild.test.ts
new file mode 100644
index 000000000..4cce5be44
--- /dev/null
+++ b/packages/trueforge/tests/unit/controller/sandboxEnvBuild.test.ts
@@ -0,0 +1,54 @@
+import { TrueForgeApi } from '@truefoundry/trueforge-sdk';
+import { internalTrueForgeClient } from '../../../src/controller/internalTrueForgeClient';
+import { dispatchSandboxEnvBuilds, sandboxEnvBuildLoop } from '../../../src/controller/sandboxEnvBuild';
+
+function fakeLogger() {
+ return { error: jest.fn(), debug: jest.fn(), info: jest.fn(), warn: jest.fn() };
+}
+
+describe('sandboxEnvBuildLoop', () => {
+ afterEach(() => {
+ jest.restoreAllMocks();
+ });
+
+ it('progresses each pending version id from the internal API', async () => {
+ jest.spyOn(internalTrueForgeClient, 'listPendingSandboxEnvironmentVersions').mockResolvedValue(['ver-1', 'ver-2']);
+ const progress = jest
+ .spyOn(internalTrueForgeClient, 'progressSandboxEnvironmentVersion')
+ .mockResolvedValue(undefined);
+
+ const logger = fakeLogger();
+ const loop = sandboxEnvBuildLoop({ logger: logger as never });
+ await loop.tick(new AbortController().signal);
+
+ expect(progress).toHaveBeenCalledTimes(2);
+ expect(progress).toHaveBeenNthCalledWith(1, 'ver-1');
+ expect(progress).toHaveBeenNthCalledWith(2, 'ver-2');
+ });
+
+ it('skips NotFoundError and continues the tick', async () => {
+ jest.spyOn(internalTrueForgeClient, 'listPendingSandboxEnvironmentVersions').mockResolvedValue(['gone', 'ok']);
+ const progress = jest
+ .spyOn(internalTrueForgeClient, 'progressSandboxEnvironmentVersion')
+ .mockImplementation(async id => {
+ if (id === 'gone') {
+ throw new TrueForgeApi.NotFoundError({ error: { message: 'not found' } });
+ }
+ });
+ const logger = fakeLogger();
+
+ await dispatchSandboxEnvBuilds({ logger: logger as never });
+
+ expect(progress).toHaveBeenCalledTimes(2);
+ expect(logger.warn).toHaveBeenCalled();
+ });
+
+ it('does not tick when aborted', async () => {
+ const list = jest.spyOn(internalTrueForgeClient, 'listPendingSandboxEnvironmentVersions');
+ const controller = new AbortController();
+ controller.abort();
+ const loop = sandboxEnvBuildLoop({ logger: fakeLogger() as never });
+ await loop.tick(controller.signal);
+ expect(list).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts b/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
index 64e765534..15ef6a5ef 100644
--- a/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
+++ b/packages/trueforge/tests/unit/controller/scheduleDispatch.test.ts
@@ -1,6 +1,6 @@
import configuration, { STANDALONE_TRUEFORGE_API_KEY } from '../../../src/config';
+import { internalTrueForgeClient } from '../../../src/controller/internalTrueForgeClient';
import {
- createHttpScheduleRunExecutor,
loadScheduleDispatchItem,
ScheduleAgentNotFoundError,
scheduleDispatchLoop,
@@ -92,9 +92,8 @@ describe('schedule execution HTTP transport', () => {
it('sends one API-key authenticated request with the run id', async () => {
const request = jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(null, { status: 204 }));
- const executeRun = createHttpScheduleRunExecutor();
- await executeRun('run-1');
+ await internalTrueForgeClient.executeScheduleRun('run-1');
expect(request).toHaveBeenCalledTimes(1);
const [url, init] = request.mock.calls[0] ?? [];
diff --git a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
index e658d1363..3d7e3c429 100644
--- a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
+++ b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
@@ -301,9 +301,6 @@ describe('validateAgentSpec', () => {
auto_archive_interval_in_minutes: 60,
auto_delete_interval_in_minutes: 7200,
},
- status: 'pending',
- status_reason: 'Sandbox image build started.',
- build_metadata: { build_ref: 'trueforge-build-029ea5ff', image_uri: 'tfy.jfrog.io/tfy-images/sandbox:029ea5ff' },
});
await expect(
diff --git a/packages/trueforge/tests/unit/sandbox/ensureDefaultSandboxEnvironment.test.ts b/packages/trueforge/tests/unit/sandbox/ensureDefaultSandboxEnvironment.test.ts
new file mode 100644
index 000000000..12d6d472c
--- /dev/null
+++ b/packages/trueforge/tests/unit/sandbox/ensureDefaultSandboxEnvironment.test.ts
@@ -0,0 +1,88 @@
+import type { ISandboxEnvironmentStore } from '../../../src/db/sandboxEnvironmentStore';
+import { ensureDefaultSandboxEnvironment } from '../../../src/sandbox/ensureDefaultSandboxEnvironment';
+import { DEFAULT_SANDBOX_ENVIRONMENT_NAME } from '../../../src/schemas/sandboxEnvironment';
+
+const SUBJECT = {
+ subject_id: 'user-1',
+ subject_type: 'user' as const,
+ subject_display_name: 'User',
+};
+
+describe('ensureDefaultSandboxEnvironment', () => {
+ it('returns existing default when present and resetPending is false', async () => {
+ const existing = {
+ environment: { id: 'env-1', name: DEFAULT_SANDBOX_ENVIRONMENT_NAME },
+ version: { id: 'v1', status: 'ready' },
+ };
+ const store = {
+ getEnvironment: jest.fn().mockResolvedValue(existing),
+ upsertEnvironment: jest.fn(),
+ };
+
+ const result = await ensureDefaultSandboxEnvironment({
+ store: store as unknown as ISandboxEnvironmentStore,
+ tenant_id: 'tenant-1',
+ created_by_subject: SUBJECT,
+ provider_type: 'daytona',
+ resetPending: false,
+ });
+
+ expect(result).toBe(existing);
+ expect(store.upsertEnvironment).not.toHaveBeenCalled();
+ });
+
+ it('upserts a pending default version when missing', async () => {
+ const created = {
+ environment: { id: 'env-new', name: DEFAULT_SANDBOX_ENVIRONMENT_NAME },
+ version: { id: 'v2', status: 'pending' },
+ };
+ const store = {
+ getEnvironment: jest.fn().mockResolvedValue(undefined),
+ upsertEnvironment: jest.fn().mockResolvedValue(created),
+ };
+
+ const result = await ensureDefaultSandboxEnvironment({
+ store: store as unknown as ISandboxEnvironmentStore,
+ tenant_id: 'tenant-1',
+ created_by_subject: SUBJECT,
+ provider_type: 'daytona',
+ resetPending: false,
+ });
+
+ expect(result).toBe(created);
+ expect(store.upsertEnvironment).toHaveBeenCalledWith(
+ expect.objectContaining({
+ tenant_id: 'tenant-1',
+ name: DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ created_by_subject: SUBJECT,
+ buildVersion: expect.any(Function),
+ }),
+ undefined,
+ );
+ const buildVersion = store.upsertEnvironment.mock.calls[0]?.[0].buildVersion as (previous?: {
+ latest_version: number;
+ }) => { status: string; version: number };
+ expect(buildVersion(undefined)).toMatchObject({ status: 'pending', version: 1 });
+ expect(buildVersion({ latest_version: 3 })).toMatchObject({ status: 'pending', version: 4 });
+ });
+
+ it('upserts again when resetPending is true even if default exists', async () => {
+ const store = {
+ getEnvironment: jest.fn().mockResolvedValue({
+ environment: { id: 'env-1' },
+ version: { id: 'v1', status: 'ready' },
+ }),
+ upsertEnvironment: jest.fn().mockResolvedValue({ environment: { id: 'env-1' }, version: { id: 'v2' } }),
+ };
+
+ await ensureDefaultSandboxEnvironment({
+ store: store as unknown as ISandboxEnvironmentStore,
+ tenant_id: 'tenant-1',
+ created_by_subject: SUBJECT,
+ provider_type: 'daytona',
+ resetPending: true,
+ });
+
+ expect(store.upsertEnvironment).toHaveBeenCalled();
+ });
+});
diff --git a/packages/trueforge/tests/unit/sandbox/progressSandboxEnvironmentVersion.test.ts b/packages/trueforge/tests/unit/sandbox/progressSandboxEnvironmentVersion.test.ts
new file mode 100644
index 000000000..a8712b058
--- /dev/null
+++ b/packages/trueforge/tests/unit/sandbox/progressSandboxEnvironmentVersion.test.ts
@@ -0,0 +1,208 @@
+import { DAYTONA_SNAPSHOT_NOT_STARTED_REASON } from '@truefoundry/trueforge-core/core';
+import { HTTPException } from 'hono/http-exception';
+import { createLogger } from 'winston';
+import type { ISandboxEnvironmentStore } from '../../../src/db/sandboxEnvironmentStore';
+import type { ISandboxProviderStore } from '../../../src/db/sandboxProviderStore';
+import { progressSandboxEnvironmentVersion } from '../../../src/sandbox/progressSandboxEnvironmentVersion';
+import * as providerUtils from '../../../src/sandbox/providerUtils';
+import * as sentry from '../../../src/sentry';
+
+jest.mock('../../../src/sentry', () => ({
+ captureCriticalException: jest.fn(),
+}));
+
+jest.mock('../../../src/sandbox/providerUtils', () => {
+ const actual = jest.requireActual<typeof import('../../../src/sandbox/providerUtils')>(
+ '../../../src/sandbox/providerUtils',
+ );
+ return {
+ ...actual,
+ toDaytonaSandboxProvider: jest.fn(),
+ };
+});
+
+const logger = createLogger({ silent: true });
+
+const PENDING = {
+ id: 'ver-1',
+ tenant_id: 'tenant-1',
+ environment_id: 'env-1',
+ environment_name: 'pyjokes-env',
+ version: 1,
+ external_ref: 'trueforge-abc',
+ manifest: {
+ name: 'pyjokes-env',
+ resources: { cpu: 1, memory: 1, disk: 3 },
+ type: 'daytona' as const,
+ sandbox_provider: 'daytona' as const,
+ image: { type: 'build' as const, build_script: 'pip install pyjokes' },
+ },
+};
+
+const PROVIDER_RECORD = {
+ tenant_id: 'tenant-1',
+ manifest: {
+ type: 'daytona' as const,
+ auth: { api_key: 'dtn-test' },
+ exec_timeout_ms: 60_000,
+ auto_stop_interval_in_minutes: 5,
+ auto_archive_interval_in_minutes: 60,
+ auto_delete_interval_in_minutes: 7200,
+ },
+ created_at: '2026-01-01T00:00:00.000Z',
+ updated_at: '2026-01-01T00:00:00.000Z',
+};
+
+function makeStores(options?: { pending?: typeof PENDING | null; provider?: typeof PROVIDER_RECORD | null }) {
+ const pending = options?.pending === null ? undefined : (options?.pending ?? PENDING);
+ const provider = options?.provider === null ? undefined : (options?.provider ?? PROVIDER_RECORD);
+ const sandboxEnvironmentStore = {
+ getSandboxEnvironmentVersion: jest.fn().mockResolvedValue(pending),
+ markVersionReady: jest.fn().mockResolvedValue(undefined),
+ markVersionFailed: jest.fn().mockResolvedValue(undefined),
+ };
+ const sandboxProviderStore = {
+ getSandboxProvider: jest.fn().mockResolvedValue(provider),
+ };
+ return {
+ sandboxEnvironmentStore: sandboxEnvironmentStore as unknown as ISandboxEnvironmentStore,
+ sandboxProviderStore: sandboxProviderStore as unknown as ISandboxProviderStore,
+ envStore: sandboxEnvironmentStore,
+ };
+}
+
+function mockProvider(methods: { getBuildStatus: jest.Mock; build: jest.Mock }): void {
+ jest.mocked(providerUtils.toDaytonaSandboxProvider).mockReturnValue(methods as never);
+}
+
+describe('progressSandboxEnvironmentVersion', () => {
+ beforeEach(() => {
+ jest.mocked(providerUtils.toDaytonaSandboxProvider).mockReset();
+ jest.mocked(sentry.captureCriticalException).mockClear();
+ });
+
+ it('throws 404 when the version is missing', async () => {
+ const { sandboxEnvironmentStore, sandboxProviderStore } = makeStores({ pending: null });
+ await expect(
+ progressSandboxEnvironmentVersion({
+ sandboxEnvironmentStore,
+ sandboxProviderStore,
+ environment_version_id: 'missing',
+ logger,
+ }),
+ ).rejects.toMatchObject({ status: 404 } satisfies Partial<HTTPException>);
+ expect(sentry.captureCriticalException).toHaveBeenCalled();
+ });
+
+ it('marks ready when getBuildStatus reports ready', async () => {
+ const { sandboxEnvironmentStore, sandboxProviderStore, envStore } = makeStores();
+ const build = jest.fn();
+ mockProvider({
+ getBuildStatus: jest.fn().mockResolvedValue({ status: 'ready', reason: null, metadata: null }),
+ build,
+ });
+
+ await progressSandboxEnvironmentVersion({
+ sandboxEnvironmentStore,
+ sandboxProviderStore,
+ environment_version_id: 'ver-1',
+ logger,
+ });
+
+ expect(build).not.toHaveBeenCalled();
+ expect(envStore.markVersionReady).toHaveBeenCalledWith({ environment_version_id: 'ver-1' });
+ });
+
+ it('calls build when snapshot has not started, then marks ready', async () => {
+ const { sandboxEnvironmentStore, sandboxProviderStore, envStore } = makeStores();
+ const build = jest.fn().mockResolvedValue({ status: 'ready', reason: null, metadata: null });
+ mockProvider({
+ getBuildStatus: jest.fn().mockResolvedValue({
+ status: 'pending',
+ reason: DAYTONA_SNAPSHOT_NOT_STARTED_REASON,
+ metadata: null,
+ }),
+ build,
+ });
+
+ await progressSandboxEnvironmentVersion({
+ sandboxEnvironmentStore,
+ sandboxProviderStore,
+ environment_version_id: 'ver-1',
+ logger,
+ });
+
+ expect(build).toHaveBeenCalledTimes(1);
+ expect(envStore.markVersionReady).toHaveBeenCalledWith({ environment_version_id: 'ver-1' });
+ });
+
+ it('marks failed when build status is failed', async () => {
+ const { sandboxEnvironmentStore, sandboxProviderStore, envStore } = makeStores();
+ mockProvider({
+ getBuildStatus: jest.fn().mockResolvedValue({
+ status: 'failed',
+ reason: 'pip blew up',
+ metadata: null,
+ }),
+ build: jest.fn(),
+ });
+
+ await progressSandboxEnvironmentVersion({
+ sandboxEnvironmentStore,
+ sandboxProviderStore,
+ environment_version_id: 'ver-1',
+ logger,
+ });
+
+ expect(envStore.markVersionFailed).toHaveBeenCalledWith({
+ environment_version_id: 'ver-1',
+ status_reason: 'pip blew up',
+ });
+ });
+
+ it('leaves pending when still building', async () => {
+ const { sandboxEnvironmentStore, sandboxProviderStore, envStore } = makeStores();
+ mockProvider({
+ getBuildStatus: jest.fn().mockResolvedValue({
+ status: 'pending',
+ reason: 'building…',
+ metadata: null,
+ }),
+ build: jest.fn(),
+ });
+
+ await progressSandboxEnvironmentVersion({
+ sandboxEnvironmentStore,
+ sandboxProviderStore,
+ environment_version_id: 'ver-1',
+ logger,
+ });
+
+ expect(envStore.markVersionReady).not.toHaveBeenCalled();
+ expect(envStore.markVersionFailed).not.toHaveBeenCalled();
+ });
+
+ it('times out a hung getBuildStatus so the build loop can continue', async () => {
+ jest.useFakeTimers();
+ try {
+ const { sandboxEnvironmentStore, sandboxProviderStore } = makeStores();
+ mockProvider({
+ getBuildStatus: jest.fn().mockReturnValue(new Promise(() => undefined)),
+ build: jest.fn(),
+ });
+
+ const progressPromise = progressSandboxEnvironmentVersion({
+ sandboxEnvironmentStore,
+ sandboxProviderStore,
+ environment_version_id: 'ver-1',
+ logger,
+ });
+ const expectation = expect(progressPromise).rejects.toThrow(/Timed out.*getBuildStatus/);
+ await jest.advanceTimersByTimeAsync(30_000);
+ await expectation;
+ expect(sentry.captureCriticalException).toHaveBeenCalled();
+ } finally {
+ jest.useRealTimers();
+ }
+ });
+});
diff --git a/packages/trueforge/tests/unit/sandbox/sandboxEnvironmentVersion.test.ts b/packages/trueforge/tests/unit/sandbox/sandboxEnvironmentVersion.test.ts
new file mode 100644
index 000000000..9fb57f273
--- /dev/null
+++ b/packages/trueforge/tests/unit/sandbox/sandboxEnvironmentVersion.test.ts
@@ -0,0 +1,101 @@
+import {
+ buildNextVersion,
+ defaultSandboxEnvironmentStoredManifest,
+} from '../../../src/sandbox/sandboxEnvironmentVersion';
+import {
+ SandboxEnvironmentManifestSchema,
+ SandboxEnvironmentSchema,
+ UpdateSandboxEnvironmentRequestSchema,
+} from '../../../src/schemas/sandboxEnvironment';
+
+describe('buildNextVersion', () => {
+ const previous = defaultSandboxEnvironmentStoredManifest('daytona');
+
+ it('allocates a new external_ref when resources change without a build image', () => {
+ const next = buildNextVersion({
+ version: 2,
+ previous_manifest: previous,
+ previous_external_ref: 'trueforge-old',
+ manifest: {
+ name: 'default',
+ resources: { cpu: 2, memory: 4, disk: 8 },
+ },
+ provider_type: 'daytona',
+ });
+
+ expect(next.external_ref).not.toBe('trueforge-old');
+ expect(next.status).toBe('pending');
+ expect(next.manifest.resources).toEqual({ cpu: 2, memory: 4, disk: 8 });
+ });
+
+ it('reuses previous_external_ref when only networking changes', () => {
+ const next = buildNextVersion({
+ version: 2,
+ previous_manifest: previous,
+ previous_external_ref: 'trueforge-old',
+ manifest: {
+ name: 'default',
+ resources: previous.resources,
+ networking: { network_block_all: true },
+ },
+ provider_type: 'daytona',
+ });
+
+ expect(next.external_ref).toBe('trueforge-old');
+ });
+
+ it('allocates a new external_ref when build_script changes', () => {
+ const withBuild = {
+ ...previous,
+ image: { type: 'build' as const, build_script: 'pip install httpx' },
+ };
+ const next = buildNextVersion({
+ version: 2,
+ previous_manifest: withBuild,
+ previous_external_ref: 'trueforge-old',
+ manifest: {
+ name: 'custom-env',
+ resources: withBuild.resources,
+ image: { type: 'build', build_script: 'pip install pyjokes' },
+ },
+ provider_type: 'daytona',
+ });
+
+ expect(next.external_ref).not.toBe('trueforge-old');
+ });
+});
+
+describe('sandbox environment wire schemas', () => {
+ const baseEnv = {
+ id: 'env-1',
+ name: 'default',
+ description: '',
+ lifecycle_stage: 'active' as const,
+ status: 'ready' as const,
+ status_reason: null,
+ manifest: {
+ name: 'default',
+ resources: { cpu: 1, memory: 1, disk: 3 },
+ },
+ created_by_subject: {
+ subject_id: 'user-1',
+ subject_type: 'user' as const,
+ subject_display_name: 'User',
+ },
+ created_at: '2026-01-01T00:00:00.000Z',
+ updated_at: '2026-01-01T00:00:00.000Z',
+ };
+
+ it('allows name "default" on SandboxEnvironment responses', () => {
+ expect(SandboxEnvironmentSchema.parse(baseEnv).manifest.name).toBe('default');
+ expect(SandboxEnvironmentManifestSchema.parse(baseEnv.manifest).name).toBe('default');
+ });
+
+ it('rejects name "default" on update requests', () => {
+ expect(() =>
+ UpdateSandboxEnvironmentRequestSchema.parse({
+ manifest: { name: 'default' },
+ }),
+ ).toThrow(/default/);
+ });
+});
diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundrySandboxEnvironmentStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundrySandboxEnvironmentStore.test.ts
new file mode 100644
index 000000000..9bf56df05
--- /dev/null
+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundrySandboxEnvironmentStore.test.ts
@@ -0,0 +1,117 @@
+import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
+import { createSqliteDb } from '../../../src/db/sqlite/client';
+import { SqliteSandboxEnvironmentStore } from '../../../src/db/sqlite/sandbox-environment-store/SqliteSandboxEnvironmentStore';
+import { DEFAULT_SANDBOX_ENVIRONMENT_NAME } from '../../../src/schemas/sandboxEnvironment';
+import { resolveTrueFoundrySandboxProviderConfig } from '../../../src/truefoundry/resolveTrueFoundrySandboxProviderConfig';
+import { TrueFoundrySandboxEnvironmentStore } from '../../../src/truefoundry/TrueFoundrySandboxEnvironmentStore';
+
+jest.mock('../../../src/truefoundry/resolveTrueFoundrySandboxProviderConfig', () => {
+ const actual = jest.requireActual('../../../src/truefoundry/resolveTrueFoundrySandboxProviderConfig');
+ return {
+ ...actual,
+ resolveTrueFoundrySandboxProviderConfig: jest.fn(),
+ };
+});
+
+const mockResolveConfig = resolveTrueFoundrySandboxProviderConfig as jest.MockedFunction<
+ typeof resolveTrueFoundrySandboxProviderConfig
+>;
+
+const TENANT = 'acme';
+const SUBJECT_ID = 'user-1';
+
+describe('TrueFoundrySandboxEnvironmentStore', () => {
+ beforeEach(() => {
+ mockResolveConfig.mockReset();
+ mockResolveConfig.mockReturnValue({
+ type: 'daytona',
+ apiKey: 'dtn-shared',
+ settings: {
+ snapshotName: 'trueforge-default-default',
+ autoStopIntervalInMinutes: 5,
+ autoArchiveIntervalInMinutes: 60,
+ autoDeleteIntervalInMinutes: 43_200,
+ timeoutMs: 60_000,
+ },
+ });
+ });
+
+ async function createStores(envSupported: boolean) {
+ const db = createSqliteDb(':memory:');
+ await migrateSqliteToLatest(db);
+ const persistence = new SqliteSandboxEnvironmentStore(db);
+ const store = new TrueFoundrySandboxEnvironmentStore(persistence, { envSupported });
+ return { store, persistence };
+ }
+
+ it('synthesizes always-ready default when envSupported', async () => {
+ const { store } = await createStores(true);
+
+ const loaded = await store.getEnvironment({
+ tenant_id: TENANT,
+ name: DEFAULT_SANDBOX_ENVIRONMENT_NAME,
+ });
+
+ expect(loaded?.version.status).toBe('ready');
+ expect(loaded?.version.external_ref).toBe('trueforge-default-default');
+ expect(loaded?.environment.name).toBe(DEFAULT_SANDBOX_ENVIRONMENT_NAME);
+ });
+
+ it('lists synthesized default ahead of custom environments', async () => {
+ const { store, persistence } = await createStores(true);
+ await persistence.upsertEnvironment({
+ tenant_id: TENANT,
+ name: 'pyjokes-env',
+ description: '',
+ created_by_subject: {
+ subject_id: SUBJECT_ID,
+ subject_type: 'user',
+ subject_display_name: 'User',
+ },
+ buildVersion: () => ({
+ version: 1,
+ manifest: {
+ name: 'pyjokes-env',
+ resources: { cpu: 1, memory: 1, disk: 3 },
+ type: 'daytona',
+ sandbox_provider: 'daytona',
+ },
+ status: 'pending',
+ status_reason: null,
+ external_ref: 'ref-1',
+ internal_metadata: { secrets: [] },
+ created_by_subject: {
+ subject_id: SUBJECT_ID,
+ subject_type: 'user',
+ subject_display_name: 'User',
+ },
+ }),
+ });
+
+ const listed = await store.listEnvironments({
+ tenant_id: TENANT,
+ created_by_subject_id: SUBJECT_ID,
+ limit: 25,
+ page_token: undefined,
+ });
+
+ expect(listed.data.map(row => row.environment.name)).toEqual([DEFAULT_SANDBOX_ENVIRONMENT_NAME, 'pyjokes-env']);
+ expect(listed.data[0]?.version.status).toBe('ready');
+ });
+
+ it('no-ops get/list inject when env is not supported', async () => {
+ const { store } = await createStores(false);
+
+ await expect(
+ store.getEnvironment({ tenant_id: TENANT, name: DEFAULT_SANDBOX_ENVIRONMENT_NAME }),
+ ).resolves.toBeUndefined();
+
+ const listed = await store.listEnvironments({
+ tenant_id: TENANT,
+ created_by_subject_id: SUBJECT_ID,
+ limit: 25,
+ page_token: undefined,
+ });
+ expect(listed.data).toEqual([]);
+ });
+});
diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundrySandboxProviderStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundrySandboxProviderStore.test.ts
index 55a699b20..368ec8817 100644
--- a/packages/trueforge/tests/unit/truefoundry/TrueFoundrySandboxProviderStore.test.ts
+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundrySandboxProviderStore.test.ts
@@ -39,16 +39,13 @@ describe('TrueFoundrySandboxProviderStore', () => {
await expect(store.getSandboxProvider(TENANT)).resolves.toBeUndefined();
});
- it('get returns ready Daytona record from static settings', async () => {
+ it('get returns Daytona record from static settings', async () => {
const store = new TrueFoundrySandboxProviderStore();
const record = await store.getSandboxProvider(TENANT);
expect(record).toMatchObject({
tenant_id: TENANT,
- status: 'ready',
- status_reason: null,
- build_metadata: { build_ref: DAYTONA_SETTINGS.snapshotName },
manifest: {
type: 'daytona',
auth: { api_key: 'dtn-shared-key' },
@@ -60,7 +57,7 @@ describe('TrueFoundrySandboxProviderStore', () => {
});
});
- it('get returns ready truefoundry record from static settings', async () => {
+ it('get returns truefoundry record from static settings', async () => {
mockResolveConfig.mockReturnValue({
type: 'truefoundry',
serverUrl: 'http://sandbox-server',
@@ -72,9 +69,6 @@ describe('TrueFoundrySandboxProviderStore', () => {
expect(record).toMatchObject({
tenant_id: TENANT,
- status: 'ready',
- status_reason: null,
- build_metadata: null,
manifest: {
type: 'truefoundry',
server_url: 'http://sandbox-server',
@@ -107,17 +101,6 @@ describe('TrueFoundrySandboxProviderStore', () => {
auto_archive_interval_in_minutes: 60,
auto_delete_interval_in_minutes: 7200,
},
- status: 'ready',
- status_reason: null,
- build_metadata: null,
- }),
- );
- assertManaged(() =>
- store.updateSandboxStatus({
- tenant_id: TENANT,
- status: 'ready',
- status_reason: null,
- build_metadata: null,
}),
);
});
diff --git a/python/trueforge_sdk/reference.md b/python/trueforge_sdk/reference.md
index a83fc737a..c50ff942f 100644
--- a/python/trueforge_sdk/reference.md
+++ b/python/trueforge_sdk/reference.md
@@ -1062,7 +1062,7 @@ client.models.list()
<dl>
<dd>
-List sandbox environments created by the authenticated subject, newest first.
+List the tenant default environment plus sandbox environments created by the authenticated subject.
</dd>
</dl>
</dd>
@@ -1100,7 +1100,7 @@ client.sandbox_environments.list()
<dl>
<dd>
-**limit:** `typing.Optional[int]` — Page size. Defaults to 25
+**limit:** `typing.Optional[int]` — Page size. Defaults to 25, max 1000.
</dd>
</dl>
@@ -1140,7 +1140,7 @@ client.sandbox_environments.list()
<dl>
<dd>
-Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+Create or replace by `manifest.name`. Requires a configured sandbox provider.
</dd>
</dl>
</dd>
@@ -1155,7 +1155,7 @@ Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
<dd>
```python
-from trueforge_sdk import TrueForge, SandboxEnvironmentManifest
+from trueforge_sdk import TrueForge, SandboxEnvironmentManifestRequest
client = TrueForge(
token="<token>",
@@ -1163,7 +1163,7 @@ client = TrueForge(
)
client.sandbox_environments.create_or_update(
- manifest=SandboxEnvironmentManifest(
+ manifest=SandboxEnvironmentManifestRequest(
name="name",
),
)
@@ -1182,7 +1182,7 @@ client.sandbox_environments.create_or_update(
<dl>
<dd>
-**manifest:** `SandboxEnvironmentManifest`
+**manifest:** `SandboxEnvironmentManifestRequest`
</dd>
</dl>
@@ -1214,7 +1214,7 @@ client.sandbox_environments.create_or_update(
<dl>
<dd>
-Get a sandbox environment by name for the authenticated subject.
+Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.
</dd>
</dl>
</dd>
@@ -4019,6 +4019,141 @@ client.internal.metrics.get_meters(
</dl>
+</dd>
+</dl>
+</details>
+
+## Internal SandboxEnvironments
+<details><summary><code>client.internal.sandbox_environments.<a href="src/trueforge_sdk/internal/sandbox_environments/client.py">list_pending</a>() -> ListPendingSandboxEnvironmentVersionsResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Returns pending environment versions for the build controller.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```python
+from trueforge_sdk import TrueForge
+
+client = TrueForge(
+ token="<token>",
+ base_url="https://yourhost.com/path/to/api",
+)
+
+client.internal.sandbox_environments.list_pending()
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.internal.sandbox_environments.<a href="src/trueforge_sdk/internal/sandbox_environments/client.py">progress</a>(...)</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Registers or polls the snapshot build and updates version status.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```python
+from trueforge_sdk import TrueForge
+
+client = TrueForge(
+ token="<token>",
+ base_url="https://yourhost.com/path/to/api",
+)
+
+client.internal.sandbox_environments.progress(
+ environment_version_id="environment_version_id",
+)
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**environment_version_id:** `str` — Version row id to progress.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
</dd>
</dl>
</details>
diff --git a/python/trueforge_sdk/src/trueforge_sdk/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
index 0f6747ad6..8768c2d49 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
@@ -108,6 +108,7 @@ if typing.TYPE_CHECKING:
ListMcpServerToolsResponse,
ListMcpServersResponse,
ListModelProvidersResponse,
+ ListPendingSandboxEnvironmentVersionsResponse,
ListPermissionsData,
ListPermissionsResponse,
ListSandboxEnvironmentsResponse,
@@ -156,6 +157,7 @@ if typing.TYPE_CHECKING:
MoonshotModelProvider,
OpenAiModelProvider,
ParallelWebSearchProviderAuth,
+ PendingSandboxEnvironmentVersion,
PermissionResourceType,
PreviousTurnIdInput,
RawToolCall,
@@ -171,7 +173,6 @@ if typing.TYPE_CHECKING:
ResponseFormatJsonSchemaJsonSchema,
ResponseFormatText,
RuntimeConfig,
- SandboxBuildStatus,
SandboxCapability,
SandboxConfig,
SandboxCreatedEvent,
@@ -179,6 +180,7 @@ if typing.TYPE_CHECKING:
SandboxEnvironmentImage,
SandboxEnvironmentLifecycleStage,
SandboxEnvironmentManifest,
+ SandboxEnvironmentManifestRequest,
SandboxEnvironmentNetworking,
SandboxEnvironmentResources,
SandboxEnvironmentSecret,
@@ -417,6 +419,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"ListMcpServerToolsResponse": ".types",
"ListMcpServersResponse": ".types",
"ListModelProvidersResponse": ".types",
+ "ListPendingSandboxEnvironmentVersionsResponse": ".types",
"ListPermissionsData": ".types",
"ListPermissionsResponse": ".types",
"ListSandboxEnvironmentsResponse": ".types",
@@ -466,6 +469,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"NotFoundError": ".errors",
"OpenAiModelProvider": ".types",
"ParallelWebSearchProviderAuth": ".types",
+ "PendingSandboxEnvironmentVersion": ".types",
"PermissionResourceType": ".types",
"PreconditionFailedError": ".errors",
"PreviousTurnIdInput": ".types",
@@ -482,7 +486,6 @@ _dynamic_imports: typing.Dict[str, str] = {
"ResponseFormatJsonSchemaJsonSchema": ".types",
"ResponseFormatText": ".types",
"RuntimeConfig": ".types",
- "SandboxBuildStatus": ".types",
"SandboxCapability": ".types",
"SandboxConfig": ".types",
"SandboxCreatedEvent": ".types",
@@ -490,6 +493,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"SandboxEnvironmentImage": ".types",
"SandboxEnvironmentLifecycleStage": ".types",
"SandboxEnvironmentManifest": ".types",
+ "SandboxEnvironmentManifestRequest": ".types",
"SandboxEnvironmentNetworking": ".types",
"SandboxEnvironmentResources": ".types",
"SandboxEnvironmentSecret": ".types",
@@ -736,6 +740,7 @@ __all__ = [
"ListMcpServerToolsResponse",
"ListMcpServersResponse",
"ListModelProvidersResponse",
+ "ListPendingSandboxEnvironmentVersionsResponse",
"ListPermissionsData",
"ListPermissionsResponse",
"ListSandboxEnvironmentsResponse",
@@ -785,6 +790,7 @@ __all__ = [
"NotFoundError",
"OpenAiModelProvider",
"ParallelWebSearchProviderAuth",
+ "PendingSandboxEnvironmentVersion",
"PermissionResourceType",
"PreconditionFailedError",
"PreviousTurnIdInput",
@@ -801,7 +807,6 @@ __all__ = [
"ResponseFormatJsonSchemaJsonSchema",
"ResponseFormatText",
"RuntimeConfig",
- "SandboxBuildStatus",
"SandboxCapability",
"SandboxConfig",
"SandboxCreatedEvent",
@@ -809,6 +814,7 @@ __all__ = [
"SandboxEnvironmentImage",
"SandboxEnvironmentLifecycleStage",
"SandboxEnvironmentManifest",
+ "SandboxEnvironmentManifestRequest",
"SandboxEnvironmentNetworking",
"SandboxEnvironmentResources",
"SandboxEnvironmentSecret",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/internal/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/internal/__init__.py
index c58f0faa0..e74a16a7e 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/internal/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/internal/__init__.py
@@ -6,10 +6,11 @@ import typing
from importlib import import_module
if typing.TYPE_CHECKING:
- from . import agents, metrics, schedules, sessions
+ from . import agents, metrics, sandbox_environments, schedules, sessions
_dynamic_imports: typing.Dict[str, str] = {
"agents": ".agents",
"metrics": ".metrics",
+ "sandbox_environments": ".sandbox_environments",
"schedules": ".schedules",
"sessions": ".sessions",
}
@@ -36,4 +37,4 @@ def __dir__():
return sorted(lazy_attrs)
-__all__ = ["agents", "metrics", "schedules", "sessions"]
+__all__ = ["agents", "metrics", "sandbox_environments", "schedules", "sessions"]
diff --git a/python/trueforge_sdk/src/trueforge_sdk/internal/client.py b/python/trueforge_sdk/src/trueforge_sdk/internal/client.py
index 69c823dad..ee9183905 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/internal/client.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/internal/client.py
@@ -13,6 +13,7 @@ from .raw_client import AsyncRawInternalClient, RawInternalClient
if typing.TYPE_CHECKING:
from .agents.client import AgentsClient, AsyncAgentsClient
from .metrics.client import AsyncMetricsClient, MetricsClient
+ from .sandbox_environments.client import AsyncSandboxEnvironmentsClient, SandboxEnvironmentsClient
from .schedules.client import AsyncSchedulesClient, SchedulesClient
from .sessions.client import AsyncSessionsClient, SessionsClient
# this is used as the default value for optional parameters
@@ -24,6 +25,7 @@ class InternalClient:
self._raw_client = RawInternalClient(client_wrapper=client_wrapper)
self._client_wrapper = client_wrapper
self._metrics: typing.Optional[MetricsClient] = None
+ self._sandbox_environments: typing.Optional[SandboxEnvironmentsClient] = None
self._schedules: typing.Optional[SchedulesClient] = None
self._sessions: typing.Optional[SessionsClient] = None
self._agents: typing.Optional[AgentsClient] = None
@@ -90,6 +92,14 @@ class InternalClient:
self._metrics = MetricsClient(client_wrapper=self._client_wrapper)
return self._metrics
+ @property
+ def sandbox_environments(self):
+ if self._sandbox_environments is None:
+ from .sandbox_environments.client import SandboxEnvironmentsClient # noqa: E402
+
+ self._sandbox_environments = SandboxEnvironmentsClient(client_wrapper=self._client_wrapper)
+ return self._sandbox_environments
+
@property
def schedules(self):
if self._schedules is None:
@@ -120,6 +130,7 @@ class AsyncInternalClient:
self._raw_client = AsyncRawInternalClient(client_wrapper=client_wrapper)
self._client_wrapper = client_wrapper
self._metrics: typing.Optional[AsyncMetricsClient] = None
+ self._sandbox_environments: typing.Optional[AsyncSandboxEnvironmentsClient] = None
self._schedules: typing.Optional[AsyncSchedulesClient] = None
self._sessions: typing.Optional[AsyncSessionsClient] = None
self._agents: typing.Optional[AsyncAgentsClient] = None
@@ -194,6 +205,14 @@ class AsyncInternalClient:
self._metrics = AsyncMetricsClient(client_wrapper=self._client_wrapper)
return self._metrics
+ @property
+ def sandbox_environments(self):
+ if self._sandbox_environments is None:
+ from .sandbox_environments.client import AsyncSandboxEnvironmentsClient # noqa: E402
+
+ self._sandbox_environments = AsyncSandboxEnvironmentsClient(client_wrapper=self._client_wrapper)
+ return self._sandbox_environments
+
@property
def schedules(self):
if self._schedules is None:
diff --git a/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/__init__.py
new file mode 100644
index 000000000..5cde0202d
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/__init__.py
@@ -0,0 +1,4 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
diff --git a/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/client.py b/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/client.py
new file mode 100644
index 000000000..5d91ddbe1
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/client.py
@@ -0,0 +1,185 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ...core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ...core.request_options import RequestOptions
+from ...types.list_pending_sandbox_environment_versions_response import ListPendingSandboxEnvironmentVersionsResponse
+from .raw_client import AsyncRawSandboxEnvironmentsClient, RawSandboxEnvironmentsClient
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class SandboxEnvironmentsClient:
+ def __init__(self, *, client_wrapper: SyncClientWrapper):
+ self._raw_client = RawSandboxEnvironmentsClient(client_wrapper=client_wrapper)
+
+ @property
+ def with_raw_response(self) -> RawSandboxEnvironmentsClient:
+ """
+ Retrieves a raw implementation of this client that returns raw responses.
+
+ Returns
+ -------
+ RawSandboxEnvironmentsClient
+ """
+ return self._raw_client
+
+ def list_pending(
+ self, *, request_options: typing.Optional[RequestOptions] = None
+ ) -> ListPendingSandboxEnvironmentVersionsResponse:
+ """
+ Returns pending environment versions for the build controller.
+
+ Parameters
+ ----------
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ ListPendingSandboxEnvironmentVersionsResponse
+ Pending versions oldest-first.
+
+ Examples
+ --------
+ from trueforge_sdk import TrueForge
+
+ client = TrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+ client.internal.sandbox_environments.list_pending()
+ """
+ _response = self._raw_client.list_pending(request_options=request_options)
+ return _response.data
+
+ def progress(self, *, environment_version_id: str, request_options: typing.Optional[RequestOptions] = None) -> None:
+ """
+ Registers or polls the snapshot build and updates version status.
+
+ Parameters
+ ----------
+ environment_version_id : str
+ Version row id to progress.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ None
+
+ Examples
+ --------
+ from trueforge_sdk import TrueForge
+
+ client = TrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+ client.internal.sandbox_environments.progress(
+ environment_version_id="environment_version_id",
+ )
+ """
+ _response = self._raw_client.progress(
+ environment_version_id=environment_version_id, request_options=request_options
+ )
+ return _response.data
+
+
+class AsyncSandboxEnvironmentsClient:
+ def __init__(self, *, client_wrapper: AsyncClientWrapper):
+ self._raw_client = AsyncRawSandboxEnvironmentsClient(client_wrapper=client_wrapper)
+
+ @property
+ def with_raw_response(self) -> AsyncRawSandboxEnvironmentsClient:
+ """
+ Retrieves a raw implementation of this client that returns raw responses.
+
+ Returns
+ -------
+ AsyncRawSandboxEnvironmentsClient
+ """
+ return self._raw_client
+
+ async def list_pending(
+ self, *, request_options: typing.Optional[RequestOptions] = None
+ ) -> ListPendingSandboxEnvironmentVersionsResponse:
+ """
+ Returns pending environment versions for the build controller.
+
+ Parameters
+ ----------
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ ListPendingSandboxEnvironmentVersionsResponse
+ Pending versions oldest-first.
+
+ Examples
+ --------
+ import asyncio
+
+ from trueforge_sdk import AsyncTrueForge
+
+ client = AsyncTrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+
+
+ async def main() -> None:
+ await client.internal.sandbox_environments.list_pending()
+
+
+ asyncio.run(main())
+ """
+ _response = await self._raw_client.list_pending(request_options=request_options)
+ return _response.data
+
+ async def progress(
+ self, *, environment_version_id: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> None:
+ """
+ Registers or polls the snapshot build and updates version status.
+
+ Parameters
+ ----------
+ environment_version_id : str
+ Version row id to progress.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ None
+
+ Examples
+ --------
+ import asyncio
+
+ from trueforge_sdk import AsyncTrueForge
+
+ client = AsyncTrueForge(
+ token="YOUR_TOKEN",
+ base_url="https://yourhost.com/path/to/api",
+ )
+
+
+ async def main() -> None:
+ await client.internal.sandbox_environments.progress(
+ environment_version_id="environment_version_id",
+ )
+
+
+ asyncio.run(main())
+ """
+ _response = await self._raw_client.progress(
+ environment_version_id=environment_version_id, request_options=request_options
+ )
+ return _response.data
diff --git a/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/raw_client.py b/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/raw_client.py
new file mode 100644
index 000000000..ca77ed123
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/internal/sandbox_environments/raw_client.py
@@ -0,0 +1,259 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+from json.decoder import JSONDecodeError
+
+from ...core.api_error import ApiError
+from ...core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ...core.http_response import AsyncHttpResponse, HttpResponse
+from ...core.parse_error import ParsingError
+from ...core.request_options import RequestOptions
+from ...core.unchecked_base_model import construct_type
+from ...errors.not_found_error import NotFoundError
+from ...errors.unauthorized_error import UnauthorizedError
+from ...types.list_pending_sandbox_environment_versions_response import ListPendingSandboxEnvironmentVersionsResponse
+from ...types.request_error_response import RequestErrorResponse
+from pydantic import ValidationError
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class RawSandboxEnvironmentsClient:
+ def __init__(self, *, client_wrapper: SyncClientWrapper):
+ self._client_wrapper = client_wrapper
+
+ def list_pending(
+ self, *, request_options: typing.Optional[RequestOptions] = None
+ ) -> HttpResponse[ListPendingSandboxEnvironmentVersionsResponse]:
+ """
+ Returns pending environment versions for the build controller.
+
+ Parameters
+ ----------
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ HttpResponse[ListPendingSandboxEnvironmentVersionsResponse]
+ Pending versions oldest-first.
+ """
+ _response = self._client_wrapper.httpx_client.request(
+ "api/internal/sandbox-environments/pending",
+ method="GET",
+ request_options=request_options,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _data = typing.cast(
+ ListPendingSandboxEnvironmentVersionsResponse,
+ construct_type(
+ type_=ListPendingSandboxEnvironmentVersionsResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ return HttpResponse(response=_response, data=_data)
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+ def progress(
+ self, *, environment_version_id: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> HttpResponse[None]:
+ """
+ Registers or polls the snapshot build and updates version status.
+
+ Parameters
+ ----------
+ environment_version_id : str
+ Version row id to progress.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ HttpResponse[None]
+ """
+ _response = self._client_wrapper.httpx_client.request(
+ "api/internal/sandbox-environments/progress",
+ method="POST",
+ json={
+ "environment_version_id": environment_version_id,
+ },
+ headers={
+ "content-type": "application/json",
+ },
+ request_options=request_options,
+ omit=OMIT,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ return HttpResponse(response=_response, data=None)
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 404:
+ raise NotFoundError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+
+class AsyncRawSandboxEnvironmentsClient:
+ def __init__(self, *, client_wrapper: AsyncClientWrapper):
+ self._client_wrapper = client_wrapper
+
+ async def list_pending(
+ self, *, request_options: typing.Optional[RequestOptions] = None
+ ) -> AsyncHttpResponse[ListPendingSandboxEnvironmentVersionsResponse]:
+ """
+ Returns pending environment versions for the build controller.
+
+ Parameters
+ ----------
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ AsyncHttpResponse[ListPendingSandboxEnvironmentVersionsResponse]
+ Pending versions oldest-first.
+ """
+ _response = await self._client_wrapper.httpx_client.request(
+ "api/internal/sandbox-environments/pending",
+ method="GET",
+ request_options=request_options,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ _data = typing.cast(
+ ListPendingSandboxEnvironmentVersionsResponse,
+ construct_type(
+ type_=ListPendingSandboxEnvironmentVersionsResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ )
+ return AsyncHttpResponse(response=_response, data=_data)
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+ async def progress(
+ self, *, environment_version_id: str, request_options: typing.Optional[RequestOptions] = None
+ ) -> AsyncHttpResponse[None]:
+ """
+ Registers or polls the snapshot build and updates version status.
+
+ Parameters
+ ----------
+ environment_version_id : str
+ Version row id to progress.
+
+ request_options : typing.Optional[RequestOptions]
+ Request-specific configuration.
+
+ Returns
+ -------
+ AsyncHttpResponse[None]
+ """
+ _response = await self._client_wrapper.httpx_client.request(
+ "api/internal/sandbox-environments/progress",
+ method="POST",
+ json={
+ "environment_version_id": environment_version_id,
+ },
+ headers={
+ "content-type": "application/json",
+ },
+ request_options=request_options,
+ omit=OMIT,
+ )
+ try:
+ if 200 <= _response.status_code < 300:
+ return AsyncHttpResponse(response=_response, data=None)
+ if _response.status_code == 401:
+ raise UnauthorizedError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ if _response.status_code == 404:
+ raise NotFoundError(
+ headers=dict(_response.headers),
+ body=typing.cast(
+ RequestErrorResponse,
+ construct_type(
+ type_=RequestErrorResponse, # type: ignore
+ object_=_response.json(),
+ ),
+ ),
+ )
+ _response_json = _response.json()
+ except JSONDecodeError:
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+ except ValidationError as e:
+ raise ParsingError(
+ status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+ )
+ raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
diff --git a/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/client.py b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/client.py
index 8c93146b5..4b2c65a10 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/client.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/client.py
@@ -9,7 +9,7 @@ from ..types.delete_sandbox_environment_response import DeleteSandboxEnvironment
from ..types.get_sandbox_environment_response import GetSandboxEnvironmentResponse
from ..types.list_sandbox_environments_response import ListSandboxEnvironmentsResponse
from ..types.sandbox_environment import SandboxEnvironment
-from ..types.sandbox_environment_manifest import SandboxEnvironmentManifest
+from ..types.sandbox_environment_manifest_request import SandboxEnvironmentManifestRequest
from .raw_client import AsyncRawSandboxEnvironmentsClient, RawSandboxEnvironmentsClient
# this is used as the default value for optional parameters
@@ -39,12 +39,12 @@ class SandboxEnvironmentsClient:
request_options: typing.Optional[RequestOptions] = None,
) -> SyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]:
"""
- List sandbox environments created by the authenticated subject, newest first.
+ List the tenant default environment plus sandbox environments created by the authenticated subject.
Parameters
----------
limit : typing.Optional[int]
- Page size. Defaults to 25
+ Page size. Defaults to 25, max 1000.
page_token : typing.Optional[str]
Opaque token from a previous response `next_page_token`.
@@ -75,14 +75,14 @@ class SandboxEnvironmentsClient:
return self._raw_client.list(limit=limit, page_token=page_token, request_options=request_options)
def create_or_update(
- self, *, manifest: SandboxEnvironmentManifest, request_options: typing.Optional[RequestOptions] = None
+ self, *, manifest: SandboxEnvironmentManifestRequest, request_options: typing.Optional[RequestOptions] = None
) -> GetSandboxEnvironmentResponse:
"""
- Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+ Create or replace by `manifest.name`. Requires a configured sandbox provider.
Parameters
----------
- manifest : SandboxEnvironmentManifest
+ manifest : SandboxEnvironmentManifestRequest
request_options : typing.Optional[RequestOptions]
Request-specific configuration.
@@ -94,14 +94,14 @@ class SandboxEnvironmentsClient:
Examples
--------
- from trueforge_sdk import SandboxEnvironmentManifest, TrueForge
+ from trueforge_sdk import SandboxEnvironmentManifestRequest, TrueForge
client = TrueForge(
token="YOUR_TOKEN",
base_url="https://yourhost.com/path/to/api",
)
client.sandbox_environments.create_or_update(
- manifest=SandboxEnvironmentManifest(
+ manifest=SandboxEnvironmentManifestRequest(
name="name",
),
)
@@ -113,7 +113,7 @@ class SandboxEnvironmentsClient:
self, *, name: str, request_options: typing.Optional[RequestOptions] = None
) -> GetSandboxEnvironmentResponse:
"""
- Get a sandbox environment by name for the authenticated subject.
+ Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.
Parameters
----------
@@ -201,12 +201,12 @@ class AsyncSandboxEnvironmentsClient:
request_options: typing.Optional[RequestOptions] = None,
) -> AsyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]:
"""
- List sandbox environments created by the authenticated subject, newest first.
+ List the tenant default environment plus sandbox environments created by the authenticated subject.
Parameters
----------
limit : typing.Optional[int]
- Page size. Defaults to 25
+ Page size. Defaults to 25, max 1000.
page_token : typing.Optional[str]
Opaque token from a previous response `next_page_token`.
@@ -246,14 +246,14 @@ class AsyncSandboxEnvironmentsClient:
return await self._raw_client.list(limit=limit, page_token=page_token, request_options=request_options)
async def create_or_update(
- self, *, manifest: SandboxEnvironmentManifest, request_options: typing.Optional[RequestOptions] = None
+ self, *, manifest: SandboxEnvironmentManifestRequest, request_options: typing.Optional[RequestOptions] = None
) -> GetSandboxEnvironmentResponse:
"""
- Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+ Create or replace by `manifest.name`. Requires a configured sandbox provider.
Parameters
----------
- manifest : SandboxEnvironmentManifest
+ manifest : SandboxEnvironmentManifestRequest
request_options : typing.Optional[RequestOptions]
Request-specific configuration.
@@ -267,7 +267,7 @@ class AsyncSandboxEnvironmentsClient:
--------
import asyncio
- from trueforge_sdk import AsyncTrueForge, SandboxEnvironmentManifest
+ from trueforge_sdk import AsyncTrueForge, SandboxEnvironmentManifestRequest
client = AsyncTrueForge(
token="YOUR_TOKEN",
@@ -277,7 +277,7 @@ class AsyncSandboxEnvironmentsClient:
async def main() -> None:
await client.sandbox_environments.create_or_update(
- manifest=SandboxEnvironmentManifest(
+ manifest=SandboxEnvironmentManifestRequest(
name="name",
),
)
@@ -292,7 +292,7 @@ class AsyncSandboxEnvironmentsClient:
self, *, name: str, request_options: typing.Optional[RequestOptions] = None
) -> GetSandboxEnvironmentResponse:
"""
- Get a sandbox environment by name for the authenticated subject.
+ Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.
Parameters
----------
diff --git a/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/raw_client.py b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/raw_client.py
index 7a52bfff4..d344bd2f3 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/raw_client.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/sandbox_environments/raw_client.py
@@ -22,7 +22,7 @@ from ..types.get_sandbox_environment_response import GetSandboxEnvironmentRespon
from ..types.list_sandbox_environments_response import ListSandboxEnvironmentsResponse
from ..types.request_error_response import RequestErrorResponse
from ..types.sandbox_environment import SandboxEnvironment
-from ..types.sandbox_environment_manifest import SandboxEnvironmentManifest
+from ..types.sandbox_environment_manifest_request import SandboxEnvironmentManifestRequest
from pydantic import ValidationError
# this is used as the default value for optional parameters
@@ -41,12 +41,12 @@ class RawSandboxEnvironmentsClient:
request_options: typing.Optional[RequestOptions] = None,
) -> SyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]:
"""
- List sandbox environments created by the authenticated subject, newest first.
+ List the tenant default environment plus sandbox environments created by the authenticated subject.
Parameters
----------
limit : typing.Optional[int]
- Page size. Defaults to 25
+ Page size. Defaults to 25, max 1000.
page_token : typing.Optional[str]
Opaque token from a previous response `next_page_token`.
@@ -121,14 +121,14 @@ class RawSandboxEnvironmentsClient:
raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
def create_or_update(
- self, *, manifest: SandboxEnvironmentManifest, request_options: typing.Optional[RequestOptions] = None
+ self, *, manifest: SandboxEnvironmentManifestRequest, request_options: typing.Optional[RequestOptions] = None
) -> HttpResponse[GetSandboxEnvironmentResponse]:
"""
- Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+ Create or replace by `manifest.name`. Requires a configured sandbox provider.
Parameters
----------
- manifest : SandboxEnvironmentManifest
+ manifest : SandboxEnvironmentManifestRequest
request_options : typing.Optional[RequestOptions]
Request-specific configuration.
@@ -143,7 +143,7 @@ class RawSandboxEnvironmentsClient:
method="PUT",
json={
"manifest": convert_and_respect_annotation_metadata(
- object_=manifest, annotation=SandboxEnvironmentManifest, direction="write"
+ object_=manifest, annotation=SandboxEnvironmentManifestRequest, direction="write"
),
},
headers={
@@ -219,7 +219,7 @@ class RawSandboxEnvironmentsClient:
self, *, name: str, request_options: typing.Optional[RequestOptions] = None
) -> HttpResponse[GetSandboxEnvironmentResponse]:
"""
- Get a sandbox environment by name for the authenticated subject.
+ Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.
Parameters
----------
@@ -369,12 +369,12 @@ class AsyncRawSandboxEnvironmentsClient:
request_options: typing.Optional[RequestOptions] = None,
) -> AsyncPager[SandboxEnvironment, ListSandboxEnvironmentsResponse]:
"""
- List sandbox environments created by the authenticated subject, newest first.
+ List the tenant default environment plus sandbox environments created by the authenticated subject.
Parameters
----------
limit : typing.Optional[int]
- Page size. Defaults to 25
+ Page size. Defaults to 25, max 1000.
page_token : typing.Optional[str]
Opaque token from a previous response `next_page_token`.
@@ -452,14 +452,14 @@ class AsyncRawSandboxEnvironmentsClient:
raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
async def create_or_update(
- self, *, manifest: SandboxEnvironmentManifest, request_options: typing.Optional[RequestOptions] = None
+ self, *, manifest: SandboxEnvironmentManifestRequest, request_options: typing.Optional[RequestOptions] = None
) -> AsyncHttpResponse[GetSandboxEnvironmentResponse]:
"""
- Create or replace by `manifest.name`. Requires a Daytona sandbox provider.
+ Create or replace by `manifest.name`. Requires a configured sandbox provider.
Parameters
----------
- manifest : SandboxEnvironmentManifest
+ manifest : SandboxEnvironmentManifestRequest
request_options : typing.Optional[RequestOptions]
Request-specific configuration.
@@ -474,7 +474,7 @@ class AsyncRawSandboxEnvironmentsClient:
method="PUT",
json={
"manifest": convert_and_respect_annotation_metadata(
- object_=manifest, annotation=SandboxEnvironmentManifest, direction="write"
+ object_=manifest, annotation=SandboxEnvironmentManifestRequest, direction="write"
),
},
headers={
@@ -550,7 +550,7 @@ class AsyncRawSandboxEnvironmentsClient:
self, *, name: str, request_options: typing.Optional[RequestOptions] = None
) -> AsyncHttpResponse[GetSandboxEnvironmentResponse]:
"""
- Get a sandbox environment by name for the authenticated subject.
+ Get a sandbox environment by name. The tenant default is readable by any tenant member; custom environments are owner-scoped.
Parameters
----------
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
index c6ba92897..9d45891a0 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
@@ -107,6 +107,7 @@ if typing.TYPE_CHECKING:
from .list_mcp_server_tools_response import ListMcpServerToolsResponse
from .list_mcp_servers_response import ListMcpServersResponse
from .list_model_providers_response import ListModelProvidersResponse
+ from .list_pending_sandbox_environment_versions_response import ListPendingSandboxEnvironmentVersionsResponse
from .list_permissions_data import ListPermissionsData
from .list_permissions_response import ListPermissionsResponse
from .list_sandbox_environments_response import ListSandboxEnvironmentsResponse
@@ -155,6 +156,7 @@ if typing.TYPE_CHECKING:
from .moonshot_model_provider import MoonshotModelProvider
from .open_ai_model_provider import OpenAiModelProvider
from .parallel_web_search_provider_auth import ParallelWebSearchProviderAuth
+ from .pending_sandbox_environment_version import PendingSandboxEnvironmentVersion
from .permission_resource_type import PermissionResourceType
from .previous_turn_id_input import PreviousTurnIdInput
from .raw_tool_call import RawToolCall
@@ -170,7 +172,6 @@ if typing.TYPE_CHECKING:
from .response_format_json_schema_json_schema import ResponseFormatJsonSchemaJsonSchema
from .response_format_text import ResponseFormatText
from .runtime_config import RuntimeConfig
- from .sandbox_build_status import SandboxBuildStatus
from .sandbox_capability import SandboxCapability
from .sandbox_config import SandboxConfig
from .sandbox_created_event import SandboxCreatedEvent
@@ -178,6 +179,7 @@ if typing.TYPE_CHECKING:
from .sandbox_environment_image import SandboxEnvironmentImage
from .sandbox_environment_lifecycle_stage import SandboxEnvironmentLifecycleStage
from .sandbox_environment_manifest import SandboxEnvironmentManifest
+ from .sandbox_environment_manifest_request import SandboxEnvironmentManifestRequest
from .sandbox_environment_networking import SandboxEnvironmentNetworking
from .sandbox_environment_resources import SandboxEnvironmentResources
from .sandbox_environment_secret import SandboxEnvironmentSecret
@@ -373,6 +375,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"ListMcpServerToolsResponse": ".list_mcp_server_tools_response",
"ListMcpServersResponse": ".list_mcp_servers_response",
"ListModelProvidersResponse": ".list_model_providers_response",
+ "ListPendingSandboxEnvironmentVersionsResponse": ".list_pending_sandbox_environment_versions_response",
"ListPermissionsData": ".list_permissions_data",
"ListPermissionsResponse": ".list_permissions_response",
"ListSandboxEnvironmentsResponse": ".list_sandbox_environments_response",
@@ -421,6 +424,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"MoonshotModelProvider": ".moonshot_model_provider",
"OpenAiModelProvider": ".open_ai_model_provider",
"ParallelWebSearchProviderAuth": ".parallel_web_search_provider_auth",
+ "PendingSandboxEnvironmentVersion": ".pending_sandbox_environment_version",
"PermissionResourceType": ".permission_resource_type",
"PreviousTurnIdInput": ".previous_turn_id_input",
"RawToolCall": ".raw_tool_call",
@@ -436,7 +440,6 @@ _dynamic_imports: typing.Dict[str, str] = {
"ResponseFormatJsonSchemaJsonSchema": ".response_format_json_schema_json_schema",
"ResponseFormatText": ".response_format_text",
"RuntimeConfig": ".runtime_config",
- "SandboxBuildStatus": ".sandbox_build_status",
"SandboxCapability": ".sandbox_capability",
"SandboxConfig": ".sandbox_config",
"SandboxCreatedEvent": ".sandbox_created_event",
@@ -444,6 +447,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"SandboxEnvironmentImage": ".sandbox_environment_image",
"SandboxEnvironmentLifecycleStage": ".sandbox_environment_lifecycle_stage",
"SandboxEnvironmentManifest": ".sandbox_environment_manifest",
+ "SandboxEnvironmentManifestRequest": ".sandbox_environment_manifest_request",
"SandboxEnvironmentNetworking": ".sandbox_environment_networking",
"SandboxEnvironmentResources": ".sandbox_environment_resources",
"SandboxEnvironmentSecret": ".sandbox_environment_secret",
@@ -663,6 +667,7 @@ __all__ = [
"ListMcpServerToolsResponse",
"ListMcpServersResponse",
"ListModelProvidersResponse",
+ "ListPendingSandboxEnvironmentVersionsResponse",
"ListPermissionsData",
"ListPermissionsResponse",
"ListSandboxEnvironmentsResponse",
@@ -711,6 +716,7 @@ __all__ = [
"MoonshotModelProvider",
"OpenAiModelProvider",
"ParallelWebSearchProviderAuth",
+ "PendingSandboxEnvironmentVersion",
"PermissionResourceType",
"PreviousTurnIdInput",
"RawToolCall",
@@ -726,7 +732,6 @@ __all__ = [
"ResponseFormatJsonSchemaJsonSchema",
"ResponseFormatText",
"RuntimeConfig",
- "SandboxBuildStatus",
"SandboxCapability",
"SandboxConfig",
"SandboxCreatedEvent",
@@ -734,6 +739,7 @@ __all__ = [
"SandboxEnvironmentImage",
"SandboxEnvironmentLifecycleStage",
"SandboxEnvironmentManifest",
+ "SandboxEnvironmentManifestRequest",
"SandboxEnvironmentNetworking",
"SandboxEnvironmentResources",
"SandboxEnvironmentSecret",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/configured_sandbox_provider.py b/python/trueforge_sdk/src/trueforge_sdk/types/configured_sandbox_provider.py
index 557c21dc9..801c47e48 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/configured_sandbox_provider.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/configured_sandbox_provider.py
@@ -5,17 +5,11 @@ import typing
import pydantic
from ..core.pydantic_utilities import IS_PYDANTIC_V2
from ..core.unchecked_base_model import UncheckedBaseModel
-from .sandbox_build_status import SandboxBuildStatus
from .sandbox_provider_manifest import SandboxProviderManifest
class ConfiguredSandboxProvider(UncheckedBaseModel):
manifest: SandboxProviderManifest
- status: SandboxBuildStatus
- status_reason: typing.Optional[str] = pydantic.Field(default=None)
- """
- Human-readable detail for the current status; null when ready.
- """
if IS_PYDANTIC_V2:
model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/list_pending_sandbox_environment_versions_response.py b/python/trueforge_sdk/src/trueforge_sdk/types/list_pending_sandbox_environment_versions_response.py
new file mode 100644
index 000000000..f56813f84
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/list_pending_sandbox_environment_versions_response.py
@@ -0,0 +1,20 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .pending_sandbox_environment_version import PendingSandboxEnvironmentVersion
+
+
+class ListPendingSandboxEnvironmentVersionsResponse(UncheckedBaseModel):
+ data: typing.List[PendingSandboxEnvironmentVersion]
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/pending_sandbox_environment_version.py b/python/trueforge_sdk/src/trueforge_sdk/types/pending_sandbox_environment_version.py
new file mode 100644
index 000000000..238f02257
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/pending_sandbox_environment_version.py
@@ -0,0 +1,22 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class PendingSandboxEnvironmentVersion(UncheckedBaseModel):
+ environment_version_id: str = pydantic.Field()
+ """
+ Version row id to progress.
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_build_status.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_build_status.py
deleted file mode 100644
index 1f7627450..000000000
--- a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_build_status.py
+++ /dev/null
@@ -1,42 +0,0 @@
-# This file was auto-generated by Fern from our API Definition.
-
-import typing
-
-from ..core import enum
-
-T_Result = typing.TypeVar("T_Result")
-
-
-class SandboxBuildStatus(enum.StrEnum):
- """
- Current build status.
- """
-
- PENDING = "pending"
- READY = "ready"
- FAILED = "failed"
- _UNKNOWN = "__SANDBOXBUILDSTATUS_UNKNOWN__"
- """
- This member is used for forward compatibility. If the value is not recognized by the enum, it will be stored here, and the raw value is accessible through `.value`.
- """
-
- @classmethod
- def _missing_(cls, value: typing.Any) -> "SandboxBuildStatus":
- unknown = cls._UNKNOWN
- unknown._value_ = value
- return unknown
-
- def visit(
- self,
- pending: typing.Callable[[], T_Result],
- ready: typing.Callable[[], T_Result],
- failed: typing.Callable[[], T_Result],
- _unknown_member: typing.Callable[[str], T_Result],
- ) -> T_Result:
- if self is SandboxBuildStatus.PENDING:
- return pending()
- if self is SandboxBuildStatus.READY:
- return ready()
- if self is SandboxBuildStatus.FAILED:
- return failed()
- return _unknown_member(self._value_)
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_manifest_request.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_manifest_request.py
new file mode 100644
index 000000000..3ec3817c1
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_manifest_request.py
@@ -0,0 +1,32 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .resource_name import ResourceName
+from .sandbox_environment_image import SandboxEnvironmentImage
+from .sandbox_environment_networking import SandboxEnvironmentNetworking
+from .sandbox_environment_resources import SandboxEnvironmentResources
+
+
+class SandboxEnvironmentManifestRequest(UncheckedBaseModel):
+ description: typing.Optional[str] = pydantic.Field(default=None)
+ """
+ Optional human-readable description.
+ """
+
+ environment_variables: typing.Optional[typing.Dict[str, str]] = None
+ image: typing.Optional[SandboxEnvironmentImage] = None
+ name: ResourceName
+ networking: typing.Optional[SandboxEnvironmentNetworking] = None
+ resources: typing.Optional[SandboxEnvironmentResources] = None
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_version_status.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_version_status.py
index c354f4825..8408aea5e 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_version_status.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_environment_version_status.py
@@ -13,7 +13,7 @@ class SandboxEnvironmentVersionStatus(enum.StrEnum):
"""
PENDING = "pending"
- ACTIVE = "active"
+ READY = "ready"
FAILED = "failed"
_UNKNOWN = "__SANDBOXENVIRONMENTVERSIONSTATUS_UNKNOWN__"
"""
@@ -29,14 +29,14 @@ class SandboxEnvironmentVersionStatus(enum.StrEnum):
def visit(
self,
pending: typing.Callable[[], T_Result],
- active: typing.Callable[[], T_Result],
+ ready: typing.Callable[[], T_Result],
failed: typing.Callable[[], T_Result],
_unknown_member: typing.Callable[[str], T_Result],
) -> T_Result:
if self is SandboxEnvironmentVersionStatus.PENDING:
return pending()
- if self is SandboxEnvironmentVersionStatus.ACTIVE:
- return active()
+ if self is SandboxEnvironmentVersionStatus.READY:
+ return ready()
if self is SandboxEnvironmentVersionStatus.FAILED:
return failed()
return _unknown_member(self._value_)