Skip to content

A curated collection of practical AI projects implementing OCR systems, RAG, AI agents, and other AI use cases.

feat(ai_agents): add TrueForge web research agent tutorial

cyberholicsb188292666d5
diff --git a/ai_agents/trueforge_web_research_briefer/.env.example b/ai_agents/trueforge_web_research_briefer/.env.example
new file mode 100644
index 0000000..f118610
--- /dev/null
+++ b/ai_agents/trueforge_web_research_briefer/.env.example
@@ -0,0 +1,8 @@
+# TrueForge server URL. Local mode default is http://localhost:8790.
+TRUEFORGE_BASE_URL=http://localhost:8790
+
+# The saved agent name to run (created in the TrueForge UI in Setup step 3).
+TRUEFORGE_AGENT=web-research-brief
+
+# Only for hosted mode with OIDC login. Leave unset in local mode.
+# TRUEFORGE_TOKEN=your-oidc-id-token
diff --git a/ai_agents/trueforge_web_research_briefer/.gitignore b/ai_agents/trueforge_web_research_briefer/.gitignore
new file mode 100644
index 0000000..8736474
--- /dev/null
+++ b/ai_agents/trueforge_web_research_briefer/.gitignore
@@ -0,0 +1,5 @@
+.env
+node_modules/
+dist/
+*.log
+.DS_Store
diff --git a/ai_agents/trueforge_web_research_briefer/README.md b/ai_agents/trueforge_web_research_briefer/README.md
new file mode 100644
index 0000000..729524b
--- /dev/null
+++ b/ai_agents/trueforge_web_research_briefer/README.md
@@ -0,0 +1,192 @@
+# Build a Long-Running Agent with TrueForge
+
+![Demo](assests/agent.png)
+
+A runnable web research agent built on [TrueForge](https://github.com/truefoundry/trueforge), the open-source agent harness. You ask a question, the harness plans the turn, searches the web through an MCP tool, fans out to parallel subagents, and builds an interactive one-page brief with sources in a sandbox, streaming every step back.
+
+## Overview
+
+The point of this build is to see the harness do its job. The model is the easy part. TrueForge is the runtime layer around it that runs the full execution loop, routes tools, manages context on long runs, gates sensitive actions, and persists the session so a run survives a reconnect. You configure four resources once (a model, an MCP web-search server, a skill, and a sandbox), save them together as an agent, and run it.
+
+The example agent is a web research briefer. You give it a question or a set of things to compare, and it searches the web, researches each part in parallel, and produces a single interactive page that answers the question with its sources cited. It only reads from the web and never writes back to any external system, so it runs end to end with no write credentials and no risky action, which makes it a safe first agent to build and run. Throughout this guide the agent is saved under the name `web-research-brief`, the name you give it when you save it.
+
+The harness itself is general: the same four building blocks can run almost any kind of agent (a codebase onboarding guide, a dependency or security auditor, an incident triage assistant, a support-ticket drafter, and so on). What changes per use case is which MCP servers and skills you attach and whether the agent takes any write actions; the execution loop, streaming trace, context management, and approval gating you see here work the same way for all of them.
+
+## How It Works
+
+1. You send a research question to the saved agent in the chat.
+2. The harness plans the turn, calls the model, and streams every step back.
+3. It calls the Exa MCP web-search tool to gather sources (loaded on demand, not preloaded).
+4. It fans out to parallel subagents, one per subtopic, each with its own isolated context.
+5. It provisions a sandbox and loads a skill to render an interactive one-page brief. A skill is a reusable instruction pack the agent pulls in only when a task needs it, so it is not clutter in the agent's context the rest of the time. Here the skill is `web-artifacts-builder`, which knows how to turn findings into a self-contained web page, and it runs in the sandbox.
+6. Context stays lean: large tool results offload to sandbox files and old history compacts past a token threshold.
+7. The turn finishes with the final brief plus per-turn token and cost metrics, and every step is a replayable event you can reconnect to.
+
+## Tech Stack
+
+| Layer | Choice |
+|---|---|
+| Agent harness | TrueForge (`npx @truefoundry/trueforge`, local mode, SQLite) |
+| Model | Any configured provider (OpenAI, Anthropic, or Google) |
+| Web search | Exa MCP server (no auth) |
+| Skill | `web-artifacts-builder` (built-in) |
+| Sandbox | Built-in local sandbox (macOS/Linux/WSL); Daytona optional for remote |
+| Runtime | Node.js 22+ (for the local server) |
+| Driver / SDK (optional) | TypeScript, `@truefoundry/trueforge-sdk` (see [Going further](#going-further-drive-it-from-code)) |
+
+## Prerequisites
+
+Read this section carefully. Missing any of these is the usual reason a run fails.
+
+**1. Node.js 22 or newer.** TrueForge's local server runs on it.
+
+```bash
+node --version # must print v22.x or higher
+```
+
+If it is older, install Node 22+ (nvm: `nvm install 22 && nvm use 22`).
+
+**2. A model provider API key.** One of OpenAI, Anthropic, or Google. You paste this into TrueForge Settings, not into this repo. Have the key ready and know which model you want (for example `anthropic/claude-sonnet-4-6` or an OpenAI model you have access to).
+
+**3. A sandbox for the skill.** The brief is rendered by a skill, and skills only run in a sandbox. How you get one depends on your OS:
+
+- **macOS or Linux (including WSL): nothing to do.** TrueForge ships a built-in local sandbox that runs on macOS and Linux, so the skill works with no provider setup.
+- **A remote sandbox (Daytona), only if you want one or can't use the local one.** Create an account at https://www.daytona.io, make an API key with permission to write and delete snapshots and write sandboxes, and paste it into Settings → Sandbox providers. This is optional on macOS/Linux and is the fallback for native Windows.
+
+**4. Exa web search.** Nothing to get. Exa is in TrueForge's connector catalog and needs no auth. You just click Connect.
+
+**Notes and gotchas**
+
+- Local mode has no login and stores data in a local SQLite file. Keep it on `localhost`; it is not hardened for internet exposure.
+- The default local server URL is `http://localhost:8790`.
+- **Native Windows is not supported by the local server today** (it fails to start with an ESM `Received protocol 'c:'` error, and the local sandbox is macOS/Linux only). Run everything inside **WSL2** instead: install/enter Ubuntu, install Node 22+ there, then run `npx @truefoundry/trueforge` from the WSL shell. Your Windows browser still reaches `http://localhost:8790`. Inside WSL the built-in local sandbox works, so no Daytona is needed.
+
+## Setup
+
+### Step 1: Start TrueForge
+
+In a separate terminal, start the local server and leave it running:
+
+```bash
+npx @truefoundry/trueforge
+```
+
+Open http://localhost:8790. In local mode, Settings are open (no login).
+
+> **Make sure you're in TrueForge, not the TrueFoundry platform.** TrueForge's Settings shows exactly four pages: **Models**, **Connectors**, **Skills**, and **Sandbox providers**. If you instead see things like AI Gateway, SSO, Provisioning, or "Revoke all PAT", you're in TrueFoundry's hosted console, a different product. Go back to `http://localhost:8790` from the `npx` server above.
+
+### Step 2: Configure the four building blocks
+
+In the TrueForge UI, set these up once under **Settings**, in this order.
+
+1. **Models.** Settings → Models → pick your provider → Configure → paste your API key → Create.
+2. **Connectors (web search).** Settings → Connectors (this is where you add MCP servers) → find **Exa** → Connect. It needs no auth and moves to Configured.
+3. **Skills.** Settings → Skills → enable **web-artifacts-builder** from the built-in list.
+4. **Sandbox.** On macOS/Linux (including WSL) there is nothing to configure here: the built-in local sandbox is used automatically once you enable the sandbox on the agent. Only configure a **Daytona** provider if you specifically want a remote sandbox.
+
+### Step 3: Compose and save the agent
+
+In the chat composer, assemble the agent and save it so you can reuse it:
+
+1. Pick your model in the composer.
+2. Open the Tools menu, enable the **Exa** connector and the **web-artifacts-builder** skill, and leave **Dynamic sub-agents** on.
+3. Send a test message, for example: `Compare the open-source LLM observability tools Langfuse, Arize Phoenix, and Helicone on features, self-hosting, and pricing, then write a one-page brief with sources.`
+4. Click **Save Agent**, name it `web-research-brief`, add the instructions below, and save. It now appears in your **Agents Library**, where you can Try or Edit it.
+
+Suggested instructions:
+
+```text
+You are a web research assistant. Given a topic or question, use Exa to search the web and pull content from the most relevant, recent sources. When the request compares several items, research each one in parallel, then synthesize the findings into a clear one-page brief with sources.
+```
+
+## Run it
+
+Open the saved agent from the **Agents Library** (or just keep chatting in the same session), send a research question, and watch the harness work. Try:
+
+```text
+Compare the open-source LLM observability tools Langfuse, Arize Phoenix, and Helicone on features, self-hosting, and pricing, then write a one-page brief with sources.
+```
+
+You can ask anything; the comparison shape is what makes it fan out to parallel subagents.
+
+## What you'll see
+
+You can watch each part of the run in the chat:
+
+- The agent calls out to **Exa** to search the web.
+- It spawns a **subagent per item** being compared, shown under **Agent steps**, each researching in parallel.
+- The answer **streams in** as it is written.
+- A **sandbox** comes up and the **web-artifacts-builder** skill renders the final interactive one-page brief with its sources.
+- The run reports its **token and cost totals**.
+
+
+## Going further: drive it from code
+
+Everything above happens in the UI, which is all you need. If you want to run the same saved agent programmatically, this repo includes a small TypeScript driver (`driver.ts`) that opens a session, streams one turn, and prints the whole trace.
+
+This part needs `npm` available, and on Windows it must run from the WSL shell (see the Windows note in Prerequisites).
+
+### Install
+
+In this folder:
+
+```bash
+npm install
+cp .env.example .env
+```
+
+Then open `.env` and set `TRUEFORGE_BASE_URL` (leave the default `http://localhost:8790` for local mode). No token is needed locally.
+
+### Run
+
+With the TrueForge server running and the agent saved:
+
+```bash
+npm start -- "Compare the open-source LLM observability tools Langfuse, Arize Phoenix, and Helicone on features, self-hosting, and pricing, then write a one-page brief with sources."
+```
+
+You can pass any question as the argument. With no argument it uses a default question. Research turns run long; the driver sets the SDK timeout to 600 seconds, so do not lower it.
+
+### The printed trace
+
+The driver prints a labeled trace of the whole run:
+
+- `turn.created` — the run starts.
+- `mcp.initialize` — the harness connected to Exa.
+- `sandbox.created` — a sandbox was provisioned (once per session).
+- `subagent: ...` — each parallel subagent that spawned (from `thread.created`).
+- The root agent's reply streaming in, token by token.
+- `tool.response` — a tool returned a result.
+- `turn.done` — the final brief, plus per-turn token and cost metrics.
+
+### Reconnect to a running session
+
+Every step is a persisted event, so a dropped stream is recoverable. Persist `session.id`, `turnId`, and the last sequence number; on reconnect call `getTurn`, then `subscribeToTurn({ afterSequenceNumber })` if it is still running, or `listTurnEvents` if it already finished. The pattern is in `driver.ts`.
+
+### Project structure
+
+```
+trueforge_web_research_briefer/
+├── driver.ts # opens a session, streams the turn, prints the trace
+├── package.json # SDK + tsx
+├── .env.example # TRUEFORGE_BASE_URL (+ optional token for hosted mode)
+├── .gitignore
+└── README.md
+```
+
+### Customising
+
+- Swap the web-search MCP server for another catalog connector.
+- Swap `web-artifacts-builder` for a different skill (for example a PDF skill) to change the deliverable.
+- Attach a write connector and gate it to make the approval pause live.
+- Point the driver at a saved agent by name, or pass an inline spec (see `driver.ts`).
+
+## Resources
+
+- TrueForge source (open source): https://github.com/truefoundry/trueforge
+- TrueForge introduction: https://trueforge.dev/introduction
+- Quickstart (build the agent in the UI): https://trueforge.dev/quickstart
+- Create an agent (every option): https://trueforge.dev/create-agent/overview
+- SDK quickstart: https://trueforge.dev/api/quickstart
+- Use an agent (streaming, approvals, reconnects): https://trueforge.dev/api/use-agent
+- Harness capabilities (context engineering): https://trueforge.dev/key-features/overview
diff --git a/ai_agents/trueforge_web_research_briefer/assests/agent.png b/ai_agents/trueforge_web_research_briefer/assests/agent.png
new file mode 100644
index 0000000..afccba7
Binary files /dev/null and b/ai_agents/trueforge_web_research_briefer/assests/agent.png differ
diff --git a/ai_agents/trueforge_web_research_briefer/driver.ts b/ai_agents/trueforge_web_research_briefer/driver.ts
new file mode 100644
index 0000000..674681c
--- /dev/null
+++ b/ai_agents/trueforge_web_research_briefer/driver.ts
@@ -0,0 +1,150 @@
+/**
+ * Web research briefer - TrueForge driver.
+ *
+ * Opens a session on the saved `web-research-brief` agent, streams one research
+ * turn, and prints a labeled trace of every step the harness takes, then the
+ * final brief and per-turn metrics. That trace is the source material for the
+ * article's Loop and Trace sections.
+ *
+ * Run (with the TrueForge server running and the agent saved):
+ * npm start -- "your research question"
+ *
+ * Verified against https://trueforge.dev/api/use-agent
+ */
+
+import "dotenv/config";
+import {
+ TrueForge,
+ TrueForgeApi,
+ isEventDelta,
+ mergeEventDelta,
+} from "@truefoundry/trueforge-sdk";
+
+const BASE_URL = process.env.TRUEFORGE_BASE_URL ?? "http://localhost:8790";
+const AGENT_NAME = process.env.TRUEFORGE_AGENT ?? "web-research-brief";
+const TOKEN = process.env.TRUEFORGE_TOKEN; // only needed for hosted mode (OIDC)
+
+const DEFAULT_QUESTION =
+ "Compare the open-source LLM observability tools Langfuse, Arize Phoenix, and Helicone on features, self-hosting, and pricing, then write a one-page brief with sources.";
+
+const question = process.argv.slice(2).join(" ").trim() || DEFAULT_QUESTION;
+
+const client = new TrueForge({
+ baseUrl: BASE_URL,
+ timeoutInSeconds: 600, // research turns run long; do not lower this
+ ...(TOKEN ? { token: TOKEN } : {}),
+});
+
+// Per-stream event index, keyed by event id. Model output arrives as an empty
+// `model.message` base followed by `model.message.delta` fragments that share
+// the base id; we merge deltas into the base so `events` always holds the full
+// message. The pause handlers below look tool calls up in this same index.
+const events = new Map<string, TrueForgeApi.TurnStreamingEvent>();
+
+let turnId: string | undefined;
+let lastSequenceNumber = 0;
+
+function log(label: string, detail = ""): void {
+ console.log(`\n[${label}]${detail ? " " + detail : ""}`);
+}
+
+async function main(): Promise<void> {
+ console.log(`TrueForge : ${BASE_URL}`);
+ console.log(`Agent : ${AGENT_NAME}`);
+ console.log(`Question : ${question}\n`);
+
+ const { data: session } = await client.sessions.create({
+ agent: { name: AGENT_NAME },
+ });
+ console.log(`Session : ${session.id}`);
+
+ const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: "user.message", content: question }],
+ });
+
+ for await (const { data: event, id } of stream.withMetadata()) {
+ if (id != null) lastSequenceNumber = Number(id);
+
+ // Keep the event index current (merge deltas, store everything else).
+ if (isEventDelta(event)) {
+ const base = events.get(event.id);
+ if (base) mergeEventDelta(base, event);
+ } else {
+ events.set(event.id, event);
+ }
+
+ switch (event.type) {
+ case "turn.created":
+ turnId = event.turnId;
+ log("turn.created", `turn ${event.turnId}`);
+ break;
+
+ case "mcp.initialize":
+ log(
+ "mcp.initialize",
+ (event.mcpServers ?? []).map((s: { name?: string }) => s.name).join(", "),
+ );
+ break;
+
+ case "sandbox.created":
+ log("sandbox.created", event.sandboxId ?? "");
+ break;
+
+ case "thread.created":
+ log("subagent", `${event.title} (thread ${event.threadId})`);
+ break;
+
+ case "thread.done":
+ log("subagent.done", `${event.title} (thread ${event.threadId})`);
+ break;
+
+ case "tool.response":
+ log("tool.response", `call ${event.toolCallId}`);
+ break;
+
+ case "model.message.delta":
+ // Stream only the root agent's reply to stdout; subagents run in their
+ // own threads and their intermediate output stays out of the console.
+ if (event.threadId === "main" && event.content) {
+ process.stdout.write(event.content);
+ }
+ break;
+
+ case "tool.approval_required":
+ // web-research-brief has no gated tool, so this never fires here. When
+ // you attach a write connector and gate it, resume with a new turn
+ // carrying a `user.tool_approval` per pending call (see README).
+ log("tool.approval_required", "would pause for human sign-off");
+ break;
+
+ case "turn.done": {
+ const state = event.state;
+ log("turn.done", `status ${state.status}`);
+ if (state.status === "done") {
+ console.log("\n----- brief -----\n");
+ console.log(state.output?.content ?? "(no text output)");
+ const m = state.metrics;
+ if (m) {
+ console.log("\n----- metrics -----");
+ console.log(`tokens : ${m.totalTokens ?? "?"}`);
+ console.log(`cost : $${m.totalCostInUsd ?? "?"}`);
+ }
+ } else if (state.status === "error") {
+ console.error(`\nTurn error: ${state.message}`);
+ }
+ break;
+ }
+
+ default:
+ break;
+ }
+ }
+
+ console.log(`\nLast sequence number: ${lastSequenceNumber}`);
+ console.log(`Turn id : ${turnId ?? "(none)"}`);
+}
+
+main().catch((err) => {
+ console.error("\nDriver failed:", err);
+ process.exit(1);
+});
diff --git a/ai_agents/trueforge_web_research_briefer/package-lock.json b/ai_agents/trueforge_web_research_briefer/package-lock.json
new file mode 100644
index 0000000..af4d41e
--- /dev/null
+++ b/ai_agents/trueforge_web_research_briefer/package-lock.json
@@ -0,0 +1,591 @@
+{
+ "name": "trueforge-web-research-briefer",
+ "version": "1.0.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "trueforge-web-research-briefer",
+ "version": "1.0.0",
+ "dependencies": {
+ "@truefoundry/trueforge-sdk": "^0.1.0",
+ "dotenv": "^16.4.0"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "tsx": "^4.19.0",
+ "typescript": "^5.6.0"
+ }
+ },
+ "node_modules/@esbuild/aix-ppc64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
+ "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "aix"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-arm": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
+ "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
+ "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
+ "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/darwin-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
+ "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/darwin-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
+ "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/freebsd-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
+ "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/freebsd-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
+ "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-arm": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
+ "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
+ "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-ia32": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
+ "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-loong64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
+ "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
+ "cpu": [
+ "loong64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-mips64el": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
+ "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
+ "cpu": [
+ "mips64el"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-ppc64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
+ "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-riscv64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
+ "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
+ "cpu": [
+ "riscv64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-s390x": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
+ "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
+ "cpu": [
+ "s390x"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
+ "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/netbsd-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
+ "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/netbsd-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
+ "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openbsd-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
+ "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openbsd-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
+ "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openharmony-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
+ "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openharmony"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/sunos-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
+ "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "sunos"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-arm64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
+ "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-ia32": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
+ "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-x64": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
+ "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@truefoundry/trueforge-sdk": {
+ "version": "0.1.3",
+ "resolved": "https://registry.npmjs.org/@truefoundry/trueforge-sdk/-/trueforge-sdk-0.1.3.tgz",
+ "integrity": "sha512-YW1I8CWOoDzIqhl8PEZYUnahibSdIlo0IPXX5A3zNT1QBSscn/jGutzB90jqgWQrPr8HKZcDF5KthnG4hmUtXA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=22"
+ }
+ },
+ "node_modules/@types/node": {
+ "version": "22.20.1",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.1.tgz",
+ "integrity": "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": "~6.21.0"
+ }
+ },
+ "node_modules/dotenv": {
+ "version": "16.6.1",
+ "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
+ "integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
+ "license": "BSD-2-Clause",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://dotenvx.com"
+ }
+ },
+ "node_modules/esbuild": {
+ "version": "0.28.2",
+ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
+ "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "bin": {
+ "esbuild": "bin/esbuild"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "optionalDependencies": {
+ "@esbuild/aix-ppc64": "0.28.2",
+ "@esbuild/android-arm": "0.28.2",
+ "@esbuild/android-arm64": "0.28.2",
+ "@esbuild/android-x64": "0.28.2",
+ "@esbuild/darwin-arm64": "0.28.2",
+ "@esbuild/darwin-x64": "0.28.2",
+ "@esbuild/freebsd-arm64": "0.28.2",
+ "@esbuild/freebsd-x64": "0.28.2",
+ "@esbuild/linux-arm": "0.28.2",
+ "@esbuild/linux-arm64": "0.28.2",
+ "@esbuild/linux-ia32": "0.28.2",
+ "@esbuild/linux-loong64": "0.28.2",
+ "@esbuild/linux-mips64el": "0.28.2",
+ "@esbuild/linux-ppc64": "0.28.2",
+ "@esbuild/linux-riscv64": "0.28.2",
+ "@esbuild/linux-s390x": "0.28.2",
+ "@esbuild/linux-x64": "0.28.2",
+ "@esbuild/netbsd-arm64": "0.28.2",
+ "@esbuild/netbsd-x64": "0.28.2",
+ "@esbuild/openbsd-arm64": "0.28.2",
+ "@esbuild/openbsd-x64": "0.28.2",
+ "@esbuild/openharmony-arm64": "0.28.2",
+ "@esbuild/sunos-x64": "0.28.2",
+ "@esbuild/win32-arm64": "0.28.2",
+ "@esbuild/win32-ia32": "0.28.2",
+ "@esbuild/win32-x64": "0.28.2"
+ }
+ },
+ "node_modules/fsevents": {
+ "version": "2.3.3",
+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+ "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+ }
+ },
+ "node_modules/tsx": {
+ "version": "4.23.12",
+ "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.12.tgz",
+ "integrity": "sha512-FDf4L4sYzKtzWYhU/Xm0AQFdTjdIxNo9ElTf2mxXM6k8YMHXzYUe4yODVaXP4V9uMFbVg8c0qyBccK2OOxb45Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "esbuild": "~0.28.0"
+ },
+ "bin": {
+ "tsx": "dist/cli.mjs"
+ },
+ "engines": {
+ "node": ">=18.0.0"
+ },
+ "optionalDependencies": {
+ "fsevents": "~2.3.3"
+ }
+ },
+ "node_modules/typescript": {
+ "version": "5.9.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ },
+ "node_modules/undici-types": {
+ "version": "6.21.0",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+ "dev": true,
+ "license": "MIT"
+ }
+ }
+}
diff --git a/ai_agents/trueforge_web_research_briefer/package.json b/ai_agents/trueforge_web_research_briefer/package.json
new file mode 100644
index 0000000..c6bf446
--- /dev/null
+++ b/ai_agents/trueforge_web_research_briefer/package.json
@@ -0,0 +1,18 @@
+{
+ "name": "trueforge-web-research-briefer",
+ "version": "1.0.0",
+ "description": "A web research briefer built on the TrueForge agent harness, driven from TypeScript.",
+ "type": "module",
+ "scripts": {
+ "start": "tsx driver.ts"
+ },
+ "dependencies": {
+ "@truefoundry/trueforge-sdk": "^0.1.0",
+ "dotenv": "^16.4.0"
+ },
+ "devDependencies": {
+ "tsx": "^4.19.0",
+ "typescript": "^5.6.0",
+ "@types/node": "^22.0.0"
+ }
+}