glove

name	glove
description	Expert guide for building AI-powered applications with the Glove framework. Use when working with glove-core, glove-react, glove-next, tools, display stack, model adapters, stores, any Glove example project, or deploying agents as sandboxed runtime services with Glovebox (glovebox / glovebox-kit / glovebox-client).

Glove Framework — Development Guide

You are an expert on the Glove framework. Use this knowledge when writing, debugging, or reviewing Glove code.

What Glove Is

Glove is an open-source TypeScript framework for building AI-powered applications. Users describe what they want in conversation, and an AI decides which capabilities (tools) to invoke. Developers define tools and renderers; Glove handles the agent loop.

Repository: https://github.com/porkytheblack/glove Docs site: https://glove.dterminal.net License: MIT (dterminal)

Package Overview

Package	Purpose	Install
glove-core	Runtime engine: agent loop, tool execution, display manager, model adapters, MemoryStore default in-memory StoreAdapter (browser-safe — no native deps)	pnpm add glove-core
glove-sqlite	Deprecated. SqliteStore — persistent SQLite-backed store. Prefer MemoryStore from glove-core for prototyping or BYO StoreAdapter for production.	pnpm add glove-sqlite
glove-react	React hooks (useGlove), GloveClient, GloveProvider, defineTool, <Render>, MemoryStore, ToolConfig with colocated renderers	pnpm add glove-react
glove-next	One-line Next.js API route handler (createChatHandler) for streaming SSE	pnpm add glove-next
glove-mcp	Bridge MCP servers into a Glove agent: mountMcp, connectMcp, bridgeMcpTool, McpAdapter, discovermcp discovery subagent. Opt-in OAuth helpers at glove-mcp/oauth.	pnpm add glove-mcp
glove-memory	Schema-first memory layer with four sibling subsystems: entity graph, episodic timeline, resource filesystem, and ambient context. BYO storage via the adapter contracts; reference in-memory adapters ship for dev/test. Storage backends (glove-memory-sqlite, glove-memory-postgres) are companion packages — not yet released. Draft v0.1.	pnpm add glove-memory
glove-mesh	Inter-agent communication on top of the inbox primitive: mountMesh, MeshAdapter (BYO transport), MeshNetwork + InMemoryMeshAdapter reference impl. Four tools — glove_mesh_send_message, glove_mesh_broadcast, glove_mesh_list_agents, glove_mesh_acknowledge. No auth (consumer's job).	pnpm add glove-mesh
glove-continuum-signal	Subprocess-based runtime substrate for agent collaboration across time. Two modes: triggered (cold, spawn-per-wakeup) and concurrent (warm, long-lived subprocess notified inline). agent() builder, ContinuumRunner (discovery + supervision + IPC), ContinuumAdapter (BYO persistence; MemoryAdapter default), ContinuumSubscriber (lifecycle + forwarded Glove events). Pairs with glove-mesh for inter-agent talk — substrate provides the supervised subprocesses, mesh provides the messaging.	pnpm add glove-continuum-signal
glovebox-core	Authoring + glovebox build CLI. glovebox.wrap(runnable, config) packages a built Glove agent into a deployable artifact (Dockerfile + nixpacks.toml + bundled server + manifest + auth key). Storage DSL (rule.*, composite) and wire protocol types live here too. The unscoped glovebox name is taken on npm — install as glovebox-core; the CLI binary is still glovebox.	pnpm add glovebox-core
glovebox-kit	In-container runtime. startGlovebox({ app, port, key, manifestPath, ... }) boots the WS server, auto-injects glovebox skills/hooks, and bridges Glove's display stack onto the wire. Storage adapters: InlineStorage, UrlStorage, LocalServerStorage, S3Storage.	(transitive — bundled by glovebox build)
glovebox-client	Client SDK. GloveboxClient.make({ endpoints }), client.box(name).prompt(text, { files }), result.read(name), box.environment(). Symmetric ClientStorage interface with a default inline+url implementation.	pnpm add glovebox-client
glove-scratchpad	Database emulator for tool use. Expose an agent's capabilities as a relational DB it queries with ONE execute_sql tool instead of loading dozens of tool defs. Resources become tables (defineResource with a Zod schema, or resourceFromTool); CRUD verbs map to underlying tools; WHERE pushes arguments down; information_schema is discovery; transactions stage outbound effects. mountDatabase(glove, { db }). MCP servers → tables via glove-scratchpad/mcp. Query engine is glove-sql (bundled); PGlite optional. Also ships the shared glove-scratchpad/fns ToolFn catalog the REPL surfaces below consume (defineFn, fnFromTool, fnsFromMcp, sampleResultShapes).	pnpm add glove-scratchpad
glove-lisp	REPL surface for tool use (Clojure-flavored). Expose capabilities as functions in a persistent, sandboxed Lisp REPL behind ONE execute_lisp tool. Two modes over the same session: ResourceTable mode (registerAll) and function mode (registerFns, the glove-scratchpad/fns catalog). LispSession.create() + mountLisp(glove, { session }). Draft v0.1.	pnpm add glove-lisp
glove-js	REPL surface for tool use (JavaScript). Capabilities become async functions in a tiny sandboxed JS interpreter driven by ONE execute_js tool over the glove-scratchpad/fns catalog. JsSession.create() + mountJs(glove, { session }). Progressive discovery is callable in-REPL under BOTH the short names (search/servers/fns/describe) and the native-tool-name aliases (search_functions/list_servers/list_functions/describe_function), so a model primed on the tool names lands its call. Hardened to the top A/B arm (97%) — see JS-EXPLORATION.md. Draft v0.1.	pnpm add glove-js
glove-python	REPL surface for tool use (Python). Capabilities become functions in a sandboxed Python subset driven by ONE execute_python tool over the same catalog; tool calls take keyword args (github.list_pull_requests(state="open")). Comprehensions, f-strings, slicing, def/lambda; dunder attributes blocked. PySession.create() + mountPy(glove, { session }). See PY-EXPLORATION.md. Draft v0.1.	pnpm add glove-python

Most projects need just glove-react + glove-next. glove-core is included as a dependency of glove-react. For server-side or non-React agents, use glove-core directly — see Server-Side Agents below. For agents that need third-party tools via the Model Context Protocol, see MCP Integration.

What's in the framework

• glove-core — agent loop, tools, display stack, store/model/subscriber adapters, context compaction, inbox, hooks/skills/subagents, MemoryStore default in-memory StoreAdapter.
• glove-react — colocated renderers via defineTool, <Render>, useGlove, MemoryStore, createRemoteStore, createEndpointModel, createRemoteModel.
• glove-next — createChatHandler (one-line SSE route), voice token handler.
• glove-sqlite — deprecated; SqliteStore for persistence (server-side only).
• glove-voice — full-duplex voice pipeline: STT/TTS/VAD adapters, GloveVoice, useGloveVoice, useGlovePTT, <VoicePTTButton>.
• glove-mcp — MCP servers as first-class tools: mountMcp, connectMcp, bridgeMcpTool, McpAdapter (consumer-supplied per-conversation seam). discovermcp discovery subagent (registered via glove.defineSubAgent(discoverySubAgent({...}))). Opt-in OAuth helpers at glove-mcp/oauth (runMcpOAuth, FsOAuthStore, MemoryOAuthStore, McpOAuthProvider).
• glove-memory — Memory layer with four sibling subsystems (entity graph / episodic timeline / resource filesystem / ambient context) and matching useMemoryReader / useMemoryCurator, useEpisodicReader / useEpisodicCurator, useResourcesReader / useResourcesCurator, and useContext helper families. Storage-agnostic adapter contracts plus reference InMemory* adapters for dev/test.
• glove-mesh — Inter-agent messaging on top of the inbox primitive: mountMesh(glove, { adapter, identity }) registers an agent and folds glove_mesh_send_message / _broadcast / _list_agents / _acknowledge. MeshAdapter is the consumer-supplied transport (BYO); ships InMemoryMeshAdapter + MeshNetwork for in-process dev/test. Each agent keeps its own inbox; incoming messages land as resolved InboxItems so the existing inbox-injection path surfaces them on the next ask(). No authentication — sender ids are unverified.
• glove-continuum-signal — Subprocess-based runtime substrate modeled on station-signal but agent-shaped. agent("name").input(zod).triggered()|.concurrent() builder produces branded agents; ContinuumRunner discovers them from a directory, pre-warms concurrent ones, dispatches triggered runs from an adapter queue (per-spawn isolation), and routes notify IPC envelopes to warm subprocesses inline. ContinuumAdapter is the persistence contract (MemoryAdapter ships; consumers BYO for SQLite/Postgres/etc.). Single fat onAgentEvent(envelope) subscriber forwards every Glove SubscriberEvent from any child upstream with the agent identity attached. Mesh integrates by being mounted per-agent inside the factory — no special IPC machinery.
• glove-scratchpad — Database emulator for LLM tool use. Instead of loading many tool definitions, expose capabilities as a relational database queried with one execute_sql tool. Resources (github_pr, emails, time, images, …) become tables; CRUD verbs map to (possibly different) underlying tools. Database.create(), defineResource({ name, schema, keys?, volatility, select?, insert?, update?, delete? }) (Zod-first — the schema is columns AND the end-to-end row type) or resourceFromTool(tool, { name, volatility, schema }), mountDatabase(glove, { db }) folds execute_sql + explain_sql and primes the prompt. Discovery via information_schema; WHERE equalities push down as arguments (Steampipe's required-key model); writes stage inside BEGIN … COMMIT for preview; EXPLAIN reports which tools a query hits with no resolver calls. Every statement is parsed and security-gated before any tool runs. MCP servers become tables via glove-scratchpad/mcp (mcpResources / mountMcpDatabase). Backend is glove-sql (bundled, zero-dep) or PgliteBackend (glove-scratchpad/pglite).

Architecture at a Glance

User message → Agent Loop → Model decides tool calls → Execute tools → Feed results back → Loop until done
                                                          ↓
                                                   Display Stack (pushAndWait / pushAndForget)
                                                          ↓
                                                   React renders UI slots

Core Concepts

• Agent — AI coordinator that replaces router/navigation logic. Reads tools, decides which to call.
• Tool — A capability: name, description, inputSchema (Zod), do function, optional render + renderResult.
• Display Stack — Stack of UI slots tools push onto. pushAndWait blocks tool; pushAndForget doesn't.
• Display Strategy — Controls slot visibility lifecycle: "stay", "hide-on-complete", "hide-on-new".
• renderData — Client-only data returned from do() that is NOT sent to the AI model. Used by renderResult for history rendering.
• Adapter — Pluggable interfaces for Model, Store, DisplayManager, and Subscriber. Swap providers without changing app code.
• Context Compaction — Auto-summarizes long conversations to stay within context window limits. The store preserves full message history (so frontends can display the entire chat), while Context.getMessages() splits at the last compaction summary so the model only sees post-compaction context. Summary messages are marked with is_compaction: true.
• Inbox — Persistent async mailbox for cross-instance communication. An agent posts a request (text) that can't be resolved now; an external service resolves it later (text response). Resolved items are automatically injected into the agent's context on the next ask() call. Items can be blocking (agent should wait) or non-blocking. Built-in glove_post_to_inbox tool auto-registered when store supports inbox methods.
• Extensions (hooks, skills, subagents) — /hookname runs a builder-defined handler with full agent controls (force compaction, swap model, short-circuit a turn). /skillname materialises a synthetic user message before the real one (marked is_skill_injection: true). defineSubAgent({ name, factory }) registers a subagent the main agent can route to via the auto-registered glove_invoke_subagent tool — the user's @name text is NOT parsed by glove, it reaches the model verbatim and acts as a routing signal (mirrors Claude Code's subagent convention). / tokens are replaced with non-triggerable placeholders ([invoked_extension__hook_<name>] / [invoked_extension__skill_<name>]) so the model sees that an extension fired without the placeholder re-binding on a future parse; unbound / tokens stay untouched (so /usr/local survives). Skills can be exposed to the agent (exposeToAgent: true) so the agent pulls them in via the auto-registered glove_invoke_skill tool.
• MCP catalogue + adapter — glove-mcp introduces two pieces: a static McpCatalogueEntry[] describing servers the app supports, and a per-conversation McpAdapter holding active ids and resolving access tokens. mountMcp reloads previously active servers and registers a discovermcp discovery subagent (via glove.defineSubAgent(discoverySubAgent({...}))) — the model invokes it through glove_invoke_subagent({ name: "discovermcp", prompt: "..." }) to find and activate servers mid-conversation.
• Mesh network — glove-mesh lets Glove agents send each other messages via a consumer-supplied MeshAdapter (transport). Each agent keeps its own StoreAdapter+inbox; when A sends to B, the framework drops a status: "resolved" InboxItem into B's store so the existing inbox-injection path surfaces it on B's next ask(). Blocking sends insert a pending blocking: true item that resolves on ack or in_reply_to reply. No auth in v1.
• Continuum (subprocess runtime) — glove-continuum-signal supervises Glove agents as Node subprocesses. Triggered agents are cold and spawn-per-wakeup (resume from a persistent StoreAdapter each time); concurrent agents are warm and notified inline. The agent() builder forks into mode-specific types after .triggered() / .concurrent() so mode-specific setters (.retries(), .every()) are type-level guarded. Persistent stores configured via .store(name => StoreAdapter) so the same store implementation can be injected across an agent fleet. Parent is single source of truth for run status (children only emit IPC). Mesh integration: mount in the factory — substrate stays out of inter-agent protocol.

Quick Start (Next.js)

1. Install

pnpm add glove-core glove-react glove-next zod

2. Server route

// app/api/chat/route.ts
import { createChatHandler } from "glove-next";

export const POST = createChatHandler({
  provider: "anthropic",     // or "openai", "openrouter", "gemini", etc.
  model: "claude-sonnet-4-20250514",
});

Set ANTHROPIC_API_KEY (or OPENAI_API_KEY, etc.) in .env.local.

3. Define tools with defineTool

// lib/glove.tsx
import { GloveClient, defineTool } from "glove-react";
import type { ToolConfig } from "glove-react";
import { z } from "zod";

const inputSchema = z.object({
  question: z.string().describe("The question to display"),
  options: z.array(z.object({
    label: z.string().describe("Display text"),
    value: z.string().describe("Value returned when selected"),
  })),
});

const askPreferenceTool = defineTool({
  name: "ask_preference",
  description: "Present options for the user to choose from.",
  inputSchema,
  displayPropsSchema: inputSchema,       // Zod schema for display props
  resolveSchema: z.string(),             // Zod schema for resolve value
  displayStrategy: "hide-on-complete",   // Hide slot after user responds
  async do(input, display) {
    const selected = await display.pushAndWait(input);  // typed!
    return {
      status: "success" as const,
      data: `User selected: ${selected}`,         // sent to AI
      renderData: { question: input.question, selected },  // client-only
    };
  },
  render({ props, resolve }) {           // typed props, typed resolve
    return (
      <div>
        <p>{props.question}</p>
        {props.options.map(opt => (
          <button key={opt.value} onClick={() => resolve(opt.value)}>
            {opt.label}
          </button>
        ))}
      </div>
    );
  },
  renderResult({ data }) {               // renders from history
    const { question, selected } = data as { question: string; selected: string };
    return <div><p>{question}</p><span>Selected: {selected}</span></div>;
  },
});

// Tools without display stay as raw ToolConfig
const getDateTool: ToolConfig = {
  name: "get_date",
  description: "Get today's date",
  inputSchema: z.object({}),
  async do() { return { status: "success", data: new Date().toLocaleDateString() }; },
};

export const gloveClient = new GloveClient({
  endpoint: "/api/chat",
  systemPrompt: "You are a helpful assistant.",
  tools: [askPreferenceTool, getDateTool],
  // getSessionId: () => fetch("/api/session").then(r => r.json()).then(d => d.id),
});

4. Provider + Render

// app/providers.tsx
"use client";
import { GloveProvider } from "glove-react";
import { gloveClient } from "@/lib/glove";

export function Providers({ children }: { children: React.ReactNode }) {
  return <GloveProvider client={gloveClient}>{children}</GloveProvider>;
}

// app/page.tsx — using <Render> component
"use client";
import { useGlove, Render } from "glove-react";

export default function Chat() {
  const glove = useGlove();

  return (
    <Render
      glove={glove}
      strategy="interleaved"
      renderMessage={({ entry }) => (
        <div><strong>{entry.kind === "user" ? "You" : "AI"}:</strong> {entry.text}</div>
      )}
      renderStreaming={({ text }) => <div style={{ opacity: 0.7 }}>{text}</div>}
    />
  );
}

Or use useGlove() directly for full manual control:

// app/page.tsx — manual rendering
"use client";
import { useState } from "react";
import { useGlove } from "glove-react";

export default function Chat() {
  const { timeline, streamingText, busy, slots, sendMessage, renderSlot, renderToolResult } = useGlove();
  const [input, setInput] = useState("");

  return (
    <div>
      {timeline.map((entry, i) => (
        <div key={i}>
          {entry.kind === "user" && <p><strong>You:</strong> {entry.text}</p>}
          {entry.kind === "agent_text" && <p><strong>AI:</strong> {entry.text}</p>}
          {entry.kind === "tool" && (
            <>
              <p>Tool: {entry.name} — {entry.status}</p>
              {entry.renderData !== undefined && renderToolResult(entry)}
            </>
          )}
        </div>
      ))}
      {streamingText && <p style={{ opacity: 0.7 }}>{streamingText}</p>}
      {slots.map(renderSlot)}
      <form onSubmit={(e) => { e.preventDefault(); sendMessage(input.trim()); setInput(""); }}>
        <input value={input} onChange={(e) => setInput(e.target.value)} disabled={busy} />
        <button type="submit" disabled={busy}>Send</button>
      </form>
    </div>
  );
}

Server-Side Agents

For CLI tools, backend services, WebSocket servers, or any non-browser environment, use glove-core directly. No React, Next.js, or browser required.

Minimal Setup

import { Glove, Displaymanager, MemoryStore, createAdapter } from "glove-core";
import z from "zod";

// MemoryStore from glove-core is the default. Omit `store` from the
// Glove config and Glove constructs one for you with a generated identifier.
// For persistence implement your own StoreAdapter.
const store = new MemoryStore("my-session");

const agent = new Glove({
  store,
  model: createAdapter({ provider: "anthropic", stream: true }),
  displayManager: new Displaymanager(),  // required but can be empty
  systemPrompt: "You are a helpful assistant.",
  serverMode: true,  // canonical "I am headless" flag — drives default permission gating + MCP discovery policy
  compaction_config: {
    compaction_instructions: "Summarize the conversation.",
  },
})
  .fold({
    name: "search",
    description: "Search the database.",
    inputSchema: z.object({ query: z.string() }),
    async do(input) {
      const results = await db.search(input.query);
      return { status: "success", data: results };
    },
  })
  .build();

const result = await agent.processRequest("Find recent orders");
console.log(result.messages[0]?.text);

MemoryStore from glove-core

MemoryStore is the default StoreAdapter used when Glove is constructed without a store. It implements every optional surface — messages, tokens, turns, tasks, permissions, inbox, and createSubAgentStore — so subagents work out of the box.

import { MemoryStore } from "glove-core";

const store = new MemoryStore("my-session");

// Sub-stores: durable: false (default) returns a fresh per-call store.
// durable: true caches the same instance per namespace so a subagent can
// carry message history across invocations.
const childStore = await store.createSubAgentStore("researcher", false);

MemoryStore is process-local — it loses data on restart. For persistence, implement StoreAdapter against your own backend. glove-sqlite is deprecated; new projects should prefer MemoryStore for prototyping or BYO StoreAdapter for production.

Key Differences from React

React (glove-react)	Server-side (glove-core)
defineTool with render/renderResult	.fold() with just do — no renderers needed
useGlove() hook manages state	Call agent.processRequest() directly
GloveClient + GloveProvider	new Glove({...}).build()
createEndpointModel (SSE client)	createAdapter() or direct adapter (e.g. new AnthropicAdapter())
MemoryStore from glove-react	MemoryStore from glove-core (default) — or implement StoreAdapter for persistence

Tools Without Display

Most server-side tools ignore the display manager — just return a result:

gloveBuilder.fold({
  name: "get_weather",
  description: "Get weather for a city.",
  inputSchema: z.object({ city: z.string() }),
  async do(input) {
    const res = await fetch(`https://wttr.in/${input.city}?format=j1`);
    return { status: "success", data: await res.json() };
  },
});

Returning a plain string also works — auto-wrapped to { status: "success", data: yourString }.

Interactive Tools (pushAndWait)

When a tool calls display.pushAndWait(), the agent loop blocks until dm.resolve(slotId, value) is called. Wire this to your UI layer (WebSocket, terminal, Slack, etc.):

// Tool side
async do(input, display) {
  const confirmed = await display.pushAndWait({
    renderer: "confirm",
    input: { message: `Delete ${input.file}?` },
  });
  if (!confirmed) return { status: "error", data: null, message: "Cancelled" };
  // proceed...
}

// Server side — resolve when user responds
dm.resolve(slotId, true);

Subscribers (Logging, Forwarding)

import type { SubscriberAdapter } from "glove-core";

const logger: SubscriberAdapter = {
  async record(event_type, data) {
    if (event_type === "text_delta") process.stdout.write((data as any).text);
    if (event_type === "tool_use") console.log(`\n[tool] ${(data as any).name}`);
  },
};

gloveBuilder.addSubscriber(logger);

Common Patterns

• CLI script: Build agent, call processRequest(), print result
• Multi-turn REPL: Loop with readline, each processRequest() accumulates in the store
• WebSocket server: Per-connection session with isolated store/dm/subscriber, forward events via record()
• Background worker: Build agent per job, process from a queue, no display needed
• Hot-swap model: Call agent.setModel(newAdapter) at runtime
• MCP-backed agent: Set serverMode: true, call mountMcp(glove, { adapter, entries }) before build(). See MCP Integration.

Optional Store Features

• Tasks (getTasks, addTasks, updateTask): Auto-registers glove_update_tasks tool
• Permissions (getPermission(name, input?), setPermission(name, status, input?)): Tools with requiresPermission: true (or a (input) => boolean gate) check consent. The Executor passes the model-supplied input on every gated call so the store can scope decisions per-input. The default MemoryStore uses exact-match keying via the exported permissionKey(name, input) helper.
• Inbox (getInboxItems, addInboxItem, updateInboxItem, getResolvedInboxItems): Auto-registers glove_post_to_inbox tool. Enables async cross-instance communication.

If your store doesn't implement these, they're silently disabled.

Inbox (Async Mailbox)

The inbox enables agents to post requests that will be resolved later by external services — surviving across sessions and instances.

How It Works

1. Agent calls glove_post_to_inbox with a tag, request text, and blocking flag
2. Item persists in the store with status pending
3. External service resolves the item (via SqliteStore.resolveInboxItem() from glove-sqlite, or store API)
4. Next time agent.ask() runs, resolved items are injected as text messages and marked consumed
5. Pending blocking items are surfaced as transient reminders (not persisted)
6. Compaction preserves pending inbox items in the summary block

Built-in Tool: glove_post_to_inbox

Auto-registered when store implements inbox methods. Input schema:

{
  tag: string,       // Category label, e.g. "restock_watch"
  request: string,   // Natural language description of what needs to happen
  blocking: boolean, // Default false. If true, agent should wait for resolution
}

External Resolution

// From a background job, webhook handler, or cron:
import { SqliteStore } from "glove-sqlite";

SqliteStore.resolveInboxItem(
  "path/to/db.db",
  "inbox_item_id",
  "The item you requested is now available."  // text response
);

Or via REST if you've set up inbox API routes (see coffee example).

InboxItem Type

interface InboxItem {
  id: string;
  tag: string;
  request: string;
  response: string | null;
  status: "pending" | "resolved" | "consumed";
  blocking: boolean;
  created_at: string;
  resolved_at: string | null;
}

Store Methods (Optional)

// Add to StoreAdapter to enable inbox:
getInboxItems?(): Promise<InboxItem[]>
addInboxItem?(item: InboxItem): Promise<void>
updateInboxItem?(itemId: string, updates: Partial<Pick<InboxItem, "status" | "response" | "resolved_at">>): Promise<void>
getResolvedInboxItems?(): Promise<InboxItem[]>

All store implementations (SqliteStore from glove-sqlite, MemoryStore, createRemoteStore) support inbox.

React Integration

useGlove() returns inbox: InboxItem[] alongside tasks:

const { inbox, tasks, timeline, sendMessage } = useGlove({ tools, sessionId });

// Show pending watches in UI
{inbox.filter(i => i.status === "pending").map(item => (
  <div key={item.id}>{item.tag}: {item.request}</div>
))}

Remote Store Actions

When using createRemoteStore, add inbox actions to persist to your backend:

const storeActions: RemoteStoreActions = {
  // ...existing getMessages, appendMessages...
  getInboxItems: (sid) => fetch(`/api/sessions/${sid}/inbox`).then(r => r.json()),
  addInboxItem: (sid, item) => fetch(`/api/sessions/${sid}/inbox`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ item }) }),
  updateInboxItem: (sid, itemId, updates) => fetch(`/api/sessions/${sid}/inbox/update`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ itemId, updates }) }),
  getResolvedInboxItems: (sid) => fetch(`/api/sessions/${sid}/inbox/resolved`).then(r => r.json()),
};

