glove-foundry 0.0.0

package/docs/building-with-foundry.md

@@ -0,0 +1,403 @@
+# Building with Glove Foundry
+
+Foundry uses the filesystem for code identity and imported values for code relationships. You should not maintain matching string IDs for static definitions.
+
+## Create and run
+
+```bash
+npx glove foundry support-workforce
+cd support-workforce
+pnpm install
+cp .env.example .env.local
+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 filesystem is the static registry
+
+```text
+agents/
+  lead/
+    agent.ts                              -> agent id: lead
+    apps/helpdesk.app.ts                  -> application id: helpdesk
+    transmissions/tickets.transmission.ts -> transmission id: tickets
+    predicates/is-urgent.predicate.ts      -> predicate id: is-urgent
+    connections/ticket-events.connection.ts
+    tools/customer-lookup.tool.ts
+    mcp/notion.mcp.ts
+    memory/customer.memory.ts
+    layers/request-context.layer.ts
+    subscribers/audit.subscriber.ts
+    schedules/daily-review.ts
+```
+
+Nested files produce nested IDs: `tools/calendar/today.tool.ts` becomes `calendar/today`. Every convention file default-exports one definition. That default export is the value other files import and reference.
+
+An explicit `id` remains a compatibility escape hatch for programmatic definitions, but the packaged ESLint preset rejects it in normal file-routed authoring.
+
+## Define an agent
+
+```ts
+// agents/lead/agent.ts
+import { MemoryStore } from "glove-core"
+import { createAdapter } from "glove-core/models/providers"
+import { defineAgent } from "glove-foundry"
+import { components } from "./composition.js"
+
+export default defineAgent({
+  description: "Coordinates customer work",
+  components,
+  store: ({ conversationId }) => new MemoryStore(`lead:${conversationId}`),
+  model: () => createAdapter({
+    provider: "openrouter",
+    model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4.1-mini",
+  }),
+  systemPrompt: (_agent, ctx) =>
+    `You are the lead. Workspace: ${ctx.workspaceId}. Message: ${ctx.message.text}`,
+  tools: (_agent, ctx) =>
+    ctx.message.text.includes("customer") ? [customerLookupTool] : [],
+  inboxes: (_agent, ctx) => loadInbox(ctx.workspaceId, ctx.agentId),
+})
+```
+
+An agent definition describes lazy assembly. It never declares request input or result output; those are Foundry contracts. An agent definition is also not an instance. Instances are durable data and may be created, updated, removed, or reconstructed independently.
+
+## Define and compose colocated pieces
+
+```ts
+// agents/lead/tools/customer-lookup.tool.ts
+import { defineSharedTool } from "glove-foundry"
+import { Effect } from "effect"
+import { z } from "zod"
+
+const customerLookup = defineSharedTool({
+  description: "Look up a customer",
+  config: z.object({ region: z.string() }),
+  create: ({ config }) => Effect.succeed(makeCustomerLookupTool(config.region)),
+})
+
+export default customerLookup
+```
+
+```ts
+// agents/lead/composition.ts
+import { composeAgent } from "glove-foundry"
+import helpdesk from "./apps/helpdesk.app.js"
+import customerLookup from "./tools/customer-lookup.tool.js"
+import customerMemory from "./memory/customer.memory.js"
+
+export const components = composeAgent(helpdesk, customerLookup, customerMemory)
+```
+
+`composeAgent` builds the agent-local catalogue. It does not install applications, MCPs, or shared tools. An instance selects those dynamically.
+
+## Mount a working environment, VFS, and REPL
+
+Foundry mounts the native Glove packages; it does not reimplement their sandboxes. A working environment supplies a persistent virtual filesystem, named scripts, checkpoints, history, artifact export, and a closed model-facing verb set. A REPL is a separate computation surface over registered functions.
+
+```bash
+pnpm add glove-working-environment glove-js
+# Use glove-python or glove-lisp instead when that is the better agent surface.
+```
+
+```ts
+// agents/lead/workbench.ts
+import { JsSession, defineFn } from "glove-js"
+import {
+  defineRepl,
+  defineWorkingEnvironment,
+  foundryDataEnvironmentPersistence,
+} from "glove-foundry"
+import { z } from "zod"
+
+export const workspace = defineWorkingEnvironment({
+  options: ({ assembly }) => ({
+    limits: { maxVfsBytes: 64 * 1024 * 1024 },
+    onVerb: event => assembly.controls.emit({
+      type: "lead.workspace.verb",
+      data: event,
+    }),
+  }),
+  persistence: foundryDataEnvironmentPersistence({ scope: "agent" }),
+})
+
+export function createRepl(actor: string) {
+  const session = JsSession.create({ actor })
+  session.register(defineFn({
+    name: "customers__active",
+    description: "List active customers",
+    input: z.object({ region: z.string().optional() }),
+    readOnlyHint: true,
+    handler: input => customerAdapter.listActive(input),
+  }))
+  return defineRepl({
+    language: "javascript",
+    session,
+    mount: { discovery: "auto" },
+  })
+}
+```
+
+```ts
+// agents/lead/agent.ts
+export default defineAgent({
+  workingEnvironment: workspace,
+  repl: (_agent, ctx) =>
+    ctx.messageText.includes("analyse") ? createRepl(ctx.agentId) : undefined,
+  run: async (_agent, ctx) => {
+    await ctx.vfs?.writeFile("/tmp/request.txt", ctx.messageText)
+    return ctx.defaultRun()
+  },
+  // model, prompt, and other surfaces...
+})
+```
+
+`workingEnvironment` and `repl` accept the same direct-value-or-lazy-resolver shape as the other assembly fields. JavaScript, Python, and Lisp sessions are supported through one discriminated `defineRepl` API. Foundry exposes the mounted `workingEnvironment`, its guarded `vfs` handle, and the native `repl` session to layers, `configure`, calls, and `run` handlers.
+
+The working environment is closed after every Foundry run. Add a persistence adapter to restore its VFS on the next run. `foundryDataEnvironmentPersistence` uses the data adapter's private snapshot seam, derives ownership from the definition and instance or conversation, and never exposes VFS contents as workspace entries. It requires a durable `FoundryDataAdapter` shared by execution workers. For high-concurrency or large trees, provide a native persistent `Vfs` such as `cachedRemote` in the environment options and let that adapter own locking and storage credentials.
+
+REPL bindings persist for the duration of the assembled run. Glove's native REPL packages intentionally do not define a cross-process snapshot format, so durable artifacts belong in the working environment VFS rather than hidden interpreter variables.
+
+## Definitions reference definitions
+
+Keep each transmission primitive atomic:
+
+```ts
+// agents/lead/predicates/is-urgent.predicate.ts
+import { Effect } from "effect"
+import { defineTransmissionPredicate } from "glove-foundry"
+
+export default defineTransmissionPredicate({
+  match: (event: { priority: number }, parameters) =>
+    Effect.succeed(event.priority >= Number(parameters.minimum ?? 1)),
+})
+```
+
+```ts
+// agents/lead/events/ticket-created.event.ts
+import { defineTransmissionEvent } from "glove-foundry"
+
+export default defineTransmissionEvent({ direction: "inbound" })
+
+// agents/lead/actions/resolve.action.ts
+import { definePlaybookAction } from "glove-foundry"
+
+export default definePlaybookAction({
+  description: "Resolve the event that activated the playbook",
+})
+```
+
+```ts
+// agents/lead/transmissions/tickets.transmission.ts
+import { Effect, Schema } from "effect"
+import { defineTransmission } from "glove-foundry"
+import ticketCreated from "../events/ticket-created.event.js"
+import isUrgent from "../predicates/is-urgent.predicate.js"
+
+const tickets = defineTransmission({
+  name: "Tickets",
+  description: "Ticket provider contract",
+  events: [ticketCreated],
+  account: {
+    required: true,
+    metadata: Schema.Struct({ workspace: Schema.String }),
+  },
+  inbound: {
+    config: Schema.Struct({ queue: Schema.String }),
+    event: Schema.Struct({
+      id: Schema.String,
+      threadId: Schema.String,
+      priority: Schema.Number,
+      body: Schema.String,
+    }),
+    classify: () => Effect.succeed(ticketCreated),
+    predicates: [isUrgent],
+  },
+  outbound: {
+    config: Schema.Struct({ queue: Schema.String }),
+    input: Schema.Struct({ threadId: Schema.String, body: Schema.String }),
+    output: Schema.Struct({ messageId: Schema.String }),
+    adapter: { deliver: (input) => userTicketAdapter.deliver(input) },
+  },
+})
+
+export default tickets
+```
+
+```ts
+// agents/lead/apps/helpdesk.app.ts
+import { defineApp } from "glove-foundry"
+import tickets from "../transmissions/tickets.transmission.js"
+import ticketEvents from "../connections/ticket-events.connection.js"
+
+export default defineApp({
+  description: "Ticket application",
+  inbound: [tickets],
+  outbound: [tickets],
+  connections: [ticketEvents],
+})
+```
+
+The application can own multiple inbound and outbound transmissions. Installing it mounts outbound transmissions as validated tools. Connections remain dormant until an active instance or subscription needs the installed app and playbook.
+
+## Config is inferred from its definition
+
+Zod config schemas flow into `install`, layer and memory selection, and the install callback:
+
+```ts
+const helpdesk = defineApp({
+  description: "Ticket application",
+  config: z.object({ queue: z.string(), retries: z.number().default(2) }),
+  install: ({ config }) => {
+    config.queue   // string
+    config.retries // number
+    return Effect.void
+  },
+})
+
+install(helpdesk, { queue: "support" })        // valid
+install(helpdesk, { queue: 42 })               // TypeScript error
+```
+
+Effect transmission schemas flow into account metadata, route config, inbound events, outbound inputs, and outbound outputs. Use `configureLayer(layer, config)` and `configureMemory(memory, config)` when those definitions expose config schemas. `defineConfig({...})` rejects unknown top-level and nested framework keys while retaining the exact inferred value type.
+
+Runtime decoding still runs at every persistence or execution boundary; TypeScript is not the only validator.
+
+## Runtime topology is data
+
+Accounts, routes, bindings, agent instances, and conversations are data records. Their IDs are not static code identities: a UI or adapter may create and update them, so their IDs remain explicit.
+
+```ts
+// agents/lead/topology.ts
+import { defineAccount, defineInboundRoute } from "glove-foundry"
+import tickets from "./transmissions/tickets.transmission.js"
+
+export const supportAccount = defineAccount({
+  id: "support-account",
+  transmission: tickets,
+  externalAccountId: "support-team",
+  accessRef: "my-adapter://support-team",
+  metadata: { workspace: "support" },
+})
+
+export const ticketInbound = defineInboundRoute({
+  id: "ticket-inbound",
+  transmission: tickets,
+  account: supportAccount,
+  visibility: "workspace",
+  enabled: true,
+  config: { queue: "support" }, // inferred from tickets.inbound.config
+})
+```
+
+`accessRef` is opaque to Foundry. Credential acquisition and refresh belong to the user-owned account-session adapter.
+
+## Runtime-composed playbooks and dynamic installations
+
+```ts
+// agents/lead/agent.ts
+import { composePlaybook, defineAgent } from "glove-foundry"
+import resolve from "../actions/resolve.action.js"
+import helpdesk from "../apps/helpdesk.app.js"
+import ticketCreated from "../events/ticket-created.event.js"
+import isUrgent from "../predicates/is-urgent.predicate.js"
+import tickets from "../transmissions/tickets.transmission.js"
+import { supportAccount, ticketInbound } from "../topology.js"
+
+export default defineAgent({
+  description: "Support lead",
+  playbooks: (_agent, ctx) => [composePlaybook({
+    name: "urgent-ticket",
+    transmission: tickets,
+    match: {
+      event: ticketCreated,
+      routes: [ticketInbound],
+      predicate: { definition: isUrgent, parameters: { minimum: ctx.agentInstance.context.minimum ?? 3 } },
+    },
+    directives: [{ action: resolve, instruction: "Investigate and respond." }],
+    applications: [helpdesk],
+  })],
+  // model and other surfaces...
+})
+```
+
+```ts
+import { defineAgentInstance, install } from "glove-foundry"
+import lead from "./agent.js"
+import helpdesk from "./apps/helpdesk.app.js"
+
+export const leadInstance = defineAgentInstance(lead, {
+  workspaceId: "support",
+  installations: [install(helpdesk, { queue: "support", retries: 3 })],
+  playbooks: [], // populated by the lazy agent resolver on its first assembly
+})
+```
+
+`composePlaybook` is called at runtime, not exported as a static playbook definition. Foundry derives the playbook id, converts direct primitive references into a value-only record, and reconciles it onto the instance. A frontend can also provide instance playbook data directly; definition-origin policy and frontend-origin policy remain distinguishable.
+
+## Background activation without an existing instance
+
+```ts
+const [urgentTicket] = persistedAgent.playbooks
+await runtime.putPlaybookSubscription({
+  id: subscriptionId,
+  workspaceId: persistedAgent.workspaceId,
+  enabled: true,
+  playbook: urgentTicket,
+  targets: runtimeSelectedTargets,
+  createdAt: now,
+  updatedAt: now,
+})
+```
+
+The subscription is evaluated even when no matching instance exists. A matching inbound event can atomically provision one or many subscribed agents, create their conversations, and start their runs.
+
+## Agent-local schedules and future work
+
+```ts
+const dailyReview = defineSchedule({
+  name: "daily-review",
+  timing: { kind: "cron", expression: "0 9 * * 1-5", timezone: "UTC" },
+  message: "Review unresolved support work.",
+})
+
+export default defineAgent({
+  schedules: (_agent, ctx) => ctx.agentInstance.context.paused ? [] : [dailyReview],
+  // ...
+})
+```
+
+```ts
+// A running agent uses the framework-owned tool:
+glove_foundry_schedule({
+  message: "Review open support work.",
+  timing: { kind: "every", interval: "24h" },
+})
+
+// Suspend this conversation and wake the same instance later:
+glove_foundry_sleep({
+  kind: "for",
+  duration: "20m",
+  message: "Check whether the deployment has finished, then resolve it.",
+})
+
+glove_foundry_schedules({ action: "list" })
+glove_foundry_schedules({ action: "update", activationId, timing: { kind: "every", interval: "2h" } })
+glove_foundry_schedules({ action: "cancel", activationId })
+```
+
+Schedules are agent-local composable values; Foundry has no root schedule registry or automatically discovered schedule files. Immediate spawning, future activation, recurrence, management, and suspension are separate runtime operations. Foundry stores activation state through `FoundryDataAdapter` before arming its private execution backend, so a durable adapter can reconstruct pending work on startup. Sleep preserves the instance and conversation so the wake-up resumes with the same stored context.
+
+## Boundary checklist
+
+- Static code identity comes from the convention filename.
+- Static code relationships use imported values.
+- IDs appear when definitions are serialized into durable data.
+- Runtime data IDs remain explicit because users and adapters create those records.
+- Applications, shared tools, and MCPs mount only when an instance installs them.
+- Memory and inboxes are agent-definition surfaces and may resolve from current context/message.
+- Working environments and one native REPL are agent-definition surfaces and may resolve from current context/message.
+- VFS persistence, remote storage, and locking remain adapter-owned.
+- Transmissions own executable integration logic; playbooks remain serializable policy.
+- Provider adapters own credential acquisition and refresh.

package/docs/evaluation-checklist.md

@@ -0,0 +1,89 @@
+# Evaluation checklist
+
+Use this when deciding whether Foundry has the structure you want.
+
+## Run the evidence
+
+```bash
+pnpm --filter glove-foundry typecheck
+pnpm --filter glove-foundry test
+pnpm --filter glove-foundry build
+pnpm --filter glove-foundry-example typecheck
+pnpm --filter glove-foundry-example verify:architecture
+pnpm --filter glove-foundry-example verify
+```
+
+The package tests include an inbound subscription with zero initial instances, two targets, per-thread provisioning, connection activation, and duplicate-event idempotency.
+
+## Definition and instance boundary
+
+- [ ] `defineAgent` produces a reusable data structure, not an invocation contract.
+- [ ] The file route is the definition route.
+- [ ] Instances are stored independently with workspace, context, installations, and playbooks.
+- [ ] An instance can be updated and reconstructed without modifying code.
+- [ ] One instance can own multiple conversations.
+- [ ] Every run assembles from current instance data and the current native Glove message.
+
+## Reference safety
+
+- [ ] Code-authored routes use `transmission`, `account`, and other imported values.
+- [ ] Runtime-composed playbooks use transmission, predicate, route, app, and account values.
+- [ ] Playbooks are produced by lazy agent resolvers or runtime data, never file-discovered definitions.
+- [ ] Schedules are agent-local composable values, never a root registry.
+- [ ] Code-authored installations use `install(definition, config)`.
+- [ ] String ids appear only in JSON-safe persisted/API records or inherently dynamic selections.
+- [ ] Reconstruction validates and freezes stored records.
+
+## Composition and installation
+
+- [ ] Tools, applications, MCPs, memory, inboxes, layers, subscribers, working environments, and REPLs can be colocated under an agent.
+- [ ] Components are functionally returnable and composable.
+- [ ] Applications and MCPs remain inert until instance data installs them.
+- [ ] Memory belongs to the definition and can be selected lazily.
+- [ ] Inboxes are always lazy functions.
+- [ ] Assembly can depend on current message, conversation, instance, and workspace.
+
+## Applications and transmissions
+
+- [ ] An app owns multiple inbound and outbound transmissions.
+- [ ] Installing an app mounts outbound transmission tools.
+- [ ] Transmissions own authentication, normalization, classification, predicates, serialization, and delivery.
+- [ ] Playbooks contain serializable match parameters and directives only.
+- [ ] Credential acquisition and refresh remain in user adapters.
+- [ ] Account metadata exposed by Foundry contains no secret values.
+
+## Background activation
+
+- [ ] A durable playbook subscription is evaluated with zero matching instances.
+- [ ] One inbound event can target one or many agent definitions.
+- [ ] `singleton`, `per-thread`, `per-event`, `existing`, and `custom` policies are supported.
+- [ ] Provisioning keys are enforced atomically by the data adapter.
+- [ ] Duplicate route/event deliveries return the original run ids.
+- [ ] A failed dispatch releases its claim for a safe retry.
+
+## Provider workers
+
+- [ ] Provider listeners are defined as application connections.
+- [ ] Connections start only for active installed-app/playbook requirements.
+- [ ] Connections receive only safe account metadata, routes, identity, abort, ready, receive, and optional account-session access.
+- [ ] Retry and supervision are observable without exposing backend worker primitives.
+- [ ] Public config, client methods, API routes, manifests, generated declarations, and inspector copy contain no backend deployment concepts.
+
+## Runtime primitives
+
+- [ ] Conversations, workspace entries, shared inbox items, tasks, and scoped environment values are first-class adapter data.
+- [ ] Agent-local schedules reconcile into adapter data; agents can also create triggers dynamically.
+- [ ] Core tools can list, update, cancel, recur, sleep, run in background, and reconvene within agent identity.
+- [ ] Layered agents, S2S/S2V calls, mesh, custom subscribers, custom build, and custom run/handler functions remain available.
+- [ ] A native working environment mounts its guarded VFS and script tools with lifecycle cleanup and telemetry.
+- [ ] JavaScript, Python, and Lisp REPLs mount through one typed, lazy agent field.
+- [ ] VFS persistence and storage credentials remain behind user-selectable adapters.
+
+## Developer experience
+
+- [ ] `npx glove foundry` scaffolds a type-checking project.
+- [ ] `.foundry/routes.d.ts` provides typed file routes.
+- [ ] ESLint checks Foundry conventions.
+- [ ] The inspector makes arrival → policy → workforce → work visible.
+- [ ] Raw trace data is available without making it the default interface.
+- [ ] The runnable example uses the same public API described in the docs.

package/docs/implementation-backlog.md

@@ -0,0 +1,67 @@
+# Glove Foundry implementation backlog
+
+This file records accepted architectural gaps and their implementation status.
+
+## Completed — filename-owned definitions and typed config flow
+
+Status: implemented across discovery, isolated execution, the scaffold, ESLint,
+the reference application, and persistence reconstruction.
+
+- convention files default-export one definition and derive nested identities
+  from their path;
+- imported definition objects are the only code-authoring reference mechanism;
+- isolated agent processes repeat discovery binding before assembly;
+- instance/playbook/subscription seeds defer serialization until identities are
+  bound;
+- Zod installation schemas infer `install(...)` input and decoded callback
+  config;
+- Effect transmission schemas infer account metadata and inbound/outbound route
+  config;
+- `defineConfig` rejects unknown framework keys while preserving exact types;
+- runtime/data records retain explicit IDs because they are dynamically
+  provisioned and editable; and
+- the recommended ESLint preset rejects explicit IDs on static file-routed
+  definitions.
+
+## Completed — Playbook subscriptions activate agents without pre-existing instances
+
+Status: implemented in the runtime and memory data adapter.
+
+The inbound dispatcher evaluates both instance playbooks and independent,
+durable `PlaybookSubscription` records. A subscription can activate work when
+no `AgentInstance` exists.
+
+Implemented behavior:
+
+- persist playbook subscriptions independently from materialized agent
+  instances;
+- let a subscription target one or more agent definition routes;
+- resolve existing instances or atomically provision instances from persisted
+  data when a matching inbound transmission arrives;
+- support explicit provisioning policies such as singleton, per-thread,
+  per-event, fixed fan-out, and a user-supplied provisioning adapter;
+- create or reuse the appropriate conversation before dispatching each run;
+- make inbound retries idempotent across event matching, instance provisioning,
+  conversation creation, and run enqueueing;
+- keep executable predicates on transmission definitions and keep playbooks and
+  subscriptions serializable;
+- emit observable match, provisioning, fan-out, and dispatch events without
+  exposing backend execution-engine terminology.
+
+The intended flow is:
+
+```text
+inbound event
+  -> authenticate, normalize, and classify through its transmission
+  -> query persisted playbook subscriptions
+  -> evaluate named transmission predicates
+  -> resolve or provision every subscribed agent instance
+  -> create or reuse conversations
+  -> reconstruct each agent from persisted instance data
+  -> enqueue one run per resolved subscription target
+```
+
+The package test suite covers zero pre-existing instances, one-to-many fan-out,
+connection activation, and duplicate delivery. Production adapters must
+implement the same atomic `provisionAgent` and inbound-delivery claim contract;
+adapter-specific restart/concurrency tests belong with those adapters.

package/docs/inspector.md

@@ -0,0 +1,56 @@
+# Foundry inspector
+
+The development server includes a read-oriented runtime inspector. It is organized around Foundry's actual ownership boundaries rather than presenting every event on one screen.
+
+## Navigation
+
+| Page | Question it answers |
+| --- | --- |
+| Overview | Is the runtime healthy, what is active, and what needs attention? |
+| Agents | Which definitions exist, which instances were provisioned, and how do they differ? |
+| Agent definition | What can this code route assemble, including lazy fields, capabilities, native surfaces, schedules, and playbooks? |
+| Agent instance | Which context, installations, playbooks, conversations, and runs belong to this persisted identity? |
+| Runs | Which invocations occurred and what status, source, and attempt count did each have? |
+| Run detail | What observable phases and events produced this outcome? |
+| Automations | Which schedules, sleeping runs, playbook listeners, and inbound application workers exist? |
+| Integrations | Which transmissions, safe account references, routes, and agent bindings form the external topology? |
+| Workspaces | Which shared entries, inbox items, tasks, and non-secret environment values are available? |
+
+Every detail view has a real URL. For example, `/agents/support-lead`, `/instances/<agent-id>`, and `/runs/<run-id>` can be bookmarked or opened directly; the Foundry server returns the inspector shell for non-API paths.
+
+## Following a run
+
+Open **Runs**, then choose one invocation. The run detail starts with a four-phase spine:
+
+1. Accepted: Foundry persisted the invocation and its source.
+2. Assembled: context-dependent agent components were resolved and mounted.
+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.
+
+## Starting work
+
+Use **New run** from any page. Select a definition and either:
+
+- choose an existing runtime instance; or
+- let Foundry create a new instance in the current/default workspace.
+
+The inspector reuses that instance's latest conversation or creates its first conversation, sends the message, then navigates directly to the new run.
+
+## 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.
+
+## Operator API used by the inspector
+
+The inspector is an API client and adds no hidden runtime state. Its primary read surfaces are:
+
+- `/api/manifest`, `/api/agent-instances`, and `/api/conversations`
+- `/api/runs`, `/api/runs/:id`, and `/api/events`
+- `/api/activations` and `/api/playbook-subscriptions`
+- `/api/application-connections`
+- `/api/transmissions`, `/api/accounts`, `/api/routes`, and `/api/bindings`
+- `/api/workspaces/:id/entries|inbox|tasks|environment`
+
+`/api/activations` exposes persisted schedule and sleep records, optionally filtered with `?workspace=<id>`. Like the rest of Foundry's operator API, it contains runtime metadata, not credential material.