glove-core

Complete API reference for the core runtime package. Contains the agent loop, tool execution engine, display manager, context management, model adapters, and all foundational types.

Glove

The top-level builder and runtime entry point. Use the builder pattern to register tools and subscribers, then call build() to produce a runnable agent.

import { Glove } from "glove-core";
import { z } from "zod";

const agent = new Glove({
  store,
  model,
  displayManager,
  systemPrompt: "You are a helpful assistant.",
  compaction_config: {
    compaction_instructions: "Summarize the conversation.",
    max_turns: 30,
  },
})
  .fold({
    name: "get_weather",
    description: "Get weather for a city.",
    inputSchema: z.object({ city: z.string() }),
    async do(input) {
      const res = await fetch(`https://api.weather.example/v1?city=${input.city}`);
      return res.json();
    },
  })
  .build();

const result = await agent.processRequest("What is the weather in Tokyo?");

Constructor

new Glove(config: GloveConfig)

GloveConfig

Methods

Properties

GloveFoldArgs

IGloveRunnable

The interface returned by build(). Represents a fully configured, ready-to-run agent.

DisplayManager

Manages the display stack: a ordered collection of UI slots that tools push and users resolve. Implements DisplayManagerAdapter.

import { Displaymanager } from "glove-core/display-manager";

const dm = new Displaymanager();

dm.subscribe((stack) => {
  console.log("Display stack changed:", stack);
});

Methods

DisplayManagerAdapter Interface

The interface that DisplayManager implements. Any custom display manager must conform to this shape.

Slot

Represents a single entry on the display stack. Pushed by tools, rendered by the UI layer.

Renderer

A named renderer definition registered with the display manager.

Context

Wraps a StoreAdapter and provides a simplified interface for reading and writing conversation data, messages, and tasks.

import { Context } from "glove-core";

const ctx = new Context(store);
const messages = await ctx.getMessages();
await ctx.appendMessages([{ sender: "user", text: "Hello" }]);

Constructor

new Context(store: StoreAdapter)

Methods

PromptMachine

Manages model prompting: sends messages and tool definitions to the model adapter and collects the response. Notifies subscribers of streaming events.

import { PromptMachine } from "glove-core";

const pm = new PromptMachine(model, ctx, "You are a helpful assistant.");
pm.addSubscriber(subscriber);
const result = await pm.run(messages, tools);

Constructor

new PromptMachine(model: ModelAdapter, ctx: Context, systemPrompt: string)

Methods

Executor

The tool execution engine. Maintains a registry of tools and a call stack. Executes tool calls from the model, validates inputs, handles errors, and returns results.

import { Executor } from "glove-core";

const executor = new Executor(3, store);
executor.registerTool(myTool);
executor.addSubscriber(subscriber);

executor.addToolCallToStack({ tool_name: "get_weather", input_args: { city: "Tokyo" } });
const results = await executor.executeToolStack();

Constructor

new Executor(MAX_RETRIES?: number, store?: StoreAdapter)

Properties

Methods

Observer

Monitors the context window size and triggers compaction when limits are exceeded. Tracks turn counts and token consumption. Compaction is history-preserving: messages are never deleted from the store. Instead, a compaction summary is appended with is_compaction: true, and resetCounters() resets the token and turn counts. The model only sees post-compaction messages because Context.getMessages() applies splitAtLastCompaction() internally.

import { Observer } from "glove-core";

const observer = new Observer(
  store,
  ctx,
  promptMachine,
  "Summarize the conversation so far.",
  30,   // max turns
  100000 // context compaction token limit
);

await observer.turnComplete();
await observer.tryCompaction();

Constructor

new Observer(store: StoreAdapter, ctx: Context, prompt: PromptMachine, compaction_instructions: string, max_turns?: number, context_compaction_limit?: number)

Properties

Methods

Agent

Orchestrates the core agent loop: prompt the model, check for tool calls, execute tools, feed results back, repeat until the model responds with text only.

import { Agent } from "glove-core";

const agent = new Agent(store, executor, context, observer, promptMachine);
const result = await agent.ask(userMessage);

Constructor

new Agent(store: StoreAdapter, executor: Executor, context: Context, observer: Observer, prompt_machine: PromptMachine)

Methods

AbortError

Custom error class thrown when an agent request is aborted via an AbortSignal. Has name set to "AbortError".

