Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/20261116143735-regenerate-sdk-from-openapi.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@truefoundry/trueforge-sdk": patch
---

Regenerate SDK from updated OpenAPI spec.
Comment thread
heerambavi1998 marked this conversation as resolved.
Resolved
6 changes: 6 additions & 0 deletions .changeset/sandbox-environment-name-backfill.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@truefoundry/trueforge': patch
'@truefoundry/trueforge-core': patch
---

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.
2 changes: 1 addition & 1 deletion .github/fern/openapi/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -3829,7 +3829,7 @@
"type": "boolean"
},
"environment_name": {
"description": "Name of a configured sandbox environment to use. Must exist when set.",
"description": "Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments.",
"minLength": 1,
"type": "string"
},
Expand Down
3 changes: 2 additions & 1 deletion docs/create-agent/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -316,7 +316,7 @@ The `manifest` you save (or the inline `spec`) is the agent spec below — every
],
"skills": [{ "name": "customer-support" }],
"config": {
"sandbox": { "enabled": true },
"sandbox": { "enabled": true, "environment_name": "trueforge-sandbox-env" },
"generative_ui": { "enabled": true },
"ask_user_questions": { "enabled": true },
"dynamic_sub_agents": { "enabled": true },
Expand Down Expand Up @@ -398,6 +398,7 @@ Runtime behavior. Every field has a default, so `config` can be omitted entirely
| Field | Default | Set via | Description |
| ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `false` | UI + API | Give the agent a sandbox. Required for skills and Code Mode. |
| `environment_name` | — | UI + API | Name of a configured sandbox environment. **Required** when sandbox is enabled and the provider supports environments (Daytona). See [Sandbox](/sandbox). |
| `file_downloads` | `true` | API | Allow clients to download files the agent produces in the sandbox. |

#### `config.context_management`
Expand Down
2 changes: 1 addition & 1 deletion docs/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -3829,7 +3829,7 @@
"type": "boolean"
},
"environment_name": {
"description": "Name of a configured sandbox environment to use. Must exist when set.",
"description": "Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments.",
"minLength": 1,
"type": "string"
},
Expand Down
5 changes: 3 additions & 2 deletions docs/sandbox.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -147,9 +147,10 @@ The sandbox is **off by default** per agent. Turn it on in the agent builder whe
Optional controls:

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

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`:
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).
When sandbox is enabled and the provider supports environments (Daytona), this field is **required**:

```json
"config": { "sandbox": { "enabled": true, "environment_name": "data-tools" } }
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,9 @@ const SandboxConfigSchema = z
.string()
.min(1)
.optional()
.describe('Name of a configured sandbox environment to use. Must exist when set.'),
.describe(
'Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments.',
),
})
.openapi('SandboxConfig');

