@agentick/shared

@agentick/shared

Platform-independent types and utilities for Agentick. Works in both Node.js and browser environments.

Installation

pnpm add @agentick/shared

Model Catalog

Reference data for known LLM models including context windows and capabilities. Supports runtime registration for custom/fine-tuned models.

Registering Custom Models

Use registerModel() to add custom or fine-tuned models that aren't in the built-in catalog:

import { registerModel } from "@agentick/shared";

// Register a custom fine-tuned model
registerModel("myorg/custom-model-v1", {
  name: "My Custom Model",
  provider: "myorg",
  contextWindow: 32768, // 32k context
  maxOutputTokens: 8192,
  supportsToolUse: true,
  supportsVision: false,
  isReasoningModel: false,
});

// Register multiple models at once
import { registerModels } from "@agentick/shared";

registerModels({
  "myorg/model-small": {
    name: "My Model Small",
    provider: "myorg",
    contextWindow: 16384,
    maxOutputTokens: 4096,
    supportsToolUse: true,
  },
  "myorg/model-large": {
    name: "My Model Large",
    provider: "myorg",
    contextWindow: 128000,
    maxOutputTokens: 8192,
    supportsToolUse: true,
    supportsVision: true,
  },
});

Looking Up Model Info

import { getModelInfo, getContextWindow, getContextUtilization } from "@agentick/shared";

// Get full model info
const info = getModelInfo("gpt-4o");
console.log(info?.contextWindow); // 128000
console.log(info?.supportsVision); // true

// Just get context window
const contextWindow = getContextWindow("claude-3-5-sonnet");
console.log(contextWindow); // 200000

// Calculate utilization percentage
const utilization = getContextUtilization("gpt-4o", 64000);
console.log(utilization); // 50

ModelInfo Interface

interface ModelInfo {
  name: string; // Display name
  provider: string; // Provider name (openai, anthropic, google, etc.)
  contextWindow: number; // Context window size in tokens
  maxOutputTokens?: number; // Max output tokens
  releaseDate?: string; // Model release date
  supportsVision?: boolean; // Supports image input
  supportsToolUse?: boolean; // Supports tool/function calling
  isReasoningModel?: boolean; // Extended thinking model (o1, etc.)
}

Built-in Model Coverage

The catalog includes models from:

• Anthropic: Claude 4, Claude 3.5, Claude 3 series
• OpenAI: GPT-5, GPT-4.1, GPT-4o, o1/o3 reasoning models
• Google: Gemini 3, Gemini 2.5, Gemini 2.0, Gemini 1.5
• Mistral: Large 3, Small 3.1, Codestral, Ministral
• Meta: Llama 4, Llama 3.1
• DeepSeek: Chat, Coder, Reasoner

Adapter Integration

When using adapters, model info from the adapter takes precedence over the catalog:

import { getEffectiveModelInfo, getEffectiveContextWindow } from "@agentick/shared";

// Adapter metadata overrides catalog values
const effectiveInfo = getEffectiveModelInfo(
  { contextWindow: 256000 }, // Adapter reports 256k
  "custom-model",
);

// Priority: adapter > runtime registry > static catalog
const contextWindow = getEffectiveContextWindow(adapterMetadata, modelId);

Formatting Utilities

import { formatContextWindow } from "@agentick/shared";

formatContextWindow(128000); // "128K"
formatContextWindow(1000000); // "1M"
formatContextWindow(2097152); // "2.1M"

Response Format

Normalized response format type for structured output across providers:

import type { ResponseFormat } from "@agentick/shared";

// Free-form text (default behavior)
const text: ResponseFormat = { type: "text" };

// JSON output (provider ensures valid JSON)
const json: ResponseFormat = { type: "json" };

// Structured output conforming to a JSON Schema
const structured: ResponseFormat = {
  type: "json_schema",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      age: { type: "number" },
    },
    required: ["name"],
  },
  name: "person", // optional
};

ResponseFormat is accepted on both ModelInput (per-call) and ModelConfig (adapter default). Each adapter maps it to the provider's native format.

Content Types

ContentBlock

Content blocks represent different types of content in messages:

import type {
  ContentBlock,
  TextBlock,
  ImageBlock,
  ToolUseBlock,
  ToolResultBlock,
} from "@agentick/shared";

// Text content
const text: TextBlock = {
  type: "text",
  text: "Hello, world!",
};

// Image content
const image: ImageBlock = {
  type: "image",
  source: {
    type: "base64",
    mediaType: "image/png",
    data: "iVBORw0KGgo...",
  },
};

// Tool use (model calling a tool)
const toolUse: ToolUseBlock = {
  type: "tool_use",
  id: "call_123",
  name: "calculator",
  input: { expression: "2 + 2" },
};

// Tool result (response to tool use)
const toolResult: ToolResultBlock = {
  type: "tool_result",
  toolUseId: "call_123",
  content: [{ type: "text", text: "4" }],
};