Extensions: Hooks, Skills & Subagents

processRequest parses two kinds of inline directive out of the user text and dispatches them before the model is called. Subagents are a third extension surface, but they are NOT parsed from user text — they are routed by the model through a dispatch tool. Builders register handlers via three builder methods (chainable, callable post-build() like fold):

Token / mechanism	Purpose	Builder method
/hookname	Mutate agent state, force compaction, swap model, short-circuit a turn	defineHook(name, handler)
/skillname	Inject context as a synthetic user message marked is_skill_injection: true	defineSkill({ name, handler, description?, exposeToAgent? })
glove_invoke_subagent({ name, prompt }) (model-side tool)	Register a child Glove the main agent can route a self-contained task to. The user's @name text reaches the model verbatim — it's a routing signal, not a parsed directive. Mirrors Claude Code's subagent convention.	defineSubAgent({ name, factory, description? })

/ tokens only bind when the name matches a registered hook or skill — /usr/local/bin survives untouched. Bound / tokens are replaced, not stripped, with a non-triggerable placeholder of the form [invoked_extension__hook_<name>] or [invoked_extension__skill_<name>]. The placeholder doesn't re-bind on a future parse, but it keeps the persisted user message structurally honest — the model can see that an extension fired. @ tokens are never parsed by glove at all, so emails like [e-mail] reach the model unchanged.

