diff --git a/.changeset/20261116143735-regenerate-sdk-from-openapi.md b/.changeset/20261116143735-regenerate-sdk-from-openapi.md new file mode 100644 index 000000000..efd8ff00f --- /dev/null +++ b/.changeset/20261116143735-regenerate-sdk-from-openapi.md @@ -0,0 +1,5 @@ +--- +"@truefoundry/trueforge-sdk": patch +--- + +Regenerate SDK from updated OpenAPI spec. diff --git a/.changeset/sandbox-environment-name-backfill.md b/.changeset/sandbox-environment-name-backfill.md new file mode 100644 index 000000000..237bb546b --- /dev/null +++ b/.changeset/sandbox-environment-name-backfill.md @@ -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. diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json index 6399bf97d..d325015ba 100644 --- a/.github/fern/openapi/openapi.json +++ b/.github/fern/openapi/openapi.json @@ -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" }, diff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdx index 227c52518..1cb376a40 100644 --- a/docs/create-agent/overview.mdx +++ b/docs/create-agent/overview.mdx @@ -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 }, @@ -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` diff --git a/docs/openapi.json b/docs/openapi.json index 6399bf97d..d325015ba 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -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" }, diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx index b59b85371..cd8474984 100644 --- a/docs/sandbox.mdx +++ b/docs/sandbox.mdx @@ -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" } } diff --git a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts index 6ee3ab99a..c3a46e736 100644 --- a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts +++ b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts @@ -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'); diff --git a/packages/trueforge-sdk/src/api/types/SandboxConfig.ts b/packages/trueforge-sdk/src/api/types/SandboxConfig.ts index aa7a0b848..81b5f4b5f 100644 --- a/packages/trueforge-sdk/src/api/types/SandboxConfig.ts +++ b/packages/trueforge-sdk/src/api/types/SandboxConfig.ts @@ -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; diff --git a/packages/trueforge/src/db/postgres/migrations/20261116_000001_sandbox_environment_name_backfill.ts b/packages/trueforge/src/db/postgres/migrations/20261116_000001_sandbox_environment_name_backfill.ts new file mode 100644 index 000000000..9087f76ab --- /dev/null +++ b/packages/trueforge/src/db/postgres/migrations/20261116_000001_sandbox_environment_name_backfill.ts @@ -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): Promise { + 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' + GROUP BY tenant_id + ) 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); + + 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): Promise { + void db; + return Promise.reject(new Error('20261116_000001_sandbox_environment_name_backfill is irreversible')); +} diff --git a/packages/trueforge/src/db/sqlite/migrations/20261116_000001_sandbox_environment_name_backfill.ts b/packages/trueforge/src/db/sqlite/migrations/20261116_000001_sandbox_environment_name_backfill.ts new file mode 100644 index 000000000..0ec9642c1 --- /dev/null +++ b/packages/trueforge/src/db/sqlite/migrations/20261116_000001_sandbox_environment_name_backfill.ts @@ -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): Promise { + 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): Promise { + void db; + return Promise.reject(new Error('20261116_000001_sandbox_environment_name_backfill is irreversible')); +} diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_config.py b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_config.py index a4e9e4589..cd102f47a 100644 --- a/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_config.py +++ b/python/trueforge_sdk/src/trueforge_sdk/types/sandbox_config.py @@ -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)