![\"moxxy\"](\"https://raw.githubusercontent.com/moxxy-ai/moxxy/main/assets/brand/png/moxxy-mark-256.png\")
\n \n\n \n \n \n
\n The typed public surface for the moxxy framework.
\n Zero runtime dependencies. The contract every plugin, channel, and provider speaks.\n
\n \n ![\"npm\"](\"https://img.shields.io/npm/v/@moxxy/sdk?logo=npm&logoColor=white\")
![\"Node](\"https://img.shields.io/badge/node-%3E%3D20.19-brightgreen?logo=node.js&logoColor=white\"){kind=icon}
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white\"){kind=icon}
![\"CI\"](\"https://github.com/moxxy-ai/moxxy/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n \n
\n Install\n · \n Quickstart\n · \n Docs\n · \n Surface\n · \n Plugin guide\n
\n\n---\n\n## What this package is\n\n`@moxxy/sdk` is the typed contract between the moxxy runtime and everything that plugs into it. Providers, modes, tools, channels, compactors, cache strategies, isolators, transcribers, view renderers, tunnel providers, agents, commands, and skills all use it as their interface to the runtime.\n\nThe package exports:\n\n- `define*` factories, the only blessed way to author each kind of block.\n- The `MoxxyEvent` discriminated union, covering every event the runtime can emit or replay.\n- `ClientSession` and `SessionLike`, the views channels and modes see.\n- Lifecycle hook signatures (`onTurnStart`, `onAssistantMessage`, and so on).\n- Small helper utilities that do not pull the runtime along: token accounting, compactor helpers, zod-to-JSON-Schema, tool gating, embedding caching, retryable-error classification.\n\nThe main barrel and the `./tool-display` subpath are free of Node builtins, so they are safe to value-import from a browser or React-Native bundle. Helpers that need a Node runtime (atomic file writes, the `~/.moxxy` path helpers, the CLI-tunnel spawner, the HTTP/WebSocket channel-auth toolkit) live on the **`@moxxy/sdk/server`** subpath instead — import those only from Node-side code.\n\nIt is the only moxxy package safe to depend on from a published plugin. `@moxxy/core` is the runtime, and plugins never import it.\n\n## Why depend on the SDK\n\n- **Zero runtime dependencies.** The package builds without pulling anything into your bundle. `zod` is declared as a peer dependency so your plugin and the host agree on one copy.\n- **One contract, every block.** The shape is consistent across tools, channels, providers, compactors, and the rest. Once you have written one plugin you know how to write the next.\n- **Strict TypeScript.** `defineTool` is generic on its zod schema so handler arguments are fully inferred. Types double as documentation.\n- **Type-only views into the runtime.** `SessionLike` exposes only what a channel needs and keeps the rest of the registry private.\n- **Event-log first.** Every block is reactive over a single typed event stream. No hidden globals, easy to record and replay.\n\n## Installation\n\n```sh\nnpm install @moxxy/sdk zod\n# or: pnpm add @moxxy/sdk zod\n# or: yarn add @moxxy/sdk zod\n```\n\n`zod` is a peer dependency. The SDK does not ship it.\n\nRequirements: Node.js 20.19 or later. Strict TypeScript is recommended.\n\n## Quickstart\n\nA tool plugin in nine lines:\n\n```ts\nimport { definePlugin, defineTool, z } from '@moxxy/sdk';\n\nexport default definePlugin({\n name: '@acme/moxxy-plugin-greet',\n tools: [\n defineTool({\n name: 'greet',\n description: 'Return a greeting for the given name.',\n inputSchema: z.object({ name: z.string() }),\n handler: ({ name }) => `Hello, ${name}!`,\n }),\n ],\n});\n```\n\nAdd a `\"moxxy\"` block to your `package.json` and moxxy auto-discovers it on the next launch:\n\n```json\n{\n \"moxxy\": { \"plugin\": { \"entry\": \"./dist/index.js\", \"kind\": \"tools\" } }\n}\n```\n\nThat is the whole setup. `moxxy plugins list` will show your tool on the next session start.\n\n## What the SDK gives you\n\n### `define*` factories\n\n| Factory | Defines |\n|---|---|\n| `definePlugin` | A bundle of any of the below. The discoverable unit. |\n| `defineTool` | A callable tool with a zod-typed input, optional `permission`, `isolation`, and `compact` display config. |\n| `defineProvider` | An LLM backend such as Anthropic, OpenAI, or a custom service. |\n| `defineMode` | A loop strategy. The agent's iteration topology (`default`, `goal`, `research`, and so on). |\n| `defineCompactor` | A context-window compaction strategy (summarise, drop, hybrid). |\n| `defineCacheStrategy` | Where to place provider cache breakpoints. |\n| `defineChannel` | A user-facing surface (TUI, HTTP, Telegram, web). |\n| `defineCommand` | A `/slash` command surfaced in every channel that hosts commands. |\n| `defineSkill` | A prompt-only Markdown skill (frontmatter + body). |\n| `defineAgent` | A subagent kind dispatchable from the parent loop. |\n| `defineTranscriber` | A speech-to-text backend wired into every audio-capable channel. |\n| `definePermission` | A permission rule contributed to the resolver chain. |\n| `defineViewRenderer` | A target for the agent-authored UI primitives. |\n| `defineTunnelProvider` | A public-URL tunnel for HTTP channels (cloudflared, ngrok). |\n| `defineIsolator` (via `@moxxy/plugin-security`) | A capability sandbox. The SDK exports the `Isolator` interface and the `ISOLATION_RANK` ordering. |\n\n### Types and events\n\n```ts\nimport type {\n MoxxyEvent, // the discriminated union of every event in the log\n EventLogReader, // a stable view over the session's event log\n ClientSession, // what channels and slash-commands see\n SessionLike, // what modes, providers, and tools see\n PendingToolCall,\n PermissionDecision,\n ApprovalRequest, ApprovalDecision,\n ToolDef, ProviderDef, ModeDef, CompactorDef, CacheStrategyDef,\n Plugin, PluginSpec,\n Skill, SkillDef, SkillFrontmatter, SkillScope,\n} from '@moxxy/sdk';\n```\n\n### Helpers\n\n- `zodToJsonSchema` converts a zod schema to JSON Schema for provider tool calls.\n- `isRetryableError` and `toFriendlyError` classify provider errors uniformly.\n- `resolveProviderTools` enables capabilities from `ModelDescriptor.hostedTools` and removes only matching client fallbacks marked with `ToolDef.hosted`.\n- `estimateContextTokens` and `runCompactionIfNeeded` are scaffolding for custom compactors.\n- `CachedEmbeddingProvider` wraps any `EmbeddingProvider` with on-disk caching.\n- `dispatchToolCall` invokes a tool through the full gating, permission, and isolation pipeline.\n- `summarizeSessionTokensFromEvents` and `summarizeTokensByModel` give pure token accounting over the event log.\n\n### Lifecycle hooks\n\nA plugin can declare optional hooks: `onInit`, `onTurnStart`, `onBeforeProviderCall`, `onToolCall`, `onToolResult`, `onEvent`, `onTurnEnd`, and `onShutdown`. All are strongly typed and fire in plugin-registration order. The SDK exposes the hook context types. `@moxxy/core` invokes them at the right point in the loop.\n\n## Authoring a plugin\n\nA tool plugin with the minimum surface:\n\n```ts\nimport { definePlugin, defineTool, z } from '@moxxy/sdk';\n\nexport default definePlugin({\n name: '@acme/moxxy-plugin-weather',\n clientChrome: [\n {\n id: 'weather-ready',\n slot: 'status.trailing',\n label: 'Weather ready',\n tone: 'positive',\n },\n ],\n tools: [\n defineTool({\n name: 'get_weather',\n description: 'Fetch current weather for a city.',\n inputSchema: z.object({ city: z.string() }),\n // Handler args are inferred from the zod schema.\n handler: async ({ city }) => {\n const res = await fetch(`https://wttr.in/${encodeURIComponent(city)}?format=j1`);\n return res.json();\n },\n // Optional: gate the call, declare capabilities, customise the compact display.\n permission: { action: 'prompt' },\n isolation: { capabilities: { net: { mode: 'allowlist', hosts: ['wttr.in'] } } },\n compact: { verb: 'Fetching weather for', noun: { one: 'city', other: 'cities' }, previewKey: 'city' },\n }),\n ],\n});\n```\n\n`clientChrome` is intentionally data-only. Plugins may contribute short items\nto `status.leading` or `status.trailing`; clients sanitize, prioritize,\ntruncate, and render them responsively. Arbitrary React/Ink injection is not\npart of the contract. Use view-specs for rich interactive content in a run.\n\nA read-only tool may opt out of approval only inside the active workspace:\n\n```ts\npermission: {\n action: 'allow',\n workspace: { pathInputs: [{ key: 'file_path' }] },\n}\n```\n\nCore resolves real paths before applying this rule, so a symlink that points\noutside the workspace still falls through to the normal permission resolver.\n\nA provider plugin:\n\n```ts\nimport {\n definePlugin,\n defineProvider,\n type LLMProvider,\n type ProviderRequest,\n type ProviderEvent,\n} from '@moxxy/sdk';\n\nclass MyLlmClient implements LLMProvider {\n readonly name = 'my-llm';\n readonly models = MODELS;\n async *stream(req: ProviderRequest): AsyncIterable