Quick example

import { Glove, MemoryStore } from "glove-core";

const agent = new Glove({ /* ... */ })
  .defineHook("compact", async ({ controls }) => {
    await controls.forceCompaction();
  })
  .defineHook("stop", async () => ({
    shortCircuit: { message: { sender: "agent", text: "Cancelled." } },
  }))
  .defineSkill({
    name: "concise",
    description: "Tighter, snappier responses",
    exposeToAgent: true,
    handler: async ({ source, args }) =>
      `Be terse. (source=${source}, hint=${args ?? "none"})`,
  })
  .defineSubAgent({
    name: "weather",
    description: "Run the weather subagent. Use for weather questions.",
    factory: async ({ parentStore, parentControls, prompt }) => {
      const subStore = await parentStore.createSubAgentStore?.("weather", false)
        ?? new MemoryStore(`weather_${Date.now()}`);
      return new Glove({
        store: subStore,
        model: parentControls.glove.model,
        displayManager: parentControls.displayManager,
        systemPrompt: "You are a weather assistant. Answer the prompt and return.",
        compaction_config: { compaction_instructions: "Summarise weather lookups." },
      })
        .fold(weatherTool)
        .build();
    },
  })
  .build();

await agent.processRequest("/concise tell me about Rust");      // user-invoked skill
await agent.processRequest("/compact what's next?");           // hook → forceCompaction
// "@weather" reaches the model verbatim. The agent calls
// glove_invoke_subagent({ name: "weather", prompt: "NYC" }).
await agent.processRequest("@weather NYC");

