diff --git a/.changeset/20260816223810-regenerate-sdk-from-openapi.md b/.changeset/20260816223810-regenerate-sdk-from-openapi.md new file mode 100644 index 000000000..91f0e5bcc --- /dev/null +++ b/.changeset/20260816223810-regenerate-sdk-from-openapi.md @@ -0,0 +1,5 @@ +--- +'@truefoundry/trueforge-sdk': patch +--- + +Regenerate SDK from updated OpenAPI spec. diff --git a/.github/fern/generators.yml b/.github/fern/generators.yml index 1659132f6..b6f286bc1 100644 --- a/.github/fern/generators.yml +++ b/.github/fern/generators.yml @@ -2,13 +2,15 @@ # # openapi/openapi.json is committed by `pnpm openapi:write`, so Fern never needs the server. readme: + apiName: TrueForge introduction: > - TypeScript client for the TrueForge agent harness server: a self-hosted + TypeScript client for the TrueForge Agent Harness Server: a self-hosted runtime that executes agent turns and streams them over Server-Sent Events. When auth is enabled on the server, pass an ID token via the optional `token` client option (`Authorization: Bearer`). + apiReferenceLink: https://trueforge.dev/api/use-agent # Fern keys this lookup on the stream flag, so the string form misses and fails. defaultEndpoint: method: POST diff --git a/README.md b/README.md index 30c303344..6e3c2ad84 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,20 @@ SDK

+

+ + npm @truefoundry/trueforge + + + npm @truefoundry/trueforge-sdk + + + npm @truefoundry/trueforge-ui + + + npm @truefoundry/trueforge-core + +

