Skip to content

Commit e4fd3d4

Browse files
backfill sandbox environment where it is undefined (#1400)
1 parent 5f25401 commit e4fd3d4

11 files changed

Lines changed: 156 additions & 8 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@truefoundry/trueforge-sdk": patch
3+
---
4+
5+
Regenerate SDK from updated OpenAPI spec.
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@truefoundry/trueforge': patch
3+
'@truefoundry/trueforge-core': patch
4+
---
5+
6+
Backfill missing `config.sandbox.environment_name` on saved agents and inline session specs that have sandbox enabled, pinning each to the tenant default environment (or `trueforge-sandbox-env` when no default is set). Docs now require the field when sandbox is enabled instead of documenting omit-as-default.

‎.github/fern/openapi/openapi.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3829,7 +3829,7 @@
38293829
"type": "boolean"
38303830
},
38313831
"environment_name": {
3832-
"description": "Name of a configured sandbox environment to use. Must exist when set.",
3832+
"description": "Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments.",
38333833
"minLength": 1,
38343834
"type": "string"
38353835
},

‎docs/create-agent/overview.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -316,7 +316,7 @@ The `manifest` you save (or the inline `spec`) is the agent spec below — every
316316
],
317317
"skills": [{ "name": "customer-support" }],
318318
"config": {
319-
"sandbox": { "enabled": true },
319+
"sandbox": { "enabled": true, "environment_name": "trueforge-sandbox-env" },
320320
"generative_ui": { "enabled": true },
321321
"ask_user_questions": { "enabled": true },
322322
"dynamic_sub_agents": { "enabled": true },
@@ -398,6 +398,7 @@ Runtime behavior. Every field has a default, so `config` can be omitted entirely
398398
| Field | Default | Set via | Description |
399399
| ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
400400
| `enabled` | `false` | UI + API | Give the agent a sandbox. Required for skills and Code Mode. |
401+
| `environment_name` | — | UI + API | Name of a configured sandbox environment. **Required** when sandbox is enabled and the provider supports environments (Daytona). See [Sandbox](/sandbox). |
401402
| `file_downloads` | `true` | API | Allow clients to download files the agent produces in the sandbox. |
402403

403404
#### `config.context_management`

‎docs/openapi.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3829,7 +3829,7 @@
38293829
"type": "boolean"
38303830
},
38313831
"environment_name": {
3832-
"description": "Name of a configured sandbox environment to use. Must exist when set.",
3832+
"description": "Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments.",
38333833
"minLength": 1,
38343834
"type": "string"
38353835
},

‎docs/sandbox.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -147,9 +147,10 @@ The sandbox is **off by default** per agent. Turn it on in the agent builder whe
147147
Optional controls:
148148

149149
- **File downloads**: let users download files the agent produces (on by default in the chat UI).
150-
- **Environment**: the environment a sandbox is cloned from. Leave it as **default**, or pick one you created (only **Ready** environments appear).
150+
- **Environment**: the environment a sandbox is cloned from. Pick the tenant default or one you created (only **Ready** environments appear).
151151

152-
In the agent builder, both controls live in **Runtime Config** under **Sandbox**, where the **Environment** dropdown also has a **Manage Environments** link to the Envs page. For a one-off chat, pick an environment from the composer's **Tools** menu under the **Environment** tab. Via the SDK, set `config.sandbox.environment_name` on the [agent spec](/create-agent/overview#config); omit it to use `default`:
152+
In the agent builder, both controls live in **Runtime Config** under **Sandbox**, where the **Environment** dropdown also has a **Manage Environments** link to the Envs page. For a one-off chat, pick an environment from the composer's **Tools** menu under the **Environment** tab. Via the SDK, set `config.sandbox.environment_name` on the [agent spec](/create-agent/overview#config).
153+
When sandbox is enabled and the provider supports environments (Daytona), this field is **required**:
153154