Hooks

type HookHandler = (ctx: HookContext) => Promise<HookResult | void>;

interface HookContext {
  name: string;
  rawText: string;
  parsedText: string;        // text with bound tokens replaced by [invoked_extension__<type>_<name>] placeholders
  controls: AgentControls;
  signal?: AbortSignal;
}

interface HookResult {
  rewriteText?: string;      // override parsedText for downstream skills + the user message
  shortCircuit?:
    | { message: Message }
    | { result: ModelPromptResult };
}

interface AgentControls {
  context: Context;
  observer: Observer;
  promptMachine: PromptMachine;
  executor: Executor;
  glove: IGloveRunnable;
  store: StoreAdapter;             // direct access to the agent's StoreAdapter
  displayManager: DisplayManagerAdapter;  // direct access to the agent's display stack
  forceCompaction: () => Promise<void>;
}

forceCompaction calls Observer.runCompactionNow() — same body as tryCompaction minus the token-threshold guard. Subscribers still see compaction_start / compaction_end.

Hooks run in document order. rewriteText overrides the working text passed to subsequent hooks, skills, and the final user message. shortCircuit persists the user message and returns immediately — the model is not called. Glove emits hook_invoked ({ name }) on subscribers just before each hook handler runs.

Skills

type SkillHandler = (ctx: SkillContext) => Promise<string | ContentPart[]>;

interface SkillContext {
  name: string;
  parsedText: string;        // when source = "user": user text with bound directives replaced by their placeholders. when source = "agent": same as args ?? "".
  args?: string;             // model-supplied free-form args (only when source = "agent")
  source: "user" | "agent";
  controls: AgentControls;
}

interface SkillOptions {
  description?: string;       // shown to the agent in the invoke-skill tool listing
  exposeToAgent?: boolean;    // default false
}

interface DefineSkillArgs extends SkillOptions {
  name: string;
  handler: SkillHandler;
}

interface RegisteredSkill {
  handler: SkillHandler;
  description?: string;
  exposeToAgent: boolean;
}

Skill-injected messages set is_skill_injection: true on Message, alongside the existing is_compaction and is_compaction_request flags. Use it in transcript renderers to render injected context differently from real user turns. Glove emits skill_invoked ({ name, source: "user" | "agent", args? }) on subscribers — for user-side directives, the dispatch fires from Glove.processRequest; for agent-side calls, it fires from inside the glove_invoke_skill tool.

Exposing skills to the agent

Set exposeToAgent: true and Glove auto-registers a single glove_invoke_skill tool on the executor. Its description lists every exposed skill (- name — description) and is rebuilt in place each time a new exposed skill is defined, so post-build() registrations are picked up immediately.

agent.defineSkill({
  name: "research-mode",
  description: "Switch to long-form research mode with citations",
  exposeToAgent: true,
  handler: async ({ source, args, parsedText }) => {
    if (source === "agent") {
      // Agent invoked via glove_invoke_skill — `args` is the model-supplied string.
      return `Switch into research mode. Focus: ${args ?? "general"}.`;
    }
    // source === "user" — `parsedText` is the user message after directive substitution
    // (e.g. "[invoked_extension__skill_research-mode] tell me about ribosomes").
    return `Switch into research mode. User said: ${parsedText}`;
  },
});

// User: "/research-mode tell me about ribosomes"
//   → source = "user", parsedText = "[invoked_extension__skill_research-mode] tell me about ribosomes"
// Agent: glove_invoke_skill({ name: "research-mode", args: "ribosome assembly" })
//   → source = "agent", args = "ribosome assembly"

The tool returns { status: "success", data: { skill, content } } on success and { status: "error", message: 'Skill "..." is not available', data: null } for unknown or unexposed names. When the skill returns ContentPart[], text parts are joined into data.content (visible to the model) and the full part list is preserved on renderData (visible to client renderers, mirroring the MCP-bridge convention).

Aspect	User /skill	Agent glove_invoke_skill
Where it lands	Synthetic user message before the real turn (is_skill_injection: true)	Tool result on the agent's tool_use
SkillContext.source	"user"	"agent"
SkillContext.args	undefined	free-form string the model supplied
Gated by exposeToAgent	No — user-invoked always works	Yes — only exposed skills are callable

Subagents

Modelled on Claude Code's subagent convention. Defining one auto-registers a glove_invoke_subagent tool (constant SUBAGENT_DISPATCH_TOOL_NAME exported from core) the main agent calls with { name, prompt }. The user's @name text in the original message is not parsed by glove — it reaches the model verbatim and acts as a routing signal. The factory builds a fresh child Glove for each invocation and the dispatcher runs it.

interface SubAgentFactoryContext {
  /** Subagent name as registered with `defineSubAgent`. */
  name: string;
  /** The task prompt the parent agent supplied when calling `glove_invoke_subagent`. */
  prompt: string;
  /** The parent agent's store. Use `createSubAgentStore(name, durable)` to derive a child store. */
  parentStore: StoreAdapter;
  /** Full parent agent controls (context, observer, promptMachine, executor, glove, store, displayManager, forceCompaction). */
  parentControls: AgentControls;
}

type SubAgentFactory = (
  ctx: SubAgentFactoryContext,
) => Promise<IGloveRunnable> | IGloveRunnable;

interface SubAgentOptions {
  /** Short description shown to the agent in the invoke-subagent tool listing. */
  description?: string;
}

interface DefineSubAgentArgs extends SubAgentOptions {
  name: string;
  factory: SubAgentFactory;
}

interface RegisteredSubAgent {
  factory: SubAgentFactory;
  description?: string;
}

Canonical factory

import { Glove, MemoryStore } from "glove-core";

glove.defineSubAgent({
  name: "researcher",
  description: "Deep research subagent",
  factory: async ({ parentStore, parentControls }) => {
    // Sub-store: durable false → fresh per-call; durable true → cached for the namespace.
    const subStore = await parentStore.createSubAgentStore?.("researcher", false)
      ?? new MemoryStore(`researcher_${Date.now()}`);

    return new Glove({
      store: subStore,
      model: parentControls.glove.model,           // inherit the parent's model
      displayManager: parentControls.displayManager, // share the parent's display stack
      systemPrompt: "You are a researcher.",
      compaction_config: { compaction_instructions: "Summarize research progress." },
    })
      .fold(searchTool)
      .fold(fetchTool)
      .build();   // build() can take a store too; passing it here is equivalent to constructor `store`
  },
});

The dispatcher attaches the parent's subscribers to the child for the run, calls child.processRequest(prompt, signal) (forwarding the parent's abort signal), then detaches them. The child's final agent text is returned as the tool result.

Tool result shape

Symmetric with glove_invoke_skill:

// Tool input
{ name: string, prompt: string }

