@asterism-app/sdk 0.0.0-stage → 1.0.0

package/src/renderer.ts

@@ -0,0 +1,174 @@
+/** SDK renderer entry point: cards, tool views, and frontend capabilities bound to objects; React is shared by the host. */
+import { createContext, createElement, useContext, type ComponentType, type ReactNode } from "react";
+import type { UiText } from "./i18n.ts";
+import type { CardAppearance } from "./card.ts";
+export type { CardAppearance } from "./card.ts";
+export * from "./renderer-i18n.ts";
+import type { ActionContract, CreationContract } from "./commands.ts";
+import type { Json } from "./json.ts";
+import { reference, type ContractReference, type DataContract } from "./presentation.ts";
+import type { ResourceRef, SessionSnapshot } from "./workspace.ts";
+export * from "./renderer-services.ts";
+export * from "./renderer-calls.ts";
+export * from "./renderer-creation.ts";
+export * from "./renderer-tools.ts";
+export * from "./renderer-records.ts";
+export * from "./renderer-card.ts";
+export * from "./renderer-island.ts";
+export * from "./renderer-view-state.ts";
+import type { CardPanelDefinition, CardPanelView } from "./renderer-card.ts";
+import type { RecordRenderer } from "./renderer-records.ts";
+export type * from "./renderer-content.ts";
+import type { RendererContentInput, RendererInputOptions } from "./renderer-content.ts";
+import type { ContentReader } from "./content-runtime.ts";
+export type { ContentReader } from "./content-runtime.ts";
+import type { CreationEntry } from "./renderer-creation.ts";
+import type { ToolRenderer } from "./renderer-tools.ts";
+import type { EventSubscriber } from "./events.ts";
+import type { PluginCalls } from "./calls.ts";
+import type { RendererCalls } from "./renderer-calls.ts";
+import type { ChannelContract, ChannelEnd, ChannelValue } from "./channels.ts";
+
+/** The frontend end of a channel: messages are delivered in order and buffered until a listener registers; closed resolves when either end terminates. */
+export interface RendererChannel<Up extends ChannelValue = ChannelValue, Down extends ChannelValue = ChannelValue> {
+  send(data: Up): void;
+  onMessage(listener: (data: Down) => void): () => void;
+  close(): void;
+  readonly closed: Promise<ChannelEnd>;
+}
+
+export type RendererReceipt = { ok: true } | { ok: false; error: { code: string; message: string; display?: UiText } };
+/**
+ * Frontend state retained per object, such as input drafts: survives card remounts, switches between focus containers, and session view disposal;
+ * release is called when the object leaves the current session projection through removal or a cursor jump, or is explicitly discarded; state is not restored after application restart.
+ */
+export interface RendererRetained {
+  /** Obtain the value for key, creating it with create on first access; the same object and key return the same instance. Prefix key with the plugin ID to avoid conflicts with other contributors. */
+  get<T>(key: string, create: () => T, release?: (value: T) => void | Promise<void>): T;
+  /** End retention immediately and call release; no effect if absent. */
+  discard(key: string): void;
+}
+/** Frontend capabilities bound to a card object; the host handles subscriptions, command gating, and current-view consistency. */
+export interface RendererObjectContext {
+  readonly ref: ResourceRef;
+  readonly content: ContentReader;
+  input<I, O extends Json>(contract: ActionContract<I, O> | CreationContract<I, Json, O>): RendererContentInput;
+  readonly view: {
+    /** The current object view is operable; ordinary background refreshes and local commits on other objects do not change this value. */
+    ready: boolean;
+    /** View read error; object action and creation failures are returned through their respective call receipts. */
+    error: UiText | null; missing: boolean;
+  };
+  readonly session: {
+    snapshot(): SessionSnapshot | null;
+    subscribe(listener: () => void): () => void;
+    create<I, O extends Json>(contract: CreationContract<I, Json, O>, input: NoInfer<I> & Json, position: { x: number; y: number }, options?: RendererInputOptions): Promise<RendererReceipt>;
+    refresh(): Promise<void>;
+  };
+  invoke<I, O extends Json>(contract: ActionContract<I, O>, input: NoInfer<I> & Json, options?: RendererInputOptions): Promise<RendererReceipt>;
+  /** Open a duplex channel for this object; the host validates that it is on the current path and routes to its owning plugin. Ends when the object leaves the current set or the connection disconnects. */
+  openChannel<Up extends ChannelValue, Down extends ChannelValue>(contract: ChannelContract<Up, Down>): RendererChannel<Up, Down>;
+  /** Object-level retained state with a lifecycle managed uniformly by the host. */
+  readonly retained: RendererRetained;
+}
+const ObjectContext = createContext<RendererObjectContext | null>(null);
+export function useRendererObject(): RendererObjectContext {
+  const object = useContext(ObjectContext);
+  if (!object) throw new Error("The renderer must be bound to an object.");
+  return object;
+}
+
+/** Static identification information at the type level; does not parse card data or create body components. */
+export interface ResourceDescription {
+  kind: string;
+  label: UiText;
+  icon: ReactNode;
+  /** Default card dimensions available before creation, sharing a declaration with the card renderer. */
+  card?: CardAppearance;
+}
+export interface CardView extends CardAppearance {
+  body: ReactNode;
+  actions?: ReactNode;
+  panels?: readonly CardPanelView[];
+}
+export interface CardRenderer {
+  contract: ContractReference;
+  resolve(data: Json, context?: RendererObjectContext): CardView | null;
+}
+export interface RendererModule {
+  resources: ResourceDescription[];
+  cards: CardRenderer[];
+  tools: ToolRenderer[];
+  /** History record views: declare summaries, icons, and optional row content by record contract. */
+  records?: RecordRenderer[];
+  /** Creation entry points: the host arbitrates menus and drag-and-drop uniformly, with all paths ultimately using the bound creation contract. */
+  creations?: CreationEntry[];
+  /** Startup preparation: the host invokes modules in parallel before the first screen, and modules initialize their own internal resources; timeouts or failures are logged without blocking startup. */
+  prepare?(context: RendererPrepareContext): Promise<void>;
+}
+export interface PluginSettingsPage {
+  /** Stable page identity within the contributing plugin. */
+  id: string;
+  title: UiText;
+  summary: UiText;
+  /** Icon component drawn by the host at its own size and color; the host uses a plugin icon when omitted. */
+  icon?: ComponentType<{ className?: string; "aria-hidden"?: boolean | "true" | "false" }>;
+  /** A directly addressable location within a page; an empty location means the root page. */
+  locations?: readonly string[];
+  Body: ComponentType<{ location?: string }>;
+}
+export interface SessionEntryProps {
+  active: boolean;
+  ready: boolean;
+  open(sessionId: string): void;
+}
+export interface PluginSessionEntry {
+  id: string;
+  title: UiText;
+  Body: ComponentType<SessionEntryProps>;
+}
+/** Frontend plugins own settings pages and shared service lifecycles; feature views are composed from modules. */
+export interface RendererPlugin {
+  modules?: readonly RendererModule[];
+  settings?: readonly PluginSettingsPage[];
+  sessionEntries?: readonly PluginSessionEntry[];
+  prepare?(context: RendererPrepareContext): Promise<void>;
+  closing?(): void | Promise<void>;
+}
+export function defineRendererPlugin(plugin: RendererPlugin): RendererPlugin { return plugin; }
+export interface RendererPrepareContext {
+  /** Typed calls for frontend module-level services; cancellation propagates with the preparation scope. */
+  readonly calls: RendererCalls;
+  /** Global subscriptions bound to the module lifecycle, cleaned up on failure, timeout, or application shutdown. */
+  readonly events: EventSubscriber;
+  /** Triggered when the host stops waiting due to timeout or shutdown; the module should stop promptly. */
+  readonly signal: AbortSignal;
+}
+
+/** Type erasure occurs only at the registration boundary; components receive data that has passed contract validation. */
+export function cardRenderer<T extends Json>(
+  contract: DataContract<T>,
+  definition: CardAppearance & {
+    Body: ComponentType<{ data: T }>;
+    Actions?: ComponentType<{ data: T }>;
+    panels?: readonly CardPanelDefinition<T>[];
+  },
+): CardRenderer {
+  const { Body, Actions, panels, ...appearance } = definition;
+  const ids = new Set<string>();
+  for (const panel of panels ?? []) {
+    if (!panel.id.trim() || panel.id !== panel.id.trim()) throw new Error("Card panel IDs must be non-empty and trimmed.");
+    if (ids.has(panel.id)) throw new Error(`Duplicate card panel ID: ${panel.id}`);
+    ids.add(panel.id);
+  }
+  return { contract: reference(contract), resolve(raw, context) {
+    const parsed = contract.schema.safeParse(raw);
+    if (!parsed.success) return null;
+    const bind = (node: ReactNode) => context ? createElement(ObjectContext.Provider, { value: context }, node) : node;
+    return { ...appearance, body: bind(createElement(Body, { data: parsed.data })),
+      actions: Actions ? bind(createElement(Actions, { data: parsed.data })) : undefined,
+      panels: panels?.map(({ Body: PanelBody, ...panel }) => ({
+        ...panel, body: bind(createElement(PanelBody, { data: parsed.data })),
+      })) };
+  } };
+}

