@asterism-app/sdk 0.0.0-stage → 0.47.0

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,188 @@
+/** 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, UsageProviderServices, UsageProvider, UsageServices } from "./runtime-providers.ts";
+import type { WebServices, WebProviderServices, WebProviderDefinition } from "./runtime-web.ts";
+import type { ModelProviderPresetContribution } from "./provider-usage.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 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 dir: string;
+  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 webProviders: WebProviderServices;
+  readonly web: WebServices;
+  readonly catalogs: { get<T extends Json>(contract: DataContract<T>): T | null };
+  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[] };
+  /** 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>;
+  prepare(resource: ResourceSnapshot, object: ObjectExecutor, target: Json, args: Json, caller: ToolCaller): ToolInvocation | PreparedResult;
+}
+export interface ModuleContribution {
+  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-providers.ts

@@ -0,0 +1,60 @@
+import type { ModelProviderConnection, ModelProviderPreset, ProviderUsageError, UsageItem, UsageProviderInfo } from "./provider-usage.ts";
+import type { UiText } from "./i18n.ts";
+
+/** Consumers explicitly supply the connection and credentials required for the query. */
+export interface UsageQueryContext {
+  readonly connection: { id: string; endpoint: string };
+  readonly credential: string | null;
+  readonly signal: AbortSignal;
+}
+interface UsageProviderIdentity {
+  readonly id: string;
+  readonly label: UiText;
+}
+export interface QueryUsageProvider extends UsageProviderIdentity {
+  readonly source?: "query";
+  query(context: UsageQueryContext): Promise<UsageItem[]>;
+}
+export interface UsageHeadersContext {
+  readonly connection: { id: string; endpoint: string };
+  readonly model: string;
+  readonly status: number;
+  readonly receivedAt: number;
+  readonly headers: Readonly<Record<string, string>>;
+}
+/** Consumers supply response metadata they obtained themselves; the parser makes no network requests. */
+export interface HeadersUsageProvider extends UsageProviderIdentity {
+  readonly source: "headers";
+  /** null means no usable data this time; an empty list explicitly reports no quota items. */
+  parseHeaders(context: UsageHeadersContext): UsageItem[] | null;
+}
+export type UsageProvider = QueryUsageProvider | HeadersUsageProvider;
+/** Providers report publicly exposable error categories; raw responses and credentials are not delivered across processes. */
+export class UsageQueryError extends Error {
+  constructor(readonly code: ProviderUsageError) { super(`Provider usage query failed: ${code}.`); }
+}
+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;
+}
+export interface UsageProviderServices {
+  list(): readonly UsageProviderInfo[];
+  /** Obtain an implementation bound to the provider lifecycle; does not select connections, read credentials, or save results. */
+  get(id: string): UsageProvider | null;
+  subscribe(listener: () => void): () => void;
+}
+/** Stateless invocation facade; consumers explicitly supply connections, credentials, and responses. */
+export interface UsageServices {
+  query(providerId: string, context: UsageQueryContext): Promise<UsageItem[]>;
+  parseHeaders(providerId: string, context: UsageHeadersContext): UsageItem[] | null;
+}

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; }
+        },
+      };
+    },
+  };
+}

package/src/runtime-tools.ts

@@ -0,0 +1,31 @@
+import { defineTool, type ToolContract } from "./module-contract.ts";
+import type { Json } from "./json.ts";
+import type { ObjectReader, ToolSession } from "./objects.ts";
+import type { CallResult } from "./runtime-contracts.ts";
+import type { ToolModelOutput } from "./tool-result.ts";
+import type { z } from "zod";
+
+export interface TopLevelToolContext<D extends Json = Json> {
+  readonly object: ObjectReader;
+  readonly session: ToolSession;
+  readonly callId: string;
+  readonly signal: AbortSignal;
+  publish(data: D): void;
+}
+/** Top-level tools declare their definition and implementation together, independently of resource support relationships. */
+export interface TopLevelTool<A extends Json = Json, D extends Json = Json> extends ToolContract<A> {
+  /** Encodes D for progress/history and decodes it for views and model projection. */
+  readonly resultSchema: z.ZodType<D>;
+  readonly effect: "read" | "write";
+  readonly execution: "parallel" | "sequential";
+  execute(args: A, context: TopLevelToolContext<D>): Promise<CallResult<D>>;
+  toModel?(data: D): ToolModelOutput;
+}
+export function defineTopLevelTool<A extends Json, D extends Json>(definition: TopLevelTool<A, D>): TopLevelTool {
+  if (!definition.resultSchema.description?.trim()) throw new Error(`Missing result schema description: ${definition.id}`);
+  const tool = defineTool(definition);
+  return { ...definition, ...tool,
+    execute: (args, context) => definition.execute(args as A, context as TopLevelToolContext<D>),
+    ...(definition.toModel ? { toModel: (data: Json) => definition.toModel!(data as D) } : {}),
+  } as TopLevelTool;
+}