Expand Down
2 changes: 1 addition & 1 deletion packages/trueforge-sdk/src/api/types/SandboxConfig.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
export interface SandboxConfig {
/** Give the agent a sandbox. Required for skills and Code Mode. */
enabled: boolean;
/** Name of a configured sandbox environment to use. Must exist when set. */
/** Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments. */
environmentName?: string;
/** Allow downloading agent-produced files via the turn download endpoint. Default: true. */
fileDownloads?: boolean;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
import { sql, type Kysely } from 'kysely';

/**
* Pin missing `config.sandbox.environment_name` on saved agents and inline
* session specs when sandbox is enabled.
*
* Before 2026-11-10 the field was optional (omit meant "tenant default").
* Validation now requires it for Daytona, which 422s those legacy rows at
* session create. Prefer the tenant `is_default` environment; fall back to the
* reserved `trueforge-sandbox-env` when that row exists and no default is set.
*/
export async function up(db: Kysely<unknown>): Promise<void> {
await sql`SET LOCAL lock_timeout = '5s'`.execute(db);

await sql`
UPDATE agent AS agent
SET manifest = jsonb_set(
agent.manifest,
'{config,sandbox,environment_name}',
to_jsonb(pin.name)
)
FROM (
SELECT
tenant_id,
COALESCE(
MAX(name) FILTER (WHERE is_default),
MAX(name) FILTER (WHERE name = 'trueforge-sandbox-env')
) AS name
FROM sandbox_environment
WHERE lifecycle_stage = 'active'
Comment thread
heerambavi1998 marked this conversation as resolved.
Resolved
Comment thread
heerambavi1998 marked this conversation as resolved.
Resolved
GROUP BY tenant_id
Comment thread
heerambavi1998 marked this conversation as resolved.
Resolved
) AS pin
WHERE pin.tenant_id = agent.tenant_id
AND pin.name IS NOT NULL
AND (agent.manifest #>> '{config,sandbox,enabled}') = 'true'
AND nullif(agent.manifest #>> '{config,sandbox,environment_name}', '') IS NULL
`.execute(db);
Comment thread
heerambavi1998 marked this conversation as resolved.
Resolved

await sql`
UPDATE session AS session
SET agent_spec = jsonb_set(
session.agent_spec,
'{config,sandbox,environment_name}',
to_jsonb(pin.name)
)
FROM (
SELECT
tenant_id,
COALESCE(
MAX(name) FILTER (WHERE is_default),
MAX(name) FILTER (WHERE name = 'trueforge-sandbox-env')
) AS name
FROM sandbox_environment
WHERE lifecycle_stage = 'active'
GROUP BY tenant_id
) AS pin
WHERE pin.tenant_id = session.tenant_id
AND pin.name IS NOT NULL
AND session.agent_spec IS NOT NULL
AND (session.agent_spec #>> '{config,sandbox,enabled}') = 'true'
AND nullif(session.agent_spec #>> '{config,sandbox,environment_name}', '') IS NULL
`.execute(db);
}

/** Irreversible: backfilled names are indistinguishable from user-pinned ones. */
export function down(db: Kysely<unknown>): Promise<void> {
void db;
return Promise.reject(new Error('20261116_000001_sandbox_environment_name_backfill is irreversible'));
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
import { sql, type Kysely } from 'kysely';

/**
* SQLite mirror of postgres/20261116_000001_sandbox_environment_name_backfill.ts.
* Pin missing sandbox environment names on agents and inline session specs.
*/
export async function up(db: Kysely<unknown>): Promise<void> {
await db.transaction().execute(async trx => {
await sql`
UPDATE agent
SET manifest = jsonb_set(
manifest,
'$.config.sandbox.environment_name',
jsonb(json_quote(pin.name))
)
FROM (
SELECT
tenant_id,
COALESCE(
MAX(CASE WHEN is_default = 1 THEN name END),
MAX(CASE WHEN name = 'trueforge-sandbox-env' THEN name END)
) AS name
FROM sandbox_environment
WHERE lifecycle_stage = 'active'
GROUP BY tenant_id
) AS pin
WHERE pin.tenant_id = agent.tenant_id
AND pin.name IS NOT NULL
AND json_extract(agent.manifest, '$.config.sandbox.enabled') IN (1, 'true')
AND nullif(json_extract(agent.manifest, '$.config.sandbox.environment_name'), '') IS NULL
`.execute(trx);

await sql`
UPDATE session
SET agent_spec = jsonb_set(
agent_spec,
'$.config.sandbox.environment_name',
jsonb(json_quote(pin.name))
)
FROM (
SELECT
tenant_id,
COALESCE(
MAX(CASE WHEN is_default = 1 THEN name END),
MAX(CASE WHEN name = 'trueforge-sandbox-env' THEN name END)
) AS name
FROM sandbox_environment
WHERE lifecycle_stage = 'active'
GROUP BY tenant_id
) AS pin
WHERE pin.tenant_id = session.tenant_id
AND pin.name IS NOT NULL
AND session.agent_spec IS NOT NULL
AND json_extract(session.agent_spec, '$.config.sandbox.enabled') IN (1, 'true')
AND nullif(json_extract(session.agent_spec, '$.config.sandbox.environment_name'), '') IS NULL
`.execute(trx);
});
}

/** Irreversible: backfilled names are indistinguishable from user-pinned ones. */
export function down(db: Kysely<unknown>): Promise<void> {
void db;
return Promise.reject(new Error('20261116_000001_sandbox_environment_name_backfill is irreversible'));
}
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ class SandboxConfig(UncheckedBaseModel):

environment_name: typing.Optional[str] = pydantic.Field(default=None)
"""
Name of a configured sandbox environment to use. Must exist when set.
Name of a configured sandbox environment to use. Required when sandbox is enabled and the provider supports environments.
"""

file_downloads: typing.Optional[bool] = pydantic.Field(default=True)
Expand Down
Loading