package/src/runtime-agent-catalog.ts

@@ -0,0 +1,27 @@
+import type { PluginModule } from "./runtime-contracts.ts";
+
+/** The host stamps plugin provenance; a null plugin identifies a user directory. */
+export type AgentSource = { id: string; plugin: string | null; directory: string };
+export type AgentSkill = { name: string; description: string; directory: string; source: AgentSource };
+export type AgentSkillSource = AgentSource & {
+  skills: AgentSkill[];
+  issues: { file: string; message: string }[];
+};
+export type AgentInstruction = { id: string; plugin: string; text: string };
+export interface AgentSkillDeclaration { id: string; path: string }
+export interface AgentInstructionDeclaration { id: string; text: string }
+export interface AgentCatalog {
+  skills(): readonly AgentSkillSource[];
+  instructions(): readonly AgentInstruction[];
+  refresh(signal: AbortSignal): readonly AgentSkillSource[];
+  /** Read current UTF-8 contents from the captured skill package, independently of later catalog refreshes. */
+  read(skill: AgentSkill, path: string, signal: AbortSignal): Promise<string>;
+}
+/** Package-relative skill directories; the host supplies the actual contributor identity. */
+export function defineAgentSkills(entries: readonly AgentSkillDeclaration[]): PluginModule {
+  return { setup: () => ({ agentSkills: entries }) };
+}
+/** Fixed instruction contributions, assembled into requests by the consuming paradigm. */
+export function defineAgentInstructions(entries: readonly AgentInstructionDeclaration[]): PluginModule {
+  return { setup: () => ({ agentInstructions: entries }) };
+}

