Skip to content

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

Update readme and script for syncing sandbox (#115)

Chirag Jaina325c0a7290e
diff --git a/README.md b/README.md
index 5f404d551..84a517112 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
# TrueForge
-**The open-source agent harness — the runtime layer that turns an LLM into a working agent.**
+**The open-source agent harness - the runtime layer that turns an LLM into a working agent.**
-TrueForge runs the agent execution loop for you — model calls, tool use, context management, and session state — and exposes the result three ways: a chat UI, an HTTP API, and a TypeScript library.
+TrueForge runs the agent execution loop for you - model calls, tool use, context management, and session state - and exposes the result three ways: a chat UI, an HTTP API, and a TypeScript library.
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js >= 22.13](https://img.shields.io/badge/Node.js-%3E%3D22.13-green.svg)](https://nodejs.org)
@@ -11,20 +11,20 @@ TrueForge runs the agent execution loop for you — model calls, tool use, conte
[Documentation](#) · [Quickstart Guide](#) · [API Reference](#) · [Community](#)
-![TrueForge chat UI](docs/assets/hero.png)
+![TrueForge Chat UI](./docs/assets/hero.png)
## Why TrueForge?
-Building an agent is easy. Running one in production is not — you need streaming, session persistence, tool servers, sandboxing, approvals, and a UI. TrueForge gives you all of that out of the box:
+Building an agent is easy. Running one in production is not - you need streaming, session persistence, tool servers, sandboxing, approvals, and a UI. TrueForge gives you all of that out of the box:
-- **Multi-turn sessions with streaming** — resumable turn streams that survive reconnects and server restarts.
-- **MCP tool servers** — connect any [Model Context Protocol](https://modelcontextprotocol.io) server, including ones that require OAuth.
-- **Any model provider** — OpenAI, Anthropic, Google Gemini, and a catalog of hosted and open-weight models, or any OpenAI-compatible endpoint — all configured from the UI or the API.
-- **Skills** — reusable instruction packs the agent loads on demand.
-- **Sandboxed code execution** — run agent-generated code in isolated sandboxes.
-- **Human-in-the-loop approvals** — pause the agent and wait for a person before sensitive tool calls.
-- **Subagents** — agents that delegate work to other agents.
-- **Chat UI, HTTP API, and TypeScript library** — use whichever surface fits your product.
+- **Multi-turn sessions with streaming** - resumable turn streams that survive reconnects and server restarts.
+- **MCP tool servers** - connect any [Model Context Protocol](https://modelcontextprotocol.io) server, including ones that require OAuth.
+- **Any model provider** - OpenAI, Anthropic, Google Gemini, and a catalog of hosted and open-weight models, or any OpenAI-compatible endpoint - all configured from the UI or the API.
+- **Skills** - reusable instruction packs the agent loads on demand.
+- **Sandboxed code execution** - run agent-generated code in isolated sandboxes.
+- **Human-in-the-loop approvals** - pause the agent and wait for a person before sensitive tool calls.
+- **Subagents** - agents that delegate work to other agents.
+- **Chat UI, HTTP API, and TypeScript library** - use whichever surface fits your product.
It scales down and up: run it as a single process backed by SQLite, or run multiple replicas backed by Postgres and Redis.
@@ -32,7 +32,11 @@ It scales down and up: run it as a single process backed by SQLite, or run multi
### Option 1: npx (fastest)
-Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure — data is stored in a local SQLite file:
+<!-- TODO: remote this note after packages are published -->
+
+> Note: This option will be available when packages are published to NPM. Please use Option 2
+
+Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure - data is stored in a local SQLite file:
```bash
npx @truefoundry/trueforge
@@ -42,23 +46,24 @@ Then open [http://localhost:8790](http://localhost:8790), add a model provider u
### Option 2: From source (pnpm)
-Runs the standalone (SQLite) topology from a clone of this repo — no Docker, no Postgres, no Redis. Requires [Node.js](https://nodejs.org) 22.13+ and [pnpm](https://pnpm.io) (`corepack enable` installs the pinned version):
+Runs the standalone (SQLite) topology from a clone of this repo — no Docker, no Postgres, no Redis. Requires [Node.js](https://nodejs.org) 22.13+ and [pnpm](https://pnpm.io)
```bash
-git clone <REPO_URL> trueforge && cd trueforge # TODO: repo URL
-pnpm install
+git clone https://github.com/truefoundry/trueforge.git
+cd trueforge
cp packages/server/.env.example packages/server/.env
pnpm standalone:dev
```
-Then open [http://localhost:3000](http://localhost:3000) — Vite serves the UI with live reload and proxies API calls to the server on port 8790. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide, including the Postgres + Redis dev topology.
+Then open [http://localhost:3000](http://localhost:3000) - Vite serves the UI with live reload and proxies API calls to the server on port 8790. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide, including the Postgres + Redis dev topology.
### Option 3: Docker Compose
Runs the full production topology on your machine: the server (UI + API), Postgres, and Redis. Clone the repo first:
```bash
-git clone https://github.com/truefoundry/trueforge.git trueforge && cd trueforge
+git clone https://github.com/truefoundry/trueforge.git
+cd trueforge
cp packages/server/.env.example packages/server/.env
docker compose up --build
```
@@ -69,7 +74,7 @@ Then open [http://localhost:8791](http://localhost:8791).
| ----------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------- |
| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | `harness` (from `.env`) | Postgres credentials, read from `packages/server/.env`. |
| `PUBLIC_BASE_URL` | `http://localhost:8791` | Public origin, used for MCP OAuth callbacks. |
-| Host ports | `8791`, `5433`, `6380` | App, Postgres, and Redis — offset so they don't clash with local dev. |
+| Host ports | `8791`, `5433`, `6380` | App, Postgres, and Redis - offset so they don't clash with local dev. |
| `OIDC_ISSUER_URL` / `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` | unset | Optional: connect an identity provider. Unset = local admin identity. |
Every environment variable is documented in [`packages/server/.env.example`](packages/server/.env.example).
@@ -78,8 +83,9 @@ Every environment variable is documented in [`packages/server/.env.example`](pac
The [`charts/truefoundry-utils`](charts/truefoundry-utils) Helm chart deploys the server in distributed mode (`STANDALONE=false`) with bundled Postgres and Redis (or point it at your own). No values are required for a basic install:
+<!-- TODO: replace <HELM_REPO> with the published Helm repo URL -->
+
```bash
-# TODO: replace <HELM_REPO> with the published Helm repo URL
helm install truefoundry-utils oci://<HELM_REPO>/truefoundry-utils \
--version <x.y.z>
```
@@ -94,25 +100,42 @@ helm install truefoundry-utils oci://<HELM_REPO>/truefoundry-utils \
See the [chart README](charts/truefoundry-utils/README.md) for Secrets, external databases, ingress via `extraObjects`, and the full values reference.
-## Getting started walkthrough
+## Getting Started Walkthrough
+
+1. **Add a model provider** - Open **Settings → Models**, pick a provider from the catalog, and paste your API key.
+
+ ![Configure a model provider](./docs/assets/getting-started-provider.png)
+
+2. **(Optional) Connect tools** - Add MCP servers, skills, and a sandbox provider under **Settings**.
+
+ ![Connectors](./docs/assets/getting-started-connectors.png)
+
+3. **(Optional) Configure Sandbox** - Open **Settings → Sandbox Providers** and configure Daytona.
+
+ Sign up with [Daytona](https://app.daytona.io/) and create an API Key with permissions to write, delete snapshots and write sandboxes
+
+ ![Daytona API Key](./docs/assets/daytona-api-key.png)
-1. **Add a model provider** — open **Settings → Models**, pick a provider from the catalog, and paste your API key.
+ Sync the sandbox image to Daytona
- ![Configure a model provider](docs/assets/getting-started-provider.png)
+ ```bash
+ export DAYTONA_API_KEY="dtn_your-daytona-api-key-..."
+ pnpm push-sandbox-image-to-daytona --image docker.io/truefoundrycloud/truefoundry-utils-core-sandbox:029ea5ff6438cf86b79282e087bfc17528067946 --name trueforge-sandbox-image
+ ```
-2. **(Optional) Connect tools** — add MCP servers, skills, and a sandbox provider under **Settings**.
+ On UI, select the Daytona sandbox provider and enter your Daytona API Key and the name of the snapshot you created above
- ![Connectors](docs/assets/getting-started-connectors.png)
+ ![Daytona Sandbox Provider](./docs/assets/getting-started-sandbox-provider.png)
-3. **Start a session** — create a chat and talk to your agent. Streaming, tool calls, and approvals all show up live in the UI.
+4. **Start a session** - Create a chat and talk to your agent. Streaming, tool calls, and approvals all show up live in the UI.
- ![Chat with the agent](docs/assets/getting-started-chat.png)
+ ![Chat with the agent](./docs/assets/getting-started-chat.png)
Interactive API docs are served by your running instance at `/api/v1/docs`. For everything else, see the [documentation](#). <!-- TODO: docs link -->
## Components
-TrueForge is a single container image (or `npx` process) plus a database — and Redis when you run more than one replica.
+TrueForge is a single container image (or `npx` process) plus a database - and Redis when you run more than one replica.
```mermaid
flowchart LR
@@ -165,7 +188,7 @@ flowchart LR
## Contributing
-We love contributions! Whether it's a bug report, a new feature, or a docs fix — see [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development environment and open a pull request. Please also read our [Code of Conduct](CODE_OF_CONDUCT.md).
+We love contributions! Whether it's a bug report, a new feature, or a docs fix - see [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development environment and open a pull request. Please also read our [Code of Conduct](CODE_OF_CONDUCT.md).
To report a security vulnerability, please follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
diff --git a/docs/assets/daytona-api-key.png b/docs/assets/daytona-api-key.png
new file mode 100644
index 000000000..4ea60bf0e
Binary files /dev/null and b/docs/assets/daytona-api-key.png differ
diff --git a/docs/assets/getting-started-sandbox-provider.png b/docs/assets/getting-started-sandbox-provider.png
new file mode 100644
index 000000000..c43c96eb0
Binary files /dev/null and b/docs/assets/getting-started-sandbox-provider.png differ
diff --git a/package.json b/package.json
index 455fd8ff6..2c1d7ce17 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,10 @@
},
"scripts": {
"build": "pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/trueforge-ui build && pnpm --filter frontend build && pnpm --filter @truefoundry/utils build",
+ "chart:deps": "helm dependency build charts/truefoundry-utils",
+ "chart:lint": "helm lint charts/truefoundry-utils --values charts/truefoundry-utils/ci/lint-values.yaml",
+ "chart:package": "helm package charts/truefoundry-utils --destination dist",
+ "chart:template": "helm template truefoundry-utils charts/truefoundry-utils --values charts/truefoundry-utils/ci/lint-values.yaml",
"clean:all": "node scripts/clean.mjs --dependencies",
"clean": "node scripts/clean.mjs",
"dev:infra": "docker compose -f docker-compose.dev.yml up",
@@ -29,13 +33,10 @@
"standalone:dev": "STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/utils --filter frontend dev",
"standalone:start": "STANDALONE=true NODE_ENV=production pnpm --filter @truefoundry/utils start",
"start": "STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/utils start",
+ "push-sandbox-image-to-daytona": "pnpm --filter @truefoundry/utils push-sandbox-image-to-daytona",
"test:store:local": "bash scripts/test-store-local.sh",
"test": "pnpm --filter @truefoundry/utils-core test && pnpm --filter @truefoundry/trueforge-ui test && pnpm --filter @truefoundry/utils test && pnpm --filter frontend test",
- "typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/trueforge-ui typecheck && pnpm --filter @truefoundry/utils typecheck && pnpm --filter frontend typecheck",
- "chart:deps": "helm dependency build charts/truefoundry-utils",
- "chart:lint": "helm lint charts/truefoundry-utils --values charts/truefoundry-utils/ci/lint-values.yaml",
- "chart:template": "helm template truefoundry-utils charts/truefoundry-utils --values charts/truefoundry-utils/ci/lint-values.yaml",
- "chart:package": "helm package charts/truefoundry-utils --destination dist"
+ "typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/trueforge-ui typecheck && pnpm --filter @truefoundry/utils typecheck && pnpm --filter frontend typecheck"
},
"devDependencies": {
"@eslint-react/eslint-plugin": "^5.18.0",
diff --git a/packages/harness/scripts/sandbox/create-daytona-snapshot.mjs b/packages/harness/scripts/sandbox/create-daytona-snapshot.mjs
deleted file mode 100644
index 902732225..000000000
--- a/packages/harness/scripts/sandbox/create-daytona-snapshot.mjs
+++ /dev/null
@@ -1,53 +0,0 @@
-#!/usr/bin/env node
-import { Daytona } from '@daytona/sdk';
-import { parseArgs } from 'node:util';
-
-function printUsage() {
- console.log(`Usage:
- node create-daytona-snapshot.mjs --image <image> --name <name>
-
-Options:
- --image <string> Container image to snapshot
- --name <string> Daytona snapshot name
- -h, --help Show this help
-`);
-}
-
-const { values } = parseArgs({
- args: process.argv.slice(2),
- options: {
- image: { type: 'string' },
- name: { type: 'string' },
- help: { type: 'boolean', short: 'h', default: false },
- },
- allowPositionals: false,
- strict: true,
-});
-
-if (values.help) {
- printUsage();
- process.exit(0);
-}
-
-if (values.image === undefined || values.name === undefined) {
- console.error('Error: --image and --name are required');
- printUsage();
- process.exit(1);
-}
-
-const image = values.image;
-const name = values.name;
-
-console.log(`image=${image}`);
-console.log(`name=${name}`);
-
-const daytona = new Daytona({
- apiKey: process.env.DAYTONA_API_KEY,
-});
-
-const snapshot = await daytona.snapshot.create({
- name,
- image,
-});
-
-console.log(`Snapshot created: ${snapshot.id}`);
diff --git a/packages/server/package.json b/packages/server/package.json
index bc766c5df..055044f0f 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -20,6 +20,7 @@
"dev": "pnpm run \"/^(build:gen:watch|dev:serve)$/\"",
"dev:no-watch": "NODE_OPTIONS='--conditions=development' NODE_ENV=development tsx --env-file=.env src/main.ts",
"start": "NODE_ENV=production node --env-file=.env dist/main.js",
+ "push-sandbox-image-to-daytona": "node scripts/push-sandbox-image-to-daytona.mjs",
"migrate": "NODE_OPTIONS='--conditions=development' STANDALONE=false tsx --env-file=.env src/db/postgres/migrate-cli.ts",
"openapi:write": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' tsx --env-file=.env.test scripts/write-openapi.ts",
"pack:dry": "pnpm pack --dry-run",
diff --git a/packages/server/scripts/push-sandbox-image-to-daytona.mjs b/packages/server/scripts/push-sandbox-image-to-daytona.mjs
new file mode 100644
index 000000000..eca1e0dde
--- /dev/null
+++ b/packages/server/scripts/push-sandbox-image-to-daytona.mjs
@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { Daytona, DaytonaNotFoundError } from '@daytona/sdk';
+import { setTimeout as delay } from 'node:timers/promises';
+import { parseArgs } from 'node:util';
+
+const POLL_INTERVAL_MS = 3_000;
+const DELETE_TIMEOUT_MS = 5 * 60 * 1_000;
+const CREATE_TIMEOUT_SECONDS = 5 * 60;
+
+function printUsage() {
+ console.log(`Usage:
+ pnpm push-sandbox-image-to-daytona -- --image <image> --name <name> [--force]
+
+Options:
+ --image <string> Container image to snapshot
+ --name <string> Daytona snapshot name
+ --force Delete an existing snapshot, wait for removal, then recreate
+ -h, --help Show this help
+
+Requires DAYTONA_API_KEY in the environment.
+`);
+}
+
+const { values } = parseArgs({
+ args: process.argv.slice(2).filter(arg => arg !== '--'),
+ options: {
+ image: { type: 'string' },
+ name: { type: 'string' },
+ force: { type: 'boolean', default: false },
+ help: { type: 'boolean', short: 'h', default: false },
+ },
+ allowPositionals: false,
+ strict: true,
+});
+
+if (values.help) {
+ printUsage();
+ process.exit(0);
+}
+
+if (values.image === undefined || values.name === undefined) {
+ console.error('Error: --image and --name are required');
+ printUsage();
+ process.exit(1);
+}
+
+const apiKey = process.env.DAYTONA_API_KEY;
+if (apiKey === undefined || apiKey === '') {
+ console.error('Error: DAYTONA_API_KEY is required');
+ process.exit(1);
+}
+
+const image = values.image;
+const name = values.name;
+const force = values.force;
+
+console.log(`image=${image}`);
+console.log(`name=${name}`);
+console.log(`force=${String(force)}`);
+
+const daytona = new Daytona({
+ apiKey,
+});
+
+let existing = null;
+try {
+ existing = await daytona.snapshot.get(name);
+} catch (error) {
+ if (!(error instanceof DaytonaNotFoundError)) {
+ throw error;
+ }
+}
+
+if (existing !== null) {
+ console.log(`Snapshot already exists: id=${existing.id} state=${existing.state}`);
+ if (!force) {
+ console.log('Pass --force to delete it and recreate.');
+ process.exit(0);
+ }
+
+ console.log('Deleting existing snapshot…');
+ console.log('Press Ctrl+C to cancel.');
+ await daytona.snapshot.delete(existing);
+
+ const deadline = Date.now() + DELETE_TIMEOUT_MS;
+ for (;;) {
+ if (Date.now() >= deadline) {
+ console.error(
+ `Timed out after 5 minutes waiting for snapshot "${name}" to be deleted. It may still be removing in Daytona.`,
+ );
+ process.exit(1);
+ }
+
+ await delay(POLL_INTERVAL_MS);
+
+ try {
+ const current = await daytona.snapshot.get(name);
+ console.log(`delete state=${current.state}`);
+ } catch (error) {
+ if (error instanceof DaytonaNotFoundError) {
+ console.log('Snapshot deleted.');
+ break;
+ }
+ throw error;
+ }
+ }
+}
+
+console.log('Press Ctrl+C to cancel.');
+
+const snapshot = await daytona.snapshot.create(
+ {
+ name,
+ image,
+ },
+ {
+ onLogs: console.log,
+ timeout: CREATE_TIMEOUT_SECONDS,
+ },
+);
+
+console.log(`Snapshot created: ${snapshot.id}`);
diff --git a/packages/server/src/catalog/sandbox-catalog.yaml b/packages/server/src/catalog/sandbox-catalog.yaml
index 404e243e8..716c31734 100644
--- a/packages/server/src/catalog/sandbox-catalog.yaml
+++ b/packages/server/src/catalog/sandbox-catalog.yaml
@@ -3,7 +3,7 @@
# PUT /api/v1/settings/sandbox-providers bodies. Discovery-only — never executed against.
providers:
- type: daytona
- snapshot_name: trueforge-local
+ snapshot_name: trueforge-sandbox-image
exec_timeout_ms: 60000
auto_stop_interval_in_minutes: 5
auto_archive_interval_in_minutes: 60
diff --git a/packages/server/tests/db/sandboxProviderStoreContractSuite.ts b/packages/server/tests/db/sandboxProviderStoreContractSuite.ts
index ff6f52e67..1dd9e560f 100644
--- a/packages/server/tests/db/sandboxProviderStoreContractSuite.ts
+++ b/packages/server/tests/db/sandboxProviderStoreContractSuite.ts
@@ -10,7 +10,7 @@ const TENANT = 'default';
function manifest(overrides: Partial<SandboxProviderManifest> = {}): SandboxProviderManifest {
return {
type: 'daytona',
- snapshot_name: 'trueforge-local',
+ snapshot_name: 'trueforge-sandbox-image',
auth: { api_key: 'dtn-test' },
exec_timeout_ms: 60000,
auto_stop_interval_in_minutes: 5,
@@ -75,7 +75,7 @@ export function runSandboxProviderStoreContractSuite(getStore: () => ISandboxPro
const forDefault = await store.getSandboxProvider(TENANT);
const forOther = await store.getSandboxProvider('other-tenant');
- expect(forDefault?.manifest.snapshot_name).toBe('trueforge-local');
+ expect(forDefault?.manifest.snapshot_name).toBe('trueforge-sandbox-image');
expect(forOther?.manifest.snapshot_name).toBe('other-tenant-snapshot');
});
}
diff --git a/packages/server/tests/unit/apis/capabilities.test.ts b/packages/server/tests/unit/apis/capabilities.test.ts
index 5c4a067df..400c66431 100644
--- a/packages/server/tests/unit/apis/capabilities.test.ts
+++ b/packages/server/tests/unit/apis/capabilities.test.ts
@@ -66,7 +66,7 @@ describe('capabilities routers', () => {
tenant_id: 'default',
manifest: {
type: 'daytona',
- snapshot_name: 'trueforge-local',
+ snapshot_name: 'trueforge-sandbox-image',
auth: { api_key: 'dtn-test' },
exec_timeout_ms: 60000,
auto_stop_interval_in_minutes: 5,
@@ -159,13 +159,31 @@ describe('capabilities routers', () => {
headers: { Cookie: `id_token=${await createIdToken(['admin'])}` },
});
expect(adminRes.status).toBe(200);
- expect((await adminRes.json()).data.settings).toEqual({ enabled: true });
+ expect(await adminRes.json()).toEqual({
+ data: {
+ sandbox: { enabled: false },
+ skill: {
+ enabled: false,
+ reason: 'Skills run in a sandbox, which is not configured.',
+ },
+ settings: { enabled: true },
+ },
+ });
const userRes = await router.request('/', {
headers: { Cookie: `id_token=${await createIdToken(['everyone'])}` },
});
expect(userRes.status).toBe(200);
- expect((await userRes.json()).data.settings).toEqual({ enabled: false });
+ expect(await userRes.json()).toEqual({
+ data: {
+ sandbox: { enabled: false },
+ skill: {
+ enabled: false,
+ reason: 'Skills run in a sandbox, which is not configured.',
+ },
+ settings: { enabled: false },
+ },
+ });
});
});
});
diff --git a/packages/server/tests/unit/apis/sandboxProviders.test.ts b/packages/server/tests/unit/apis/sandboxProviders.test.ts
index bfc496815..32f3ee538 100644
--- a/packages/server/tests/unit/apis/sandboxProviders.test.ts
+++ b/packages/server/tests/unit/apis/sandboxProviders.test.ts
@@ -6,7 +6,7 @@ import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provi
const putBody = {
type: 'daytona' as const,
- snapshot_name: 'trueforge-local',
+ snapshot_name: 'trueforge-sandbox-image',
auth: { api_key: 'dtn-test' },
exec_timeout_ms: 60000,
auto_stop_interval_in_minutes: 5,
diff --git a/packages/server/tests/unit/schemas/sandboxProvider.test.ts b/packages/server/tests/unit/schemas/sandboxProvider.test.ts
index 3a61bbba8..291332f48 100644
--- a/packages/server/tests/unit/schemas/sandboxProvider.test.ts
+++ b/packages/server/tests/unit/schemas/sandboxProvider.test.ts
@@ -4,7 +4,7 @@ describe('toDaytonaSandboxProviderInput', () => {
it('maps a Daytona wire/DB manifest to apiKey plus provider settings', () => {
const manifest: SandboxProviderManifest = {
type: 'daytona',
- snapshot_name: 'trueforge-local',
+ snapshot_name: 'trueforge-sandbox-image',
auth: { api_key: 'dtn-test' },
exec_timeout_ms: 60_000,
auto_stop_interval_in_minutes: 5,
@@ -14,7 +14,7 @@ describe('toDaytonaSandboxProviderInput', () => {
expect(toDaytonaSandboxProviderInput(manifest)).toEqual({
apiKey: 'dtn-test',
- snapshotName: 'trueforge-local',
+ snapshotName: 'trueforge-sandbox-image',
timeoutMs: 60_000,
autoStopIntervalInMinutes: 5,
autoArchiveIntervalInMinutes: 60,
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/DraftReasoningEffortSelector.tsx b/packages/trueforge-ui-sdk/src/atoms/draft/DraftReasoningEffortSelector.tsx
index a1cff23e3..bb52a733a 100644
--- a/packages/trueforge-ui-sdk/src/atoms/draft/DraftReasoningEffortSelector.tsx
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/DraftReasoningEffortSelector.tsx
@@ -31,6 +31,7 @@ export function DraftReasoningEffortSelector({ disabled, isRunning }: DraftReaso
const updateAgentSpec = useTrueFoundryUpdateAgentSpec();
const [open, setOpen] = useState(false);
const containerRef = useRef<HTMLDivElement>(null);
+ const clearedStickyEffortForModelRef = useRef<string | null>(null);
const menuId = useId();
const isMobile = useIsMobile();
const compactLayout = useCompactLayout();
@@ -58,6 +59,22 @@ export function DraftReasoningEffortSelector({ disabled, isRunning }: DraftReaso
return () => document.removeEventListener('mousedown', handler);
}, [open]);
+ // Heal sticky effort left by mergeAgentSpec when the selected model has none.
+ useEffect(() => {
+ if (!updateAgentSpec || selected === undefined) return;
+ if (hasReasoningEfforts(efforts)) {
+ clearedStickyEffortForModelRef.current = null;
+ return;
+ }
+ if (currentEffort === undefined) return;
+ const modelKey = modelValue(selected);
+ if (clearedStickyEffortForModelRef.current === modelKey) return;
+ clearedStickyEffortForModelRef.current = modelKey;
+ updateAgentSpec({
+ model: modelPatchWithReasoningEffort(modelKey, agentSpec?.model?.params, undefined),
+ });
+ }, [updateAgentSpec, selected, efforts, currentEffort, agentSpec?.model?.params]);
+
if (!hasReasoningEfforts(efforts) || !resolved) return null;
const content = (
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.ts b/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.ts
index 8bd00625d..15346aecd 100644
--- a/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.ts
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.ts
@@ -14,7 +14,14 @@ export function resolveReasoningEffort(
return efforts[0];
}
-/** Draft model patch: preserve other params, set or clear `reasoningEffort`. */
+/**
+ * Draft model patch: preserve other params, set or clear `reasoningEffort`.
+ *
+ * When clearing, set `reasoningEffort: undefined` (do not omit the key).
+ * `mergeAgentSpec` in `@truefoundry/assistant-ui-runtime` shallow-merges
+ * `model.params`, so omitting the key leaves a sticky prior effort and the
+ * server then 422s on models that do not advertise `reasoning_efforts`.
+ */
export function modelPatchWithReasoningEffort(
name: string,
existingParams: ModelParams | undefined,
@@ -24,7 +31,7 @@ export function modelPatchWithReasoningEffort(
if (nextEffort === undefined) {
if (!existingParams) return { name };
const { reasoningEffort: _cleared, ...rest } = existingParams;
- return Object.keys(rest).length > 0 ? { name, params: rest } : { name };
+ return { name, params: { ...rest, reasoningEffort: undefined } };
}
return {
name,
diff --git a/packages/trueforge-ui-sdk/test/atoms/AgentsLibrary.test.tsx b/packages/trueforge-ui-sdk/test/atoms/AgentsLibrary.test.tsx
index cc94d357c..005f37e57 100644
--- a/packages/trueforge-ui-sdk/test/atoms/AgentsLibrary.test.tsx
+++ b/packages/trueforge-ui-sdk/test/atoms/AgentsLibrary.test.tsx
@@ -210,8 +210,11 @@ describe('AgentsLibraryButton', () => {
it('re-fetches the agent count when agentsListEpoch bumps', async () => {
const searchAgents = vi
.fn()
- .mockResolvedValueOnce([{ name: 'alpha' }])
- .mockResolvedValueOnce([{ name: 'alpha' }, { name: 'beta' }]);
+ .mockResolvedValueOnce([{ name: 'alpha', agentId: 'alpha' }])
+ .mockResolvedValueOnce([
+ { name: 'alpha', agentId: 'alpha' },
+ { name: 'beta', agentId: 'beta' },
+ ]);
const server = createMockAgentUIServer({ searchAgents });
function Invalidate() {
@@ -247,7 +250,10 @@ describe('AgentsLibraryButton', () => {
});
it('shows 50+ when the first page is full', async () => {
- const agents = Array.from({ length: 50 }, (_, i) => ({ name: `agent-${i}` }));
+ const agents = Array.from({ length: 50 }, (_, i) => ({
+ name: `agent-${i}`,
+ agentId: `agent-${i}`,
+ }));
const server = mockServer(agents);
render(
diff --git a/packages/trueforge-ui-sdk/test/atoms/draft/DraftModelSelector.test.tsx b/packages/trueforge-ui-sdk/test/atoms/draft/DraftModelSelector.test.tsx
index 50c213997..ad932f72d 100644
--- a/packages/trueforge-ui-sdk/test/atoms/draft/DraftModelSelector.test.tsx
+++ b/packages/trueforge-ui-sdk/test/atoms/draft/DraftModelSelector.test.tsx
@@ -98,6 +98,28 @@ describe('DraftModelSelector', () => {
expect(trigger).toHaveAttribute('aria-expanded', 'false');
});
+ it('clears sticky reasoningEffort when switching to a model without efforts', async () => {
+ agentSpec = {
+ model: {
+ name: 'anthropic/claude-3.7-sonnet',
+ params: { maxTokens: 512, reasoningEffort: 'high' },
+ },
+ };
+ renderSelector();
+
+ const trigger = await screen.findByTitle('Select model');
+ await waitFor(() => expect(trigger).toHaveTextContent('claude-3.7-sonnet'));
+ fireEvent.click(trigger);
+ fireEvent.click(screen.getByRole('option', { name: /gpt-4.1/i }));
+
+ expect(updateAgentSpec).toHaveBeenCalledWith({
+ model: {
+ name: 'openai/gpt-4.1',
+ params: { maxTokens: 512, reasoningEffort: undefined },
+ },
+ });
+ });
+
it('uses the first catalog model when the runtime has no draft spec', async () => {
agentSpec = undefined;
renderSelector();
diff --git a/packages/trueforge-ui-sdk/test/atoms/draft/reasoningEffort.test.ts b/packages/trueforge-ui-sdk/test/atoms/draft/reasoningEffort.test.ts
index bdbbcc739..547ce5c49 100644
--- a/packages/trueforge-ui-sdk/test/atoms/draft/reasoningEffort.test.ts
+++ b/packages/trueforge-ui-sdk/test/atoms/draft/reasoningEffort.test.ts
@@ -47,9 +47,15 @@ describe('modelPatchWithReasoningEffort', () => {
params: { maxTokens: 100, reasoningEffort: 'low' },
});
+ // `undefined` must be present so mergeAgentSpec overwrites a sticky effort.
expect(modelPatchWithReasoningEffort('m', { maxTokens: 100, reasoningEffort: 'high' }, [])).toEqual({
name: 'm',
- params: { maxTokens: 100 },
+ params: { maxTokens: 100, reasoningEffort: undefined },
+ });
+
+ expect(modelPatchWithReasoningEffort('m', { reasoningEffort: 'high' }, undefined)).toEqual({
+ name: 'm',
+ params: { reasoningEffort: undefined },
});
});
});
diff --git a/packages/trueforge-ui-sdk/test/atoms/lib/useSearchAgentsList.test.tsx b/packages/trueforge-ui-sdk/test/atoms/lib/useSearchAgentsList.test.tsx
index 956500a73..9951775ae 100644
--- a/packages/trueforge-ui-sdk/test/atoms/lib/useSearchAgentsList.test.tsx
+++ b/packages/trueforge-ui-sdk/test/atoms/lib/useSearchAgentsList.test.tsx
@@ -20,8 +20,11 @@ describe('useSearchAgentsList', () => {
});
it('fetches the first page when enabled and paginates via loadMore sentinel', async () => {
- const page1 = Array.from({ length: SEARCH_AGENTS_PAGE_SIZE }, (_, i) => ({ name: `agent-${i}` }));
- const page2 = [{ name: 'agent-extra' }];
+ const page1 = Array.from({ length: SEARCH_AGENTS_PAGE_SIZE }, (_, i) => ({
+ name: `agent-${i}`,
+ agentId: `agent-${i}`,
+ }));
+ const page2 = [{ name: 'agent-extra', agentId: 'agent-extra' }];
const searchAgents = vi.fn().mockResolvedValueOnce(page1).mockResolvedValueOnce(page2);
const server = createMockAgentUIServer({ searchAgents });
@@ -80,7 +83,9 @@ describe('useSearchAgentsList', () => {
it('debounces query changes before re-fetching', async () => {
vi.useFakeTimers();
- const searchAgents = vi.fn(async ({ query }: { query?: string } = {}) => [{ name: query ?? 'all' }]);
+ const searchAgents = vi.fn(async ({ query }: { query?: string } = {}) => [
+ { name: query ?? 'all', agentId: query ?? 'all' },
+ ]);
const server = createMockAgentUIServer({ searchAgents });
const { result, rerender } = renderHook(
@@ -105,6 +110,6 @@ describe('useSearchAgentsList', () => {
});
expect(searchAgents).toHaveBeenCalledTimes(2);
expect(searchAgents).toHaveBeenLastCalledWith({ query: 'alpha', limit: SEARCH_AGENTS_PAGE_SIZE, offset: 0 });
- expect(result.current.agents).toEqual([{ name: 'alpha' } satisfies AgentLibraryEntry]);
+ expect(result.current.agents).toEqual([{ name: 'alpha', agentId: 'alpha' } satisfies AgentLibraryEntry]);
});
});