// Success
{ status: "success", data: { subagent: string, content: string } }

// Unknown name
{ status: "error", message: 'Subagent "..." is not registered. Use one of: ...', data: null }

// Factory threw
{ status: "error", message: 'Subagent "..." factory threw: ...', data: null }

// Child run threw
{ status: "error", message: 'Subagent "..." failed: ...', data: null }

Bracket events — guaranteed 1:1 symmetry

The Executor (not the dispatcher) brackets every glove_invoke_subagent call with subagent_invoked ({ name, prompt }) before the run and subagent_completed ({ name, status: "success" | "error", message? }) after. The bracket is symmetric even when a parent abort short-circuits the dispatcher's promise chain: the executor's abort handler still fires the close bracket. Events emitted by the child Glove between them belong to that subagent — parent subscribers are attached to the child for the duration of the run.

Common patterns

• Fresh child per call: factory builds a new Glove each invocation, with its own MemoryStore (or a non-durable sub-store). Default and recommended.
• Durable child: parentStore.createSubAgentStore("name", true) returns the same store for the namespace, so the subagent carries message history across invocations. The factory still builds a fresh Glove; only the store is reused.
• Multiple in one message ("@reviewer @architect please discuss this design"): both names reach the model, which can call glove_invoke_subagent once per subagent (sequentially or in parallel via separate tool calls — its choice).

Sub-stores: createSubAgentStore

StoreAdapter exposes an optional createSubAgentStore(namespace: string, durable?: boolean): Promise<StoreAdapter> factory:

• durable: false (default) → a fresh, isolated store per call. The subagent starts from zero context every invocation.
• durable: true → the same instance is returned for the same namespace, so the subagent retains messages, tasks, tokens, and counters across invocations within the parent's lifetime.

MemoryStore from glove-core implements both modes. If your store doesn't implement createSubAgentStore, fall back to new MemoryStore(...) inside the factory — that preserves the "fresh per call" behavior.

setDisplayManager (chainable)

Glove (both builder and runnable forms) exposes setDisplayManager(displayManager). Subagent factories typically pass parentControls.displayManager into the child's constructor, but they can also opt in mid-flight by calling child.setDisplayManager(parentControls.displayManager) after build. Returns this for chaining.

Dispatch order in processRequest

1. Parse / directives from the raw text (regex (^|\s)\/([A-Za-z][\w-]*)(?=\s|$)). Bound tokens are replaced with [invoked_extension__<type>_<name>] placeholders; unbound tokens stay in place. @ tokens are not parsed at all.
2. Run hooks in document order. Glove emits hook_invoked per hook. Apply any rewriteText; honour the first shortCircuit and return.
3. Materialise skills (source: "user") — each becomes a synthetic user message persisted via context.appendMessages before the real one. Glove emits skill_invoked per skill.
4. Build the real user Message from the placeholder-substituted text (still contains any @mentions untouched) + any non-text ContentParts the caller passed.
5. Hand off to Agent.ask. Subagent invocations happen inside the agent loop via glove_invoke_subagent tool calls; the executor brackets each one with subagent_invoked / subagent_completed.

is_skill_injection flag

Skill-materialised user messages set is_skill_injection: true on Message. Pair it with is_compaction for transcript rendering — collapse, mute, or filter injected messages so they're visually distinct from real user turns.

pre_modified_text on Message

When a hook rewrites the user message via rewriteText, the original raw text is preserved on Message.pre_modified_text so frontends can render what the user actually typed alongside the rewritten version the model received.

Public API surface

import {
  // Builder
  Glove, // .defineHook(), .defineSkill(), .defineSubAgent()
  // Types
  HookHandler, HookContext, HookResult,
  SkillHandler, SkillContext, SkillOptions, DefineSkillArgs, RegisteredSkill,
  SubAgentFactory, SubAgentFactoryContext, SubAgentOptions, DefineSubAgentArgs, RegisteredSubAgent,
  AgentControls,
  // Constants
  SUBAGENT_DISPATCH_TOOL_NAME, // "glove_invoke_subagent"
  // Helpers
  parseTokens, formatSkillMessage,
  createSkillInvokeTool, renderSkillToolDescription,
  createSubAgentInvokeTool, renderSubAgentToolDescription,
} from "glove-core";

Available at the main entry and the glove-core/extensions subpath.

MCP Integration (glove-mcp)

glove-mcp bridges Model Context Protocol servers (Notion, Gmail, Linear, Slack, an internal MCP wrapper around your own APIs, …) into a Glove agent so their tools appear in the model's tool list as ordinary Glove tools. Streamable HTTP transport only in v1.

When to use it

• You need third-party capabilities a vendor already exposes via MCP — Notion, Gmail, Linear, Slack, Zapier-MCP, etc.
• You have multiple internal services and want a single integration shape across them.
• You want the agent to discover and activate capabilities mid-conversation rather than wiring all tools at startup.

If you control both ends and just need a few first-party tools, hand-rolled glove.fold(...) is still simpler. MCP earns its keep when the catalogue is large or the servers are not yours.

Mental model: catalogue + adapter

Two pieces, deliberately split:

• McpCatalogueEntry[] — a static list authored at the application level. One entry per MCP server the app supports: id, name, description, url, tags?, excludeTools?, metadata?. Identical across users. The id doubles as the tool namespace prefix and the activation key. excludeTools?: string[] drops tools by exact un-namespaced name — filtered at the connection, so an excluded tool is never mounted by ANY path (boot reload, discovermcp activate, or a glove-scratchpad bridge over the same connection).

• McpAdapter — a per-conversation interface the consumer implements (analogous to StoreAdapter). Holds the conversation's active server ids and resolves access tokens.

  interface McpAdapter {
    identifier: string;                          // for log correlation
    getActive(): Promise<string[]>;              // ids active in this conversation
    activate(id: string): Promise<void>;         // called by the discovery subagent
    deactivate(id: string): Promise<void>;       // for the consumer's UI; v1 limitation: doesn't unload tools
    getAccessToken?(id: string): Promise<string>;                // bearer seam — return a token string
    getAuthHeaders?(id: string): Promise<Record<string, string>>; // custom-header seam — e.g. { "x-api-key": ... }; wins over getAccessToken
  }
  

getAccessToken / getAuthHeaders are the only auth seams. The common case is getAccessToken — the framework wraps the returned string in Authorization: Bearer .... For servers that don't take a bearer token (e.g. Composio's x-api-key), implement getAuthHeaders and return the full header map; it takes precedence when both are defined, and with neither, connections are made without auth headers. Credential acquisition, refresh, and persistence are entirely the consumer's responsibility — env vars, vault, your own OAuth flow, the opt-in runMcpOAuth helper, all valid.

mountMcp — the canonical entry point

After new Glove(...) and before glove.build():

import { mountMcp } from "glove-mcp";

const glove = new Glove({ /* ... */ , serverMode: true });

await mountMcp(glove, {
  adapter,                                  // McpAdapter
  entries,                                  // McpCatalogueEntry[]
  ambiguityPolicy: { type: "auto-pick-best" },  // optional
  subagentModel: undefined,                 // optional — defaults to glove.model
  subagentSystemPrompt: undefined,          // optional — defaults to per-policy prompt
  clientInfo: { name: "My App", version: "1.0.0" },  // optional
  filterTools: (tool, entry) => !tool.annotations?.destructiveHint,  // optional — catalogue-wide drop
});

glove.build();

What it does, in order:

1. Reads adapter.getActive(), opens an MCP connection per active id (using getAccessToken), lists tools, and folds each one onto the main agent via bridgeMcpTool. Per-server reload failures are logged and skipped — a transient outage doesn't kill the agent.
2. Registers the discovermcp discovery subagent via glove.defineSubAgent(discoverySubAgent({...})) so the model can ask it to activate more servers mid-conversation. The model invokes it via glove_invoke_subagent({ name: "discovermcp", prompt: "..." }).