package/src/runtime-application.ts

@@ -0,0 +1,7 @@
+/** One directory exposed under a distinct relative path in the manual catalog. */
+export interface ManualSource {
+  readonly path: string;
+  readonly directory: string;
+}
+export interface ManualCatalog { sources(): readonly ManualSource[] }
+export interface ApplicationIdentity { readonly name: string; readonly userAgent: string }

package/src/runtime-calls.ts

@@ -0,0 +1,22 @@
+import type { CallContract, CallScope } from "./calls.ts";
+import type { z } from "zod";
+import type { Json } from "./json.ts";
+import type { ObjectReader } from "./objects.ts";
+import type { Source } from "./workspace.ts";
+import type { ContentReader } from "./content-runtime.ts";
+
+export type CallContext<S extends CallScope = CallScope> = {
+  /** The host binds the source for backend plugin calls; null for desktop user calls. */
+  readonly source: Source;
+  readonly signal: AbortSignal;
+  readonly content: ContentReader;
+} & (S extends "object" ? { readonly object: ObjectReader } : { readonly object?: never });
+export interface CallContribution {
+  readonly contract: CallContract;
+  execute(input: Json, context: CallContext): Promise<Json>;
+}
+/** Implementations receive parsed input and return JSON accepted by the output schema before caller-side decoding. */
+export function implementCall<Input extends z.ZodType<Json>, Output extends z.ZodType<Json>, S extends CallScope>(contract: CallContract<Input, Output, S>,
+  execute: (input: NoInfer<z.output<Input>>, context: CallContext<NoInfer<S>>) => Promise<NoInfer<z.input<Output>> & Json>): CallContribution {
+  return { contract, execute: (input, context) => execute(input as z.output<Input>, context as CallContext<S>) };
+}

package/src/runtime-channels.ts

@@ -0,0 +1,24 @@
+import type { ChannelContract, ChannelEnd, ChannelValue } from "./channels.ts";
+import type { ObjectReader } from "./objects.ts";
+
+/**
+ * The backend end of a channel. Messages are delivered in send order; messages arriving before listener registration are buffered and delivered in order when the first listener registers.
+ * signal aborts when either end closes, the object leaves the current set, the plugin shuts down, or the connection disconnects; reason is ChannelEnd.
+ */
+export interface ObjectChannel<Up extends ChannelValue = ChannelValue, Down extends ChannelValue = ChannelValue> {
+  readonly object: ObjectReader;
+  readonly signal: AbortSignal;
+  send(data: Down): void;
+  onMessage(listener: (data: Up) => void): () => void;
+  close(): void;
+}
+export interface ChannelContribution {
+  readonly contract: ChannelContract;
+  /** Called when the frontend opens a channel; throwing PluginApiError ends the channel with unavailable. */
+  open(channel: ObjectChannel): void | Promise<void>;
+}
+export function implementChannel<Up extends ChannelValue, Down extends ChannelValue>(contract: ChannelContract<Up, Down>,
+  open: (channel: ObjectChannel<Up, Down>) => void | Promise<void>): ChannelContribution {
+  return { contract, open: channel => open(channel as unknown as ObjectChannel<Up, Down>) };
+}
+export type { ChannelEnd };