package/src/runtime-web.ts

@@ -0,0 +1,36 @@
+import type { UiText } from "./i18n.ts";
+import type { WebCredentialDefinition, WebProviderState, WebProviderType, WebSearchRequest, WebFetchRequest, WebResponse, WebSearchResult, WebFetchResult } from "./web.ts";
+
+export interface WebProviderInstance {
+  search?(request: WebSearchRequest, options: { signal: AbortSignal }): Promise<WebResponse>;
+  fetch?(request: WebFetchRequest, options: { signal: AbortSignal }): Promise<WebResponse>;
+}
+export interface WebProviderDefinition {
+  id: string;
+  label: UiText;
+  search: boolean;
+  fetch: boolean;
+  /** Glob for the complete URL, with * matching any characters; fetch routing matches in declaration order. */
+  urlPatterns: readonly string[];
+  defaultBaseUrl: string;
+  /** Required credential type; null means no credentials are required. */
+  credential: WebCredentialDefinition | null;
+  /** Synchronous factory; baseUrl has trailing slashes removed, and credential is null if and only if the credential declaration is null. */
+  create(context: { baseUrl: string; credential: string | null }): WebProviderInstance;
+}
+export interface WebProviderServices {
+  types(): readonly WebProviderType[];
+  list(): readonly WebProviderState[];
+  get(id: string): WebProviderState | null;
+  /** Return an invocation facade bound to the provider lifecycle; id is the provider type slug. */
+  resolve(id: string, options: { signal: AbortSignal }): Promise<WebProviderInstance>;
+  subscribe(listener: () => void): () => void;
+}
+export interface WebServices {
+  search(request: WebSearchRequest, options: { signal: AbortSignal }): Promise<WebSearchResult>;
+  fetch(request: WebFetchRequest, options: { signal: AbortSignal }): Promise<WebFetchResult>;
+}
+export type WebErrorCode = "provider_unavailable" | "credential_unavailable" | "unsupported" | "invalid_request" | "protocol" | "request_failed";
+export class WebError extends Error {
+  constructor(readonly code: WebErrorCode, message: string) { super(message); }
+}

package/src/runtime.ts

