Glove Foundry

Glove Foundry

Build Foundry projects as cohesive agent applications: typed code definitions, durable runtime data, message-aware assembly, and observable execution. Foundry is the preferred Glove application/runtime framework. Glovebox is deprecated and should only be maintained when a task explicitly targets a legacy Glovebox deployment.

Start with the repository

Before changing Foundry, inspect the current public surface and the closest executable example. Do not rely on remembered APIs.

• Read packages/glove-foundry/docs/building-with-foundry.md for authoring conventions.
• Read packages/glove-foundry/docs/architecture.md when changing definitions, instances, activation, persistence, credentials, or runtime boundaries.
• Read packages/glove-foundry/docs/inspector.md for observability and workbench changes.
• Use examples/foundry-agent as the canonical small application. Use the Braind Storm and voice examples only when their specialized behavior is relevant.
• Inspect exports in packages/glove-foundry/src/index.ts and tests beside the affected module before inventing a helper.

Preserve the mental model

Foundry separates immutable code definitions from mutable runtime data.

• agents/<route>/agent.ts defines reusable behavior and lazy assembly. It is not a running agent and never declares request input or result output.
• Agent instances are persisted data with their own ids, workspace, context, installations, and playbooks. They can be provisioned, updated, removed, and reconstructed without changing the definition.
• Conversations are first-class instance-owned records. One instance may own many conversations.
• Applications, transmissions, predicates, actions, shared tools, MCP definitions, memory profiles, layers, subscribers, and schedules are composable code values colocated with the owning agent.
• Installations, selected accounts/routes, playbooks, subscriptions, scheduled activations, workspace state, and conversations are runtime data.

Filenames own static identity. Convention files default-export one definition, and static code references imported values. Do not repeat string ids for code-owned relationships or add an id to a file-routed definition. String ids are appropriate only after serialization or at database, HTTP, frontend, and other data boundaries.

Author colocated, composable definitions

Use the conventional project shape and keep pieces atomic:

agents/<agent>/
  agent.ts
  composition.ts
  apps/*.app.ts
  transmissions/*.transmission.ts
  events/*.event.ts
  predicates/*.predicate.ts
  actions/*.action.ts
  connections/*.connection.ts
  tools/*.tool.ts
  mcp/*.mcp.ts
  memory/*.memory.ts
  inboxes/*.inbox.ts
  layers/*.layer.ts
  subscribers/*.subscriber.ts
  schedules/*.ts

Use composeAgent(...) to assemble the agent-local catalogue. Composition makes definitions available; it does not install applications, MCPs, or shared tools. An instance chooses those surfaces dynamically with typed install(...) records.

Prefer the definition helper that owns the contract (defineAgent, defineApp, defineTransmission, defineSharedTool, defineMcp, defineMemory, defineLayer, defineSchedule, and related helpers). Let the definition's Zod or Effect schema carry config types through installation and runtime decoding. Do not add parallel handwritten config types or cast away inference.

Resolve behavior lazily

Agent assembly is contextual. Use a direct value for fixed behavior and a resolver when the result can depend on the instance, conversation, workspace, installation state, current Glove message, prior messages, or request.

Common lazy fields include model, system prompt, tools, memory, inboxes, layers, subscribers, calls, subagents, mesh, playbooks, schedules, working environment, REPL, build, and run.

• Inboxes must be lazy; do not model an inbox as a static singleton.
• Applications, MCPs, and shared tools are available through composition but mounted only when installed on the current instance.
• Memory belongs to the agent definition and may be selected lazily for the current context.
• A custom build augments assembly; a custom run controls execution. Prefer the default path unless a real lifecycle requirement needs an override.
• Use the native Glove Message shape. Do not invent a Foundry-specific input/output contract inside defineAgent.

Applications, transmissions, and credentials

An application may own multiple inbound and outbound transmissions. Outbound transmissions become validated tools only when the application is installed. Transmission definitions own authentication, normalization, classification, predicates, serialization, and delivery behavior; playbooks remain data-oriented policy.

Connections are colocated with their application and receive the narrow Foundry connection context. Keep backend concepts such as Station networks, beacons, signals, or worker topology out of public Foundry definitions, client types, manifests, and inspector language. Expose only purpose-built agent-system concepts such as inbound connections, activations, scheduled work, and runs.

Foundry never acquires, refreshes, or stores credential material. Account records contain safe metadata and opaque access references. The consumer's account-session/provider adapter owns credential lookup and refresh. Never copy secrets into instance data, manifests, prompts, telemetry, or inspector payloads.

Playbooks, inbound activation, and provisioning

Playbooks are serializable instance policy composed at runtime from imported transmission primitives. They match inbound events, supply directives and serialization, and describe any outbound response route. They are not a global file-routed registry.

Agent definitions may lazily return desired playbooks, and persisted instances may carry frontend-authored playbooks. Durable playbook subscriptions are evaluated even when no instance exists and may provision zero, one, or many subscribed agents before delivering the event into a conversation.

When changing inbound behavior, preserve idempotency: claim delivery by route and event before provisioning or enqueueing runs. Provision through the data adapter so provisioningKey remains atomic.

Schedules, sleep, and future work

Schedules are agent-local definition values that reconcile into persisted activations. They are not a system-wide static registry.

• A lazy schedules resolver may load predefined desired schedules for an agent instance.
• Agents create future or recurring work with Foundry's schedule tool.
• Agents must be able to list, update, and cancel their own scheduled triggers.
• Sleep suspends the logical run and wakes the same instance and conversation later with a resolution message.
• Pending and recurring activations must reconstruct from a durable FoundryDataAdapter on restart.

Do not expose the private execution backend as the authoring model for schedules or sleep.

Working environment, VFS, REPL, and media

Foundry mounts native Glove surfaces instead of reimplementing them.

• Use defineWorkingEnvironment(...) for a guarded VFS, scripts, history, checkpoints, and artifact export.
• Add a persistence adapter when work must survive across runs. Treat the VFS as the durable boundary; REPL bindings are run-scoped.
• Use defineRepl(...) with glove-js, glove-python, or glove-lisp for computation over explicitly registered functions.
• Use glove-image and the working-environment format adapters for image, document, slide, spreadsheet, archive, audio, or video work.
• Pass artifacts between agents by durable workspace/VFS references rather than copying large document bodies into prompts.
• For HTTP calls/downloads/uploads and host keystores, read HTTP files and host secrets. Mount fetchFiles() and secret() in the environment options; scope the host store to the owning instance and re-supply it after restore. Snapshots do not persist secrets or network grants.
• Native fetch blocks non-public DNS/IP destinations; private services require exact host opt-ins. Keep credentials in host aliases, not scripts or manifests. Custom transports own equivalent network/TLS safety. In adapter bindings, read ctx.signal at call time so run termination aborts host I/O.

Goals, facts, and prepared workflows

Goals, forms, and pinned context require glove-core >=4.0.0 for live runtime snapshots. They append transient user-role messages at the model-input tail before each model iteration without rewriting system instructions or saved history. Runnable proxies forward addContextProvider and getRuntimeContext; subscribers receive runtime_context snapshots. Realtime voice refreshes silently at start and after tools; call await realtime.refreshContext() after external changes.

Use glove-memory/goals for dynamic goals and glove-facts for reusable scoped evidence; there is no standalone glove-goals package. Mount useGoalRunner or useFormRunner from glove-memory/tools on the conversational runnable, and useFacts from glove-facts for capture.

Enable shared preparation with new FactPreparation(facts, { agent: preparationAgent }). Supply a dedicated, built Glove runnable and separate store per fact scope, with the application's tracing subscribers attached. The library mounts submit_preparation and calls processRequest; do not bypass Glove with a direct model invocation or substitute the conversational agent. No agent means automatic preparation is off while capture/manual progression remain available. Host rules allowlist fields/items; workflow commits retain authority over values, progress and effects.

Use existing Foundry build/assembly extension points; do not invent a Foundry goals or facts definition field. Read the shared workflow guide and facts adapter contracts for scope, correction, tracing and recovery requirements.

Multi-agent systems

Choose the smallest correct composition surface:

• defineSubagent for an isolated nested task under a parent run.
• Foundry calls for typed agent-to-agent or agent-to-service invocation.
• Mesh for peer messaging and acknowledgements.
• Playbook subscriptions for inbound events that can provision a workforce.
• Workspaces, conversations, inbox items, tasks, and artifacts for durable coordination.

Keep agent definition identity separate from agent instance identity in traces and APIs. Make concurrent campaigns distinct instances/conversations/runs so orchestration and progress remain legible.

Effect and error handling

Foundry's service, persistence, transmission, and orchestration internals are Effect-native. Preserve typed errors, resource scopes, cancellation, and service boundaries. Use Effect.gen, schemas, layers, and scoped finalizers where they clarify lifecycle or failure semantics. Do not wrap Effect code in ad-hoc promises merely to suppress its error channel.

User-provided Glove callbacks may return promises where the public type permits it. Keep adapters replaceable and avoid coupling domain definitions to the in-memory implementation.

Observability and inspector language

Emit safe, correlated events using Foundry concepts: definition, instance, conversation, activation, run, model, tool, application, transmission, inbox, memory, MCP, workspace, artifact, and system. Show work intent, action, handoff, status, and result—not private hidden reasoning or raw secrets.

The inspector should make the causal path obvious:

arrival -> matched playbook -> provisioned instance(s) -> conversations -> runs -> artifacts/outcomes

Avoid provider/backend error jargon in primary UI copy. Put detailed raw events behind diagnostics while presenting a plain-language current state and next action.

Verification

Run checks proportional to the change. For framework work, the normal floor is:

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

For scaffold or public API changes, also generate a temporary project and verify its typecheck. For inspector/site changes, build the site and exercise the affected UI. Assert behavioral invariants rather than snapshots of prose. Finish with git diff --check and check that no credential value entered generated files, events, or manifests.