Skip to content

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

Refactor release workflow according to official changeset example (#266)

Chirag Jaina6bd7d383b58
diff --git a/.changeset/vast-meteors-boil.md b/.changeset/20260814092239-wrap-settings-bodies-as-manifest.md
similarity index 100%
rename from .changeset/vast-meteors-boil.md
rename to .changeset/20260814092239-wrap-settings-bodies-as-manifest.md
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 546313934..83b84191d 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -16,5 +16,5 @@ Closes #
- [ ] `pnpm build`, `pnpm test`, `pnpm typecheck`, `pnpm lint:ci`, and `pnpm format:check` pass locally
- [ ] Tests added/updated where it makes sense
-- [ ] No hand-edits to generated code (`packages/sdk`, `.github/fern/openapi/openapi.json`)
+- [ ] No hand-edits to generated code (`packages/sdk`, `.github/fern/openapi/openapi.json`, `docs/openapi.json`)
- [ ] Docs / `.env.example` updated if configuration or behavior changed
diff --git a/.github/workflows/generate-sdk.yaml b/.github/workflows/generate-sdk.yaml
index 17a3bc465..d35893f39 100644
--- a/.github/workflows/generate-sdk.yaml
+++ b/.github/workflows/generate-sdk.yaml
@@ -87,7 +87,7 @@ jobs:
set -euo pipefail
reason=""
- if [ -n "$(git status --porcelain -- .github/fern/openapi/openapi.json)" ]; then
+ if [ -n "$(git status --porcelain -- .github/fern/openapi/openapi.json docs/openapi.json)" ]; then
reason="the OpenAPI document changed"
elif ! git rev-parse --verify --quiet "${BASE_SHA}^{commit}" >/dev/null; then
# A branch's first push reports an all-zero base commit.
@@ -120,7 +120,9 @@ jobs:
set -euo pipefail
# --porcelain, not `git diff`, so new files count too.
- if [ -z "$(git status --porcelain -- .github/fern/openapi packages/sdk pnpm-lock.yaml)" ]; then
+ # docs/openapi.json is a second copy of the same document (Mintlify); keep it
+ # in the same commit as .github/fern/openapi or the docs site drifts.
+ if [ -z "$(git status --porcelain -- .github/fern/openapi docs/openapi.json packages/sdk pnpm-lock.yaml)" ]; then
echo "OpenAPI document and SDK are already up to date."
exit 0
fi
@@ -135,7 +137,7 @@ jobs:
pnpm changeset:sdk-regen
fi
- git add .github/fern/openapi packages/sdk pnpm-lock.yaml .changeset
+ git add .github/fern/openapi docs/openapi.json packages/sdk pnpm-lock.yaml .changeset
git commit -m "Regenerate OpenAPI document and TypeScript SDK"
git push origin "HEAD:refs/heads/$BRANCH"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a7946dd90..4418dcd76 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,17 +1,18 @@
# npm publish for the four public packages.
#
-# Filename is load-bearing: npm trusted publishers are bound to `release.yml`.
+# npm trusted publishers are bound to `release.yml`.
# Do not rename this file without updating every package on npmjs.com.
#
-# On every push to main, changesets/action does one of:
-# - pending `.changeset/*.md` → open/update the Version Packages PR
+# On every push to main, changesets/action/select-mode chooses:
+# - pending `.changeset/*.md` → version job opens/updates the Version Packages PR
# (install only; that PR is gated by CI.yml)
-# - none pending → build, test, then `pnpm release`
+# - none pending + unpublished versions → pack (build/test) then publish
# Merge the Version Packages PR to publish. There is no separate publish Action
# and no `v*` tag trigger.
#
# Auth is GitHub OIDC (no NPM_TOKEN). An `_authToken` in user `.npmrc` disables
-# pnpm's OIDC exchange, so this job must not set NPM_TOKEN / NODE_AUTH_TOKEN.
+# pnpm's OIDC exchange, so the publish job must not set NPM_TOKEN / NODE_AUTH_TOKEN.
+# id-token is granted only on the publish job (trusted-publishing best practice).
name: Release
on:
@@ -24,74 +25,148 @@ concurrency:
# Never cancel a publish that is already talking to npm.
cancel-in-progress: false
-permissions:
- contents: write # Version Packages branch + optional GitHub Releases
- pull-requests: write # open/update the Version Packages PR
- id-token: write # npm trusted publishing (OIDC)
+permissions: {}
jobs:
- release:
- name: Version or publish
+ select-mode:
+ name: Select mode
runs-on: ubuntu-latest
- # Fern rebake when the sdk version moves, or build+test on publish.
+ timeout-minutes: 10
+ outputs:
+ mode: ${{ steps.select-mode.outputs.mode }}
+ publish-plan-artifact-id: ${{ steps.select-mode.outputs.publish-plan-artifact-id }}
+ permissions:
+ contents: read
+ steps:
+ - name: Check out repo
+ uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+
+ - uses: pnpm/action-setup@v6
+
+ - name: Set up Node.js
+ uses: actions/setup-node@v7
+ with:
+ node-version: 24
+ cache: pnpm
+
+ - run: pnpm install --frozen-lockfile
+
+ - name: Select Changesets mode
+ id: select-mode
+ uses: changesets/action/select-mode@v2
+
+ version:
+ name: Version packages
+ if: needs.select-mode.outputs.mode == 'version'
+ needs: select-mode
+ runs-on: ubuntu-latest
+ # Fern rebake when the sdk version moves.
timeout-minutes: 30
+ permissions:
+ contents: write
+ pull-requests: write
steps:
- - uses: actions/checkout@v4
+ - name: Check out repo
+ uses: actions/checkout@v7
with:
# Full history so `changeset version` can write CHANGELOG from commits.
fetch-depth: 0
- # Named branch, not a detached SHA: `pnpm publish` git-checks require
- # HEAD to be on `main` (the old tag-push job needed --no-git-checks).
- ref: ${{ github.ref }}
+ persist-credentials: false
- - uses: pnpm/action-setup@v4
+ - uses: pnpm/action-setup@v6
- - uses: actions/setup-node@v4
+ - name: Set up Node.js
+ uses: actions/setup-node@v7
with:
node-version: 24
cache: pnpm
- # No registry-url / NODE_AUTH_TOKEN: an `_authToken` in .npmrc disables
- # pnpm's OIDC exchange for npm trusted publishing.
- run: pnpm install --frozen-lockfile
- # Same rule changesets/action uses: any `.changeset/*.md` except README.
- - id: pending
- name: Detect pending changesets
- run: |
- pending=false
- shopt -s nullglob
- for file in .changeset/*.md; do
- [ "$(basename "$file")" = README.md ] && continue
- pending=true
- break
- done
- echo "pending=$pending" >> "$GITHUB_OUTPUT"
-
- - if: steps.pending.outputs.pending != 'true'
- run: pnpm build
- - if: steps.pending.outputs.pending != 'true'
- run: pnpm test
+ # Must be @v2: @changesets/cli@3 stores applied RC changesets under
+ # `.changeset/pre/`; @v1 still expects folder-style `pre/changes.md` and
+ # fails with ENOENT right after the Version Packages merge.
+ - name: Version packages
+ id: version
+ uses: changesets/action/version@v2
+ with:
+ script: pnpm run version
+ push-with-git-cli: true
+
+ pack:
+ name: Pack packages
+ if: needs.select-mode.outputs.mode == 'publish'
+ needs: select-mode
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ outputs:
+ pack-dir-artifact-id: ${{ steps.pack.outputs.pack-dir-artifact-id }}
+ permissions:
+ contents: read
+ steps:
+ - name: Check out repo
+ uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+
+ - uses: pnpm/action-setup@v6
+
+ - name: Set up Node.js
+ uses: actions/setup-node@v7
+ with:
+ node-version: 24
+ package-manager-cache: false
+
+ - run: pnpm install --frozen-lockfile
+
+ - run: pnpm build
+ - run: pnpm test
# Root build copies FE into packages/server/dist/_frontend; refuse an API-only tarball.
- - if: steps.pending.outputs.pending != 'true'
- name: Verify packaged UI is present
+ - name: Verify packaged UI is present
run: |
test -f packages/server/dist/cli.js
test -f packages/server/dist/_frontend/index.html
- # Must be @v2: @changesets/cli@3 stores applied RC changesets under
- # `.changeset/pre/`; @v1 still expects folder-style `pre/changes.md` and
- # fails with ENOENT right after the Version Packages merge.
- - name: Create Version Packages PR or publish to npm
- uses: changesets/action@v2
+ - name: Pack packages
+ id: pack
+ uses: changesets/action/pack@v2
with:
- version-script: pnpm run version
- publish-script: pnpm run release
+ publish-plan-artifact-id: ${{ needs.select-mode.outputs.publish-plan-artifact-id }}
+
+ publish:
+ name: Publish packages
+ needs: pack
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ permissions:
+ contents: write
+ id-token: write
+ steps:
+ - name: Check out repo
+ uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+
+ - uses: pnpm/action-setup@v6
+
+ - name: Set up Node.js
+ uses: actions/setup-node@v7
+ with:
+ node-version: 24
+ # No registry-url / NODE_AUTH_TOKEN: an `_authToken` in .npmrc disables
+ # pnpm's OIDC exchange for npm trusted publishing.
+ package-manager-cache: false
+
+ - run: pnpm install --frozen-lockfile
+
+ - name: Publish packages
+ uses: changesets/action/publish@v2
+ with:
+ pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }}
create-github-releases: true
- push-with-git-cli: true
- env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- # TODO(oss): set NPM_CONFIG_PROVENANCE once the repo is public. Do NOT
- # set it now: provenance publicly attests the source repo and commit.
- # publishConfig.provenance is false on every public package.
+ # TODO(oss): set NPM_CONFIG_PROVENANCE once the repo is public. Do NOT
+ # set it now: provenance publicly attests the source repo and commit.
+ # publishConfig.provenance is false on every public package.
diff --git a/AGENTS.md b/AGENTS.md
index d35354242..8700d61db 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,7 @@
- A change that makes code unused MUST remove that dead code in the same change; it MUST NOT leave stale exports, files, documentation, duplicates, or “just in case” shims.
- Comments MUST explain intent, trade-offs, or constraints and remain concise; they MUST NOT restate the code or include issue-tracker IDs.
- Every nested `AGENTS.md` MUST have a sibling `CLAUDE.md` containing only `@AGENTS.md`, so Cursor and Claude Code load the same scoped rules.
-- OpenAPI spec under `.github/fern/openapi/openapi.json` is autogenerated in CI and MUST NOT be edited manually
+- OpenAPI specs under `.github/fern/openapi/openapi.json` and `docs/openapi.json` are autogenerated in CI and MUST NOT be edited manually (both copies MUST stay identical)
- Code under `packages/sdk` is autogenerated in CI and MUST NOT be edited manually
- Tests MUST live under a top-level `test` directory that mirrors the `src` layout; they MUST NOT be inlined under `src`.
- Functions with more than one parameter of the same type MUST take a single options object (e.g. `f({ a, b }: { a: string; b: string })`); they MUST NOT use multiple positional parameters of that repeated type (e.g. `f(a: string, b: string)`).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a62b157c5..765cc3a3e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -176,7 +176,7 @@ Open [http://localhost:8791](http://localhost:8791). Credentials come from `pack
## Generated code — do not edit by hand
-- [`packages/sdk`](packages/sdk) and [`.github/fern/openapi/openapi.json`](.github/fern/openapi/openapi.json) are generated by [Fern](https://buildwithfern.com) and committed. Edit route handlers under `packages/server/src/routes/` instead; CI regenerates the outputs. To regenerate locally (Docker required): `pnpm sdk:generate`.
+- [`packages/sdk`](packages/sdk), [`.github/fern/openapi/openapi.json`](.github/fern/openapi/openapi.json), and [`docs/openapi.json`](docs/openapi.json) are generated and committed. Edit route handlers under `packages/server/src/routes/` instead; CI regenerates the outputs. To regenerate locally (Docker required): `pnpm sdk:generate`.
- Catalog YAML files under `packages/server/catalog/` are inlined at build time by `build:gen` scripts.
## Server entry points
diff --git a/RELEASING.md b/RELEASING.md
index 574cc9cae..ad1272ceb 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -28,7 +28,7 @@ Workspace dependencies use `workspace:*`. On publish, pnpm rewrites them to the
## Release flow
-There is no `v*` git-tag publish. One workflow both versions and publishes:
+There is no `v*` git-tag publish. One workflow both versions and publishes, split into least-privilege jobs (`select-mode` → `version` | `pack` → `publish`):
1. **Add a changeset** in the same PR as the code change:
@@ -40,17 +40,17 @@ There is no `v*` git-tag publish. One workflow both versions and publishes:
Name only the packages that should bump. A dependency can ship without its dependents. SDK regeneration on a PR already adds `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.
-2. **Merge to `main`.** `.github/workflows/release.yml` runs. With pending `.changeset/*.md` files, `changesets/action` opens or updates a **Version Packages** PR (`pnpm run version`: `changeset version`, then `pnpm sdk:generate` only if the SDK version moved). Review bumps and changelogs, then merge.
+2. **Merge to `main`.** `.github/workflows/release.yml` runs. `changesets/action/select-mode` picks the path. With pending `.changeset/*.md` files, the **version** job opens or updates a **Version Packages** PR (`pnpm run version`: `changeset version`, then `pnpm sdk:generate` only if the SDK version moved). Review bumps and changelogs, then merge.
-3. **Merge Version Packages to publish.** The same workflow sees no pending changesets and runs `pnpm release` (`pnpm build && changeset publish`). Auth is npm trusted publishing over GitHub OIDC (no `NPM_TOKEN`).
+3. **Merge Version Packages to publish.** The same workflow sees no pending changesets: **pack** builds/tests and packs tarballs, then **publish** uploads them. Auth is npm trusted publishing over GitHub OIDC (`id-token` only on the publish job; no `NPM_TOKEN`).
**Dist-tags:** while `.changeset/pre.json` exists (`pnpm changeset pre enter rc`), publishes use the `rc` tag. After `pnpm changeset pre exit`, the next Version Packages merge publishes to `latest`. Install an RC with `npx @truefoundry/trueforge@rc` or a concrete `x.y.z-rc.N` version.
4. **Update downstream pins** that depend on these packages. Prefer exact versions (no `^`) during early `0.x` churn.
-`workflow_dispatch` on **Release** re-runs the same job (useful after a bot-only commit that did not re-trigger the workflow).
+`workflow_dispatch` on **Release** re-runs the same workflow (useful after a bot-only commit that did not re-trigger it).
-A push to `main` with no pending changesets still runs `changeset publish`, which publishes any `package.json` version not yet on npm and no-ops the rest.
+A push to `main` with no pending changesets still publishes any `package.json` version not yet on npm and no-ops the rest.
## Prerelease mode
@@ -97,9 +97,9 @@ Each of the four packages must list this repository and workflow as a trusted pu
- Repository: `truefoundry/trueforge`
- Workflow filename: `release.yml` (must match exactly)
-- No GitHub Environment name (the job does not use one)
+- No GitHub Environment name (the publish job does not use one)
-Configure the trusted-publisher row **before** the first `changeset publish` for a new package. Do not set `NPM_TOKEN` or an `_authToken` in `.npmrc` on the release job — that disables the OIDC exchange.
+Configure the trusted-publisher row **before** the first publish for a new package. Do not set `NPM_TOKEN` or an `_authToken` in `.npmrc` on the publish job — that disables the OIDC exchange. Only the **publish** job has `id-token: write`.
## Troubleshooting
@@ -107,7 +107,7 @@ Configure the trusted-publisher row **before** the first `changeset publish` for
- **Publish fails requiring a tag** — prerelease versions need the `rc` dist-tag. `changeset publish` sets that while pre mode is on; for a local publish use `pnpm publish --tag rc`.
- **Publish fails with 403/E403** — version already published (npm versions are immutable), or the trusted publisher config does not match the workflow filename/repo exactly.
- **OIDC/auth error** — requires pnpm >= 11.0.7 (native OIDC; `pnpm/action-setup@v4` reads `packageManager` from the root) and a matching trusted publisher config. Remove any registry `_authToken`.
-- **Missing `dist/_frontend/index.html`** — root `pnpm build` must build `frontend` before `@truefoundry/trueforge`; the release job fails closed if the copy is absent.
+- **Missing `dist/_frontend/index.html`** — root `pnpm build` must build `frontend` before `@truefoundry/trueforge`; the pack job fails closed if the copy is absent.
- **Version PR did not regenerate the SDK** — `scripts/version.mjs` only runs `pnpm sdk:generate` when `@truefoundry/trueforge-sdk`'s version changed. That step needs Docker (available on `ubuntu-latest`).
---
diff --git a/docs/openapi.json b/docs/openapi.json
index cbd8f02d1..d57cca8a5 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -35,14 +35,7 @@
"$ref": "#/components/schemas/AgentSpec"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
}
},
"required": [
@@ -433,7 +426,12 @@
"additionalProperties": false,
"properties": {
"auth": {
- "$ref": "#/components/schemas/ConfiguredMcpServerAuth"
+ "$ref": "#/components/schemas/McpServerManifestAuth"
+ },
+ "description": {
+ "description": "Concise summary of what this MCP server provides.",
+ "minLength": 1,
+ "type": "string"
},
"logo": {
"description": "URL of the MCP server logo asset.",
@@ -441,14 +439,7 @@
"type": "string"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
},
"type": {
"$ref": "#/components/schemas/McpServerType"
@@ -462,7 +453,8 @@
"required": [
"type",
"name",
- "url"
+ "url",
+ "description"
],
"type": "object"
},
@@ -485,14 +477,7 @@
"type": "string"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
},
"path": {
"description": "Path to the skill directory within the repository. Omit to use the repository root.",
@@ -681,63 +666,38 @@
"ConfiguredMcpServer": {
"additionalProperties": false,
"properties": {
- "auth": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ConfiguredMcpServerAuth"
- },
- {
- "description": "Optional auth settings. Omit when the server needs no credentials."
- }
- ]
- },
"auth_status": {
"$ref": "#/components/schemas/McpAuthStatus"
},
- "name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
- },
- "type": {
- "$ref": "#/components/schemas/McpServerType"
+ "manifest": {
+ "$ref": "#/components/schemas/McpServerManifest"
},
- "url": {
- "description": "URL of the remote MCP server.",
- "format": "uri",
- "type": "string"
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
}
},
"required": [
- "type",
"name",
- "url",
+ "manifest",
"auth_status"
],
"type": "object"
},
- "ConfiguredMcpServerAuth": {
- "description": "Optional default auth settings for the preset.",
- "discriminator": {
- "mapping": {
- "dcr": "#/components/schemas/McpServerDcrAuth",
- "header": "#/components/schemas/McpServerHeaderAuth"
- },
- "propertyName": "type"
- },
- "oneOf": [
- {
- "$ref": "#/components/schemas/McpServerHeaderAuth"
+ "ConfiguredSkill": {
+ "additionalProperties": false,
+ "properties": {
+ "manifest": {
+ "$ref": "#/components/schemas/SkillManifest"
},
- {
- "$ref": "#/components/schemas/McpServerDcrAuth"
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
}
- ]
+ },
+ "required": [
+ "name",
+ "manifest"
+ ],
+ "type": "object"
},
"ContextManagementConfig": {
"default": {
@@ -780,14 +740,7 @@
"$ref": "#/components/schemas/AgentSpec"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
}
},
"required": [
@@ -799,39 +752,24 @@
"CreateMcpServerRequest": {
"additionalProperties": false,
"properties": {
- "auth": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ConfiguredMcpServerAuth"
- },
- {
- "description": "Optional auth settings. Omit when the server needs no credentials."
- }
- ]
- },
- "name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
- },
- "type": {
- "$ref": "#/components/schemas/McpServerType"
- },
- "url": {
- "description": "URL of the remote MCP server.",
- "format": "uri",
- "type": "string"
+ "manifest": {
+ "$ref": "#/components/schemas/McpServerManifest"
}
},
"required": [
- "type",
- "name",
- "url"
+ "manifest"
+ ],
+ "type": "object"
+ },
+ "CreateModelProviderRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "manifest": {
+ "$ref": "#/components/schemas/ModelProviderManifest"
+ }
+ },
+ "required": [
+ "manifest"
],
"type": "object"
},
@@ -857,6 +795,18 @@
],
"type": "object"
},
+ "CreateSkillRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "manifest": {
+ "$ref": "#/components/schemas/SkillManifest"
+ }
+ },
+ "required": [
+ "manifest"
+ ],
+ "type": "object"
+ },
"CreateTurnRequest": {
"properties": {
"input": {
@@ -897,14 +847,7 @@
"type": "array"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
},
"type": {
"enum": [
@@ -1163,6 +1106,17 @@
],
"type": "object"
},
+ "GetModelProviderResponse": {
+ "properties": {
+ "data": {
+ "$ref": "#/components/schemas/ModelProvider"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"GetSandboxProviderCatalogResponse": {
"properties": {
"data": {
@@ -1180,7 +1134,7 @@
"GetSandboxProviderResponse": {
"properties": {
"data": {
- "$ref": "#/components/schemas/SandboxProviderResponse"
+ "$ref": "#/components/schemas/SandboxProvider"
}
},
"required": [
@@ -1213,6 +1167,17 @@
],
"type": "object"
},
+ "GetSkillResponse": {
+ "properties": {
+ "data": {
+ "$ref": "#/components/schemas/ConfiguredSkill"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"GetTurnResponse": {
"properties": {
"data": {
@@ -1313,20 +1278,6 @@
],
"type": "object"
},
- "ListConfiguredSkillsResponse": {
- "properties": {
- "data": {
- "items": {
- "$ref": "#/components/schemas/SkillManifest"
- },
- "type": "array"
- }
- },
- "required": [
- "data"
- ],
- "type": "object"
- },
"ListMcpServerToolsResponse": {
"properties": {
"data": {
@@ -1430,6 +1381,20 @@
],
"type": "object"
},
+ "ListSkillsResponse": {
+ "properties": {
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/ConfiguredSkill"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "data"
+ ],
+ "type": "object"
+ },
"ListTurnEventsOrder": {
"default": "asc",
"description": "Sort events by insertion order. Defaults to \"asc\".",
@@ -1730,7 +1695,7 @@
},
"McpAuthStatus": {
"additionalProperties": false,
- "description": "Auth state for the calling user.",
+ "description": "Current auth state.",
"properties": {
"authorization_url": {
"description": "When auth is required, this contains the URL to redirect the user to for authorization.",
@@ -1832,24 +1797,15 @@
"additionalProperties": false,
"properties": {
"auth": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ConfiguredMcpServerAuth"
- },
- {
- "description": "Optional auth settings. Omit when the server needs no credentials."
- }
- ]
+ "$ref": "#/components/schemas/McpServerManifestAuth"
+ },
+ "description": {
+ "description": "Concise summary of what this MCP server provides.",
+ "minLength": 1,
+ "type": "string"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
},
"type": {
"$ref": "#/components/schemas/McpServerType"
@@ -1863,10 +1819,29 @@
"required": [
"type",
"name",
- "url"
+ "url",
+ "description"
],
"type": "object"
},
+ "McpServerManifestAuth": {
+ "description": "Optional auth settings. Omit when the server needs no credentials.",
+ "discriminator": {
+ "mapping": {
+ "dcr": "#/components/schemas/McpServerDcrAuth",
+ "header": "#/components/schemas/McpServerHeaderAuth"
+ },
+ "propertyName": "type"
+ },
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/McpServerHeaderAuth"
+ },
+ {
+ "$ref": "#/components/schemas/McpServerDcrAuth"
+ }
+ ]
+ },
"McpServerReadEntry": {
"additionalProperties": false,
"properties": {
@@ -1877,14 +1852,7 @@
"$ref": "#/components/schemas/McpAuthStatus"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
},
"url": {
"description": "URL of the remote MCP server.",
@@ -1900,7 +1868,6 @@
"type": "object"
},
"McpServerType": {
- "description": "MCP server kind (`remote` today).",
"enum": [
"remote"
],
@@ -2273,6 +2240,37 @@
"type": "object"
},
"ModelProvider": {
+ "additionalProperties": false,
+ "properties": {
+ "manifest": {
+ "$ref": "#/components/schemas/ModelProviderManifest"
+ },
+ "name": {
+ "$ref": "#/components/schemas/ResourceName"
+ }
+ },
+ "required": [
+ "name",
+ "manifest"
+ ],
+ "type": "object"
+ },
+ "ModelProviderAuth": {
+ "additionalProperties": false,
+ "description": "Provider authentication credentials.",
+ "properties": {
+ "api_key": {
+ "description": "Provider API key. Responses are redacted; on PUT, a real value sets/rotates and a redacted value keeps the stored key.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "api_key"
+ ],
+ "type": "object"
+ },
+ "ModelProviderManifest": {
"discriminator": {
"mapping": {
"alibaba": "#/components/schemas/AlibabaModelProvider",
@@ -2317,21 +2315,6 @@
}
]
},
- "ModelProviderAuth": {
- "additionalProperties": false,
- "description": "Provider authentication credentials.",
- "properties": {
- "api_key": {
- "description": "Provider API key. Responses are redacted; on PUT, a real value sets/rotates and a redacted value keeps the stored key.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "api_key"
- ],
- "type": "object"
- },
"MoonshotModelProvider": {
"additionalProperties": false,
"properties": {
@@ -2434,47 +2417,51 @@
],
"type": "object"
},
- "PutMcpServerResponse": {
+ "PutMcpServerRequest": {
+ "additionalProperties": false,
"properties": {
- "data": {
- "$ref": "#/components/schemas/ConfiguredMcpServer"
+ "manifest": {
+ "$ref": "#/components/schemas/McpServerManifest"
}
},
"required": [
- "data"
+ "manifest"
],
"type": "object"
},
- "PutModelProviderResponse": {
+ "PutModelProviderRequest": {
+ "additionalProperties": false,
"properties": {
- "data": {
- "$ref": "#/components/schemas/ModelProvider"
+ "manifest": {
+ "$ref": "#/components/schemas/ModelProviderManifest"
}
},
"required": [
- "data"
+ "manifest"
],
"type": "object"
},
- "PutSandboxProviderResponse": {
+ "PutSandboxProviderRequest": {
+ "additionalProperties": false,
"properties": {
- "data": {
- "$ref": "#/components/schemas/SandboxProviderResponse"
+ "manifest": {
+ "$ref": "#/components/schemas/SandboxProviderManifest"
}
},
"required": [
- "data"
+ "manifest"
],
"type": "object"
},
- "PutSkillResponse": {
+ "PutSkillRequest": {
+ "additionalProperties": false,
"properties": {
- "data": {
+ "manifest": {
"$ref": "#/components/schemas/SkillManifest"
}
},
"required": [
- "data"
+ "manifest"
],
"type": "object"
},
@@ -2545,7 +2532,6 @@
"type": "object"
},
"ResourceName": {
- "description": "Internal identifier; forms the fully qualified name `name/model_name`.",
"maxLength": 64,
"minLength": 2,
"pattern": "^[a-z](?:[a-z0-9._-]{0,62}[a-z0-9])$",
@@ -2848,6 +2834,30 @@
},
"type": "object"
},
+ "SandboxProvider": {
+ "additionalProperties": false,
+ "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"
+ ],
+ "type": "object"
+ },
"SandboxProviderManifest": {
"additionalProperties": false,
"properties": {
@@ -2892,30 +2902,6 @@
],
"type": "object"
},
- "SandboxProviderResponse": {
- "additionalProperties": false,
- "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"
- ],
- "type": "object"
- },
"Session": {
"properties": {
"agent": {
@@ -2996,14 +2982,7 @@
"additionalProperties": false,
"properties": {
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
}
},
"required": [
@@ -3131,14 +3110,7 @@
"type": "string"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
},
"path": {
"description": "Path to the skill directory within the repository. Omit to use the repository root.",
@@ -3196,14 +3168,7 @@
"type": "string"
},
"name": {
- "allOf": [
- {
- "$ref": "#/components/schemas/ResourceName"
- },
- {
- "description": "Fully qualified name. Unique within a tenant."
- }
- ]
+ "$ref": "#/components/schemas/ResourceName"
}
},
"required": [
@@ -4970,7 +4935,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/PutMcpServerResponse"
+ "$ref": "#/components/schemas/GetMcpServerResponse"
}
}
},
@@ -6367,11 +6332,11 @@
"required": true
},
"responses": {
- "200": {
+ "201": {
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/PutMcpServerResponse"
+ "$ref": "#/components/schemas/GetMcpServerResponse"
}
}
},
@@ -6424,7 +6389,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/McpServerManifest"
+ "$ref": "#/components/schemas/PutMcpServerRequest"
}
}
},
@@ -6435,7 +6400,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/PutMcpServerResponse"
+ "$ref": "#/components/schemas/GetMcpServerResponse"
}
}
},
@@ -6603,7 +6568,7 @@
},
"/api/v1/settings/model-providers": {
"get": {
- "description": "All configured providers with their models.",
+ "description": "All configured providers with nested manifests.",
"responses": {
"200": {
"content": {
@@ -6652,18 +6617,18 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/ModelProvider"
+ "$ref": "#/components/schemas/CreateModelProviderRequest"
}
}
},
"required": true
},
"responses": {
- "200": {
+ "201": {
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/PutModelProviderResponse"
+ "$ref": "#/components/schemas/GetModelProviderResponse"
}
}
},
@@ -6706,7 +6671,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/ModelProvider"
+ "$ref": "#/components/schemas/PutModelProviderRequest"
}
}
},
@@ -6717,7 +6682,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/PutModelProviderResponse"
+ "$ref": "#/components/schemas/GetModelProviderResponse"
}
}
},
@@ -6786,7 +6751,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/SandboxProviderManifest"
+ "$ref": "#/components/schemas/PutSandboxProviderRequest"
}
}
},
@@ -6797,7 +6762,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/PutSandboxProviderResponse"
+ "$ref": "#/components/schemas/GetSandboxProviderResponse"
}
}
},
@@ -6837,13 +6802,13 @@
},
"/api/v1/settings/skills": {
"get": {
- "description": "All configured skills with full manifests (settings / admin projection).",
+ "description": "All configured skills with nested manifests (settings / admin projection).",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/ListConfiguredSkillsResponse"
+ "$ref": "#/components/schemas/ListSkillsResponse"
}
}
},
@@ -6886,18 +6851,18 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/SkillManifest"
+ "$ref": "#/components/schemas/CreateSkillRequest"
}
}
},
"required": true
},
"responses": {
- "200": {
+ "201": {
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/PutSkillResponse"
+ "$ref": "#/components/schemas/GetSkillResponse"
}
}
},
@@ -6940,7 +6905,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/SkillManifest"
+ "$ref": "#/components/schemas/PutSkillRequest"
}
}
},
@@ -6951,7 +6916,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/PutSkillResponse"
+ "$ref": "#/components/schemas/GetSkillResponse"
}
}
},
diff --git a/package.json b/package.json
index d6631962f..abaf7b96e 100644
--- a/package.json
+++ b/package.json
@@ -38,7 +38,6 @@
"standalone:start": "STANDALONE=true NODE_ENV=production pnpm --filter @truefoundry/trueforge start",
"start": "STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/trueforge start",
"push-sandbox-image-to-daytona": "pnpm --filter @truefoundry/trueforge push-sandbox-image-to-daytona",
- "release": "pnpm build && changeset publish",
"test:frontend": "pnpm --filter frontend test",
"test:harness": "pnpm --filter @truefoundry/trueforge-core test",
"test:server": "pnpm --filter @truefoundry/trueforge test",
diff --git a/packages/server/scripts/migrate-legacy-sqlite-path.mjs b/packages/server/scripts/migrate-legacy-sqlite-path.mjs
index 4df0bab25..b18f0fbb9 100644
--- a/packages/server/scripts/migrate-legacy-sqlite-path.mjs
+++ b/packages/server/scripts/migrate-legacy-sqlite-path.mjs
@@ -67,8 +67,5 @@ try {
rmSync(legacyDbDir, { recursive: true, force: true });
}
} catch (error) {
- console.warn(
- `Could not remove empty legacy dir ${legacyDbDir}:`,
- error instanceof Error ? error.message : error,
- );
+ console.warn(`Could not remove empty legacy dir ${legacyDbDir}:`, error instanceof Error ? error.message : error);
}
diff --git a/packages/server/scripts/write-openapi.ts b/packages/server/scripts/write-openapi.ts
index a7bfcb4cb..4019c618b 100644
--- a/packages/server/scripts/write-openapi.ts
+++ b/packages/server/scripts/write-openapi.ts
@@ -1,5 +1,7 @@
/**
- * Writes the server's OpenAPI document to `.github/fern/openapi/openapi.json` for Fern.
+ * Writes the server's OpenAPI document to `.github/fern/openapi/openapi.json`
+ * (Fern) and `docs/openapi.json` (Mintlify). Both copies must stay identical;
+ * CI's Generate SDK workflow commits both after this script runs.
*
* The real app is built in-process and asked for its document, so the committed
* spec cannot drift from what the server serves. Nothing listens or dials out:
@@ -78,8 +80,7 @@ mkdirSync(path.dirname(sdkOutputPath), { recursive: true });
writeFileSync(sdkOutputPath, `${JSON.stringify(canonicalise(document), null, 2)}\n`);
console.log(`Wrote ${String(Object.keys(document.paths ?? {}).length)} paths to ${sdkOutputPath}`);
-// we are replicating it here because we need to use it in the docs
-// TODO (chiragjn): We tried symlinking but that did not work, revisit it later
+// Mintlify cannot consume the Fern path; keep a second identical copy for docs.
const docsOutputPath = path.join(import.meta.dirname, '../../../docs/openapi.json');
mkdirSync(path.dirname(docsOutputPath), { recursive: true });
writeFileSync(docsOutputPath, `${JSON.stringify(canonicalise(document), null, 2)}\n`);
diff --git a/scripts/changeset-sdk-regen.sh b/scripts/changeset-sdk-regen.sh
index 669dba96f..85878ec76 100755
--- a/scripts/changeset-sdk-regen.sh
+++ b/scripts/changeset-sdk-regen.sh
@@ -15,4 +15,14 @@ for file in .changeset/*.md; do
fi
done
-pnpm change --bump patch --summary "Regenerate SDK from updated OpenAPI spec." @truefoundry/trueforge-sdk
+slug="regenerate-sdk-from-openapi"
+outfile=".changeset/$(date -u +%Y%m%d%H%M%S)-${slug}.md"
+cat >"$outfile" <<'EOF'
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.
+EOF
+
+echo "Wrote $outfile"
diff --git a/scripts/generate-sdk.sh b/scripts/generate-sdk.sh
index 427262e7a..4d107d8de 100755
--- a/scripts/generate-sdk.sh
+++ b/scripts/generate-sdk.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Regenerates .github/fern/openapi/openapi.json and packages/sdk (same steps as CI).
+# Regenerates OpenAPI (.github/fern + docs/) and packages/sdk (same steps as CI).
# Requires Docker (Fern --local) and network access for the Fern CLI/image.
set -euo pipefail