Skip to content

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

Add BUGBOT.md files

Chirag Jainf7a0a181a87e
diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md
new file mode 100644
index 000000000..aaca56cc1
--- /dev/null
+++ b/.cursor/BUGBOT.md
@@ -0,0 +1,59 @@
+# TrueForge review rules
+
+Repo-wide checks. Package-specific rules live in `packages/trueforge-core/.cursor/BUGBOT.md` and `packages/trueforge/.cursor/BUGBOT.md`.
+
+## Changeset (non-blocking)
+
+If the diff changes code that ships in a published package and does not add a new `.changeset/*.md` file, add a **non-blocking** finding. Tell the author to run `pnpm changeset` and name only the packages that should bump:
+
+- `packages/trueforge-core` → `@truefoundry/trueforge-core`
+- `packages/trueforge` → `@truefoundry/trueforge`
+- `packages/trueforge-ui` → `@truefoundry/trueforge-ui`
+- `packages/trueforge-sdk` → `@truefoundry/trueforge-sdk` (SDK regen already adds this via `pnpm changeset:sdk-regen`)
+- `packages/frontend` → `@truefoundry/trueforge` (UI is bundled into the server tarball)
+
+Skip when:
+
+- The PR already adds `.changeset/*.md`
+- Changes are docs, `AGENTS.md`, CI/workflows, charts, docker-compose, or `packages/local-sandbox` only
+- The PR is a Version Packages / `changeset-release/*` release PR
+
+## CI and release wiring
+
+If a workspace package is added, renamed, or moved, flag unless CI package path filters, matrix package ids, and root `test:*` scripts in `.github/workflows/ci.yml` and root `package.json` stay synchronized.
+
+If the change touches release, pack, or publish wiring, flag if it would break dist-free host development, `pnpm smoke`, or packed CJS/ESM consumers of `@truefoundry/trueforge-core`.
+
+If `docker-compose.yml` or `docker-compose.dev.yml` changes, flag when shared Postgres/Redis settings (image versions, health checks, `env_file`) drift. Intentional differences (app services, data paths, project `name`, host ports, in-network `POSTGRES_HOST` / `REDIS_URL`) must stay explicit. `docker-compose.yml` may read `packages/trueforge/.env` but must override container connectivity so host-dev localhost values are not used inside the smoke-test stack.
+
+## Types, schemas, and ownership
+
+If types or schemas change, flag when `packages/trueforge-core`, `packages/frontend`, `packages/trueforge`, or `patches` is updated without the other affected layers.
+
+Flag TypeScript that uses `as T`, `as unknown as T`, non-null `!`, or `as never` to silence type errors. Implementations must use sound contracts, guards, or corrected types.
+
+If a `catch` throws a new error, flag unless the new error sets `{ cause: caught }`.
+
+Flag duplicate type, schema, helper, or contract definitions and forwarding shims that hide ownership. Each must have one canonical owner.
+
+`AgentChatServer`, `AgentBuilderServer`, catalog ports, session/turn DTOs, and stream events must be defined only in `@truefoundry/assistant-ui-runtime` (`src/server/types.ts` / `events.ts`). Flag hand-written parallel definitions in `@truefoundry/trueforge-ui`. That package may only re-export them from `src/server/types.ts`. React wiring (`ServerContext`, `ShellModeContext`, `TrueForgeServerConfig`) may import those types; it must not redefine ports.
+
+Flag runtime types backed by Zod schemas that are duplicated as hand-written interfaces or indirect utility-type chains. They must be named `z.infer<typeof Schema>` aliases.
+
+## Modules, dead code, generated files
+
+Flag `require()`, `require.resolve()`, or lint suppressions used to bypass import checks. Modules must use static `import` and `import type`.
+
+If a change makes code unused, flag leftover exports, files, documentation, duplicates, or “just in case” shims. Dead code must be removed in the same change.
+
+Flag manual edits to `.github/fern/openapi/openapi.json`, `docs/openapi.json`, or `packages/trueforge-sdk`. Those are autogenerated in CI. Both OpenAPI copies must stay identical.
+
+## Tests and APIs
+
+Flag tests inlined under `src`. Tests must live under a package-top-level `test` or `tests` directory that mirrors `src`.
+
+Flag functions with more than one parameter of the same type passed positionally (e.g. `f(a: string, b: string)`). They must take a single options object.
+
+Flag `z.union` when every member carries a shared literal discriminator field. Use `z.discriminatedUnion` in that case.
+
+Flag HTTP/OpenAPI wire shapes (path params, query params, request/response JSON fields) and database identifiers (table/column names, persisted jsonb document keys) that are not `snake_case`.
diff --git a/AGENTS.md b/AGENTS.md
index 6e3be15a6..bda083a68 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,7 @@
- Workspace tasks MUST use `package.json` scripts; add a script when a missing workflow is repeatable like the existing commands, not ad hoc commands.
- CI package path filters, matrix package ids, and root scripts `test:*` in `.github/workflows/ci.yml` and root `package.json` MUST stay synchronized when a workspace package is added, renamed, or moved; the `store` filter sync rule lives in `packages/trueforge-core/src/agent-session/store/AGENTS.md`.
- Release wiring MUST keep dist-free host development, `pnpm smoke`, and packed CJS/ESM consumers of `@truefoundry/trueforge-core` working without changes.
+- PRs that change published-package code (`packages/trueforge-core`, `packages/trueforge`, `packages/trueforge-ui`, `packages/trueforge-sdk`) or `packages/frontend` (ships inside `@truefoundry/trueforge`) MUST include a new `.changeset/*.md` file (`pnpm changeset`). Docs, CI/workflows, charts, docker-compose, and `packages/local-sandbox`-only changes do not. SDK regeneration already adds `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.
- Shared Postgres/Redis settings in `docker-compose.yml` and `docker-compose.dev.yml` (image versions, health checks, `env_file`) MUST stay synchronized; intentional differences (app services, data paths, project `name`, host ports, in-network `POSTGRES_HOST` / `REDIS_URL`) MUST stay explicit. `packages/trueforge/.env` is the host-dev + secrets source; `docker-compose.yml` may read it but MUST override container connectivity so host-dev localhost values are not used inside the smoke-test stack.
- Changes to types or schemas MUST keep `packages/trueforge-core`, `packages/frontend`, `packages/trueforge`, and `patches` synchronized; they MUST NOT update only one affected layer.
- TypeScript code MUST NOT use assertion escapes such as `as T`, `as unknown as T`, non-null `!`, or `as never` to silence type errors; implementations MUST use sound contracts, guards, or corrected types.
@@ -14,7 +15,7 @@
- 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 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/trueforge-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`.
+- Tests MUST live under a package-top-level `test` or `tests` 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)`).
- Zod unions MUST use `z.discriminatedUnion` whenever every member carries a shared literal discriminator field; `z.union` is only permitted when no such common discriminator exists.
- HTTP/OpenAPI wire shapes (path params, query params, request/response JSON fields) and database identifiers (table/column names, persisted jsonb document keys) MUST use `snake_case`.
diff --git a/README.md b/README.md
index 6e3c2ad84..8f955b9a0 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,9 @@
<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>
+ <a href="https://deepwiki.com/truefoundry/trueforge">
+ <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+ </a>
</p>
# TrueForge
diff --git a/packages/trueforge-core/.cursor/BUGBOT.md b/packages/trueforge-core/.cursor/BUGBOT.md
new file mode 100644
index 000000000..c836a8c9d
--- /dev/null
+++ b/packages/trueforge-core/.cursor/BUGBOT.md
@@ -0,0 +1,32 @@
+# @truefoundry/trueforge-core review rules
+
+Included when reviewing files under `packages/trueforge-core`. Repo-wide rules are in the root `.cursor/BUGBOT.md`.
+
+## Package exports and dist
+
+Flag a `"trueforge-dev"` export condition renamed to `"development"` or `"production"`. Workspace source must stay ESM so that condition can load `src/` without a build. The package publishes from its own root with `files: ["dist", "README.md"]`, so `src/` is never in the tarball; Vite/webpack auto-activate a literal `"development"` condition in dev mode with no consumer opt-in.
+
+Flag `dist/` output that does not expose CJS `.js` and ESM `.mjs` alongside `.d.ts`.
+
+## Optional properties
+
+Top-level public package surfaces (`core`, `agent-session`, and other exported entrypoints) MAY use optional (`?`) properties.
+
+Flag `?` on internal records, snapshots, store INPUT types, and other internal contracts. Absence must be an explicit required `| null` or `| undefined` field. Prefer `null` for domain absence; use `undefined` only when update/patch semantics must distinguish “not provided” from “clear.” Public surfaces must supply those explicit absences when calling inward.
+
+## Session store
+
+`ISessionStore` is the session/turn persistence contract (no streaming/SSE). Postgres, SQLite, and `InMemorySessionStore` must implement it. Shared behavior must live in `storeContractSuite.ts`; backend wrappers only bind a store.
+
+If an `ISessionStore` method, input, error, or semantic changes, flag unless the interface, every implementation, and the contract suite are updated in the same change.
+
+If store or contract-test paths are added, moved, or renamed, flag unless the `store` path filter in `.github/workflows/ci.yml` stays synchronized.
+
+## Durable runtime state
+
+Flag in-memory mutation that runs before the corresponding event is yielded. Durable state must follow:
+
+```ts
+yield event; // consumer persists and may throw
+mutateMemory(); // runs only after persistence succeeds
+```
diff --git a/packages/trueforge/.cursor/BUGBOT.md b/packages/trueforge/.cursor/BUGBOT.md
new file mode 100644
index 000000000..9baea9a94
--- /dev/null
+++ b/packages/trueforge/.cursor/BUGBOT.md
@@ -0,0 +1,85 @@
+# @truefoundry/trueforge review rules
+
+Included when reviewing files under `packages/trueforge`. Repo-wide rules are in the root `.cursor/BUGBOT.md`. Do not re-flag generated OpenAPI/SDK edits; that check lives in the root file.
+
+## Environment variables
+
+Flag `process.env` reads in `packages/trueforge/src/**` other than `config.ts` and documented bootstrap in `cli.ts` (flags applied before `./main` import because config reads env at module load).
+
+Do not flag tests. Do not flag `logger.ts` `NO_COLOR` / `FORCE_COLOR` reads unless that file grows unrelated env reads.
+
+## Transactions
+
+Flag `withTransaction` callbacks that `await` `fetch`, an SDK client, Redis, or other remote I/O (including through helpers). Finish remote work before opening the txn. Callbacks must only do local DB work.
+
+`withTransaction` is `db.transaction().execute(callback)`: commits on resolve, rolls back on throw. Return domain data from the callback; build success `c.json(...)` after it. Flag `return c.json({ error: ... }, status)` inside the callback — a returned Response commits while the client still sees an error. Failures that must undo writes must `throw` (e.g. `HTTPException`).
+
+## OpenAPI naming
+
+Wire fields stay `snake_case` (also covered at repo root). New endpoints must follow this convention; renaming shipped schemas breaks `packages/trueforge-sdk`.
+
+**Paths:** plural kebab under `/api/v1/{collection}`, nested `/…/{id}/{subcollection}`, settings `/api/v1/settings/{collection}`, catalog `/api/v1/catalog/{collection}`. Ids as `{resource}_id`; name-keyed ops use `{name}` — do not mix id and name across verbs for one resource.
+
+If a settings resource is one-per-tenant (e.g. sandbox provider), keep the plural path `/api/v1/settings/sandbox-providers` for URL consistency, but Fern methods are `get`/`upsert` returning a single object — not `list` returning an array.
+
+**Verbs:** `GET` list/get → 200; `POST` create → **201**; `PUT` replace/upsert → 200; `DELETE` → **200** with `DeleteFooResponse` (`{}`), optional `DeleteFoosRequestQuery`; actions `POST /{id}/{action}`.
+
+**Schemas** (resource `Foo`, collection `foos`; item OpenAPI name is PascalCase singular):
+
+| Operation | Request | Response |
+| ----------------------- | ----------------------------------- | ----------------------------------------- |
+| `GET /foos` | `ListFoosRequestQuery` (if any) | `ListFoosResponse` |
+| `POST /foos` | `CreateFooRequest` | `GetFooResponse` (or `CreateFooResponse`) |
+| `GET /foos/{foo_id}` | — | `GetFooResponse` |
+| `PUT` upsert/replace | `PutFooRequest` | `GetFooResponse` (or `PutFooResponse`) |
+| `DELETE /foos/{foo_id}` | `DeleteFoosRequestQuery` (optional) | `DeleteFooResponse` (`{}`) |
+
+Prefer reusing `GetFooResponse` when create/update return the same item.
+
+**Request body vs manifest:** `FooManifest` is only the persisted jsonb document. Flag create/put bodies that flatten manifest fields onto the request root or alias the request schema to `FooManifest`. They must be `CreateFooRequest` / `PutFooRequest` with an explicit wrapper:
+
+```ts
+{
+ manifest: FooManifest; // stored document only
+ dry_run?: boolean; // operation-level fields live beside manifest
+}
+```
+
+Session/turn-style creates that are not a stored manifest keep a flat `Create*Request` without a `manifest` key.
+
+Settings list → `ListFoosResponse`; chat → `ListAvailableFoosResponse`; catalog → `ListCatalogFoosResponse` / item `CatalogFoo`.
+
+Nested child `Bar`: `ListBarsResponse`, `CreateBarRequest`, `GetBarResponse`; Fern `list_bars`, `create_bar`, …
+
+**Envelopes:** success `{ data: Item | Item[] }` (+ `pagination` via `fernExtensions.ts` token contract); errors `RequestErrorResponse`.
+
+**Fern:** set `x-fern-sdk-group-name` / `x-fern-sdk-method-name` (`list`/`get`/`create`/`update`/`upsert`/`delete` + snake_case actions). Schemas live in `src/schemas/` with matching `.openapi('…')` names; types via `z.infer`.
+
+**No inline object schemas:** flag anonymous `z.object({ … })` nested inside another object. Extract each nested object as a top-level named schema with a meaningful `.openapi('…')` name (e.g. `FooAuth`, `FooManifest`). Primitives, arrays of primitives, and `$ref`s to existing named schemas are fine inline.
+
+**Avoid `allOf`:** new wire schemas must emit flat OpenAPI objects.
+
+- Flag `z.merge` — prefer `z.object({ ...A.shape, ...B.shape })` or leave bases unnamed and `.extend` only then.
+- Flag `.extend()` on a schema that already has `.openapi('Name')` — use `z.object({ ...Base.shape, … })` or leave the base unnamed.
+- Flag `.describe()` on a named `$ref` field (`NameSchema.describe(…)`) — describe the shared schema once, or inline constraints.
+- Discriminated `oneOf` for real polymorphism is fine; flag a one-member `oneOf`. Single-variant unions must be a plain object alias.
+
+## Postgres
+
+Flag temporal columns that are `timestamp` without time zone. Use `timestamptz`.
+
+Flag application timestamps that are not treated as UTC instants. Serialize with `Date.prototype.toISOString()` (always `...Z` with milliseconds).
+
+Flag DB queries inside loops (N+1). Prefer a single batched query, a join, or an `IN`/`ANY` lookup.
+
+Flag Postgres migrations whose `up`/`down` do not start with `SET LOCAL lock_timeout = '5s'`.
+
+## SQLite
+
+Flag JSON projection aliases missing from `client.ts` `JSON_RESULT_COLUMNS`.
+
+Kysely's SqliteAdapter keeps `supportsTransactionalDdl: false`, so Migrator does not wrap migrations. Flag every schema-touching `up`/`down` that does not open `db.transaction()` itself. `PRAGMA foreign_keys` is a no-op inside a transaction — toggle it outside the txn when rebuilding a referenced parent.
+
+## Persisted JSON schemas
+
+If a Zod schema that backs persisted JSON (e.g. `model_provider.manifest`) changes in a breaking way, flag unless the change includes a data migration or rewrite for existing rows.