package/src/runtime-contracts.ts

@@ -0,0 +1,207 @@
+/** Backend interfaces shared by plugins and the host; the host implements storage, transactions, and authorization. */
+import type { UiText } from "./i18n.ts";
+import type { CardAppearance } from "./card.ts";
+import type { ConfigContract } from "./config.ts";
+import type { DatabaseSync } from "node:sqlite";
+import type { Json } from "./json.ts";
+import type { PluginNamespace } from "./plugin.ts";
+import type { ResourceContract, ImplementationContract } from "./module-contract.ts";
+import type { DataContract, Presentation } from "./presentation.ts";
+import type { RecordContract, SessionRecord } from "./records.ts";
+import type { EventContract, PluginEvents } from "./events.ts";
+import type { ToolCompletion, ToolInvocationInfo, ToolModelOutput } from "./tool-result.ts";
+import type { PluginConfig, PluginLogger, PluginSecrets, PluginTasks } from "./runtime.ts";
+import type { ModelServices } from "./models.ts";
+import type { ResourceSnapshot, SessionSnapshot, SessionDirectory } from "./workspace.ts";
+import type { ActionContract, CreationContract } from "./commands.ts";
+import type { ObjectReader, ObjectExecutor, SessionExecutor } from "./objects.ts";
+import type { ContentReader, ContentScope } from "./content-runtime.ts";
+import type { PluginCalls } from "./calls.ts";
+import type { CallContribution } from "./runtime-calls.ts";
+import type { ChannelContribution } from "./runtime-channels.ts";
+import type { TopLevelTool } from "./runtime-tools.ts";
+import type { ModelProviderServices } from "./runtime-model-providers.ts";
+import type { UsageProviderServices, UsageProvider, UsageServices, ProviderUsage } from "./runtime-usage.ts";
+import type { WebServices, WebProviderServices, WebProviderDefinition } from "./runtime-web.ts";
+import type { ModelProviderPresetContribution } from "./model-provider.ts";
+import type { AgentCatalog, AgentSkillDeclaration, AgentInstructionDeclaration } from "./runtime-agent-catalog.ts";
+import type { SessionCreation } from "./runtime-sessions.ts";
+export type * from "./objects.ts";
+export type { ResourceRef, ResourceCreationResult, ResourceSnapshot, SessionSnapshot } from "./workspace.ts";
+
+/**
+ * Lifecycle scope: on termination, abort signal first, then await all cleanup in reverse registration order.
+ * The host maintains application, session, and object scopes; child scopes end before their parent. Exit, archival, and object removal share the same cleanup path.
+ */
+export interface Lifetime {
+  readonly signal: AbortSignal;
+  /** Register cleanup; throws unavailable if the scope has ended. Cleanup failures are only logged and do not block remaining cleanup. */
+  defer(cleanup: () => void | Promise<void>): void;
+}
+export interface PluginContext {
+  readonly mcp: import("./runtime-mcp.ts").McpServices;
+  readonly shell: import("./runtime-shell.ts").ShellServices;
+  readonly application: import("./runtime-application.ts").ApplicationIdentity;
+  readonly manual: import("./runtime-application.ts").ManualCatalog;
+  readonly id: string;
+  /** Plugin-level lifecycle: lasts as long as the host runtime instance; shared plugin services such as connection pools, subscriptions, and public registrations belong here. */
+  readonly lifetime: Lifetime;
+  readonly sessions: SessionDirectory;
+  readonly createSession: SessionCreation;
+  readonly dir: string;
+  /** Resolve a package-relative asset, independently of writable plugin data. */
+  readonly assets: { path(relativePath: string): string };
+  readonly agentCatalog: AgentCatalog;
+  readonly log: PluginLogger;
+  readonly ipc: { readonly events: PluginEvents; readonly calls: PluginCalls };
+  config<T extends Json>(contract: ConfigContract<T>): PluginConfig<T>;
+  readonly secrets: PluginSecrets;
+  db(): DatabaseSync;
+  readonly tasks: PluginTasks;
+  readonly models: ModelServices;
+  readonly modelProviders: ModelProviderServices;
+  readonly usageProviders: UsageProviderServices;
+  readonly usages: UsageServices;
+  readonly providerUsage: ProviderUsage;
+  readonly webProviders: WebProviderServices;
+  readonly web: WebServices;
+  session(id: string): SessionExecutor;
+  /** Obtain an object handle using a named resource contract; the host validates plugin ownership of the contract, object existence, and matching type, and stamps records accordingly. */
+  object<S extends Json>(sessionId: string, contract: ResourceContract<S>, id: string): ObjectExecutor;
+}
+export interface SessionCommitted {
+  readonly snapshot: SessionSnapshot;
+  readonly records: readonly SessionRecord[];
+  readonly session: SessionExecutor;
+}
+/** Fixed snapshot after the execution cursor changes; ordinary appends and explicit cursor selection use the same shape, while panel candidate selection does not trigger it. */
+export interface SessionCursorChanged {
+  readonly snapshot: SessionSnapshot;
+  readonly session: SessionExecutor;
+}
+export interface SessionObserver {
+  readonly id: string;
+  committed?(event: SessionCommitted): undefined;
+  cursorChanged?(event: SessionCursorChanged): undefined;
+}
+export type Preparation<C extends Json = Json> =
+  | { action: "accept" }
+  | { action: "replace"; input: C }
+  | { action: "reject"; code: string; message: string; display?: UiText };
+/** Preparation context: the resource's own preparation can read and write content in this scope, while external preparers can only read; neither modifies session data. */
+export interface CreationPreparation { readonly signal: AbortSignal; readonly content: ContentScope }
+export interface ActionPreparation extends CreationPreparation { readonly object: ObjectReader }
+export interface ExternalPreparation { readonly signal: AbortSignal; readonly object: ObjectReader; readonly content: ContentReader }
+export interface CommandPreparer<O extends Json = Json, I = unknown> {
+  readonly id: string;
+  readonly contract: ActionContract<I, O>;
+  prepare(input: O, context: ExternalPreparation): Preparation<I & Json> | Promise<Preparation<I & Json>>;
+}
+export interface ContextFile { readonly file: string; readonly text: string }
+export interface CreationContribution {
+  readonly contract: CreationContract<unknown>;
+  prepare?(input: Json, context: CreationPreparation): Preparation | Promise<Preparation>;
+  create(input: Json, object: ObjectExecutor): { title: string; data: Json };
+}
+export interface ActionContribution {
+  readonly contract: ActionContract<unknown>;
+  prepare?(input: Json, context: ActionPreparation): Preparation | Promise<Preparation>;
+  execute(input: Json, object: ObjectExecutor, signal: AbortSignal): Promise<void>;
+}
+export interface ResourceContribution {
+  readonly resource: ResourceContract;
+  /** Geometry declarations for backend placement, shared with ResourceDescription and cardRenderer. */
+  readonly card?: CardAppearance;
+  readonly records: readonly RecordContract[];
+  /** Opt into templates that copy encoded resource state and only these current-data contracts, preserving their values under new host identities. */
+  readonly template?: {
+    readonly current: readonly DataContract[];
+    /** Omit the source title when saving; generate a title for each template instance, overriding any previously saved title. */
+    createTitle?(): string;
+  };
+  /** Declare that this resource can receive links and provide the recipient's tool policy; independent of Agent domain types. */
+  readonly links?: { receive: boolean; tools?(object: ObjectReader): { allow?: readonly string[]; exclude?: readonly string[] } };
+  readonly creation?: CreationContribution;
+  readonly actions?: readonly ActionContribution[];
+  project(resource: ResourceSnapshot, object: ObjectReader): Presentation;
+  inspect(resource: ResourceSnapshot, object: ObjectReader): Promise<Json>;
+  context?(resource: ResourceSnapshot, object: ObjectReader): Promise<ContextFile[]>;
+  /** Explanation presented to users before ending the current instance; does not block backend removal or wait for external cleanup. */
+  disposalWarning?(resource: ResourceSnapshot, object: ObjectReader): UiText | null;
+  /**
+   * Called synchronously when an object enters the current set through startup, creation, restoration, or rewinding that makes it reappear; lifetime ends when the object leaves the current set,
+   * its session is archived, or the application exits. Register cleanup here for external instances owned exclusively by the object.
+   */
+  attach?(resource: ResourceSnapshot, object: ObjectReader, lifetime: Lifetime): void;
+}
+type OptionalData<T, D> = T extends unknown ? Omit<T, "data"> & { data?: D | null } : never;
+export type CallResult<D extends Json = Json> =
+  | { kind: "succeeded"; data: D }
+  | { kind: "partial"; data: D; message: string }
+  | OptionalData<Exclude<ToolCompletion, { kind: "succeeded" | "partial" }>, D>;
+export type PreparedResult = CallResult & ToolInvocationInfo;
+/** Tool caller identity captured at the request boundary; carries neither private resource state nor operation permissions. */
+export type ToolCaller = Readonly<Pick<ResourceSnapshot, "ref" | "title">>;
+export interface ToolInvocation extends ToolInvocationInfo {
+  effect: "read" | "write";
+  execution: "parallel" | "sequential";
+  execute(signal: AbortSignal, publish?: (data: Json) => void): Promise<CallResult>;
+  toModel?(data: Json): ToolModelOutput;
+}
+export interface ToolContribution {
+  readonly contract: ImplementationContract<Json, Json, Json, Json>;
+  /** Bind resource-specific access and configuration at the model request boundary. The returned contribution handles that request's calls. */
+  capture?(resource: ResourceSnapshot, object: ObjectReader, caller: ToolCaller): ToolContribution;
+  prepare(resource: ResourceSnapshot, object: ObjectExecutor, target: Json, args: Json, caller: ToolCaller): ToolInvocation | PreparedResult;
+}
+export interface ModuleContribution {
+  agentSkills?: readonly AgentSkillDeclaration[];
+  agentInstructions?: readonly AgentInstructionDeclaration[];
+  webProviders?: readonly WebProviderDefinition[];
+  usageProviders?: readonly UsageProvider[];
+  modelProviderPresets?: readonly ModelProviderPresetContribution[];
+  calls?: readonly CallContribution[];
+  /** Object-level duplex channel; the contract belongs to this plugin, and routing follows the plugin owning the object type. */
+  channels?: readonly ChannelContribution[];
+  topLevelTools?: readonly TopLevelTool[];
+  events?: readonly EventContract[];
+  records?: readonly RecordContract[];
+  resources?: readonly ResourceContribution[];
+  tools?: readonly ToolContribution[];
+  observers?: readonly SessionObserver[];
+  preparers?: readonly CommandPreparer[];
+}
+/** Named module entry point: plugins provide contributions, and the host handles assembly and invocation. */
+export interface PluginModule { setup(plugin: PluginContext): ModuleContribution }
+/** Composition of shared plugin services and feature modules; shared services are established first and released after the modules. */
+export interface PluginContribution extends ModuleContribution {
+  modules?: readonly PluginModule[];
+}
+/**
+ * Format declarations for persistent plugin files; paths are relative to extensions/<pluginId>, and migration key n means n → n+1.
+ * Versions are stamped by the writer: JSON uses a `{ version, data }` envelope, and SQLite uses `PRAGMA user_version`.
+ */
+export type PluginStorageDeclaration = {
+  kind: "json"; path: string; version: number;
+  migrations: Readonly<Record<number, (data: unknown) => Json>>;
+} | {
+  kind: "sqlite"; path: string; version: number;
+  migrations: Readonly<Record<number, (db: DatabaseSync) => void>>;
+};
+/** Default export of the storage entry point (manifest `asterism.storage`); the host imports it separately before the plugin runtime. */
+export function defineStorage(declarations: readonly PluginStorageDeclaration[]): readonly PluginStorageDeclaration[] {
+  for (const item of declarations) if (!Number.isSafeInteger(item.version) || item.version < 1)
+    throw new Error(`Storage ${item.path} must declare a positive integer version.`);
+  return Object.freeze([...declarations]);
+}
+export interface PluginDefinition {
+  namespace: PluginNamespace; modules?: readonly PluginModule[];
+  setup?(plugin: PluginContext): PluginContribution;
+}
+export function defineModule(setup: PluginModule["setup"]): PluginModule {
+  if (typeof setup !== "function") throw new Error("A plugin module must declare a setup function.");
+  return { setup };
+}
+export function definePlugin(definition: PluginDefinition): PluginDefinition & { modules: readonly PluginModule[] } {
+  return { ...definition, modules: [...definition.modules ?? []] };
+}