@@ -0,0 +1,44 @@
+/** SDK runtime entry point: generic service interfaces available to backend plugins; excludes host internal types and domain knowledge. */
+import type { Json } from "./json.ts";
+import type { UiText } from "./i18n.ts";
+import type { ResourceRef } from "./workspace.ts";
+export * from "./runtime-contracts.ts";
+export * from "./runtime-resources.ts";
+export * from "./runtime-calls.ts";
+export * from "./runtime-channels.ts";
+export * from "./runtime-tools.ts";
+export * from "./runtime-providers.ts";
+export * from "./runtime-web.ts";
+export type * from "./content-runtime.ts";
+export type * from "./models.ts";
+export { validationMessage, jsonArgumentHint } from "./tool-validation.ts";
+
+/** Stable plugin API error: code supports plugin branching, and message is used for logs. */
+export class PluginApiError extends Error {
+  constructor(readonly code: "invalid_argument" | "foreign_resource" | "foreign_event" | "unavailable" | "rejected" | "conflict" | "not_found", message: string,
+    /** Business reason codes for preparation rejection or model input preflight checks. */
+    readonly reason?: string, readonly display?: UiText) { super(message); }
+}
+export interface PluginLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string, error?: unknown): void;
+}
+/** Backend handle for host-managed configuration: get reads the current value each time; update uses the latest complete configuration; subscribe receives changes from settings pages or other modules. */
+export interface PluginConfig<T extends Json> {
+  get(): T;
+  update(next: (current: T) => T): void;
+  subscribe(listener: (value: T) => void): () => void;
+}
+/** Namespaced credentials: plaintext exists only in the system-protected vault, while plugin directories store only references. */
+export interface PluginSecrets {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+/** Host-managed asynchronous tasks within the process: a running key is not started again, and host shutdown cancels tasks; no timeout by default, and tasks are not resumed after restart. */
+export interface PluginTasks {
+  start(key: string, run: (signal: AbortSignal) => Promise<void>, options?: { timeoutMs?: number; object?: ResourceRef }): boolean;
+  cancel(key: string): void;
+  has(key: string): boolean;
+}

package/src/tool-result.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { jsonSchema, type Json } from "./json.ts";
+import { contractReferenceSchema } from "./presentation.ts";
+import { modelInputPartsSchema, type ModelInputPart } from "./model-input.ts";
+
+export const toolResourceSchema = z.strictObject({ id: z.string(), kind: z.string(), title: z.string() });
+/** Identity selected for this request; history display must not substitute the current resource or current implementation. */
+export const toolInvocationSchema = z.strictObject({
+  implementation: contractReferenceSchema.optional(),
+  resource: toolResourceSchema.optional(),
+  startedAt: z.number().nonnegative().optional(),
+  finishedAt: z.number().nonnegative().optional(),
+});
+export type ToolInvocationInfo = z.infer<typeof toolInvocationSchema>;
+
+const error = z.strictObject({ code: z.string(), message: z.string() });
+export const toolCompletionSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("succeeded"), data: jsonSchema }),
+  z.strictObject({ kind: z.literal("partial"), data: jsonSchema, message: z.string() }),
+  z.strictObject({ kind: z.literal("rejected"), data: jsonSchema, error }),
+  z.strictObject({ kind: z.literal("failed"), data: jsonSchema, error }),
+  z.strictObject({ kind: z.literal("cancelled"), data: jsonSchema, message: z.string() }),
+  z.strictObject({ kind: z.literal("unknown"), data: jsonSchema, message: z.string() }),
+]);
+export const toolRunningResultSchema = z.strictObject({ kind: z.literal("running"), data: jsonSchema });
+type WithData<T, D> = T extends unknown ? Omit<T, "data"> & { data: D | null } : never;
+export type ToolCompletion<D = Json> = WithData<z.infer<typeof toolCompletionSchema>, D>;
+/** Progress and terminal states share the data contract; null means no valid output yet. */
+export type ToolResult<D = Json> = { kind: "running"; data: D | null } | ToolCompletion<D>;
+/** Model projection and user input share text | file parts; only success and partial success may carry files. */
+const saved = { ...toolInvocationSchema.shape, model: modelInputPartsSchema };
+function extendSaved<I extends 0 | 1 | 2 | 3 | 4 | 5>(index: I) { return toolCompletionSchema.options[index].extend(saved); }
+export const toolOutcomeSchema = z.discriminatedUnion("kind",
+  toolCompletionSchema.options.map(option => option.extend(saved)) as unknown as [
+    ReturnType<typeof extendSaved<0>>, ReturnType<typeof extendSaved<1>>, ReturnType<typeof extendSaved<2>>,
+    ReturnType<typeof extendSaved<3>>, ReturnType<typeof extendSaved<4>>, ReturnType<typeof extendSaved<5>>,
+  ]).refine(outcome => outcome.kind === "succeeded" || outcome.kind === "partial" || outcome.model.every(part => part.kind === "text"),
+  "Only succeeded or partial tool results can carry files.");
+export type ToolOutcome = z.infer<typeof toolOutcomeSchema>;
+/** Content passed from a tool to the model: a string becomes one text part; file parts reference immutable content staged during execution or already owned by the object. */
+export type ToolModelOutput = string | ModelInputPart[];
+/** Projection used when a tool declares no toModel: strings are text, other decoded values are JSON text. */
+export function defaultToolModel(data: Json): string {
+  return typeof data === "string" ? data : JSON.stringify(data);
+}

package/src/tool-validation.ts

@@ -0,0 +1,14 @@
+import type { z } from "zod";
+
+/** Preserve field paths and specific validation reasons from union branches so the model can correct the raw JSON arguments. */
+export function validationMessage(error: z.ZodError, field: string): string {
+  const format = (issues: readonly z.core.$ZodIssue[]): string => issues.map(issue => {
+    const path = [field, ...issue.path.map(String)].filter(Boolean).join(".");
+    return issue.code === "invalid_union"
+      ? `${path}: must match one of these alternatives: ${issue.errors.map(branch => `(${format(branch)})`).join(" OR ")}`
+      : `${path}: ${issue.message}`;
+  }).join("; ");
+  return format(error.issues);
+}
+
+export const jsonArgumentHint = "target and args are JSON values matching their schemas; objects and null retain their JSON types.";

