glove-foundry 0.0.0 → 0.2.0

package/dist/index.js

@@ -45,7 +45,7 @@ import {
   memoryTopologyStore,
   serializeInboundTransmissionXml,
   writeGeneratedTypes
-} from "./chunk-UNHGCCSA.js";
+} from "./chunk-P65RT7H5.js";
 import {
   FoundryClient,
   FoundryRunHandle,

package/docs/building-with-foundry.md

@@ -5,15 +5,52 @@ Foundry uses the filesystem for code identity and imported values for code relat
 ## Create and run
 
 ```bash
-npx glove foundry support-workforce
+npx glove foundry init support-workforce
 cd support-workforce
-pnpm install
 cp .env.example .env.local
+pnpm install
 pnpm dev
 ```
 
 `glove foundry dev` discovers the source graph, derives identities, checks types and conventions, generates `.foundry/routes.d.ts`, and starts the runtime and inspector.
 
+The generated project depends on the exact Glove versions the `glove-foundry` that created it was built against. That is not tidiness: a narrower range makes the package manager install a second copy of `glove-js`, and the two `JsSession` classes then fail to type-match.
+
+### Templates
+
+| `--template` | What you get |
+| --- | --- |
+| `travel-concierge` (default) | A travel agent that searches flights, installs a calendar application, replies over a chat transmission, remembers the traveller, wakes on a schedule, and owns a sandboxed VFS and REPL. One example per convention. |
+| `minimal` | One agent and one tool. |
+
+The travel concierge runs before you configure a provider — `lib/demo-model.ts` answers deterministically until `OPENROUTER_API_KEY` is set, so the first run produces a real trace with real tool calls.
+
+### Adding Foundry to an existing Next.js app
+
+```bash
+cd my-next-app
+npx glove foundry init . --target nextjs   # or just: npx glove foundry init .
+```
+
+A directory holding a Next.js app is detected, so `--target` is usually unnecessary. Foundry then joins the project rather than taking it over:
+
+| Path | What lands there |
+| --- | --- |
+| `foundry/agents/**` | The agents |
+| `foundry/foundry.application.ts` | Data adapter, accounts, routes |
+| `foundry/package.json` | `{"type":"module"}`, scoping ESM to the agents |
+| `foundry.config.mts` | Points the runtime at `foundry/agents` |
+| `lib/foundry.ts` | A typed client your app imports |
+| `app/api/<agent>/route.ts` | An example route handler |
+
+Your `package.json` keeps its name, scripts, and dependencies; it gains `foundry:dev`, `foundry:start`, and the Glove packages. Nothing it already owns is overwritten.
+
+The runtime is a separate process from `next dev`, deliberately — it holds durable state and should not restart when a component changes. The app reaches it over HTTP through `lib/foundry.ts`, so no part of the agent graph is bundled into your app, and `FoundryRoutes` stays a type-only import.
+
+Two details make this work in a Next.js project specifically. A Next.js app is not `"type": "module"`, so Node would load the agents through the CommonJS resolver and fail on Foundry's ESM-only export map; the nested `foundry/package.json` scopes ESM to the agent tree, and `.mts` makes the config unambiguous whatever the root declares.
+
+In production, set `FOUNDRY_URL` to wherever the runtime is deployed and keep it private to your network — the inspector is a development surface.
+
 ## The filesystem is the static registry
 
 ```text

package/docs/inspector.md

@@ -27,7 +27,9 @@ Open **Runs**, then choose one invocation. The run detail starts with a four-pha
 3. Agent work: observable model and tool work occurred.
 4. Completed, failed, cancelled, or still in progress.
 
-The event trace below the spine is collapsed by default. Expand an event when you need its adapter payload. The inspector shows observable intent, actions, and outcomes; it does not expose a model's private hidden chain-of-thought.
+The event trace below the spine is collapsed by default. Each row carries its wall-clock time and its offset from the start of the run, so a slow phase is visible without arithmetic. Filter the trace by event category, expand an event when you need its adapter payload, and copy a payload straight from the expanded row. The inspector shows observable intent, actions, and outcomes; it does not expose a model's private hidden chain-of-thought.
+
+A failed run states its error above the spine rather than only inside the recorded output. A run that is still going says so and keeps a running duration. **Run again** reopens the run drawer with the same instance and message.
 
 ## Starting work
 
@@ -38,9 +40,40 @@ Use **New run** from any page. Select a definition and either:
 
 The inspector reuses that instance's latest conversation or creates its first conversation, sends the message, then navigates directly to the new run.
 
+## Filtering runs
+
+The **Runs** page keeps its filters in the query string, so any view is a link you can send or bookmark:
+
+| Parameter | Values |
+| --- | --- |
+| `status` | `running`, `completed`, `failed`, or `cancelled`. `running` also covers pending runs. |
+| `source` | Any recorded source kind, such as `direct`, `transmission`, `activation`, or `spawn`. |
+| `q` | Free text matched against the agent, run id, instance id, and recorded input. |
+
+`/runs?status=failed&q=invoice` opens directly on the failed runs mentioning an invoice. The status tabs carry live counts, and each row shows the run's duration alongside a relative start time.
+
 ## Live updates and search
 
-The inspector subscribes to `/api/events` with server-sent events and also performs a low-frequency reconciliation. Press `Command-K` or `Control-K` to search pages, definitions, instances, and retained runs.
+The inspector subscribes to `/api/events` with server-sent events and also performs a low-frequency reconciliation. A busy run emits many events, so they are coalesced into one refresh rather than one repaint each.
+
+A refresh preserves what you are doing: scroll position, an expanded event, an open `Output` panel, and the text and caret in a filter box all survive it. Relative timestamps and the duration of an in-flight run tick every second without a repaint.
+
+Press `Command-K` or `Control-K` to search pages, definitions, instances, and retained runs.
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `j` / `k` | Move down and up the current list |
+| `Enter` or `o` | Open the highlighted row |
+| `/` | Focus the run filter, or open search elsewhere |
+| `c` | Start a run |
+| `r` | Refresh runtime data |
+| `Command-K` / `Control-K` | Search |
+| `Escape` | Close the drawer or search |
+| `Command-Enter` | Submit the run drawer |
+
+Every truncated identifier in the inspector has a copy button, so the full run, instance, or conversation id is always retrievable.
 
 ## Operator API used by the inspector
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glove-foundry",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "An Effect-native, file-routed framework for typed, observable Glove agent applications",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,7 @@
   "files": [
     "dist",
     "docs",
+    "templates",
     "THIRD_PARTY_NOTICES.md"
   ],
   "keywords": [
@@ -62,14 +63,14 @@
     "station-schedules": "^2.2.0",
     "tsx": "^4.21.0",
     "zod": "^4.3.6",
-    "glove-core": "3.6.0",
-    "glove-js": "0.4.0",
     "glove-mcp": "1.1.0",
+    "glove-js": "0.4.0",
+    "glove-memory": "1.1.0",
+    "glove-core": "3.6.0",
     "glove-lisp": "0.4.0",
     "glove-mesh": "0.1.1",
-    "glove-memory": "1.1.0",
-    "glove-working-environment": "0.6.0",
-    "glove-python": "0.3.0"
+    "glove-python": "0.3.0",
+    "glove-working-environment": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",

package/templates/minimal/README.md

@@ -0,0 +1,58 @@
+# {{projectName}}
+
+A [Glove Foundry](https://github.com/porkytheblack/glove/tree/main/packages/glove-foundry) application.
+
+```bash
+cp .env.example .env.local     # add your OPENROUTER_API_KEY
+{{installCommand}}
+{{devCommand}}
+```
+
+Then open **http://127.0.0.1:4141** and press **Start a run**.
+
+## The one idea to understand first
+
+Foundry separates a **definition** (code — what an agent can assemble, at `agents/assistant/agent.ts`) from an **instance** (data — one persisted identity with its own context, installed apps, and conversations). One definition serves many instances.
+
+**The filesystem is the registry.** `agents/assistant/agent.ts` *is* the agent `assistant`. There are no string ids to keep in sync.
+
+## Adding capabilities
+
+Any file matching these names under an agent folder is discovered automatically. Each default-exports one definition, and the **filename becomes its id**.
+
+| File | Defines | Helper |
+| --- | --- | --- |
+| `agent.ts` | The agent | `defineAgent` |
+| `tools/*.tool.ts` | A tool any agent can mount | `defineSharedTool` |
+| `apps/*.app.ts` | An installable capability bundle | `defineApp` |
+| `transmissions/*.transmission.ts` | An external transport shape | `defineTransmission` |
+| `events/*.event.ts` | A transmission event | `defineTransmissionEvent` |
+| `predicates/*.predicate.ts` | An inbound match rule | `defineTransmissionPredicate` |
+| `mcp/*.mcp.ts` | An MCP server entry | `defineMcp` |
+| `memory/*.memory.ts` | A memory profile | `defineMemory` |
+| `layers/*.layer.ts` | Native Glove setup | `defineLayer` |
+| `subscribers/*.subscriber.ts` | An observer | `defineSubscriber` |
+| `schedules/*.ts` | Recurring or future work | `defineSchedule` |
+
+Create the file, add it to `composeAgent(...)`, and the dev server picks it up and regenerates types.
+
+Want a worked example with a calendar application, a chat transport, memory, a schedule, and a sandboxed REPL? Scaffold the travel concierge:
+
+```bash
+npx glove-foundry init my-concierge --template travel-concierge
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `{{devCommand}}` | Discover agents, typecheck, generate routes, serve the runtime and inspector |
+| `{{startCommand}}` | Run without file watching |
+| `{{lintCommand}}` | Lint, including the Foundry file-routing rules |
+| `{{typecheckCommand}}` | `tsc --noEmit` |
+
+## Documentation
+
+- [Building with Foundry](https://github.com/porkytheblack/glove/blob/main/packages/glove-foundry/docs/building-with-foundry.md)
+- [Architecture](https://github.com/porkytheblack/glove/blob/main/packages/glove-foundry/docs/architecture.md)
+- [The inspector](https://github.com/porkytheblack/glove/blob/main/packages/glove-foundry/docs/inspector.md)

package/templates/minimal/agents/assistant/agent.ts

@@ -0,0 +1,28 @@
+import { MemoryStore } from "glove-core";
+import { createAdapter } from "glove-core/models/providers";
+import { composeAgent, defineAgent } from "glove-foundry";
+import currentTime from "./tools/current-time.tool.js";
+
+/**
+ * The file path is the identity: this is the agent `assistant`.
+ *
+ * Every field may be a value or a function; a function is called per run with
+ * the request context. Add capabilities as sibling files — `tools/*.tool.ts`,
+ * `apps/*.app.ts`, `memory/*.memory.ts` — and compose them below.
+ */
+export default defineAgent({
+  description: "A general-purpose Glove assistant",
+  components: composeAgent(currentTime),
+  store: ({ conversationId }) => new MemoryStore(`assistant:${conversationId}`),
+  model: () => createAdapter({
+    provider: "openrouter",
+    model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4.1-mini",
+    stream: true,
+  }),
+  systemPrompt: (_agent, { message, history }) => [
+    "You are a precise, practical assistant.",
+    `Current request: ${message.text}`,
+    `Prior messages: ${history.length}`,
+  ].join("\n"),
+  compactionInstructions: () => "Preserve decisions, open work, and important context.",
+});

package/templates/minimal/agents/assistant/tools/current-time.tool.ts

@@ -0,0 +1,17 @@
+import { defineSharedTool } from "glove-foundry";
+import { z } from "zod";
+
+/** One file, one default export. The filename is the id: `current-time`. */
+const currentTime = defineSharedTool({
+  description: "Return the current ISO timestamp",
+  tool: {
+    name: "current_time",
+    description: "Return the current ISO timestamp",
+    inputSchema: z.object({}),
+    async do() {
+      return { status: "success" as const, data: new Date().toISOString() };
+    },
+  },
+});
+
+export default currentTime;

package/templates/minimal/env.example

@@ -0,0 +1,2 @@
+OPENROUTER_API_KEY=
+OPENROUTER_MODEL=openai/gpt-4.1-mini

package/templates/minimal/foundry.application.ts

@@ -0,0 +1,12 @@
+import { MemoryFoundryDataAdapter, defineApplication } from "glove-foundry";
+
+/** Swap this adapter for your own to persist instances across restarts. */
+export const data = new MemoryFoundryDataAdapter();
+
+export default defineApplication({
+  name: "{{projectName}}",
+  data,
+  accounts: [],
+  routes: [],
+  bindings: [],
+});

package/templates/minimal/foundry.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "glove-foundry/config";
+
+export default defineConfig({
+  server: { port: 4141 },
+  execution: { pollIntervalMs: 100, maxConcurrent: 4 },
+});

package/templates/minimal/gitignore

@@ -0,0 +1,3 @@
+node_modules
+.env.local
+.foundry/manifest.json

package/templates/travel-concierge/README.md

@@ -0,0 +1,203 @@
+# {{projectName}}
+
+A [Glove Foundry](https://github.com/porkytheblack/glove/tree/main/packages/glove-foundry) application. The example agent is a **travel concierge**: it searches flights, checks a calendar, remembers the traveller, replies over a chat transport, and wakes itself on a schedule.
+
+It runs before you configure anything — there is a built-in demo model, so you get real runs and a real event trace with no API key.
+
+```bash
+cp .env.example .env.local     # optional: add OPENROUTER_API_KEY for real answers
+{{installCommand}}
+{{devCommand}}
+```
+
+Then open **http://127.0.0.1:4141** and press **Start a run**.
+
+---
+
+## The one idea to understand first
+
+Foundry separates two things that most frameworks merge:
+
+| | What it is | Where it lives | Changes when |
+| --- | --- | --- | --- |
+| **Definition** | Code. What an agent *can* assemble. | `agents/concierge/agent.ts` | You edit a file |
+| **Instance** | Data. One persisted identity, with its own context, installed apps, and conversations. | Your data adapter | You call the API or use the inspector |
+
+One definition serves many instances. Two travellers can run the same concierge with different calendars, budgets, and chat accounts — without a branch in your code.
+
+**The filesystem is the registry.** `agents/concierge/agent.ts` *is* the agent `concierge`. There are no string ids to keep in sync, and renaming a file breaks the import at compile time rather than at 3am.
+
+---
+
+## What is in this project
+
+```
+agents/concierge/
+  agent.ts                              the agent. start here
+  composition.ts                        composeAgent(...) — what it is built from
+  tools/find-flights.tool.ts            a shared tool
+  apps/calendar.app.ts                  an application an instance installs
+  transmissions/messaging.transmission.ts   Telegram/WhatsApp-shaped transport
+  events/message-received.event.ts      an inbound event
+  events/message-sent.event.ts          an outbound event
+  predicates/mentions-trip.predicate.ts routing logic, kept out of the agent
+  memory/traveller.memory.ts            ambient context across conversations
+  schedules/trip-countdown.ts           recurring work
+  layers/trip-context.layer.ts          direct access to the native Glove runtime
+  subscribers/usage.subscriber.ts       observation without behaviour change
+  workbench.ts                          the agent's VFS + JavaScript REPL
+  topology.ts                           accounts and routes (runtime data)
+
+foundry.application.ts                  data adapter, accounts, routes
+foundry.config.ts                       port, execution policy
+lib/demo-model.ts                       keyless model — delete once you have a key
+src/client.ts                           a typed client for these agents
+.foundry/routes.d.ts                    generated. do not edit
+```
+
+### Conventions
+
+Any file matching these names under an agent folder is discovered automatically. Each one default-exports a single definition, and its **filename becomes its id**. Nested folders nest the id: `tools/calendar/today.tool.ts` is `calendar/today`.
+
+| File | Defines | Helper |
+| --- | --- | --- |
+| `agent.ts` | The agent | `defineAgent` |
+| `tools/*.tool.ts` | A tool any agent can mount | `defineSharedTool` |
+| `apps/*.app.ts` | An installable capability bundle | `defineApp` |
+| `transmissions/*.transmission.ts` | An external transport shape | `defineTransmission` |
+| `events/*.event.ts` | A transmission event | `defineTransmissionEvent` |
+| `predicates/*.predicate.ts` | An inbound match rule | `defineTransmissionPredicate` |
+| `mcp/*.mcp.ts` | An MCP server entry | `defineMcp` |
+| `memory/*.memory.ts` | A memory profile | `defineMemory` |
+| `layers/*.layer.ts` | Native Glove setup | `defineLayer` |
+| `subscribers/*.subscriber.ts` | An observer | `defineSubscriber` |
+| `schedules/*.ts` | Recurring or future work | `defineSchedule` |
+| `connections/*.connection.ts` | A long-lived inbound worker | `defineConnection` |
+| `actions/*.action.ts` | A playbook action | `definePlaybookAction` |
+
+Every field of `defineAgent` accepts **a value or a function**. A function runs per request with the full context — message, history, instance, installations — which is how one definition adapts without branching inside a prompt.
+
+---
+
+## Things you will want to do
+
+### Add a tool
+
+Create `agents/concierge/tools/weather.tool.ts`, default-export `defineSharedTool({...})`, then add it to `composition.ts`. That is the whole loop — the dev server picks it up and regenerates types.
+
+### Add a second agent
+
+Create `agents/<name>/agent.ts`. It is immediately routable, appears in the inspector, and is added to `FoundryRoutes` for the typed client.
+
+### Give an instance a capability
+
+Applications and MCP servers stay inert until an instance installs one. From the inspector, open the instance and install `calendar`; or over the API:
+
+```bash
+curl -X PUT http://127.0.0.1:4141/api/installations \
+  -H 'content-type: application/json' \
+  -d '{"agentId":"<instance-id>","kind":"application","id":"calendar","config":{"calendarId":"primary"}}'
+```
+
+### Connect a real chat app
+
+`transmissions/messaging.transmission.ts` has the shape; only `deliver` needs a real call.
+
+```ts
+function deliver(input: { threadId: string; text: string }, provider: string) {
+  return Effect.tryPromise(async () => {
+    const response = await fetch(
+      `https://api.telegram.org/bot${process.env.TELEGRAM_BOT_TOKEN}/sendMessage`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ chat_id: input.threadId, text: input.text }),
+      },
+    );
+    const body = await response.json() as { result: { message_id: number } };
+    return { externalMessageId: String(body.result.message_id) };
+  });
+}
+```
+
+For inbound, point the provider's webhook at your own HTTP handler and call `dispatchInbound` with the route id. Foundry stores only the safe metadata on the account — the token stays in your environment, behind `accessRef`.
+
+### Schedule work
+
+Agents never call `setTimeout`. Add a `schedules/*.ts` definition, or let the agent create one at runtime through Foundry's scheduling tools. Either way it becomes a persisted activation you can see under **Automations**.
+
+### Call agents from your own code
+
+```ts
+import { createFoundryClient } from "glove-foundry/client";
+import type { FoundryRoutes } from "../.foundry/routes.js";
+
+const foundry = createFoundryClient<FoundryRoutes>({ baseUrl: "http://127.0.0.1:4141" });
+const agent = await foundry.agent("concierge").create({ workspaceId: "demo" });
+const conversation = await foundry.createConversation(agent.id);
+const run = await foundry.send(agent.id, conversation.id, "Find me a flight to Nairobi");
+console.log((await run.wait()).output);
+```
+
+`src/client.ts` is a runnable version of this.
+
+---
+
+## The inspector
+
+`{{devCommand}}` serves a runtime inspector at **http://127.0.0.1:4141**.
+
+| Page | Answers |
+| --- | --- |
+| Overview | Is the runtime healthy, what is running, what needs attention |
+| Agents | Which definitions exist and which instances were provisioned |
+| Runs | Every invocation, with status, duration, and source |
+| Run detail | The phase spine and the full observable event trace |
+| Automations | Schedules, sleeping runs, playbook listeners, inbound workers |
+| Integrations | Transmissions, accounts, routes, and bindings |
+| Workspaces | Shared entries, inbox, tasks, and non-secret environment values |
+
+Filters live in the URL, so `/runs?status=failed` is a link you can send. Press `⌘K` to search, `j`/`k` to move through a list, `c` to start a run.
+
+---
+
+## Going to production
+
+1. **Replace the data adapter.** `MemoryFoundryDataAdapter` in `foundry.application.ts` loses everything on restart. Implement `FoundryDataAdapter` against your database.
+2. **Delete `lib/demo-model.ts`** and the fallback in `agent.ts` once `OPENROUTER_API_KEY` is set.
+3. **Own your credentials.** Foundry stores account *references*, never secrets. Keep tokens in your own adapter or secret manager.
+4. **Run `{{startCommand}}`** rather than `dev` — no file watching, no restart-on-change.
+5. **Keep the ESLint preset.** `glove-foundry/eslint` rejects patterns that break file routing, such as a hand-written `id` on a file-routed definition.
+
+---
+
+## The Glove packages
+
+| Package | What it gives you |
+| --- | --- |
+| [`glove-foundry`](https://www.npmjs.com/package/glove-foundry) | This framework: routing, runtime, inspector, client |
+| [`glove-core`](https://www.npmjs.com/package/glove-core) | The agent runtime, model adapters, stores, tools |
+| [`glove-js`](https://www.npmjs.com/package/glove-js) | The JavaScript REPL session used in `workbench.ts` |
+| [`glove-python`](https://www.npmjs.com/package/glove-python) | A Python REPL, same shape |
+| [`glove-lisp`](https://www.npmjs.com/package/glove-lisp) | A Lisp REPL, same shape |
+| [`glove-working-environment`](https://www.npmjs.com/package/glove-working-environment) | The sandboxed VFS behind `defineWorkingEnvironment` |
+| [`glove-memory`](https://www.npmjs.com/package/glove-memory) | Memory schemas and adapters |
+| [`glove-mcp`](https://www.npmjs.com/package/glove-mcp) | MCP client and server support |
+| [`glove-mesh`](https://www.npmjs.com/package/glove-mesh) | Multi-agent messaging |
+
+Add an environment package when you need it — `glove-env-documents`, `glove-env-spreadsheets`, `glove-env-images`, `glove-env-slides`, `glove-env-render`, `glove-env-ocr`, `glove-env-media`, `glove-env-email`, `glove-env-zip`, `glove-env-motion` — and mount it in `workbench.ts`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `{{devCommand}}` | Discover agents, typecheck, generate routes, serve the runtime and inspector |
+| `{{startCommand}}` | Run without file watching |
+| `{{lintCommand}}` | Lint, including the Foundry file-routing rules |
+| `{{typecheckCommand}}` | `tsc --noEmit` |
+
+## Documentation
+
+- [Building with Foundry](https://github.com/porkytheblack/glove/blob/main/packages/glove-foundry/docs/building-with-foundry.md)
+- [Architecture](https://github.com/porkytheblack/glove/blob/main/packages/glove-foundry/docs/architecture.md)
+- [The inspector](https://github.com/porkytheblack/glove/blob/main/packages/glove-foundry/docs/inspector.md)

package/templates/travel-concierge/agents/concierge/actions/reply.action.ts

@@ -0,0 +1,6 @@
+import { definePlaybookAction } from "glove-foundry";
+
+/** What the playbook asks the agent to do when a traveller message matches. */
+export default definePlaybookAction({
+  description: "Draft a reply to the traveller's message.",
+});