import { AbortError } from "glove-core";

try {
  await agent.processRequest("Hello", signal);
} catch (err) {
  if (err instanceof AbortError) {
    console.log("Request was aborted.");
  }
}

Constructor

new AbortError(message?: string)

ModelAdapter

Interface for language model providers. Implement this to connect any LLM to Glove.

interface ModelAdapter {
  name: string;
  prompt(
    request: PromptRequest,
    notify: NotifySubscribersFunction,
    signal?: AbortSignal
  ): Promise<ModelPromptResult>;
  setSystemPrompt(systemPrompt: string): void;
}

PromptRequest

ModelPromptResult

Subscriber Events

Every model adapter emits events via the notify callback during prompting. These events are fully typed using a discriminated union so that subscribers (and custom adapter authors) get compile-time safety.

SubscriberEvent

A discriminated union of all event shapes. Each variant has a type field plus event-specific data.

type SubscriberEvent =
  | { type: "text_delta"; text: string }
  | { type: "tool_use"; id: string; name: string; input: unknown }
  | { type: "model_response"; text: string; tool_calls?: ToolCall[];
      stop_reason?: string; tokens_in?: number; tokens_out?: number }
  | { type: "model_response_complete"; text: string; tool_calls?: ToolCall[];
      stop_reason?: string; tokens_in?: number; tokens_out?: number }
  | { type: "tool_use_result"; tool_name: string; call_id?: string;
      result: ToolResultData }
  | { type: "compaction_start"; current_token_consumption: number }
  | { type: "compaction_end"; current_token_consumption: number;
      summary_message: Message }

Event Reference

SubscriberEventDataMap

A mapped type that extracts the data shape (everything except type) for each event. Use this when implementing a SubscriberAdapter or handling events in a switch statement.

type SubscriberEventDataMap = {
  [E in SubscriberEvent as E["type"]]: Omit<E, "type">;
};

// Example: SubscriberEventDataMap["text_delta"] = { text: string }

SubscriberAdapter

Interface for receiving events. Both the React hook subscriber and GloveVoice implement this. The record method is generic over the event type.

interface SubscriberAdapter {
  record: <T extends SubscriberEvent["type"]>(
    event_type: T,
    data: SubscriberEventDataMap[T],
  ) => Promise<void>;
}

Implementing a Custom Model Adapter

When building a custom ModelAdapter, you must emit the correct events via the notify callback. Here is the minimal contract:

import type { ModelAdapter, NotifySubscribersFunction, PromptRequest, ModelPromptResult } from "glove-core";

class MyAdapter implements ModelAdapter {
  name = "my-provider:model-name";
  private systemPrompt?: string;

  setSystemPrompt(systemPrompt: string) {
    this.systemPrompt = systemPrompt;
  }

  async prompt(
    request: PromptRequest,
    notify: NotifySubscribersFunction,
    signal?: AbortSignal,
  ): Promise<ModelPromptResult> {
    // ... call your LLM API ...

    // Non-streaming: emit a single model_response event
    await notify("model_response", {
      text: responseText,
      tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
      stop_reason: finishReason ?? undefined,
      tokens_in: usage.promptTokens,
      tokens_out: usage.completionTokens,
    });

    return { messages: [message], tokens_in: ..., tokens_out: ... };
  }
}

For streaming adapters, emit events incrementally:

// During streaming — emit text fragments as they arrive
notify("text_delta", { text: chunk });

// When a tool call is fully assembled
await notify("tool_use", { id: toolCallId, name: toolName, input: parsedArgs });

// After the stream completes — emit the final aggregated response
await notify("model_response_complete", {
  text: fullText,
  tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
  stop_reason: finishReason ?? undefined,
});

Key rules:

• Non-streaming adapters emit model_response (one event per prompt call).
• Streaming adapters emit text_delta for each text chunk, tool_use for each completed tool call, and model_response_complete once at the end.
• stop_reason should be undefined (not null) when unavailable. Use ?? undefined to coerce provider SDK nulls.
• tool_use_result, compaction_start, and compaction_end are emitted by the framework — adapters should not emit these.

StoreAdapter

Interface for conversation persistence. Implement this to store messages, token counts, tasks, and permissions in any backend.

