@aster/authoring

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

Plugin authoring primitives for Aster host integrations.

Use plugins as installable artifact packages. Runtime behavior is declared through services: modes, tools, managed apps, HTTP routes, auth flows, and other host/user/space capabilities should be exposed as service facets.

Install

npm install @aster/authoring

Quick start

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

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

Service facets

Facet	Purpose
http_route	Expose internal or app-scoped HTTP handlers.
auth_handler	Declare user-facing auth flows.
command, assistant_command, runtime_command, channel_command	Expose command surfaces.
model_catalog, model_access_provider, workspace_provider, execution_cell_host, permission_provider, evidence_search_provider	Provide runtime provider contracts.
mode, execution_surface, managed_app_server, managed_mcp_server	Provide selectable or supervised runtime behavior.
tool, skill, composer_source, space_import	Provide composable user and space capabilities.

Protocol providers

Providers declare protocol refs in service provides[] entries and wrap their plain implementation with the protocol module’s .provide(...) helper when the protocol exposes a runtime service tag. Spaces declare requires[] against protocol IDs and version ranges; the runtime owns provider selection.

Execution-host providers

An execution_cell_host contribution advertises immutable profiles. Each profile distinguishes product posture (ambient or isolated), physical confinement class, enforcement mechanisms, broker support, recovery behavior, and the environment projection classes it can actually run. Unsupported host or platform capabilities must be omitted or refused explicitly; a provider must never weaken a selected profile or fall back to an ambient launch.

The public ExecutionCellHostProviderApi owns construction, observation, framed transport, resource sampling, cancellation, recovery cleanup, and shutdown. The kernel owns selection and receipt acceptance. A provider cannot validate its own physical receipt: every profile that requires independent validation must have a separately registered kernel or node-attestation probe. Use runExecutionCellHostConformance and an ExecutionCellHostConformanceFixture against the prepared out-of-process artifact before advertising a profile.

Execution-host and ordinary capability plugins must not receive or retain:

• raw credentials, substitution maps, or credential-resolution APIs;
• the gateway process environment or inherited host login state;
• Docker sockets, hypervisor handles, or provider-selected daemon endpoints;
• self-stamped assurance, unverified physical claims, or compatibility fallback authority.

General runtime contexts expose only credentialRefs: safe connected-state metadata and non-bearer host-only references. Credential use occurs through an authorized host HTTP request or a product-enrolled host credential operation. Ordinary plugin manifests cannot enroll those operations themselves.

Authoring helpers

• Messaging transports and runtime capabilities live behind service facets rather than parallel plugin registries.
• Plugin.make() is the entrypoint for installable plugin packages. It maps id, name, description, settings, and services into a full plugin definition.
• defineProviderFamilyPlugin() is a convenience helper for provider-only plugins.
• buildProviderDefinition(), toPluginProviderModels(), apiKeyMethod(), oauthMethod(), oauthMethodFromProvider(), and PROVIDER_API_KEY_SENTINEL help construct provider plugins consistently.
• parsePluginSettings(), parseJsonWithSchema(), and executeRuntimeTool() cover the shared validation and runtime-context ergonomics plugin authors otherwise repeat.

Settings and runtime model

Plugins can declare:

• service-scoped settings shared across the runtime
• user-scoped settings with status reporting and actions
• service facets with runtime auth resolution
• gateway-scoped and user-scoped Effect service implementations

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.

Related packages

• @aster/authoring provides plugin packaging helpers and the service authoring surface used by runtime supervisors.
• The host runtime is implemented in packages/gate.