package/src/runtime-mcp.ts

@@ -0,0 +1,24 @@
+import type { Json } from "./json.ts";
+import type { McpCatalogServer, McpServerState } from "./mcp.ts";
+
+export type McpContent =
+  | { type: "text"; text: string }
+  | { type: "image" | "audio"; data: string; mimeType: string }
+  | { type: "resource"; resource: { uri: string; mimeType?: string } & ({ text: string } | { blob: string }) }
+  | { type: "resource_link"; uri: string; name: string; description?: string };
+export interface McpCallResult { content: McpContent[]; structuredContent?: unknown; isError?: boolean }
+export interface McpProgress { progress: number; total?: number; message?: string }
+/** Bound to the server instance and tool identity captured by resolve. */
+export interface McpToolHandle {
+  readonly serverId: string;
+  readonly serverName: string;
+  readonly toolName: string;
+  call(args: Record<string, Json>, options: { signal: AbortSignal; progress(value: McpProgress): void }): Promise<McpCallResult>;
+}
+export interface McpServices {
+  states(): McpServerState[];
+  catalog(): McpCatalogServer[];
+  connect(serverId: string, signal: AbortSignal): Promise<void>;
+  resolve(toolId: string): McpToolHandle;
+  subscribe(listener: () => void): () => void;
+}