154155
```json
155156
"config": { "sandbox": { "enabled": true, "environment_name": "data-tools" } }

‎packages/trueforge-core/src/agent-session/schemas/agentSpec.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,9 @@ const SandboxConfigSchema = z
140140
.string()
141141
.min(1)
142142
.optional()
143-
.describe('Name of a configured sandbox environment to use. Must exist when set.'),
143+
.describe(
144+
'Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments.',
145+
),
144146
})
145147
.openapi('SandboxConfig');
146148

‎packages/trueforge-sdk/src/api/types/SandboxConfig.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
export interface SandboxConfig {
44
/** Give the agent a sandbox. Required for skills and Code Mode. */
55
enabled: boolean;
6-
/** Name of a configured sandbox environment to use. Must exist when set. */
6+
/** Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments. */
77
environmentName?: string;
88
/** Allow downloading agent-produced files via the turn download endpoint. Default: true. */
99
fileDownloads?: boolean;
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
import { sql, type Kysely } from 'kysely';
2+
3+
/**
4+
* Pin missing `config.sandbox.environment_name` on saved agents and inline
5+
* session specs when sandbox is enabled.
6+
*
7+
* Before 2026-11-10 the field was optional (omit meant "tenant default").
8+
* Validation now requires it for Daytona, which 422s those legacy rows at
9+
* session create. Prefer the tenant `is_default` environment; fall back to the
10+
* reserved `trueforge-sandbox-env` when that row exists and no default is set.
11+
*/
12+
export async function up(db: Kysely<unknown>): Promise<void> {
13+
await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
14+
15+
await sql`
16+
UPDATE agent AS agent
17+
SET manifest = jsonb_set(
18+
agent.manifest,
19+
'{config,sandbox,environment_name}',
20+
to_jsonb(pin.name)
21+
)
22+
FROM (
23+
SELECT
24+
tenant_id,
25+
COALESCE(
26+
MAX(name) FILTER (WHERE is_default),
27+
MAX(name) FILTER (WHERE name = 'trueforge-sandbox-env')
28+
) AS name
29+
FROM sandbox_environment
30+
WHERE lifecycle_stage = 'active'
31+
GROUP BY tenant_id
32+
) AS pin
33+
WHERE pin.tenant_id = agent.tenant_id
34+
AND pin.name IS NOT NULL
35+
AND (agent.manifest #>> '{config,sandbox,enabled}') = 'true'
36+
AND nullif(agent.manifest #>> '{config,sandbox,environment_name}', '') IS NULL
37+
`.execute(db);
38+
39+
await sql`
40+
UPDATE session AS session
41+
SET agent_spec = jsonb_set(
42+
session.agent_spec,
43+
'{config,sandbox,environment_name}',
44+
to_jsonb(pin.name)
45+
)
46+
FROM (
47+
SELECT
48+
tenant_id,
49+
COALESCE(
50+
MAX(name) FILTER (WHERE is_default),
51+
MAX(name) FILTER (WHERE name = 'trueforge-sandbox-env')
52+
) AS name
53+
FROM sandbox_environment
54+
WHERE lifecycle_stage = 'active'
55+
GROUP BY tenant_id
56+
) AS pin
57+
WHERE pin.tenant_id = session.tenant_id
58+
AND pin.name IS NOT NULL
59+
AND session.agent_spec IS NOT NULL
60+
AND (session.agent_spec #>> '{config,sandbox,enabled}') = 'true'
61+
AND nullif(session.agent_spec #>> '{config,sandbox,environment_name}', '') IS NULL
62+
`.execute(db);
63+
}
64+
65+
/** Irreversible: backfilled names are indistinguishable from user-pinned ones. */
66+
export function down(db: Kysely<unknown>): Promise<void> {
67+
void db;
68+
return Promise.reject(new Error('20261116_000001_sandbox_environment_name_backfill is irreversible'));
69+
}
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import { sql, type Kysely } from 'kysely';
2+
3+
/**
4+
* SQLite mirror of postgres/20261116_000001_sandbox_environment_name_backfill.ts.
5+
* Pin missing sandbox environment names on agents and inline session specs.
6+
*/
7+
export async function up(db: Kysely<unknown>): Promise<void> {
8+
await db.transaction().execute(async trx => {
9+
await sql`
10+
UPDATE agent
11+
SET manifest = jsonb_set(
12+
manifest,
13+
'$.config.sandbox.environment_name',
14+
jsonb(json_quote(pin.name))
15+
)
16+
FROM (
17+
SELECT
18+
tenant_id,
19+
COALESCE(
20+
MAX(CASE WHEN is_default = 1 THEN name END),
21+
MAX(CASE WHEN name = 'trueforge-sandbox-env' THEN name END)
22+
) AS name
23+
FROM sandbox_environment
24+
WHERE lifecycle_stage = 'active'
25+
GROUP BY tenant_id
26+
) AS pin
27+
WHERE pin.tenant_id = agent.tenant_id
28+
AND pin.name IS NOT NULL
29+
AND json_extract(agent.manifest, '$.config.sandbox.enabled') IN (1, 'true')
30+
AND nullif(json_extract(agent.manifest, '$.config.sandbox.environment_name'), '') IS NULL
31+
`.execute(trx);
32+
33+
await sql`
34+
UPDATE session
35+
SET agent_spec = jsonb_set(
36+
agent_spec,
37+
'$.config.sandbox.environment_name',
38+
jsonb(json_quote(pin.name))
39+
)
40+
FROM (
41+
SELECT
42+
tenant_id,
43+
COALESCE(
44+
MAX(CASE WHEN is_default = 1 THEN name END),
45+
MAX(CASE WHEN name = 'trueforge-sandbox-env' THEN name END)
46+
) AS name
47+
FROM sandbox_environment
48+
WHERE lifecycle_stage = 'active'
49+
GROUP BY tenant_id
50+
) AS pin
51+
WHERE pin.tenant_id = session.tenant_id
52+
AND pin.name IS NOT NULL
53+
AND session.agent_spec IS NOT NULL
54+
AND json_extract(session.agent_spec, '$.config.sandbox.enabled') IN (1, 'true')
55+
AND nullif(json_extract(session.agent_spec, '$.config.sandbox.environment_name'), '') IS NULL
56+
`.execute(trx);
57+
});
58+
}
59+
60+
/** Irreversible: backfilled names are indistinguishable from user-pinned ones. */
61+
export function down(db: Kysely<unknown>): Promise<void> {
62+
void db;
63+
return Promise.reject(new Error('20261116_000001_sandbox_environment_name_backfill is irreversible'));
64+
}

0 commit comments

Comments
 (0)