Excluding tools. To keep specific tools off the model, set excludeTools: string[] (exact un-namespaced names) on the McpCatalogueEntry, or pass filterTools: (tool, entry) => boolean to mountMcp for a catalogue-wide rule (runs on top of each entry's excludeTools). Both are applied at the connection (connectMcp also accepts excludeTools / filterTools directly), so the exclusion bubbles through every mount path from one place — boot reload, discovermcp activate, and any glove-scratchpad bridge (mcpResources / fnsFromMcp) built over the same connection. Only the listing is filtered; conn.raw / conn.callTool stay untouched. includeTool(tool, { excludeTools, filterTools }) is the exported pure predicate.

mountMcp returns when reload + subagent registration are complete. Call it before build() for the cleanest init order, but fold() / defineSubAgent() after build() work too.

Bridged tool shape

bridgeMcpTool(connection, tool, serverMode) produces a GloveFoldArgs with these conventions:

• Name: ${entry.id}__${tool.name} (e.g. notion__search). The __ separator (exported as MCP_NAMESPACE_SEP) is regex-safe across all model providers.
• Input schema: raw JSON Schema from the MCP server, passed via jsonSchema (no Zod). The MCP server is the source of truth.
• Result shape: when the server declares an outputSchema (MCP 2025-06-18+), a compact Returns: … shape (via jsonSchemaToShape, exported) is appended to the tool description — model tool-call wire formats are input-only, so the description is the only channel to surface the return shape on the plain bridged path. Servers below that revision, or without a declared schema, omit it.
• requiresPermission: in serverMode always false; otherwise true unless the MCP tool annotates readOnlyHint: true.
• Result: the model sees the server's structuredContent when present (MCP 2025-06-18+, JSON-stringified into data), else the joined content[] text; the full content[] is always passed through as renderData so React renderers can use it.
• Auth-expired contract: any 401-shaped error during callTool is mapped to { status: "error", message: "auth_expired", data: null }. Detect this from the conversation log, refresh your token, and the next call picks up the new value via getAccessToken.

Discovery (discovermcp) and ambiguity policies

mountMcp registers a single subagent the model can route to: discovermcp. The model invokes it via glove_invoke_subagent({ name: "discovermcp", prompt: "send an email" }). The factory builds a child Glove (with its own sub-store from parentStore.createSubAgentStore("discovermcp", false), falling back to a private DiscoveryMemoryStore when sub-stores aren't supported, inheriting the main agent's model, displayManager, and serverMode), and folds these tools onto the child:

• list_capabilities(query?, tags?) — substring search the catalogue.
• activate(id) — connect, bridge tools onto the main agent, persist active state. Tools become available to the main model on its next turn.
• deactivate(id) — flip persisted state. v1 limitation: tools stay loaded until session refresh.
• ask_user(question, options) — only registered under the interactive policy. Renders via the mcp_picker renderer on the main displayManager.

The ambiguity policy controls what happens when the subagent finds multiple plausible matches:

Policy	Behavior	When to use
{ type: "interactive" }	Subagent calls ask_user via pushAndWait. Requires an mcp_picker renderer on your displayManager.	Browser UIs / chat apps with a renderer wired up. Default when serverMode: false.
{ type: "auto-pick-best" }	Subagent always picks the highest-ranked match. No human in the loop.	Headless / server-side / CLI. Default when serverMode: true.
{ type: "defer-to-main" }	Subagent returns the candidate list as text and lets the main agent decide what to activate.	Multi-MCP discovery flows where the main model has more conversation context than the subagent.

serverMode: true on the Glove config is the canonical "I am headless" flag — drives both the default ambiguity policy and the default requiresPermission on bridged tools (never gate).

Auth model — static headers (bearer or custom)

The framework only knows about static headers per connection. connectMcp ships two helpers: auth: bearer(token | () => token) for Authorization: Bearer ..., and auth: headers(map | () => map) for servers that want custom headers (e.g. Composio's x-api-key). Both accept a thunk that re-resolves per connection. mountMcp and the discovery activate tool resolve auth via adapterAuth(adapter, id) — getAuthHeaders when defined, else getAccessToken wrapped as a bearer, else no auth headers.

import { bearer, headers, connectMcp } from "glove-mcp";

const conn = await connectMcp({
  namespace: "notion",
  url: "https://mcp.notion.com/mcp",
  auth: bearer(() => adapter.getAccessToken!("notion")),
  clientInfo: { name: "My App", version: "1.0.0" },
});

const composio = await connectMcp({
  namespace: "composio",
  url: "https://mcp.composio.dev/...",
  auth: headers({ "x-api-key": process.env.COMPOSIO_API_KEY! }),
});

auth_expired contract

Mid-call, an expired token surfaces as { status: "error", message: "auth_expired" } on the bridged tool result. The framework does not refresh tokens. Your app must:

1. Detect auth_expired on the conversation log (subscriber tool_use_result event, or post-hoc).
2. Refresh / re-auth via whatever mechanism owns the credential.
3. Update your store; the next bridged call pulls a fresh token from getAccessToken.

For UI consumers this is usually a "Reconnect Notion" toast. For CLIs, instructing the user to re-run the auth command is normal.

glove-mcp/oauth — opt-in OAuth tooling

If you don't already have an OAuth flow, the glove-mcp/oauth subpath ships a small reference implementation built on the MCP authorization spec:

• runMcpOAuth(opts) — one call, end-to-end flow. Spins up a local listener on http://localhost:53683/callback (configurable), drives the SDK through DCR (or skips it via preRegisteredClient), opens the user's browser, exchanges the code for tokens, and verifies via listTools (or a callTool of your choice). Used by the examples/mcp-cli/*-mcp-auth.ts scripts.
• FsOAuthStore / MemoryOAuthStore — OAuthStore implementations. FsOAuthStore writes a single JSON file with mode 0600 and atomic temp+rename. Replace with your DB for production.
• McpOAuthProvider — lower-level OAuthClientProvider for advanced consumers driving auth() from the SDK directly.
• buildClientMetadata, MCP_DEFAULT_CLIENT_INFO, emptyOAuthState — small helpers.

Consumers who already have tokens (env vars, internal integrations, vault, an existing OAuth setup) can ignore this subpath entirely — getAccessToken returns the bearer, full stop.

See api-reference.md — glove-mcp/oauth for full type signatures, and examples.md — Pattern: MCP OAuth flow for a worked example.

Production lift-and-shift

The reference examples/mcp-cli setup is a single-user Node CLI; production typically wants:

• Multi-user store — replace FsOAuthStore with a per-user OAuthStore backed by your DB. The interface is three methods (get, set, delete).
• OAuth flow in route handlers — GET /oauth/<id>/start calls runMcpOAuth (or the lower-level SDK auth() directly), GET /oauth/<id>/callback finishes it. Same machinery, different invocation. The local-listener flavour of runMcpOAuth is convenient for CLIs but not what you want behind a load balancer.
• Background refresh — refresh expired tokens however your stack does it; getAccessToken just reads the latest bearer string.
• Persistent active state — the McpAdapter shown in examples uses an in-memory Set for active ids. In production, persist active ids per conversation (alongside messages) so reload after restart actually does something.

The agent code itself doesn't change — McpAdapter.getAccessToken is the only seam.

Quick reference — where things live

Need	Symbol
Mount MCP onto an agent	mountMcp(glove, { adapter, entries, ... })
Implement consumer adapter	McpAdapter interface
Author catalogue entries	McpCatalogueEntry
One-off connect (preflight, custom flow)	connectMcp({ namespace, url, auth })
Bridge a tool by hand	bridgeMcpTool(connection, tool, serverMode)
Bearer header helper	`bearer(token
Custom headers helper (non-bearer, e.g. x-api-key)	`headers(map
Adapter → auth resolver	adapterAuth(adapter, id)
Discovery subagent factory	discoverySubAgent({ adapter, entries, ambiguityPolicy }) (returns DefineSubAgentArgs; pass to glove.defineSubAgent(...))
Tool namespace separator	MCP_NAMESPACE_SEP ("__")
401 detection on raw connect	UnauthorizedError
Run the OAuth flow	runMcpOAuth(opts) from glove-mcp/oauth
Persist OAuth state	FsOAuthStore, MemoryOAuthStore from glove-mcp/oauth
Build client metadata	buildClientMetadata(opts) from glove-mcp/oauth

Memory (glove-memory)

Schema-first memory layer with four sibling subsystems. Storage-agnostic adapter contracts; reference in-memory adapters ship for dev/test. Status: draft v0.1; companion storage backends (glove-memory-sqlite, glove-memory-postgres) are not yet released.

The four subsystems

Subsystem	Adapter	What it's for
Entity	EntityMemoryAdapter	Graph-shaped, schema-first, deterministic identity resolution. Nodes (people, organizations, projects) and typed edges between them. Curator-written, agent-read.
Episodic	EpisodicMemoryAdapter	Timeline-bound, append-only events. Meetings, decisions, observations. Time is a first-class field; semantic search is opt-in (advertised by supportsSemanticSearch).
Resources	ResourceFsAdapter	POSIX-style virtual filesystem the agent navigates with ls / read / grep / glob / edit. Holds research notes, transcripts, link collections. Text-only; absolute paths only (no . / ..).
Context	ContextAdapter	User-configured ambient context, auto-injected into the system prompt every turn. Different shape: not curator-extracted, no reader/curator split — one registration gives the agent both read and write tools.

Architectural recommendation: don't dump memory tools on the main Glove

If you're building an agent that needs memory access, do not attach the entity / episodic / resources tools directly to your main Glove. Build subagents — one per retrieval task — and register them on the main agent. Each subagent attaches only the adapter slice it needs.

Why:

• Bounded prompt surface. Tool descriptions render the schema slice for that role only — token cost scales with role, not with total ontology size.
• Sharper routing. lookup / recall / find-notes subagent names are themselves a reasoning surface. Tighter signal than "you have eight memory tools, decide which".
• Mutation scope is structural. A subagent attached with useMemoryReader cannot write; the affordance isn't there.
• Adapters stay shared. All subagents read and write to the same underlying graph / timeline / filesystem. Splitting tools does not split the data.

Same advice on the curator side: a parent curator that routes to specialised write-side subagents (entity-linker, episode-recorder, resource-filer) beats a single curator with every write tool attached.

The exception is useContext. Context is small (4 tools), user-driven ("remember that…"), and ships with the system-prompt-injection wrapper that has to live on the agent the user actually talks to. Keep useContext on the main agent.

See examples.md — Memory: subagent-delegated reader / curator composition / context flow for worked-out patterns.

Helper families

Each helper folds the relevant tool surface onto a Glove. All return the same G for chaining; all operate on either an IGloveBuilder or an IGloveRunnable (anything that exposes fold).

Helper	Folds	Notes
useMemoryReader(glove, adapter)	glove_memory_find, _get, _query	Read-only entity graph access.
useMemoryCurator(glove, adapter)	reader tools + _add_node, _update_node, _connect, _disconnect, _merge_nodes	Full entity write access.
useEpisodicReader(glove, adapter)	glove_episodic_find, _timeline, _search	_search only registered when adapter.supportsSemanticSearch === true.
useEpisodicCurator(glove, adapter)	reader tools + _record, _update, _delete
useResourcesReader(glove, adapter)	glove_resources_ls, _read, _stat, _grep, _glob, _search, _links_for	_search only when supportsSemanticSearch.
useResourcesCurator(glove, adapter)	reader tools + _write, _edit, _mkdir, _move, _remove, _set_metadata
useContext(glove, adapter)	glove_context_get, _set, _update, _unset	Also wraps processRequest to call adapter.render() and prepend the rendered markdown block to the system prompt every turn.

Tool inventory

Entity (useMemoryReader / useMemoryCurator)

Tool	Purpose
glove_memory_find	Find nodes by class + filter, optional fuzzy
glove_memory_get	Fetch a node by id + one-hop neighbourhood
glove_memory_query	Full structured query via the query DSL
glove_memory_add_node	Create or upsert a node by identity keys (curator)
glove_memory_update_node	Patch a node's properties (curator)
glove_memory_connect	Create or update an edge (curator)
glove_memory_disconnect	Remove an edge (curator)
glove_memory_merge_nodes	Fold one node into another (curator)

Episodic (useEpisodicReader / useEpisodicCurator)

Tool	Purpose
glove_episodic_search	Content search over episodes — embedding-based semantic or in-process fuzzy/lexical, depending on the adapter (only when supportsSemanticSearch)
glove_episodic_find	Structured filter — by kind, participant, time range, properties
glove_episodic_timeline	Chronological listing for an entity or time window
glove_episodic_record	Append a new episode (curator)
glove_episodic_update	Patch an existing episode (curator)
glove_episodic_delete	Remove an episode (curator)

Resources (useResourcesReader / useResourcesCurator)

Tool	Purpose
glove_resources_ls	List directory contents
glove_resources_read	Read a file body, with optional line range
glove_resources_stat	Get metadata about a single path
glove_resources_grep	Text/regex search across the tree
glove_resources_glob	Find paths by name pattern
glove_resources_search	Semantic search (only when supportsSemanticSearch)
glove_resources_links_for	Reverse-lookup: find resources linking to a target
glove_resources_write	Create or overwrite a file (curator)
glove_resources_edit	Replace a unique substring (curator)
glove_resources_mkdir	Create an empty directory (curator)
glove_resources_move	Rename or relocate (curator)
glove_resources_remove	Delete a file or directory (curator)
glove_resources_set_metadata	Patch metadata without rewriting body (curator)

Context (useContext)

Tool	Purpose
glove_context_get	Read entries by section or list all
glove_context_set	Add a new entry
glove_context_update	Patch an existing entry in place
glove_context_unset	Remove an entry or wipe an entire section

MemorySchema — the shared ontology

One schema object is passed to every adapter. Lives in code; the package does not persist it, validate it across deployments, or expose migration primitives — that's the consumer's concern.

import { MemorySchema } from "glove-memory/core";
import { z } from "zod";

const schema = new MemorySchema()
  .defineNodeClass({
    name: "Person",
    schema: z.object({ name: z.string(), email: z.string().optional() }),
    identityKeys: [["email"], ["name"]],          // multi-set: any matching set folds the write
    searchableProperties: ["name", "email"],      // indexed for fuzzy / contains
  })
  .defineRelationship({
    type: "worksAt",
    from: "Person",
    to: "Organization",
    propertiesSchema: z.object({ since: z.string().optional() }).optional(),
    multi: false,                                  // default — re-connect updates rather than duplicating
  })
  .defineEpisodeKind({
    name: "meeting",
    description: "A scheduled gathering.",
    propertiesSchema: z.object({ duration_min: z.number() }).optional(),
  })
  .defineResourceRoot({
    path: "/research",
    description: "External research artifacts.",
    semanticSearch: true,                          // default true; false skips embedding lifecycle for this root
  });

What's safe at runtime:

• Adding a new node class, relationship, or episode kind is always safe.
• Adding an optional property is always safe.
• Adding a required property won't break reads; new writes that don't supply it fail validation.
• Removing or renaming properties needs a consumer-managed rewrite — the adapter won't notice.
• Changing identity keys may silently collapse or split nodes on subsequent writes.

Provenance — required, append-only, every write

Every adapter write takes a Provenance. It's append-only per node, edge, episode, resource, and context entry. Reader-facing tools filter provenance out of results; only direct adapter calls return it.

interface Provenance {
  source: string;     // "conversation:<id>/turn:<n>", "manual", "import:<kind>:<id>"
  actor: string;      // "curator-run-xyz", "user:don", "system"
  timestamp: string;  // ISO 8601
  note?: string;      // free-form rationale (identity-merge decisions, conflict notes)
}

Link is the shared cross-reference vocabulary — episodes pointing at people, resources pointing at episodes, context entries pointing at projects.

interface Link {
  kind: "entity" | "episode" | "resource";
  id: string;             // entity / episode id, or resource path
  relation?: string;      // free-form, e.g. "primary-contact", "source-transcript"
}

The package does not validate that link targets exist — adapters stay decoupled. Cross-validation is the curator / orchestrator's job.

Embedding lifecycle — out-of-band, BYO adapter

Episodic and resources use the same lifecycle. Writes mark records embeddingStatus: "missing" (initial) or "stale" (content change) and return immediately. A separate process — typically a Station signal — does the embed pass:

interface EmbeddingAdapter {
  dimensions: number;
  embed(texts: string[]): Promise<number[][]>;
}

The refresh loop:

const pending = await episodic.findEpisodesNeedingEmbedding({ limit: 50 });
const vectors = await embedder.embed(pending.map((p) => p.content));
for (let i = 0; i < pending.length; i++) {
  await episodic.setEmbedding(pending[i].id, vectors[i]);
}

Resources use findFilesNeedingEmbedding / setEmbedding (both optional on ResourceFsAdapter, present only when supportsSemanticSearch === true). Stale marking on episodes is content-only in the in-memory adapter — kind / participants / properties / occurredAt patches don't re-embed; consumers wanting different behaviour can delete + re-record. The recency blend in searchEpisodes defaults to recencyWeight = 0.2 with a 30-day half-life.

Custom episodic adapter with a background index (BYO search)

The embeddingStatus + findEpisodesNeedingEmbedding + setEmbedding lifecycle is a generic background-indexing seam, not embedding-specific — the index can be vectors, SQLite FTS5, Postgres tsvector, BM25, Meilisearch, Tantivy, etc. To back glove_episodic_search with a custom index, implement EpisodicMemoryAdapter with supportsSemanticSearch: true and a searchEpisodes method. The method groups play distinct roles:

• Writes (recordEpisode / updateEpisode / deleteEpisode) persist to the primary store, mark the row missing (new) / stale (content changed), and return fast — no indexing on the hot path.
• Structured reads (findEpisodes / episodesForEntity / episodesBetween) hit the primary store directly and are always current — they don't touch the index.
• Index lifecycle (findEpisodesNeedingEmbedding → build artifact → setEmbedding) is the background worker's queue + commit. setEmbedding(id, vector) commits the index artifact and flips the row to fresh.
• searchEpisodes(query, opts) is what the tool calls: query the index, apply opts.filter (kind / participantIds / timeRange), return EpisodeSearchResult[] ({ episode, score, distance }) highest-score-first.

// Out-of-band worker (Station signal / cron / queue). Index type is your choice.
const pending = await adapter.findEpisodesNeedingEmbedding({ limit: 100 });
const artifacts = await buildIndex(pending.map((p) => p.content)); // vectors | FTS docs | BM25 postings
for (let i = 0; i < pending.length; i++) await adapter.setEmbedding(pending[i].id, artifacts[i]);

Contract rules (match the reference adapter): supportsSemanticSearch: true is the switch that folds the search tool — without it searchEpisodes is dead code; a just-written episode is searchable only after the worker catches up (eventual consistency — find/timeline see it immediately); searchEpisodes must honor opts.filter, sort by score desc, and strip provenance; normalize relevance to [0,1] before the recency blend ((1 - recencyWeight) * relevance + recencyWeight * recencyScore, default recencyWeight = 0.2, 30-day half-life) since BM25 scores are unbounded; re-flag on content change only; setEmbedding's vector param is only meaningful for a vector index — for lexical/external indexes ignore it and treat setEmbedding as "write doc + mark fresh" (still required by the interface).

Reconciliation primitives

The package's contract is deliberately narrow: store, query, write, search. It does not cascade across adapters. When an entity is merged or deleted, episodes that reference its old ID don't auto-update. Orchestrators reach for these primitives:

Action	Primitive
Entity merged	episodic.replaceParticipantId(oldId, newId, prov), resources.replaceLinkTarget("entity", oldId, newId, prov)
Entity deleted	episodic.findEpisodes({ where: { participantIds: [id] } }), resources.linksFor("entity", id) then orchestrator decides
Resource moved	resources.replaceLinkTarget("resource", fromPath, toPath, prov)
Episode deleted	resources.linksFor("episode", id) then orchestrator decides
Stale embeddings	findEpisodesNeedingEmbedding / findFilesNeedingEmbedding → embed → setEmbedding

Reference in-memory adapters

For dev / tests / quick prototypes. All exported from glove-memory/in-memory (and re-exported from the barrel).

import {
  InMemoryEntityAdapter,
  InMemoryEpisodicAdapter,
  InMemoryResourcesAdapter,
  InMemoryContextAdapter,
} from "glove-memory";

const entity = new InMemoryEntityAdapter({ schema });
const episodic = new InMemoryEpisodicAdapter({ schema, embedder });   // omit embedder → supportsSemanticSearch = false
// Embedding-free content search: `{ schema, fuzzySearch: true }` runs in-process
// lexical/fuzzy search over episode content — no embedder, no external service,
// supportsSemanticSearch = true. `embedder` wins if both are supplied.
const resources = new InMemoryResourcesAdapter({ schema, embedder }); // ditto
const context = new InMemoryContextAdapter({ schema });

Process-local — they lose data on restart. Production projects swap in a companion package or BYO adapter.

Out of scope

• Triggering, scheduling, or pipeline orchestration (Station's territory).
• Curation logic itself (configured by the consumer).
• Embedding generation — consumers plug in their own EmbeddingAdapter.
• Schema persistence or migration — schema lives in code only.
• Cross-adapter cascade on entity merge, episode delete, or resource rename — that's reconciliation, an orchestrator responsibility.
• The user-side write path for context — the adapter exposes set / update / unset; the UI / API / form / wherever users edit their preferences calls those directly.
• Binary resources. Resources is text-only.
• . and .. path resolution. All resource paths are absolute.

Quick reference — where things live

Need	Symbol
Define the ontology	MemorySchema from glove-memory/core
Required write metadata	Provenance from glove-memory/core
Cross-reference between subsystems	Link from glove-memory/core
Embedding contract	EmbeddingAdapter from glove-memory/core
Entity contract	EntityMemoryAdapter from glove-memory/entity
Episodic contract	EpisodicMemoryAdapter from glove-memory/episodic
Resources contract	ResourceFsAdapter from glove-memory/resources
Context contract	ContextAdapter from glove-memory/context
Reader / curator helpers	useMemoryReader / useMemoryCurator, useEpisodicReader / useEpisodicCurator, useResourcesReader / useResourcesCurator, useContext from glove-memory/tools
Reference in-process adapters	InMemoryEntityAdapter, InMemoryEpisodicAdapter, InMemoryResourcesAdapter, InMemoryContextAdapter from glove-memory/in-memory
Error classes	MemoryError, MemoryNotFoundError, MemorySchemaError, MemoryQueryError, MemoryWriteError, EpisodicMemoryError, ResourceFsError, ContextError from glove-memory/core

See api-reference.md — glove-memory for full type signatures, and examples.md — Memory for worked examples (schema definition, subagent-delegated reader, curator composition, context flow).

Mesh Network (glove-mesh)

glove-mesh lets multiple Glove agents talk to each other — direct messages, broadcasts, acknowledgements — on top of the existing glove-inbox primitive. The package is behaviorally additive to glove-core except for one small runtime API addition: IGloveRunnable.store (a readonly accessor that mountMesh reads to write resolved inbox items directly). No agent-loop semantics change. The package itself ships no authentication; the consumer's MeshAdapter owns transport and any signing/verification.

When to use it

• Two or more Glove agents running async or in parallel in the same process (or across processes/hosts) need to coordinate.
• You want the agent loop to surface peer messages as plain context the model can read, without writing custom subscriber/store integration.

If you just need one agent to delegate work to another sub-task in isolation, use defineSubAgent instead — subagents run nested under the parent. Mesh is for peers.

Mental model

Each agent owns its own StoreAdapter+inbox. The MeshAdapter is a per-agent view of the network (matches McpAdapter's per-conversation pattern). When agent A calls glove_mesh_send_message({ to: "b", content: ... }), the framework drops a status: "resolved" InboxItem with tag mesh:from:a into B's store. B's existing Agent.injectResolvedInboxItems path (glove-core) surfaces it as a synthetic user message on B's next ask() — exactly like an externally-resolved inbox item.

The "shared inbox" is conceptual: the mesh is shared; the inbox stays per-agent.

mountMesh — the canonical entry point

After new Glove(...).build():

import { mountMesh, MeshNetwork, InMemoryMeshAdapter } from "glove-mesh";

const network = new MeshNetwork();          // in-process bus; for distributed, BYO

await mountMesh(glove, {
  adapter: new InMemoryMeshAdapter(network, "agent-a"),
  identity: {
    id: "agent-a",
    name: "Agent A",
    description: "Plans tasks for the team.",
    capabilities: ["chat", "planning"],
  },
});

What it does:

1. Validates glove.store implements the four inbox methods (getInboxItems, addInboxItem, updateInboxItem, getResolvedInboxItems) — throws MeshStoreUnsupportedError otherwise.
2. Awaits adapter.register(identity) so peers can discover this agent.
3. Calls adapter.subscribe(handler) once. The handler converts incoming messages into resolved inbox items (or resolves a pending blocking item on ack).
4. Folds four tools onto the running Glove: glove_mesh_send_message, glove_mesh_broadcast, glove_mesh_list_agents, glove_mesh_acknowledge.

Returns Promise<void> (not chainable). Mirrors mountMcp's async-setup convention.

The four tools

Tool	Input	Behavior
glove_mesh_send_message	{ to, content, in_reply_to?, blocking? }	Calls adapter.send. Blocking inserts a pending blocking inbox item tagged mesh:waiting:<msg_id> that resolves on ack or reply.
glove_mesh_broadcast	{ content, blocking? }	Calls adapter.broadcast. Blocking resolves on the FIRST ack received.
glove_mesh_list_agents	{ filter?: { capability?, name_contains? } }	Calls adapter.listAgents; filters; excludes self.
glove_mesh_acknowledge	{ message_id, note? }	Calls adapter.acknowledge. Lightweight confirmation; for substantive replies use glove_mesh_send_message with in_reply_to instead.

MeshAdapter contract

Implement one per agent. Consumer-supplied — the package never knows about your transport.

interface MeshAdapter {
  identifier: string;

  // Identity / registration
  register(identity: AgentIdentity): Promise<void>;
  unregister(): Promise<void>;
  listAgents(): Promise<AgentIdentity[]>;
  getAgent(id: string): Promise<AgentIdentity | null>;

  // Outbound
  send(message: MeshMessage): Promise<void>;
  broadcast(message: Omit<MeshMessage, "to">): Promise<void>;
  acknowledge(messageId: string, note?: string): Promise<void>;

  // Inbound — framework registers ONE handler per agent
  subscribe(handler: (msg: IncomingMeshMessage) => Promise<void>): () => void;
}

Adapter guarantees the framework relies on:

• send resolves when the transport has accepted the message, not when the recipient handles it.
• broadcast excludes the sender from fan-out.
• Handler errors must NOT bubble — log and continue so fan-out to other agents stays intact.
• acknowledge routes an IncomingMeshMessage with kind: "ack" back to the original sender of messageId.

Reference InMemoryMeshAdapter

For dev, tests, and single-host setups. MeshNetwork is the shared bus; construct once, hand the same instance to every InMemoryMeshAdapter in the process.