package/templates/travel-concierge/agents/concierge/agent.ts

@@ -0,0 +1,106 @@
+import { MemoryStore } from "glove-core";
+import { createAdapter } from "glove-core/models/providers";
+import { composePlaybook, defineAgent } from "glove-foundry";
+import { DemoModel } from "../../lib/demo-model.js";
+import reply from "./actions/reply.action.js";
+import calendar from "./apps/calendar.app.js";
+import { conciergeComponents } from "./composition.js";
+import messageReceived from "./events/message-received.event.js";
+import messageSent from "./events/message-sent.event.js";
+import tripContext from "./layers/trip-context.layer.js";
+import travellerMemory from "./memory/traveller.memory.js";
+import mentionsTrip from "./predicates/mentions-trip.predicate.js";
+import tripCountdown from "./schedules/trip-countdown.js";
+import usage from "./subscribers/usage.subscriber.js";
+import { travellerInbound, travellerOutbound, travellerAccount } from "./topology.js";
+import messaging from "./transmissions/messaging.transmission.js";
+import { conciergeRepl, conciergeWorkspace } from "./workbench.js";
+
+/**
+ * The file path is the identity: `agents/concierge/agent.ts` is the agent
+ * `concierge`. There is no id to keep in sync.
+ *
+ * Every field below may be a value or a function. A function is called per
+ * run with the request context, which is how one definition serves many
+ * instances without branching inside the prompt.
+ */
+
+/** Runs with no API key so `pnpm dev` works before you have configured one. */
+function model() {
+  if (!process.env.OPENROUTER_API_KEY) return new DemoModel();
+  return createAdapter({
+    provider: "openrouter",
+    model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4.1-mini",
+    stream: true,
+  });
+}
+
+/**
+ * When a chat message arrives on the inbound route and mentions a trip, answer
+ * it and deliver the reply back to the same thread.
+ */
+const travellerChat = composePlaybook({
+  name: "traveller-chat",
+  transmission: messaging,
+  match: {
+    event: messageReceived,
+    routes: [travellerInbound],
+    predicate: { definition: mentionsTrip, parameters: { any: ["trip", "flight", "hotel"] } },
+  },
+  directives: [{
+    action: reply,
+    instruction: "Answer the traveller's message. Keep it short enough to read on a phone.",
+  }],
+  applications: [calendar],
+  outbound: [{
+    route: travellerOutbound,
+    application: calendar,
+    account: travellerAccount,
+    applicationAccount: travellerAccount,
+    event: messageSent,
+    instruction: "Send the reply back to the traveller's thread.",
+  }],
+});
+
+export default defineAgent({
+  description: "Plans trips: finds flights, checks the calendar, and keeps the traveller updated",
+  tags: ["travel", "example"],
+  components: conciergeComponents,
+
+  // Persisted context, per conversation.
+  memory: [travellerMemory],
+  store: ({ conversationId }) => new MemoryStore(`concierge:${conversationId}`),
+  model,
+
+  // The prompt is built per run, so it can name what is actually mounted.
+  systemPrompt: (_agent, { message, history, installations }) => [
+    "You are a travel concierge. You are practical and you never invent bookings.",
+    "Use find_flights for availability, and the calendar tools before proposing dates.",
+    `Traveller asked: ${message.text}`,
+    `Prior messages: ${history.length}.`,
+    `Installed for this instance: ${installations.map((item) => `${item.kind}:${item.id}`).join(", ") || "nothing yet"}.`,
+  ].join("\n"),
+
+  // The sandbox. `budgetUsd` is read off the instance so two travellers differ.
+  workingEnvironment: conciergeWorkspace,
+  repl: (_agent, { agentId, agentInstance }) =>
+    conciergeRepl(agentId, Number(agentInstance.context.budgetUsd ?? 2_000)),
+
+  // Recurring work. An instance can opt out through its own context.
+  schedules: (_agent, { agentInstance }) =>
+    agentInstance.context.muteCountdown === true ? [] : [tripCountdown],
+
+  // A playbook can only bind a transmission that an installed application
+  // owns, so this one exists only once `calendar` is installed on the
+  // instance. That is lazy assembly in one line: the same code adapts to
+  // whatever each instance actually has.
+  playbooks: (_agent, { installations }) =>
+    installations.some((item) => item.kind === "application" && item.id === "calendar")
+      ? [travellerChat]
+      : [],
+
+  compactionInstructions: () =>
+    "Keep the destination, dates, budget, confirmed bookings, and open decisions.",
+  layers: [tripContext],
+  subscribers: [usage],
+});