@aster/authoring

Canonical package README synced from packages/authoring/README.md.

Canonical source: packages/authoring/README.md · Edit the source file

Plugin authoring primitives for Aster host integrations.

Use plugins when an integration needs to live at the host/runtime layer: model providers, messaging channels, HTTP routes, runtime services, auth flows, or plugin-provided space extensions. Use the extension side of @aster/authoring when you only need to add tools, mounts, settings, or prompt behavior inside a space.

Install

npm install @aster/authoring

Quick start

import {
  PROVIDER_API_KEY_SENTINEL,
  apiKeyMethod,
  buildProviderDefinition,
  Plugin
} from "@aster/authoring"

export default Plugin.make({
  id: "example-provider",
  name: "Example Provider",
  description: "Registers an Example API provider.",
  register(api) {
    api.registerProvider(
      buildProviderDefinition({
        id: "example",
        name: "Example",
        methods: [apiKeyMethod()],
        baseUrl: "https://api.example.com/v1",
        apiKey: PROVIDER_API_KEY_SENTINEL,
      }),
    )
  },
})

Registration surfaces

Registration	Purpose
`registerProvider()`	Add model providers and provider metadata to the runtime.
`registerHttpRoute()`	Expose internal or app-scoped HTTP handlers.
`registerService()`	Start long-lived runtime or gateway services.
`registerHook()`	Intercept runtime events such as message ingress or tool calls.
`registerAuth()`	Register user-facing auth flows.
`registerCommand()` / `registerCli()`	Expose CLI commands from the plugin.
`registerExtension()` / `registerExtensions()`	Bridge `@aster/authoring` extensions through the plugin system.

Authoring helpers

Messaging transports now live in extension runtimes via @aster/authoring, not plugin channel registrations.
Plugin.make() is the simplest entrypoint for most plugins. It maps id, name, description, settings, and a single register() function into a full plugin definition.
Plugin.make() is the lower-level form for plugins that want to split behavior across registerGateway(), registerUserRuntime(), registerRunner(), or registerExtensions().
defineProviderFamilyPlugin() is a convenience helper for provider-only plugins.
buildProviderDefinition(), toPluginProviderModels(), apiKeyMethod(), oauthMethod(), oauthMethodFromProvider(), and PROVIDER_API_KEY_SENTINEL help construct provider plugins consistently.

Settings and runtime model

Plugins can declare:

service-scoped settings shared across the runtime
user-scoped settings with status reporting and actions
channels with runtime auth resolution
runner, gateway, and user-runtime registrations

Entrypoints

Entrypoint	Contents
`@aster/authoring`	Runtime definitions, provider helpers, constants, and the full plugin type surface.
`@aster/authoring/runtime`	`Plugin.make`, `Plugin.is`, and `isPluginDefinition`.

@aster/authoring provides the space-level extension system that plugins can bridge into the runtime.
The host runtime is implemented in packages/gate.