The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Update READMEs for npm (#291)
Chirag Jain5100c59dbbee
diff --git a/.changeset/20260816223810-regenerate-sdk-from-openapi.md b/.changeset/20260816223810-regenerate-sdk-from-openapi.mdnew file mode 100644index 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.ymlindex 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: TrueForgeintroduction: >- TypeScript client for the TrueForge agent harness server: a self-hosted+ TypeScript client for the TrueForge Agent Harness Server: a self-hostedruntime 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: POSTdiff --git a/README.md b/README.mdindex 30c303344..6e3c2ad84 100644--- a/README.md+++ b/README.md@@ -26,6 +26,20 @@<img src="https://img.shields.io/badge/SDK-trueforge.dev/api/overview-blue.svg" alt="SDK"></a></p>+<p align="center">+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge">+ <img src="https://img.shields.io/npm/v/@truefoundry/trueforge?label=trueforge" alt="npm @truefoundry/trueforge">+ </a>+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-sdk">+ <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-sdk?label=trueforge-sdk" alt="npm @truefoundry/trueforge-sdk">+ </a>+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-ui">+ <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-ui?label=trueforge-ui" alt="npm @truefoundry/trueforge-ui">+ </a>+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-core">+ <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-core?label=trueforge-core" alt="npm @truefoundry/trueforge-core">+ </a>+</p># TrueForgediff --git a/RELEASING.md b/RELEASING.mdindex 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.mdindex 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.mdnew file mode 100644index 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.jsonindex 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.mjsindex 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 literaldiff --git a/packages/trueforge-sdk/README.md b/packages/trueforge-sdk/README.mdindex 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[](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=Truefoundry%2FTypeScript)[](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```shdiff --git a/packages/trueforge-ui/src/containers/TrueforgeUI.tsx b/packages/trueforge-ui/src/containers/TrueForgeUI.tsxsimilarity index 100%rename from packages/trueforge-ui/src/containers/TrueforgeUI.tsxrename to packages/trueforge-ui/src/containers/TrueForgeUI.tsxdiff --git a/packages/trueforge-ui/src/server/TrueforgeServerConfig.ts b/packages/trueforge-ui/src/server/TrueForgeServerConfig.tssimilarity index 100%rename from packages/trueforge-ui/src/server/TrueforgeServerConfig.tsrename to packages/trueforge-ui/src/server/TrueForgeServerConfig.tsdiff --git a/packages/trueforge-ui/test/containers/TrueforgeUI.test.tsx b/packages/trueforge-ui/test/containers/TrueForgeUI.test.tsxsimilarity index 100%rename from packages/trueforge-ui/test/containers/TrueforgeUI.test.tsxrename to packages/trueforge-ui/test/containers/TrueForgeUI.test.tsxdiff --git a/packages/trueforge/README.md b/packages/trueforge/README.mdnew file mode 100644index 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.jsonindex 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"