package/src/web.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { presentationSchema } from "./presentation.ts";
+import { uiTextSchema } from "./i18n.ts";
+
+export const webUrlSchema = z.string().url().refine(value => {
+  const url = new URL(value);
+  return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+}, "An HTTP or HTTPS URL without embedded credentials is required.");
+export const webHintSchema = z.object({ code: z.string(), message: z.string(), parameter: z.string().optional() });
+export const webContentPartSchema = z.object({
+  kind: z.enum(["snippet", "excerpt", "body", "summary"]), format: z.enum(["text", "markdown"]), text: z.string(),
+  truncated: z.boolean().optional().describe("Known content truncation. Omitted when completeness is unknown."),
+});
+/** Dates retain upstream precision and kind; use unknown for an unknown date kind. */
+export const webDateSchema = z.object({ kind: z.enum(["published", "modified", "fetched", "unknown"]), value: z.string() });
+export const webDocumentSchema = z.object({
+  url: webUrlSchema, title: z.string().optional(), author: z.string().optional(),
+  dates: z.array(webDateSchema).optional(), content: z.array(webContentPartSchema),
+  image: webUrlSchema.optional(), favicon: webUrlSchema.optional(),
+  links: z.array(z.object({ url: webUrlSchema, title: z.string().optional() })).optional(),
+  /** Scores are interpreted by the actual provider; consumers preserve result order. */
+  score: z.number().finite().optional(), details: z.array(presentationSchema).optional(),
+});
+export const webUsageSchema = z.object({
+  name: z.string(), amount: z.number().finite(), unit: z.string(), currency: z.string().optional(),
+});
+export const webResponseSchema = z.object({
+  documents: z.array(webDocumentSchema), hints: z.array(webHintSchema),
+  requestId: z.string().optional(), usage: z.array(webUsageSchema).optional(), details: z.array(presentationSchema).optional(),
+});
+const date = z.union([z.iso.date(), z.iso.datetime({ offset: true })]);
+export const webSearchRequestSchema = z.object({
+  query: z.string().trim().min(1).describe("Web search query."),
+  maxResults: z.number().int().positive().default(10).describe("Maximum number of search results."),
+  includeDomains: z.array(z.string().trim().min(1)).optional().describe("Domains to include."),
+  excludeDomains: z.array(z.string().trim().min(1)).optional().describe("Domains to exclude."),
+  publishedAfter: date.optional().describe("Publication date lower bound, as an ISO date or timestamp."),
+  publishedBefore: date.optional().describe("Publication date upper bound, as an ISO date or timestamp."),
+  language: z.string().trim().min(1).optional().describe("Preferred content language."),
+  region: z.string().regex(/^[A-Z]{2}$/u).optional().describe("Two-letter country code for localized results."),
+}).describe("Search terms and optional filters. Result hints describe conditions that were not applied.");
+export const webFetchRequestSchema = z.object({
+  url: webUrlSchema.describe("URL to retrieve."),
+  query: z.string().trim().min(1).optional().describe("Optional focus for additional excerpts delivered alongside the page body. Excerpt retrieval may incur additional provider charges."),
+  maxCharacters: z.number().int().positive().optional().describe("Maximum body characters per document, counted as Unicode code points across body parts. Excerpts and metadata are separate. Omitted uses provider defaults."),
+}).describe("URL, optional additional excerpt focus and body character limit.");
+
+/** Providers declare credential types; the UI renders corresponding inputs by type and does not accept arbitrary JSON. */
+export const webCredentialDefinitionSchema = z.object({
+  kind: z.enum(["api_key"]),
+  keyUrl: webUrlSchema.optional(),
+});
+/** At most one configuration per provider type; id equals the type slug. */
+export const webProviderStateSchema = z.strictObject({
+  id: z.string().trim().min(1),
+  enabled: z.boolean(),
+});
+export const webProviderTypeSchema = z.object({
+  id: z.string().min(1), label: uiTextSchema, owner: z.string(),
+  search: z.boolean(), fetch: z.boolean(), urlPatterns: z.array(z.string().min(1)),
+  credential: webCredentialDefinitionSchema.nullable(),
+});
+/** provider in results is the type slug of the provider that actually handled the request. */
+export const webSearchResultSchema = webResponseSchema.extend({ query: z.string(), provider: z.string() });
+export const webFetchResultSchema = webResponseSchema.extend({ requestedUrl: webUrlSchema, provider: z.string() });
+export type WebHint = z.infer<typeof webHintSchema>;
+export type WebDocument = z.infer<typeof webDocumentSchema>;
+export type WebResponse = z.infer<typeof webResponseSchema>;
+export type WebSearchRequest = z.infer<typeof webSearchRequestSchema>;
+export type WebFetchRequest = z.infer<typeof webFetchRequestSchema>;
+export type WebCredentialDefinition = z.infer<typeof webCredentialDefinitionSchema>;
+export type WebProviderState = z.infer<typeof webProviderStateSchema>;
+export type WebProviderType = z.infer<typeof webProviderTypeSchema>;
+export type WebSearchResult = z.infer<typeof webSearchResultSchema>;
+export type WebFetchResult = z.infer<typeof webFetchResultSchema>;