Message Types

import type { Message, UserMessage, AssistantMessage } from "@agentick/shared";

const userMessage: UserMessage = {
  role: "user",
  content: [{ type: "text", text: "Hello!" }],
};

const assistantMessage: AssistantMessage = {
  role: "assistant",
  content: [{ type: "text", text: "Hi there!" }],
};

Stream Events

Events emitted during streaming responses:

import type {
  StreamEvent,
  ContentDeltaEvent,
  MessageEndEvent,
  ToolCallEvent,
  ContextUpdateEvent,
} from "@agentick/shared";

// Text streaming
const delta: ContentDeltaEvent = {
  type: "content_delta",
  delta: "Hello",
  contentIndex: 0,
};

// Context utilization update
const contextUpdate: ContextUpdateEvent = {
  type: "context_update",
  modelId: "gpt-4o",
  modelName: "GPT-4o",
  provider: "openai",
  contextWindow: 128000,
  inputTokens: 1500,
  outputTokens: 500,
  totalTokens: 2000,
  utilization: 1.56, // percentage
  supportsVision: true,
  supportsToolUse: true,
};

Error Types

Typed errors with codes for proper error handling:

import {
  AgentickError,
  ValidationError,
  AbortError,
  isAbortError,
  isAgentickError,
} from "@agentick/shared";

// Check error types
try {
  await operation();
} catch (error) {
  if (isAbortError(error)) {
    console.log("Operation was cancelled");
  } else if (isAgentickError(error)) {
    console.log(`Error [${error.code}]: ${error.message}`);
  }
}

// Throw typed errors
throw new ValidationError("email", "Invalid email format");
throw new AbortError("User cancelled");
throw AbortError.timeout(30000); // Timeout via AbortError factory

Input Normalization

Utilities for normalizing various input formats:

import { normalizeContent, normalizeMessage } from "@agentick/shared";

// Normalize string to content blocks
const content = normalizeContent("Hello!");
// [{ type: "text", text: "Hello!" }]

// Normalize various message formats
const message = normalizeMessage("Hello!");
// { role: "user", content: [{ type: "text", text: "Hello!" }] }

const message2 = normalizeMessage({
  role: "user",
  content: "Hello!",
});
// { role: "user", content: [{ type: "text", text: "Hello!" }] }

Transport Types

The transport layer abstracts the connection between @agentick/client and an Agentick backend. Transport types live in @agentick/shared so both @agentick/client and @agentick/core can implement transports without circular dependencies.

import type {
  ClientTransport,
  TransportState,
  TransportEventData,
  TransportEventHandler,
  TransportConfig,
} from "@agentick/shared";

ClientTransport

The core transport interface. All transports implement this — SSE/HTTP, WebSocket, and local (in-process).

Method	Description
connect()	Establish connection
disconnect()	Close connection
send(input, sessionId?)	Send a message, returns AsyncIterable<TransportEventData> with .abort()
subscribeToSession(id)	Subscribe to session events
abortSession(id, reason?)	Abort a running execution
closeSession(id)	Close a session
submitToolResult(sessionId, toolUseId, result)	Submit tool confirmation result
onEvent(handler)	Register event handler, returns unsubscribe function
onStateChange(handler)	Register state change handler

TransportEventData

All transport events share this structure:

interface TransportEventData {
  type: string; // Event type (e.g., "content_delta", "execution_end")
  sessionId?: string; // Session this event belongs to
  executionId?: string;
  data?: unknown; // Structured event payload
}

The data field contains the original stream event payload. It is never spread into the top level — this prevents property collisions and makes the wire format predictable.

Wire format: The gateway sends EventMessage envelopes ({ type: "event", event: "<type>", sessionId, data }). The unwrapEventMessage() utility normalizes these to TransportEventData, promoting event to type and preserving data as-is.

TransportState

"disconnected" | "connecting" | "connected" | "error"

Available Transports

Transport	Package	Description
SSE/HTTP	@agentick/client	Default remote transport (HTTP + Server-Sent Events)
WebSocket	@agentick/client	Bidirectional via createWSTransport(config)
Unix Socket	@agentick/gateway	NDJSON over Unix domain socket (Node.js only)
Local	@agentick/core	In-process bridge via createLocalTransport(app)

WebSocket and Unix socket transports are built on the shared createRPCTransport factory, which provides all protocol machinery (request correlation, event streaming, reconnection, session operations). Each transport is a thin delegate that provides wire-specific I/O.

See packages/shared/src/transport.ts for the ClientTransport interface and packages/shared/src/rpc-transport.ts for the RPC factory.

Tool Types

import type { ToolDefinition, ToolCall, ToolResult } from "@agentick/shared";

const tool: ToolDefinition = {
  name: "calculator",
  description: "Performs mathematical calculations",
  inputSchema: {
    type: "object",
    properties: {
      expression: { type: "string", description: "Math expression" },
    },
    required: ["expression"],
  },
};

License

MIT