# TrueForge diff --git a/RELEASING.md b/RELEASING.md index 0d8f5ffe5..adad7418c 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -13,7 +13,7 @@ Publishing npm does not stamp or push the chart. Publishing the image/chart does | Package | Source | Notes | | ----------------------------- | ------------------------- | --------------------------------------------------------------- | -| `@truefoundry/trueforge-core` | `packages/trueforge-core` | Library (`files: ["dist"]`) | +| `@truefoundry/trueforge-core` | `packages/trueforge-core` | Library (`files: ["dist", "README.md"]`) | | `@truefoundry/trueforge` | `packages/trueforge` | App + CLI; tarball includes embedded UI under `dist/_frontend/` | | `@truefoundry/trueforge-sdk` | `packages/trueforge-sdk` | Fern-generated client — do not hand-edit | | `@truefoundry/trueforge-ui` | `packages/trueforge-ui` | Embeddable chat UI | @@ -68,7 +68,7 @@ Do not mix stable and RC packages in one `changeset version` — exit pre only w ## Package layout (`@truefoundry/trueforge-core`) -Packages publish from their package root. The core build emits CJS (`.js`), ESM (`.mjs`), and `.d.ts` under `dist/`; `package.json` `exports` point at those paths and `files: ["dist"]` limits the tarball to compiled output. +Packages publish from their package root. The core build emits CJS (`.js`), ESM (`.mjs`), and `.d.ts` under `dist/`; `package.json` `exports` point at those paths and `files: ["dist", "README.md"]` keeps `src/` out of the tarball. - Deep imports such as `@truefoundry/trueforge-core/core/llm/LLMTypes` resolve via the package `exports` map for modern `moduleResolution` modes (`bundler`, `node16`, `nodenext`). - Curated barrels (`.`, `./core`, `./agent-session`) are the supported public API; deep imports are an escape hatch. diff --git a/packages/trueforge-core/AGENTS.md b/packages/trueforge-core/AGENTS.md index 19a9de949..df2e81032 100644 --- a/packages/trueforge-core/AGENTS.md +++ b/packages/trueforge-core/AGENTS.md @@ -1,3 +1,3 @@ -- Workspace source MUST remain ESM so `exports["trueforge-dev"]` can load `src/` without a build. That condition name MUST NOT be `"development"` (or `"production"`) — the package publishes from its own root with `files: ["dist"]`, so `src/` is never in the tarball, and Vite/webpack default to auto-activating a literal `"development"` condition in dev mode with no consumer opt-in, which would break resolution for any such consumer. `dist/` output MUST expose CJS `.js` and ESM `.mjs` outputs alongside `.d.ts`. +- Workspace source MUST remain ESM so `exports["trueforge-dev"]` can load `src/` without a build. That condition name MUST NOT be `"development"` (or `"production"`) — the package publishes from its own root with `files: ["dist", "README.md"]`, so `src/` is never in the tarball, and Vite/webpack default to auto-activating a literal `"development"` condition in dev mode with no consumer opt-in, which would break resolution for any such consumer. `dist/` output MUST expose CJS `.js` and ESM `.mjs` outputs alongside `.d.ts`. - Top-level public package surfaces (`core`, `agent-session`, and other exported entrypoints) MAY use optional (`?`) properties for caller ergonomics. - Within this package, records, snapshots, store INPUT types, and other internal contracts MUST NOT use `?`. Absence MUST be an explicit required `| null` or `| undefined` field; prefer `null` for domain absence and `undefined` only when update/patch semantics must distinguish “not provided” from “clear.” Public surfaces adapt by supplying those explicit absences when calling inward. This forces internal object literals to be exhaustive under `tsc`, preventing forgotten fields and silent data loss. diff --git a/packages/trueforge-core/README.md b/packages/trueforge-core/README.md new file mode 100644 index 000000000..977c5e868 --- /dev/null +++ b/packages/trueforge-core/README.md @@ -0,0 +1,27 @@ +# @truefoundry/trueforge-core + +[Documentation](https://trueforge.dev) · [npm](https://www.npmjs.com/package/@truefoundry/trueforge-core) · [GitHub](https://github.com/truefoundry/trueforge) + +The agent execution library behind [TrueForge](https://trueforge.dev): the runtime that runs the agent loop — model calls, MCP tools, skills, sandboxing, approvals, context management, and session state. + +## Use TrueForge instead + +This package is the library the TrueForge server is built on. It is **not** a complete product on its own. + +If you want HTTP APIs, a TypeScript SDK, and a chat UI, use [`@truefoundry/trueforge`](https://www.npmjs.com/package/@truefoundry/trueforge) and start at **[trueforge.dev](https://trueforge.dev)**. + +```bash +npx @truefoundry/trueforge +``` + +- [Quickstart](https://trueforge.dev/quickstart) +- [HTTP API & SDK](https://trueforge.dev/api/overview) +- [Chat UI](https://trueforge.dev/chat-ui) + +## Compatibility + +`@truefoundry/trueforge-core` does **not** offer backward compatibility guarantees at this time. Public APIs and types may change in any release. Pin an exact version if you depend on this package. + +## License + +[MIT](https://github.com/truefoundry/trueforge/blob/main/LICENSE) diff --git a/packages/trueforge-core/package.json b/packages/trueforge-core/package.json index 77988c592..87c8e0355 100644 --- a/packages/trueforge-core/package.json +++ b/packages/trueforge-core/package.json @@ -1,7 +1,7 @@ { "name": "@truefoundry/trueforge-core", "version": "0.1.0", - "description": "TrueForge core library", + "description": "TrueForge Agent Harness library.", "author": "TrueFoundry", "license": "MIT", "repository": { @@ -9,7 +9,7 @@ "url": "git+https://github.com/truefoundry/trueforge.git", "directory": "packages/trueforge-core" }, - "homepage": "https://github.com/truefoundry/trueforge/tree/main/packages/trueforge-core#readme", + "homepage": "https://trueforge.dev", "bugs": { "url": "https://github.com/truefoundry/trueforge/issues" }, @@ -79,7 +79,8 @@ "./package.json": "./package.json" }, "files": [ - "dist" + "dist", + "README.md" ], "engines": { "node": ">=22" diff --git a/packages/trueforge-core/scripts/check-dist.mjs b/packages/trueforge-core/scripts/check-dist.mjs index d4724ede0..3658d15ed 100644 --- a/packages/trueforge-core/scripts/check-dist.mjs +++ b/packages/trueforge-core/scripts/check-dist.mjs @@ -46,8 +46,9 @@ if (!fs.existsSync(distPkgPath)) { } } -// package.json is published as-is (no more staged dist/package.json rewrite), and only -// `dist` ships (files: ["dist"]) — so a literal "development" condition pointing at +// package.json is published as-is (no more staged dist/package.json rewrite), and +// `src/` does not ship (files: ["dist", "README.md"]) — so a literal "development" +// condition pointing at // ./src/... would be a live, resolvable-but-broken promise for any consumer whose // tooling defaults to activating it, not dead weight. Vite's default resolve.conditions // is ['module', 'browser', 'development|production'], which it substitutes to the literal diff --git a/packages/trueforge-sdk/README.md b/packages/trueforge-sdk/README.md index 12f6cd22a..6b618b865 100644 --- a/packages/trueforge-sdk/README.md +++ b/packages/trueforge-sdk/README.md @@ -1,15 +1,16 @@ -# Truefoundry TypeScript Library +# TrueForge TypeScript Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=Truefoundry%2FTypeScript) [![npm shield](https://img.shields.io/npm/v/@truefoundry/trueforge-sdk)](https://www.npmjs.com/package/@truefoundry/trueforge-sdk) -TypeScript client for the TrueForge agent harness server: a self-hosted runtime that executes agent turns and streams them over Server-Sent Events. +TypeScript client for the TrueForge Agent Harness Server: a self-hosted runtime that executes agent turns and streams them over Server-Sent Events. When auth is enabled on the server, pass an ID token via the optional `token` client option (`Authorization: Bearer`). ## Table of Contents +- [Documentation](#documentation) - [Installation](#installation) - [Reference](#reference) - [Usage](#usage) @@ -31,6 +32,10 @@ When auth is enabled on the server, pass an ID token via the optional `token` cl - [Runtime Compatibility](#runtime-compatibility) - [Contributing](#contributing) +## Documentation + +API reference documentation is available [here](https://trueforge.dev/api/use-agent). + ## Installation ```sh diff --git a/packages/trueforge-ui/src/containers/TrueforgeUI.tsx b/packages/trueforge-ui/src/containers/TrueForgeUI.tsx similarity index 100% rename from packages/trueforge-ui/src/containers/TrueforgeUI.tsx rename to packages/trueforge-ui/src/containers/TrueForgeUI.tsx diff --git a/packages/trueforge-ui/src/server/TrueforgeServerConfig.ts b/packages/trueforge-ui/src/server/TrueForgeServerConfig.ts similarity index 100% rename from packages/trueforge-ui/src/server/TrueforgeServerConfig.ts rename to packages/trueforge-ui/src/server/TrueForgeServerConfig.ts diff --git a/packages/trueforge-ui/test/containers/TrueforgeUI.test.tsx b/packages/trueforge-ui/test/containers/TrueForgeUI.test.tsx similarity index 100% rename from packages/trueforge-ui/test/containers/TrueforgeUI.test.tsx rename to packages/trueforge-ui/test/containers/TrueForgeUI.test.tsx diff --git a/packages/trueforge/README.md b/packages/trueforge/README.md new file mode 100644 index 000000000..4f7f111c8 --- /dev/null +++ b/packages/trueforge/README.md @@ -0,0 +1,30 @@ +# @truefoundry/trueforge + +[Documentation](https://trueforge.dev) · [Quickstart](https://trueforge.dev/quickstart) · [npm](https://www.npmjs.com/package/@truefoundry/trueforge) · [GitHub](https://github.com/truefoundry/trueforge) + +The open-source agent harness — the runtime that turns an LLM into a working agent. + +TrueForge runs the agent loop (model calls, MCP tools, skills, sandboxing, approvals, context management, and session state) and exposes it as a **chat UI**, an **HTTP API**, and a TypeScript **SDK**. + +## Quick start + +Requires [Node.js](https://nodejs.org) 22+. + +```bash +npx @truefoundry/trueforge +``` + +Open [http://localhost:8790](http://localhost:8790). This is local mode (one process, SQLite) — for your machine only. + +## Docs + +Guides, hosted deployment, API reference, and the UI SDK live at **[trueforge.dev](https://trueforge.dev)**. + +## Related packages + +- [`@truefoundry/trueforge-sdk`](https://www.npmjs.com/package/@truefoundry/trueforge-sdk) — TypeScript client for the HTTP API +- [`@truefoundry/trueforge-ui`](https://www.npmjs.com/package/@truefoundry/trueforge-ui) — embeddable React chat UI + +## License + +[MIT](https://github.com/truefoundry/trueforge/blob/main/LICENSE) diff --git a/packages/trueforge/package.json b/packages/trueforge/package.json index 155ec8a52..0fcf0fd9b 100644 --- a/packages/trueforge/package.json +++ b/packages/trueforge/package.json @@ -1,7 +1,7 @@ { "name": "@truefoundry/trueforge", "version": "0.1.0", - "description": "TrueForge agent server + UI (npx @truefoundry/trueforge)", + "description": "TrueForge Agent Harness: server, HTTP API, and chat UI (npx @truefoundry/trueforge)", "author": "TrueFoundry", "license": "MIT", "repository": { @@ -9,7 +9,7 @@ "url": "git+https://github.com/truefoundry/trueforge.git", "directory": "packages/trueforge" }, - "homepage": "https://github.com/truefoundry/trueforge/tree/main/packages/trueforge#readme", + "homepage": "https://trueforge.dev", "bugs": { "url": "https://github.com/truefoundry/trueforge/issues" }, @@ -21,7 +21,8 @@ "type": "module", "bin": "./dist/cli.js", "files": [ - "dist" + "dist", + "README.md" ], "engines": { "node": ">=22"