glove-foundry 0.3.3 → 0.4.0

package/docs/building-with-foundry.md

@@ -4,6 +4,16 @@ Foundry uses the filesystem for code identity and imported values for code relat
 
 ## Create and run
 
+Use Node 20.12 or newer; Node 22.13+ is recommended and required by optional SQLite memory adapters. In a terminal, `init` opens a guided wizard: choose a directory, standalone or Next.js integration, guided or minimal starter, package manager, and dependency installation. Review the plan before any files are written. Arrow keys select, Enter confirms, and Ctrl+C cancels without creating the project. The wizard never requests credentials.
+
+For CI or repeatable setup, use explicit choices:
+
+```bash
+npx glove-foundry init support-workforce --yes --target standalone --template travel-concierge --package-manager pnpm --no-install
+```
+
+`--no-interactive` also skips prompts; piped input never opens them. `--interactive` requires a terminal. `--install` opts into installation in scripts; otherwise install dependencies yourself. Existing project files are preserved; installation failures leave the generated project available for retry. Use `glove foundry init --help` for all setup and runtime flags. The [setup wizard and CLI reference](https://glove.dterminal.net/foundry/docs/getting-started) walks through the entire first run.
+
 ```bash
 npx glove foundry init support-workforce
 cd support-workforce
@@ -12,7 +22,21 @@ 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.
+`glove foundry dev` discovers the source graph, derives identities, generates `.foundry/routes.d.ts`, and starts the runtime and inspector. Run the generated `typecheck` and `lint` scripts separately to validate types and authoring conventions.
+
+The HTTP server keeps JSON requests at 1 MB by default. For a trusted multimodal
+client that sends base64 images or documents, raise the explicit typed bound rather
+than removing it:
+
+```ts
+export default defineConfig({
+  server: { port: 4141, messageBodyBytes: 40 * 1024 * 1024 },
+})
+```
+
+Native Glove media parts may include a human-facing `name`. A custom `run` handler can
+persist or normalize those parts and then call `context.defaultRun(enrichedMessage)`
+to keep the standard Glove loop and conversation semantics.
 
 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.
 
@@ -49,7 +73,71 @@ The runtime is a separate process from `next dev`, deliberately — it holds dur
 
 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.
+In production, set `FOUNDRY_URL` to wherever the runtime is deployed and keep it
+inside a deliberate trust boundary. Loopback is the default. Foundry refuses to bind
+another interface unless `foundry.application.ts` supplies an Effect-native request
+authorization adapter:
+
+```ts
+import { Effect } from "effect"
+import { defineApplication } from "glove-foundry"
+
+export default defineApplication({
+  name: "Support workforce",
+  requestAuthorization: {
+    identifier: "company-control-auth",
+    challenge: 'Bearer realm="Support Foundry"',
+    authorize: request => Effect.tryPromise({
+      try: () => companyIdentityAdapter.authorize({
+        authorization: request.authorization,
+        cookie: request.cookie,
+        path: request.path,
+      }),
+      catch: cause => new Error("Control authorization unavailable", { cause }),
+    }),
+  },
+})
+```
+
+This is verification, not credential acquisition: your adapter owns tokens, cookies,
+OIDC/trusted-proxy identity, refresh, revocation, and rate policy. The result is only
+a boolean; credential material does not enter Foundry state, manifests, prompts, or
+events. Put TLS and a restrictive firewall/proxy in front of any network-visible
+listener.
+
+A remote typed client resolves its own headers at request time:
+
+```ts
+const foundry = createFoundryClient({
+  baseUrl: process.env.FOUNDRY_URL,
+  authorization: {
+    identifier: "company-control-client",
+    headers: () => companyIdentityAdapter.requestHeaders(),
+  },
+})
+```
+
+For a single-host deployment, persist Foundry's mutable data with the bundled atomic file adapter:
+
+```ts
+import { FileFoundryDataAdapter, defineApplication } from "glove-foundry"
+import { join } from "node:path"
+
+const data = new FileFoundryDataAdapter({
+  file: join(process.env.AGENT_DATA_DIR ?? ".data", "foundry.json"),
+  agents: [primaryInstance],
+  conversations: [primaryConversation],
+  subscriptions: [inboundSubscription],
+})
+
+export default defineApplication({
+  name: "Support workforce",
+  data,
+  conversationStore: createConversationStore,
+})
+```
+
+`FileFoundryDataAdapter` coordinates sibling execution processes with an advisory lock and commits by atomic rename. It persists instances, subscriptions, delivery claims, activations, conversations, workspace data, VFS snapshots, inbox items, tasks, and non-secret environment data. Use a transactional database adapter when several hosts need to share the same state.
 
 ## The filesystem is the static registry
 
@@ -129,6 +217,50 @@ 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.
 
+### HTTP and stdio MCP definitions
+
+An MCP definition is a typed catalogue entry, not a global connection. Its instance
+installation decides whether it is present for an agent. HTTP remains concise; stdio
+uses an explicit transport:
+
+```ts
+const projectTools = defineMcp({
+  description: "Approved project operations",
+  entry: {
+    name: "Project tools",
+    description: "Search and update the mounted project",
+    transport: {
+      kind: "stdio",
+      command: "/opt/agents/project-mcp",
+      args: ["--stdio"],
+    },
+    includeTools: ["search_*", "read_*", "create_issue"],
+    excludeTools: ["delete_repository"],
+    resources: true,
+    prompts: false,
+    connectTimeoutMs: 15_000,
+    requestTimeoutMs: 60_000,
+    idleTimeoutMs: 15 * 60_000,
+    maxLifetimeMs: 24 * 60 * 60_000,
+  },
+})
+```
+
+For HTTP, return `{ url: "https://mcp.example.com/mcp", ... }` or an explicit
+`{ transport: { kind: "http", url }, ... }`. Authentication and stdio environment
+values are connection-time adapter concerns: implement `getAuthHeaders` /
+`getAccessToken` for HTTP and `getStdioEnvironment` for stdio. Never place their
+resolved values in definition config, installation data, manifests, or events.
+
+`includeTools` and `excludeTools` accept exact un-namespaced names or globs. A
+non-empty allowlist is authoritative. `resources` and `prompts` independently control
+capability-aware list/read and list/get utility tools. Selection and defensive result sanitization happen at the shared MCP
+connection boundary, so boot reload, lazy activation, and scratchpad bridges see
+the same safe capability set. Finite connection and request timeouts keep broken
+servers from stalling a run indefinitely.
+Stdio-only idle and lifetime limits can recycle memory-heavy children without
+interrupting in-flight calls; adapter environment values are resolved again on reopen.
+
 ## 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.
@@ -172,6 +304,18 @@ export function createRepl(actor: string) {
     language: "javascript",
     session,
     mount: { discovery: "auto" },
+    programmaticTools: {
+      maxCalls: 50,
+      select: ({ tools }) => tools
+        .filter((tool) => tool.name.startsWith("workspace_"))
+        .map((tool) => ({
+          tool,
+          name: `workspace__${tool.name.slice("workspace_".length)}`,
+          server: "workspace",
+          readOnly: ["workspace_read_file", "workspace_ls", "workspace_grep"]
+            .includes(tool.name),
+        })),
+    },
   })
 }
 ```
@@ -192,6 +336,23 @@ export default defineAgent({
 
 `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.
 
+`programmaticTools` turns an explicit least-privilege projection of the live
+agent tool registry into functions inside that sandbox. The selector runs after
+application transmissions, instance-installed tools and MCPs, calls, memory,
+mesh, and `configure`, so it sees the actual message-specific assembly. It must
+return those exact tool objects (or `{ tool, ...discoveryMetadata }` wrappers),
+not copied names. Nothing is projected by default.
+
+This is the programmatic tool-calling path for workflows with several reads,
+loops, filters, or branches: the model writes one complete program and only its
+last, structurally bounded value returns to conversation context. A shared
+`maxCalls` budget defaults to 50 for the assembled run. Foundry validates Zod
+inputs again, forwards cancellation, records safe started/completed/failed
+events for each underlying call, and refuses to execute a tool whose current
+input requires interactive approval. The agent must call that tool normally so
+the approval surface remains visible. Do not select outbound or destructive
+tools merely because a sandbox can call them.
+
 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.
 
 For HTTP requests and file transfers, put `fetchFiles()` from `glove-env-fetch` in the environment options’ `stdlib`. Mount `secret()` from `glove-env-secret` when scripts need scoped key metadata or references, and supply the same instance-scoped host store to fetch credential aliases. Neither credentials nor the store are included in the VFS snapshot; re-supply them each run. The [HTTP and secrets guide](../../glove-working-environment/HTTP-AND-SECRETS.md) covers the complete setup, private-network opt-ins, cancellation, and persistent store boundaries.
@@ -257,6 +418,7 @@ const tickets = defineTransmission({
     config: Schema.Struct({ queue: Schema.String }),
     input: Schema.Struct({ threadId: Schema.String, body: Schema.String }),
     output: Schema.Struct({ messageId: Schema.String }),
+    observe: ({ threadId, body }) => ({ threadId, characters: body.length }),
     adapter: { deliver: (input) => userTicketAdapter.deliver(input) },
   },
 })
@@ -278,7 +440,52 @@ export default defineApp({
 })
 ```
 
-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.
+The application can own multiple inbound and outbound transmissions. Installing it mounts outbound transmissions as validated tools. Each generated tool awaits the parent-owned delivery adapter and returns its output after the transmission's output schema validates it. The agent subprocess never receives provider credentials or an account session. Cancellation propagates back to adapters through `context.signal`. Connections remain dormant until an active instance or subscription needs the installed app and playbook.
+
+Outbound inputs cross the worker boundary through a private, mode-0600 command record rather than the event stream or child stdout. Foundry deletes a settled exchange. Retained observability is redacted by default; define `outbound.observe(input)` when the transmission can expose a deliberate, secret-safe projection such as a route, byte count, or digest. Never return credentials or file bodies from that projection.
+
+Outbound adapters that select an account receive `context.withAccountSession`. Use it to enter the same user-owned, operation-scoped credential boundary used by application installers and inbound connections:
+
+```ts
+adapter: {
+  deliver: (input, context) => context.withAccountSession!(
+    "tickets:reply",
+    session => sendTicketReply(session, input, context.signal),
+  ),
+}
+```
+
+The session value is never added to Foundry data or observability. Credential acquisition, refresh, SDK construction, and cleanup remain responsibilities of the adapter supplied on the agent definition.
+
+Inbound connections normally isolate conversations by route and `threadKey`. A
+trusted identity adapter can additionally provide an agent-scoped
+`conversationKey` when two authenticated external identities represent the same
+principal:
+
+```ts
+yield* context.receive({
+  route,
+  eventId: event.id,
+  threadKey: providerThread.id,
+  conversationKey: `principal:${resolvedIdentity.id}`,
+  conversationScope: "agent",
+  awaitCompletion: true,
+  raw: event,
+})
+```
+
+Foundry reuses an existing conversation whose data context has that key, or creates
+a deterministic conversation for the agent. The transport thread remains on the
+event and outbound route, so joining private history never changes where a reply is
+delivered. Only use this after an adapter authenticates and explicitly links the
+identities; route-scoped isolation remains the default.
+
+`receive()` normally resolves once matching runs have been durably dispatched. Set
+`awaitCompletion: true` for a stateful chat or voice transport that must not accept
+the next turn until every subscribed run reaches a terminal state. This keeps a
+conversation transcript ordered without changing direct requests or unrelated
+connections. A high-throughput adapter can instead keep the default and implement
+its own per-conversation queue.
 
 ## Config is inferred from its definition
 
@@ -423,10 +630,134 @@ glove_foundry_sleep({
 
 glove_foundry_schedules({ action: "list" })
 glove_foundry_schedules({ action: "update", activationId, timing: { kind: "every", interval: "2h" } })
+glove_foundry_schedules({ action: "pause", activationId })
+glove_foundry_schedules({ action: "resume", activationId })
 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.
+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. Pausing disarms a trigger without losing its message, timing, payload, ownership, or definition provenance; edits made while paused remain paused until an explicit resume. Foundry stores activation state through `FoundryDataAdapter` before arming its private execution backend, so a durable adapter can reconstruct active work—and keep paused work disarmed—on startup. Sleep preserves the instance and conversation so the wake-up resumes with the same stored context.
+
+Schedule management reloads the owning instance's persisted activations on each
+tool call and overlays the current run's pending commands. A recurring run can
+therefore inspect and cancel its own trigger even when it was inserted after the
+assembly snapshot. Another instance's schedules do not appear in that tool view.
+
+For an application-specific loop or goal controller, reuse these tools and store
+the policy in `FoundryDataAdapter`; do not create another timer service. Mount native
+`glove-memory/goals` for goal tracking. Durable coordination can use the optional
+`compareAndSetWorkspaceEntry(entry, expectedUpdatedAt)` adapter method: `null`
+means the key must be absent, an update compares the previously read timestamp,
+and every accepted replacement must advance that timestamp. Validate the value
+with the consumer's schema and retry conflicts against fresh state. Both bundled
+adapters support it; database adapters should implement it transactionally. Every
+writer to that coordinated key must use the same contract.
+
+## Client and control protocols
+
+Foundry exposes one runtime through three HTTP shapes. The native `/api` routes are
+the typed control plane used by `createFoundryClient`. OpenAI-compatible clients can
+use streaming or non-streaming `/v1/chat/completions` and `/v1/responses`. Automation
+hosts can create an asynchronous run, inspect it, follow its events, and stop it:
+
+```text
+POST /v1/runs
+GET  /v1/runs/:runId
+GET  /v1/runs/:runId/events
+POST /v1/runs/:runId/stop
+POST /v1/runs/:runId/steer
+GET  /v1/capabilities
+GET  /health/detailed
+```
+
+All three paths resolve the supplied model to a persisted agent instance and write
+into a durable conversation. Reuse `conversation_id`, `user`, or the returned
+`x-foundry-conversation-id` header to continue the same conversation. Run-event
+requests return JSON by default and become live server-sent events when the client
+sends `Accept: text/event-stream`.
+
+`/v1/capabilities` is authoritative: a client must inspect it instead of assuming a
+control feature exists. Steering is explicitly `interrupt-and-restart`: Foundry
+cooperatively cancels active work, waits for a terminal boundary, then starts the
+guidance as a replacement run in the same durable conversation with lineage back to
+the source. It never injects arbitrary text halfway through a tool side effect.
+The typed client exposes the same boundary as `handle.steer(message)`, returning a
+new run handle plus the source id and whether active work was interrupted.
+
+Build chat hosts with `createFoundryClient`: resume durable conversations, read
+`conversationTranscript`, follow correlated run events, and route new guidance
+during active work through the typed steering operation.
+
+## Effect approvals
+
+A Glove tool can set `requiresPermission: true` or return a boolean from
+`requiresPermission(input)`. In Foundry, an unset decision becomes a public,
+expiring approval record rather than an unresolved in-process display promise.
+The worker pauses; a trusted host lists and resolves the exact request:
+
+```ts
+const [approval] = await client.approvals({
+  runId: handle.id,
+  status: "pending",
+});
+
+if (approval) {
+  await client.resolveApproval(approval.id, "approve"); // or "deny"
+}
+```
+
+Approval identity includes the agent instance, conversation, run, tool name, and
+serialized tool input. Decisions are fail-closed when the channel is unavailable,
+the run is cancelled, or the request expires. A custom conversation store that
+omits permission methods receives a per-run exact-input overlay; stores that
+implement Glove permissions may persist the decision under their own policy.
+The inspector shows pending decisions on its overview and on the blocked run, with
+the exact payload and direct approve/deny controls.
+
+## Voice hosts
+
+For typed `goals`, `facts`, `forms`, and `contextProviders` fields, see
+[Guided conversations](./guidance.md). They mount native runners and providers
+and expose typed execution handles; no custom layer is required.
+
+Voice is a host adapter, not a second agent-definition vocabulary. Keep realtime
+audio, provider turn detection, interruption, telephony, and device access in the
+host. Delegate substantive work to a persisted Foundry instance and conversation
+through the native client or `/v1/responses`; the resulting run stays durable and
+observable.
+
+Use `glove-voice-s2s` for Gemini Live or OpenAI Realtime and `glove-voice` for a
+speech-to-text / Glove / text-to-speech pipeline. A realtime host can expose a
+delegation tool backed by the typed Foundry client, or mount `RealtimeAgent` against
+the assembled Glove in a scoped layer. Stop the voice session in the layer's
+cleanup. Keep provider credentials and audio device access in the host adapter.
+
+`examples/foundry-braind-storm` demonstrates a voice lead delegating durable work
+to Foundry agents. Phone bridges, LiveKit rooms and native audio hosts can use the
+same instance/conversation boundary. Messenger-specific voice gateways and codecs
+are consumer adapters, not built-in Foundry telephony services.
+
+Core 4 runtime context is transient: goals, forms and pinned memory reach the model
+without rewriting system instructions or persisted user turns. Native realtime
+agents refresh that context silently at startup and after tool calls. Call
+`await realtime.refreshContext()` after externally changing it, and forward
+`addContextProvider` and `getRuntimeContext` from any custom runnable wrapper.
+
+### Durable knowledge and documents
+
+Persist conversation history, structured memory and VFS files separately. A durable
+Foundry data adapter alone does not make an in-memory Glove store durable. For
+single-host Node 22.13+ deployments, `glove-memory/sqlite` provides
+`createSqliteMemoryAdapters({ file, namespace, schema })` for entity, episodic,
+resource and pinned-context memory. Select namespaces from trusted instance
+identity, not incoming tool input. See the [memory persistence guide](../../glove-memory/README.md).
+
+Mount `documents()` from `glove-env-documents` through
+`defineWorkingEnvironment({ options: { stdlib: [documents()] }, persistence })`.
+It supplies native PDF and DOCX creation, inspection, editing and extraction within
+the guarded VFS. Add the optional PDF extraction and rendering dependencies where
+needed. Pass documents between agents as authorized durable artifact references;
+do not copy entire file bodies into orchestration events. Persist the VFS before
+run cleanup. See the [document adapter](../../glove-env-documents/README.md).
 
 ## Boundary checklist
 
@@ -440,3 +771,4 @@ Schedules are agent-local composable values; Foundry has no root schedule regist
 - 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.
+- Voice and device hosts own audio transport while Foundry owns the durable agent run.

package/docs/evaluation-checklist.md

@@ -47,6 +47,7 @@ The package tests include an inbound subscription with zero initial instances, t
 
 - [ ] An app owns multiple inbound and outbound transmissions.
 - [ ] Installing an app mounts outbound transmission tools.
+- [ ] An outbound transmission tool receives the adapter's validated result and propagates cancellation without moving credentials into the agent process.
 - [ ] 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.
@@ -73,7 +74,7 @@ The package tests include an inbound subscription with zero initial instances, t
 
 - [ ] 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.
+- [ ] Core tools can list, update, pause, resume, 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.
@@ -87,3 +88,11 @@ The package tests include an inbound subscription with zero initial instances, t
 - [ ] 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.
+
+## Control-plane security
+
+- [ ] Loopback is the default listener boundary.
+- [ ] A non-loopback bind fails before listening unless the application supplies `requestAuthorization`.
+- [ ] Inspector HTML, health, APIs, and event streams all cross the same authorization adapter.
+- [ ] Remote typed clients resolve authorization headers per request through their own adapter.
+- [ ] Control credentials never enter Foundry config, manifests, data, prompts, or observability.

package/docs/guidance.md

@@ -0,0 +1,146 @@
+# Goals, facts, forms, and live context
+
+Foundry exposes `goals`, `facts`, `forms`, and `contextProviders` as typed lazy
+agent fields. Use them in `defineAgent` or as named exports in `agent.ts`.
+Configurations may be literal values or resolvers returning values, Promises, or
+Effects based on the current message, history, instance, and conversation.
+
+These mount native Glove surfaces, not a second workflow engine. Programs, schemas,
+gates, hooks, and preparation rules are code. Progress, answers, fact revisions,
+evidence claims, and effect receipts are adapter-owned runtime data.
+
+## Mount native surfaces
+
+```ts
+import { defineAgent, defineFacts, defineGoals, defineForms,
+  foundryGuidanceSubject, type AgentAssemblyContext } from "glove-foundry";
+import { createSqliteMemoryAdapters } from "glove-memory/sqlite";
+import { MemorySchema } from "glove-memory/core";
+import { intakeGoals, intakeForms } from "./workflow.js";
+import model from "./model.js";
+
+const memory = (ctx: AgentAssemblyContext) => createSqliteMemoryAdapters({
+  file: "/data/agent-memory.sqlite",
+  namespace: foundryGuidanceSubject(ctx, "instance"),
+  schema: new MemorySchema(),
+});
+
+export default defineAgent({
+  description: "Conversational intake",
+  systemPrompt: "Collect information conversationally using workflow tools.",
+  model,
+  facts: (_agent, ctx) => defineFacts({ adapter: memory(ctx).facts }),
+  goals: (_agent, ctx) => defineGoals({ adapter: memory(ctx).goals, program: intakeGoals }),
+  forms: (_agent, ctx) => defineForms({ adapter: memory(ctx).forms, registry: intakeForms }),
+  contextProviders: (_agent, ctx) => [async signal => {
+    signal?.throwIfAborted();
+    return `Response preference: ${ctx.agentInstance.context.concise ? "concise" : "detailed"}`;
+  }],
+});
+```
+
+See the complete [guided-intake example](../../../examples/foundry-agent/agents/guided-intake)
+for the native program, Zod form, direct code references, deterministic no-key
+model, and optional OpenRouter model. Run `pnpm verify:guidance` in the example
+project for a real Foundry worker/restart check.
+
+One surface of each kind mounts per runnable. A program can contain many goals;
+a registry can contain many forms. Return `undefined` to omit a surface for a run.
+This removes its tools from that assembly, not its saved state.
+
+## Scope and reconstruction
+
+The default subject derives from workspace, instance, and conversation—not run id.
+Set `scope: "instance"` to deliberately share across an instance's conversations.
+For externally scoped business identities, supply a native goal/fact scope or
+form `{ subject }`. Authorization and tenant isolation remain host-owned.
+`foundryGuidanceSubject(ctx, scope)` derives the same key outside assembly.
+Facts additionally have an evidence context; goals have a program key.
+
+`program` seeds an absent goal scope through native idempotent `start`. Reassembly
+never resets progress or overwrites an existing program. To adapt obligations,
+call the runner's `revise` with the version you read and a reason. Keep native
+goal/item keys stable; use code values such as `identityGoal.key`, not repeated
+string references. These are native revision keys, not a new Foundry registry.
+
+`configure`, `spawn`, and `run` receive `ctx.goals`, `ctx.facts`, and `ctx.forms`
+as typed native handles. Goals also accept native `configure({ glove, status })`,
+`hooks`, `tools`, and `onChange` options for progress-dependent behavior.
+
+## Facts and opt-in preparation
+
+Mounting facts adds native `record_fact`. The model supplies text and urgency;
+Foundry binds message/run provenance. It cannot grant verification or choose
+another subject. Supply `source` for transport-specific stable operation ids.
+Host-verified evidence can be written with `ctx.facts.record(...)`.
+
+To enable automatic preparation, give `facts.preparationAgent` a dedicated,
+built Glove runnable with its own scope-specific store and tracing subscribers.
+Then configure `goals.preparation` or `forms.preparation` with native `rule` and
+optional `eligible` callbacks. Foundry constructs the shared native
+`FactPreparation`; it never calls a model adapter directly. Preparation without
+a dedicated agent, or with mismatched facts/workflow subjects, rejects explicitly.
+Never reuse the conversational runnable or a preparation store across fact scopes.
+
+Rules are host-owned allowlists; omitted requirements remain manual. Unverified
+information needs confirmation unless explicitly permitted. Actions and outcomes
+need verified successful evidence with the correct evidence key; approvals need
+an authorized actor. Intentions are not actions. Corrections can require review;
+they do not automatically overwrite answers or repeat completed effects. The same
+evidence can support multiple workflows without being consumed globally.
+
+## Forms and effects
+
+Use native `defineForm`, Zod fields, gates, checkpoints and executors. Register a
+definition using its own `.id`, not a copied reference string. The registry makes
+forms available; it does not start every form. Native tools select, start, fill,
+inspect, revise and abandon them. A host may call `ctx.forms.start(form.id)`;
+check saved instances, including completed ones, before once-only initialization.
+
+Adapters retain full answer history, pending hook batches, prepared claims,
+checkpoint state, and dispatch receipts. Goal hooks and form effects are
+at-least-once: downstream effects must use their idempotency keys. Native schemas
+and gates retain authority over valid values and permitted effects.
+
+## Custom context providers
+
+The outer resolver selects providers once per run. Each returned native provider
+is re-read before a model iteration and may fetch live adapter state. It returns
+text, null, or undefined and receives an abort signal. Keep providers read-only;
+do not run inference inside one. Foundry removes its providers during cleanup,
+including failures.
+
+Glove appends transient user-role context after complete tool-result pairs, without
+rewriting system instructions or storing snapshots as conversation messages.
+Custom runnable wrappers must forward `addContextProvider` and `getRuntimeContext`.
+Realtime voice refreshes at startup and after tools; after external changes the
+host calls `realtime.refreshContext()`. It does not automatically interrupt speech
+or erase superseded context already in the provider's session.
+
+## Persistence and inspection
+
+`createSqliteMemoryAdapters` supplies goals, facts and forms alongside entity,
+episodic, resource and pinned-context memory. Use Node 22.13+ and a local persistent
+volume. Goal/form operations are transactional with native CAS and audit state.
+Facts use a separate SQLite lock file across asynchronous scope callbacks;
+each save commits independently and process death releases the OS-owned lock.
+All fact scopes in one database serialize. For greater concurrency use separate
+files or a production database adapter. Network filesystems are unsupported.
+Same-process callers queue behind the active callback; `busyTimeoutMs` bounds
+SQLite contention after that queue, not inference or callback duration. Bound
+preparation-agent execution in the host and avoid recursive fact callbacks.
+Do not delete or replace database/lock files while workers run. Back up a coherent
+SQLite snapshot, not just a live main file without its WAL. The lock file contains
+no application records.
+
+The inspector's **Conversation guidance** card shows goal progress, fact
+revision/claim counts, and form status/pending effects. It is the latest observed
+run snapshot, not a live database query. Its `foundry.guidance.state` event omits
+answers and fact bodies. Native runtime-context/tool traces can still contain
+conversation content; apply normal access and retention controls. Never put
+credentials in facts or context providers.
+
+Foundry data, transcript storage, workflow state, and VFS persistence are separate
+boundaries. Durable workflow adapters do not make a transient transcript durable.
+These fields do not schedule background work; use Foundry's existing schedules,
+sleep, and inbound activations for that.

package/docs/inspector.md

@@ -1,5 +1,10 @@
 # Foundry inspector
 
+Run detail includes a **Conversation guidance** card when goals, facts, forms or
+custom context providers are mounted. It shows the latest observed progress,
+fact/claim counts and pending form effects, not a live database query. Answer
+values and fact bodies are excluded from this summary. See [guidance](./guidance.md).
+
 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
@@ -10,13 +15,43 @@ The development server includes a read-oriented runtime inspector. It is organiz
 | 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? |
+| Chat | What has this exact instance/conversation said, and how can I continue, stop, or redirect it? |
 | 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.
+Every detail view has a real URL. For example, `/agents/support-lead`, `/instances/<agent-id>`, `/chat/<conversation-id>?agent=<agent-id>`, and `/runs/<run-id>` can be bookmarked or opened directly; the Foundry server returns the inspector shell for non-API paths.
+
+The inspector and APIs share one authorization boundary. Loopback remains the
+development default. Foundry refuses a non-loopback bind without the application's
+`requestAuthorization` adapter; when configured, every HTML, API, health, and event
+stream request must pass it. The adapter owns credential/session validation and the
+browser challenge, while Foundry keeps credential values out of state and traces.
+
+## Talking to an agent
+
+**Chat** is a browser conversation client, not a second transcript system. Select a
+runtime instance in the left rail, create or reopen any of its conversations, and
+send text, images, video, or documents. The page reads native Glove `Message`
+records from the definition or root `conversationStore`, including tool calls and
+results. Recent history loads first; **Earlier** and **Newer** page through long
+sessions without putting an unbounded transcript into the browser. It also displays
+the store's turn and token counters. When no store is
+configured the page says that history is unavailable instead of inventing history
+from run output or observability events.
+
+During an active turn the conversation shows safe runtime progress and links to the
+complete run trace. Provider-approved `text_delta` events form a transient assistant
+bubble while work is active; when the run settles, the exact stored message replaces
+that projection. Buffered output from failed provider attempts never reaches the page.
+**Stop** cooperatively cancels it. Sending another message while
+it is active becomes **Redirect**: Foundry interrupts at a run boundary and creates
+a replacement run in the same conversation with steering lineage. Session routing
+is explicit in the URL, and every refresh reloads history from the server. New
+conversations take the first text turn as their initial title and can be renamed
+later without changing their stable conversation identity.
 
 ## Following a run
 
@@ -80,6 +115,9 @@ Every truncated identifier in the inspector has a copy button, so the full run,
 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/conversations/:id/messages?agent=<agent-id>` for exact adapter-backed history
+- `POST /api/conversations/:id/messages` and `/api/runs/:id/cancel|steer`
+- `PATCH /api/conversations/:id` for an instance-owned title or context update
 - `/api/runs`, `/api/runs/:id`, and `/api/events`
 - `/api/activations` and `/api/playbook-subscriptions`
 - `/api/application-connections`