Ostia extension SDK

Write extensions for Ostia: the client library and its types, JSON Schemas for the manifest files, a generator for a new extension project, and a command that checks an extension the way Ostia does.

An extension is a folder with a ostia.json manifest and, usually, a main.js that Ostia starts as its own process. The process talks to Ostia over a local socket; this SDK wraps that protocol. The full contract is in docs/EXTENSIONS.md.

Start a new extension

pnpm dlx @aurigax-ai/ostia-extension-sdk create weather
cd weather
pnpm install
pnpm validate     # builds dist/weather and checks it the way Ostia will

create <id> [folder] writes a small TypeScript project: a ostia.json with your id, one command in src/main.ts, a build that bundles it into a single main.js, and this SDK as a dev dependency. The id is 2 to 40 lowercase letters, digits or dashes; it becomes the ostia <id> ... command.

dist/weather is the extension. To try it, copy that folder to ~/.config/ostia/extensions/weather; Ostia notices it within a moment and asks you to approve it. Then run ostia weather greet you in a pane, or "Weather: Greet" from the palette.

The project translates itself: locales/zh-Hant.json holds its manifest strings and messages in Traditional Chinese, locales/en.json its English messages, and src/main.ts answers in the caller's language with createTranslator(). See "Translations" in docs/EXTENSIONS.md.

Ostia never runs a build, a package manager or a script from an extension, so ship one bundled main.js, as the generated build.mjs does.

Add it to an existing project

pnpm add -D @aurigax-ai/ostia-extension-sdk

The package is built: there is no install script to approve. It needs Node 20 or newer.

What is in the package

Point your editor at the schema from the manifest:

{ "$schema": "./node_modules/@aurigax-ai/ostia-extension-sdk/schemas/ostia.schema.json" }

The schema catches shape mistakes while you type. ostia-extension validate is the authority: it runs the same checks Ostia runs when it loads the extension.

Check an extension or a marketplace

pnpm exec ostia-extension validate dist/weather     # one extension folder
pnpm exec ostia-extension validate .                # a marketplace: a folder with ostia-marketplace.json
pnpm exec ostia-extension unlist extensions/weather # hide it in Ostia: installable only by the printed code

It exits 0 when Ostia would accept it and prints one line per problem otherwise. For an extension it also checks what a marketplace install requires: regular files only, at most 8000 files and 50 MiB. Run it on the folder you publish, not on a project folder that holds node_modules.

Publish

A marketplace is a git repository with an ostia-marketplace.json that lists extension folders. Commit your built folder to one, and people add the repository in Ostia under Settings → Extensions → Marketplaces. See "Marketplaces" in docs/EXTENSIONS.md.

Source

dist/ is what you import: the SDK bundled into a few plain, unminified JavaScript files. src/ holds the TypeScript it was built from, at the same paths as in packages/extension-sdk of the Ostia repository (src/client is the library, src/assist the assistant engine, src/contract the contract types, src/manifest the manifest loader and the ostia-extension command that runs it). It is there to read. The SDK is developed in the Ostia repository and published from it on every release, so the SDK and the app cannot drift apart. Report problems in that repository's issues.

Versions

Two numbers matter:

• The extension API version (EXTENSION_API_VERSION, ostiaExtensionApi in package.json, api.json): the version of the contract, major.minor. Put it in your manifest as "api". A minor adds things and keeps every existing extension working; Ostia provides exactly one major. Ostia refuses an extension whose api it doesn't provide, and connect() refuses to run against an app older than the SDK it was built with.
• The package version: the version of Ostia this SDK was built from.

Licence

MIT