interface StoreAdapter {
  identifier: string;
  getMessages(): Promise<Message[]>;
  appendMessages(msgs: Message[]): Promise<void>;
  getTokenCount(): Promise<number>;
  addTokens(count: number): Promise<void>;
  getTurnCount(): Promise<number>;
  incrementTurn(): Promise<void>;
  resetCounters(): Promise<void>;
  // Optional:
  getTasks?(): Promise<Task[]>;
  addTasks?(tasks: Task[]): Promise<void>;
  updateTask?(taskId: string, updates: Partial<Task>): Promise<void>;
  getPermission?(toolName: string): Promise<PermissionStatus>;
  setPermission?(toolName: string, status: PermissionStatus): Promise<void>;
}

SubscriberAdapter

Interface for observing agent events. Subscribers receive streaming text deltas, tool invocations, tool results, and model response completions.

interface SubscriberAdapter {
  record(event_type: string, data: any): Promise<void>;
}

Subscriber Events

The following events are emitted by the system and received by subscribers via the record method.

Message

Represents a single message in the conversation history.

interface Message {
  sender: "user" | "agent";
  id?: string;
  text: string;
  content?: ContentPart[];
  tool_results?: ToolResult[];
  tool_calls?: ToolCall[];
  is_compaction?: boolean;
}

ContentPart

Represents a multimodal content element within a message.

interface ContentPart {
  type: "text" | "image" | "video" | "document";
  text?: string;
  source?: {
    type: string;
    media_type: string;
    data?: string;
    url?: string;
  };
}

Tool

The core tool interface used by the Executor. This is the runtime representation, distinct from ToolConfig in glove-react which adds the render property.

ToolCall

ToolResult

ToolResultData

The shape of the result field on a ToolResult. Contains the data returned by the tool, a status indicator, an optional error message, and an optional client-only rendering payload.

interface ToolResultData {
  status: "success" | "error";
  data: unknown;          // Sent to the AI model
  message?: string;       // Error message (for status: "error")
  renderData?: unknown;   // Client-only — NOT sent to model, used by renderResult
}

Model adapters (Anthropic, OpenAI-compat) explicitly destructure and only send data, status, and message to the API. The renderData field is preserved in the message store for client-side rendering via renderResult but is never sent to the AI model.

Task

Represents a tracked task in the agent's task list.

TaskStatus

type TaskStatus = "pending" | "in_progress" | "completed";

PermissionStatus

type PermissionStatus = "granted" | "denied" | "unset";

Function Types

CompactionConfig

Compaction is history-preserving. When triggered, the full conversation is summarized and the summary is appended as a new message with is_compaction: true. No messages are deleted from the store, so frontends can still display the complete history. The model only sees messages from the last compaction point onward, courtesy of splitAtLastCompaction() in Context.getMessages().

Built-in Task Tool

The framework provides a built-in tool for task management. It is automatically registered when the store supports tasks (implements getTasks, addTasks, updateTask).

import { createTaskTool } from "glove-core";

const taskTool = createTaskTool(context);
// taskTool.name === "glove_update_tasks"

Signature

function createTaskTool(context: Context): Tool<TaskToolInput>

TaskToolInput

The tool name is glove_update_tasks. The model calls it to create, update, or complete tasks. Each invocation sends the full current task list, enabling additions, status changes, and removals in a single call.

Providers

The glove-core/models/providers module exports factory functions for creating model adapters from supported providers.

import { createAdapter, getAvailableProviders } from "glove-core/models/providers";

const model = createAdapter({
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  maxTokens: 4096,
  stream: true,
});

const available = getAvailableProviders();
// [{ id: "openai", name: "OpenAI", ... }, ...]

createAdapter

function createAdapter(opts: CreateAdapterOptions): ModelAdapter

CreateAdapterOptions

getAvailableProviders

Returns an array of provider configurations that have API keys available in the current environment.

function getAvailableProviders(): Array<{ id: string; name: string; available: boolean; models: string[]; defaultModel: string }>

Supported Providers

Each provider has properties: id, name, baseURL, envVar, defaultModel, models[], format (either "openai", "anthropic", or "bedrock"), defaultMaxTokens, and requiresApiKey.

Local providers (ollama and lmstudio) don't require an API key and have no default model — you must pass a model name. Use baseURL to override the default port if needed:

const model = createAdapter({
  provider: "ollama",
  model: "llama3",
  baseURL: "http://localhost:9999/v1", // optional, defaults to :11434
});