package/src/runtime-model-providers.ts

@@ -0,0 +1,16 @@
+import type { ModelProviderConnection, ModelProviderPreset } from "./model-provider.ts";
+
+export interface ModelProviderServices {
+  presets(): readonly ModelProviderPreset[];
+  list(): readonly ModelProviderInfo[];
+  get(id: string): ModelProviderInfo | null;
+  /** Backend only; reads the connection's current credentials, returning null for connections without authentication. */
+  credential(id: string, options?: { signal?: AbortSignal }): Promise<string | null>;
+  /** Connection or preset catalog changes; returns an unsubscribe function and unsubscribes automatically when the plugin closes. */
+  subscribe(listener: () => void): () => void;
+}
+export interface ModelProviderInfo extends ModelProviderConnection {
+  id: string;
+  name: string;
+  enabled: boolean;
+}

package/src/runtime-resources.ts

@@ -0,0 +1,117 @@
+import type { ActionContract, CreationContract } from "./commands.ts";
+import type { z } from "zod";
+import { jsonSchema, type Json } from "./json.ts";
+import { defaultToolModel, type ToolModelOutput } from "./tool-result.ts";
+import type { ResourceContract, ImplementationContract } from "./module-contract.ts";
+import type { RecordContract } from "./records.ts";
+import { reference, present, type DataContract } from "./presentation.ts";
+import { PluginApiError } from "./runtime.ts";
+import type { ContextFile, ObjectReader, ObjectExecutor, CreationContribution, ActionContribution, CommandPreparer, CreationPreparation, ActionPreparation, ExternalPreparation, ResourceContribution, ToolContribution, Preparation, CallResult, Lifetime } from "./runtime-contracts.ts";
+import { validationMessage, jsonArgumentHint } from "./tool-validation.ts";
+import type { ToolCaller } from "./runtime-contracts.ts";
+import { encodeJson } from "./data-encoding.ts";
+
+function parse<T>(schema: z.ZodType<T>, input: unknown, subject: string): T {
+  const result = schema.safeParse(input);
+  if (!result.success) throw new PluginApiError("invalid_argument", validationMessage(result.error, subject));
+  return result.data;
+}
+/** Creation and actions are invoked after host validation; types are erased only during contribution assembly. */
+export function implementCreation<I, S extends Json, O extends Json>(contract: CreationContract<I, S, O>, definition: {
+  prepare?(input: NoInfer<O>, context: CreationPreparation): Preparation<NoInfer<I> & Json> | Promise<Preparation<NoInfer<I> & Json>>;
+  create(input: NoInfer<O>, object: ObjectExecutor): { title: string; data: NoInfer<S> };
+}): CreationContribution {
+  return { contract, ...definition } as CreationContribution;
+}
+export function implementAction<I, O extends Json>(contract: ActionContract<I, O>, definition: {
+  prepare?(input: NoInfer<O>, context: ActionPreparation): Preparation<NoInfer<I> & Json> | Promise<Preparation<NoInfer<I> & Json>>;
+  execute(input: NoInfer<O>, object: ObjectExecutor, signal: AbortSignal): Promise<void>;
+}): ActionContribution {
+  return { contract, ...definition } as ActionContribution;
+}
+export function implementPreparer<I, O extends Json>(contract: ActionContract<I, O>, definition: {
+  id: string;
+  prepare(input: NoInfer<O>, context: ExternalPreparation): Preparation<NoInfer<I> & Json> | Promise<Preparation<NoInfer<I> & Json>>;
+}): CommandPreparer {
+  return { contract, ...definition } as CommandPreparer;
+}
+export function implementResource<S extends Json, V extends Json>(
+  resource: ResourceContract<S>, view: DataContract<V>, definition: {
+    card?: ResourceContribution["card"];
+    records?: readonly RecordContract[];
+    template?: ResourceContribution["template"];
+    links?: ResourceContribution["links"];
+    creation?: CreationContribution;
+    actions?: readonly ActionContribution[];
+    project(data: NoInfer<S>, object: ObjectReader): NoInfer<V>;
+    inspect(data: NoInfer<S>, object: ObjectReader): Promise<Json>;
+    context?(data: NoInfer<S>, object: ObjectReader): Promise<ContextFile[]>;
+    disposalWarning?(data: NoInfer<S>, object: ObjectReader): import("./i18n.ts").UiText | null;
+    /** Called when an object enters the current set; external instances owned exclusively by the object register cleanup with lifetime. */
+    attach?(data: NoInfer<S>, object: ObjectReader, lifetime: Lifetime): void;
+  },
+): ResourceContribution {
+  const attach = definition.attach;
+  return {
+    resource, card: definition.card, records: [...definition.records ?? []], links: definition.links, template: definition.template,
+    creation: definition.creation, actions: definition.actions,
+    project: (snapshot, object) => present(view, definition.project(parse(resource.stateSchema, snapshot.data, "resource"), object)),
+    inspect: async (snapshot, object) => jsonSchema.parse(await definition.inspect(parse(resource.stateSchema, snapshot.data, "resource"), object)),
+    context: async (snapshot, object) => definition.context?.(parse(resource.stateSchema, snapshot.data, "resource"), object) ?? [],
+    disposalWarning: (snapshot, object) => definition.disposalWarning?.(parse(resource.stateSchema, snapshot.data, "resource"), object) ?? null,
+    ...(attach ? { attach: (snapshot: Parameters<NonNullable<ResourceContribution["attach"]>>[0], object: ObjectReader, lifetime: Lifetime) =>
+      attach(parse(resource.stateSchema, snapshot.data, "resource"), object, lifetime) } : {}),
+  };
+}
+export function implementTool<S extends Json, T extends Json, A extends Json, D extends Json>(
+  contract: ImplementationContract<S, T, A, D>, definition: {
+    call(data: S, target: T, args: A, context: {
+      object: ObjectExecutor; caller: ToolCaller; signal: AbortSignal; publish(data: NoInfer<D>): void;
+    }): Promise<CallResult<NoInfer<D>>>;
+    toModel?(data: D): ToolModelOutput;
+  },
+): ToolContribution {
+  const identity = reference(contract);
+  return {
+    contract: contract as unknown as ToolContribution["contract"],
+    prepare(resource, object, target, args, caller) {
+      const state = contract.resource.stateSchema.safeParse(resource.data);
+      if (!state.success) return { kind: "failed", implementation: identity,
+        error: { code: "invalid_resource", message: "The resource state does not match its backend contract." } };
+      const parsedTarget = contract.targetSchema.safeParse(target);
+      const parsedArgs = contract.tool.argsSchema.safeParse(args);
+      if (!parsedTarget.success || !parsedArgs.success) return { kind: "rejected", implementation: identity,
+        error: { code: "invalid_arguments", message: [
+          `Invalid arguments for ${contract.resource.kind}/${contract.tool.name}.`,
+          ...(!parsedTarget.success ? [validationMessage(parsedTarget.error, "target")] : []),
+          ...(!parsedArgs.success ? [validationMessage(parsedArgs.error, "args")] : []),
+          jsonArgumentHint,
+        ].join("\n") } };
+      return {
+        effect: contract.effect, execution: contract.execution, implementation: identity,
+        // Model projections consume decoded values.
+        toModel: data => {
+          const decoded = contract.schema.parse(data);
+          return definition.toModel ? definition.toModel(decoded) : defaultToolModel(decoded);
+        },
+        async execute(signal, publish) {
+          let active = true;
+          const snapshot = (data: Json) => {
+            const encoded = encodeJson<Json>(contract.schema, data, contract.id);
+            if (encoded === null && data !== null)
+              throw new PluginApiError("invalid_argument", `${contract.id}: non-null tool results require a non-null encoding; null denotes absent output.`);
+            return encoded;
+          };
+          try {
+            const result = await definition.call(state.data, parsedTarget.data, parsedArgs.data, { object, caller, signal,
+              publish(data) { if (active) publish?.(snapshot(data)); } });
+            if (result.kind === "succeeded" || result.kind === "partial") {
+              if (result.data === undefined) throw new PluginApiError("invalid_argument", "The tool did not provide final data.");
+            } else if (result.data === undefined || result.data === null) return result;
+            return { ...result, data: snapshot(result.data) };
+          } finally { active = false; }
+        },
+      };
+    },
+  };
+}