@asterism-app/sdk 0.0.0-stage → 1.0.0

package/examples/tool-renderer.ts

@@ -0,0 +1,47 @@
+/** Tool view author example: the three states are declared in parallel, and the same component can be reused across phases. */
+import { createElement } from "react";
+import { z } from "zod";
+import { defineData, type Json } from "@asterism-app/sdk/contracts";
+import { toolRenderer, type ToolRenderProps } from "@asterism-app/sdk/renderer";
+
+const Result = defineData("example.writer/write", z.object({ written: z.number() }));
+const targetSchema = z.object({ path: z.string() });
+const argsSchema = z.object({ content: z.string() });
+type Props = ToolRenderProps<z.infer<typeof Result.schema>, z.infer<typeof targetSchema>, z.infer<typeof argsSchema>>;
+
+function inputContent(args: Json): string {
+  return args !== null && typeof args === "object" && !Array.isArray(args) && typeof args.content === "string" ? args.content : "";
+}
+
+function Header(props: Props) {
+  let path: string | undefined;
+  if (props.phase === "input") {
+    const target = props.target;
+    if (target !== null && typeof target === "object" && !Array.isArray(target) && typeof target.path === "string") path = target.path;
+  } else path = props.target.path;
+  return createElement("span", null, path ?? "Write");
+}
+function Body(props: Props) {
+  if (props.phase === "input") {
+    return createElement("pre", null, inputContent(props.args).slice(-2_000));
+  }
+  return createElement("pre", null, props.result?.data?.written ?? props.args.content);
+}
+const view = { headerRenderer: Header, bodyRenderer: Body };
+export const writerView = toolRenderer({ ...Result, targetSchema, tool: { argsSchema } }, {
+  label: "Write",
+  input: { ...view, streaming: ({ args }) => inputContent(args).length > 0 },
+  execution: view, result: view,
+});
+
+/** Plugins render progressive output themselves; the shell manages automatic expansion and collapse based on declarations and user settings. */
+const Report = defineData("example.writer/report", z.object({ text: z.string() }));
+function ReportBody({ phase, result }: ToolRenderProps<z.infer<typeof Report.schema>>) {
+  const text = result?.data?.text ?? "";
+  return createElement("pre", null, phase === "executing" ? text.slice(-2_000) : text);
+}
+export const reportView = toolRenderer(Report, {
+  label: "Report",
+  execution: { bodyRenderer: ReportBody, streaming: ({ result }) => !!result?.data?.text },
+  result: { bodyRenderer: ReportBody },
+});

package/examples/web-provider.ts

@@ -0,0 +1,27 @@
+import { pluginNamespace, present, webResponseSchema } from "@asterism-app/sdk/contracts";
+import { definePlugin, WebError, type WebProviderDefinition } from "@asterism-app/sdk/runtime";
+import { z } from "zod";
+
+const ns = pluginNamespace("example.web");
+const Metadata = ns.data("metadata", z.object({ sourceId: z.string() }));
+const responseSchema = z.object({ id: z.string(), title: z.string(), text: z.string() });
+const provider: WebProviderDefinition = {
+  id: "example.web/pages", label: "Example pages", search: false, fetch: true,
+  urlPatterns: ["https://docs.example.test/*", "https://help.example.test/*"],
+  defaultBaseUrl: "https://api.example.test", credential: { kind: "api_key", keyUrl: "https://example.test/api-keys" },
+  create({ baseUrl, credential }) {
+    return { async fetch(request, { signal }) {
+      const response = await fetch(new URL("/read", baseUrl), {
+        method: "POST", signal, headers: { "Content-Type": "application/json", Authorization: `Bearer ${credential}` },
+        body: JSON.stringify({ url: request.url }),
+      });
+      if (!response.ok) throw new WebError("request_failed", `Page service returned HTTP ${response.status}.`);
+      const page = responseSchema.parse(await response.json());
+      return webResponseSchema.parse({ documents: [{ url: request.url, title: page.title,
+        content: [{ kind: "body", format: "markdown", text: page.text }], details: [present(Metadata, { sourceId: page.id })] }],
+        hints: request.query ? [{ code: "unsupported_parameter", parameter: "query", message: "This provider returned the page without query-focused excerpts." }] : [],
+      });
+    } };
+  },
+};
+export default definePlugin({ namespace: ns, setup: () => ({ webProviders: [provider] }) });

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@asterism-app/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Public contracts and host capabilities for Asterism plugins",
+  "license": "MIT",
+  "author": "Chien Zhang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/d3ara1n/asterism.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./contracts": "./src/contracts.ts",
+    "./runtime": "./src/runtime.ts",
+    "./renderer": "./src/renderer.ts"
+  },
+  "peerDependencies": {
+    "zod": "^4.6.5",
+    "react": "^19.3.0",
+    "react-intl": "^12.1.4"
+  },
+  "peerDependenciesMeta": {
+    "react-intl": {
+      "optional": true
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "docs",
+    "examples",
+    "README.md"
+  ]
+}

package/src/calls.ts

@@ -0,0 +1,28 @@
+import type { z } from "zod";
+import type { Json } from "./json.ts";
+import { contractReferenceSchema } from "./presentation.ts";
+import type { ResourceRef } from "./workspace.ts";
+import type { ContentReader } from "./content-runtime.ts";
+
+export type CallScope = "plugin" | "object";
+/** Scope is declared by the contract; callers cannot downgrade an object-level operation by omitting the object. */
+export interface CallContract<Input extends z.ZodType<Json> = z.ZodType<Json>, Output extends z.ZodType<Json> = z.ZodType<Json>, S extends CallScope = CallScope> {
+  readonly id: string;
+  readonly scope: S;
+  readonly input: Input;
+  readonly output: Output;
+}
+export function defineCall<Input extends z.ZodType<Json>, Output extends z.ZodType<Json>, S extends CallScope>(id: string, definition: {
+  scope: S; input: Input; output: Output;
+}): CallContract<Input, Output, S> {
+  if (definition.scope !== "plugin" && definition.scope !== "object") throw new Error("A call must declare plugin or object scope.");
+  return Object.freeze({ ...contractReferenceSchema.parse({ id }), ...definition });
+}
+export type CallOptions<S extends CallScope = CallScope, Content = ContentReader> = { signal?: AbortSignal; content?: Content } &
+  (S extends "object" ? { object: ResourceRef } : { object?: never });
+export interface PluginCalls<Content = ContentReader> {
+  /** Submit JSON matching the input schema's input; receive the output schema's parsed result. */
+  invoke<Input extends z.ZodType<Json>, Output extends z.ZodType<Json>, S extends CallScope>(
+    contract: CallContract<Input, Output, S>, input: NoInfer<z.input<Input>> & Json, options: CallOptions<NoInfer<S>, Content>,
+  ): Promise<z.output<Output>>;
+}

package/src/card.ts

@@ -0,0 +1,7 @@
+/** Card geometry declarations shared by frontend and backend, measured in canvas units. */
+export interface CardAppearance {
+  width: number;
+  height: number;
+  minWidth?: number;
+  minHeight?: number;
+}

package/src/channels.ts

@@ -0,0 +1,20 @@
+import { contractReferenceSchema } from "./presentation.ts";
+
+/** Channel payloads: JSON values and bytes supported by structured cloning, with arbitrary nesting. The host does not validate each frame. */
+export type ChannelValue = null | boolean | number | string | Uint8Array | readonly ChannelValue[] | { readonly [key: string]: ChannelValue };
+/** Channel end reasons: closed means either end closed it explicitly; removed means the object left the current set; unavailable means the contract or object is unavailable; disconnected means the connection was lost. */
+export type ChannelEnd = { reason: "closed" | "removed" | "unavailable" | "disconnected"; message?: string };
+
+/**
+ * Object-level duplex channel contract: opened by the frontend and routed by the backend to the object's owning plugin according to the contract.
+ * Up carries frontend-to-backend messages, and Down carries backend-to-frontend messages; both ends deliver in order without per-frame acknowledgments.
+ */
+export interface ChannelContract<Up extends ChannelValue = ChannelValue, Down extends ChannelValue = ChannelValue> {
+  readonly id: string;
+  readonly kind: "channel";
+  /** For type inference only. */
+  readonly __types?: { up: Up; down: Down };
+}
+export function defineChannel<Up extends ChannelValue, Down extends ChannelValue>(id: string): ChannelContract<Up, Down> {
+  return Object.freeze({ ...contractReferenceSchema.parse({ id }), kind: "channel" as const });
+}

package/src/commands.ts

@@ -0,0 +1,28 @@
+import type { z } from "zod";
+import { jsonSchema, type Json } from "./json.ts";
+import type { ResourceContract } from "./module-contract.ts";
+import { contractReferenceSchema, type ContractReference } from "./presentation.ts";
+
+/** I is the invocation input and O is the schema parsing result; both are inferred automatically from the declared schema. */
+export interface CreationContract<I = Json, S extends Json = Json, O extends Json = Json> extends ContractReference {
+  readonly kind: "creation";
+  readonly resource: ResourceContract<S>;
+  readonly schema: z.ZodType<O, I>;
+}
+export interface ActionContract<I = Json, O extends Json = Json> extends ContractReference {
+  readonly kind: "action";
+  readonly resource: ResourceContract;
+  readonly schema: z.ZodType<O, I>;
+}
+export function defineCreation<S extends Json, I, O extends Json>(resource: ResourceContract<S>, definition: ContractReference & { schema: z.ZodType<O, I> }): CreationContract<I, S, O> {
+  return { ...contractReferenceSchema.parse({ id: definition.id }), kind: "creation", resource, schema: definition.schema };
+}
+export function defineAction<I, O extends Json>(resource: ResourceContract, definition: ContractReference & { schema: z.ZodType<O, I> }): ActionContract<I, O> {
+  return { ...contractReferenceSchema.parse({ id: definition.id }), kind: "action", resource, schema: definition.schema };
+}
+/** Command envelopes carry only stable identity and raw JSON input; the host parses them using assembled declarations. */
+export const resourceCallSchema = contractReferenceSchema.extend({ input: jsonSchema });
+export type ResourceCall = z.infer<typeof resourceCallSchema>;
+export function resourceCall<I, O extends Json>(contract: CreationContract<I, Json, O> | ActionContract<I, O>, input: NoInfer<I> & Json): ResourceCall {
+  return { id: contract.id, input };
+}

package/src/config.ts

@@ -0,0 +1,25 @@
+import type { z } from "zod";
+import type { Json } from "./json.ts";
+import { encodeJson } from "./data-encoding.ts";
+
+/**
+ * Plugin configuration contract: settings agreed between users and plugins, with one configuration per plugin shared by frontend and backend.
+ * Identity is the plugin ID; the host handles storage, validation, and change notifications, while the plugin provides the page. Preferences such as the last selection are not configuration.
+ */
+export interface ConfigContract<T extends Json = Json> {
+  readonly plugin: string;
+  /** Decodes stored and transported configuration; updates and defaults use T. */
+  readonly schema: z.ZodType<T>;
+  readonly defaults: T;
+}
+export function defineConfig<T extends Json>(plugin: string, schema: z.ZodType<T>, defaults: NoInfer<T>): ConfigContract<T> {
+  const parsed = schema.safeParse(encodeJson(schema, structuredClone(defaults), `${plugin}.configuration defaults`));
+  if (!parsed.success) throw new Error(`Configuration defaults of ${plugin} do not match the schema.`);
+  return Object.freeze({ plugin, schema, defaults: structuredClone(parsed.data) });
+}
+/** Decode saved values according to the contract; fall back to defaults when invalid or missing, leaving status display to the caller. */
+export function readConfig<T extends Json>(contract: ConfigContract<T>, raw: unknown): { value: T; status: "saved" | "defaults" | "invalid" } {
+  if (raw === undefined) return { value: structuredClone(contract.defaults), status: "defaults" };
+  const parsed = contract.schema.safeParse(raw);
+  return parsed.success ? { value: parsed.data, status: "saved" } : { value: structuredClone(contract.defaults), status: "invalid" };
+}

package/src/content-runtime.ts

@@ -0,0 +1,11 @@
+import type { ContentRef, ContentRange } from "./content.ts";
+
+/** Individual reads have a size limit; large content uses bounded byte chunks through open. */
+export interface ContentReader {
+  read(ref: ContentRef, range?: ContentRange): Promise<Uint8Array>;
+  open(ref: ContentRef, range?: ContentRange): AsyncIterable<Uint8Array>;
+}
+/** Temporary workspace managed by the host; stage neither modifies the session nor establishes persistent references. */
+export interface ContentScope extends ContentReader {
+  stage(source: Uint8Array | AsyncIterable<Uint8Array>): Promise<ContentRef>;
+}

package/src/content.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+
+/** A JSON reference value reserved by the SDK; identity contains no path and grants no right to read or retain content. */
+export const contentRefSchema = z.strictObject({ "$asterism.content": z.string().uuid() });
+export type ContentRef = z.infer<typeof contentRefSchema>;
+export interface ContentRange { offset?: number; length?: number }

package/src/contracts.ts

@@ -0,0 +1,39 @@
+/** SDK pure contract entry point: does not depend on Node, Electron, React, or host source code. */
+export * from "./json.ts";
+export * from "./error-details.ts";
+export * from "./presentation.ts";
+export * from "./module-contract.ts";
+export type { CardAppearance } from "./card.ts";
+export * from "./plugin.ts";
+export * from "./records.ts";
+export * from "./events.ts";
+export * from "./calls.ts";
+export * from "./channels.ts";
+export * from "./tool-result.ts";
+export * from "./workspace.ts";
+export type * from "./models.ts";
+export { thinkingLevels } from "./models.ts";
+export * from "./model-records.ts";
+export { validationMessage, jsonArgumentHint } from "./tool-validation.ts";
+export * from "./commands.ts";
+export * from "./i18n.ts";
+export * from "./config.ts";
+export * from "./content.ts";
+export * from "./model-input.ts";
+
+export * from "./model-selection.ts";
+export * from "./model-catalog.ts";
+export * from "./model-cost.ts";
+export * from "./model-cost-estimate.ts";
+export * from "./model-media.ts";
+export * from "./model-provider.ts";
+export * from "./provider-usage.ts";
+export * from "./web.ts";
+
+export * from "./session-title.ts";
+
+export * from "./usage-state.ts";
+
+export * from "./shell.ts";
+export * from "./terminal.ts";
+export * from "./mcp.ts";

package/src/data-encoding.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { jsonSchema, type Json } from "./json.ts";
+import { validationMessage } from "./tool-validation.ts";
+
+/** Data producers supply decoded values; storage and transport retain the JSON encoding. */
+export function encodeJson<T extends Json>(schema: z.ZodType<T>, value: T, subject: string): Json {
+  try { return jsonSchema.parse(z.encode(schema, value)); }
+  catch (error) {
+    if (!(error instanceof z.ZodError) && !(error instanceof z.core.$ZodEncodeError)) throw error;
+    const detail = error instanceof z.ZodError ? validationMessage(error, subject)
+      : `${subject}: ${error.message}`;
+    throw new Error(`Cannot encode data: ${detail}`, { cause: error });
+  }
+}

package/src/error-details.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+
+/** Transferable raw error data; response bodies and additional data remain text to avoid being scanned as business references. */
+export type ErrorDetails = {
+  name?: string;
+  message: string;
+  code?: string | number;
+  statusCode?: number;
+  /** The actual HTTP status received; statusCode preserves the error object's original value, which may be inferred by the SDK. */
+  httpStatus?: number;
+  responseBody?: string;
+  /** The streaming response fragment actually received by the transport when the SDK fails before delivering the first model block. */
+  rawResponse?: string;
+  rawEvent?: string;
+  responseHeaders?: Record<string, string>;
+  data?: string;
+  stack?: string;
+  causes?: ErrorDetails[];
+};
+export const errorDetailsSchema: z.ZodType<ErrorDetails> = z.strictObject({
+  name: z.string().optional(), message: z.string(), code: z.union([z.string(), z.number()]).optional(),
+  statusCode: z.number().optional(), httpStatus: z.number().optional(), responseBody: z.string().optional(),
+  rawResponse: z.string().optional(), rawEvent: z.string().optional(),
+  responseHeaders: z.record(z.string(), z.string()).optional(), data: z.string().optional(),
+  stack: z.string().optional(), causes: z.lazy(() => errorDetailsSchema.array()).optional(),
+});
+
+/** Extract the error itself and response data; request bodies, request headers, and credentials are not error details. */
+export function describeError(error: unknown): ErrorDetails {
+  const seen = new Set<object>();
+  const encode = (value: unknown): string => {
+    if (typeof value === "string") return value;
+    const ancestors: object[] = [];
+    return JSON.stringify(value, function (_key, item: unknown) {
+      if (typeof item === "bigint") return String(item);
+      if (item && typeof item === "object") {
+        while (ancestors.length && ancestors.at(-1) !== this) ancestors.pop();
+        if (ancestors.includes(item)) return "[Circular]";
+        ancestors.push(item);
+      }
+      return item;
+    }) ?? String(value);
+  };
+  const visit = (value: unknown): ErrorDetails => {
+    if (!value || typeof value !== "object") return { message: typeof value === "string" ? value : encode(value) };
+    if (seen.has(value)) return { message: "[Circular error cause]" };
+    seen.add(value);
+    const record = value as Record<string, unknown>;
+    const attached = errorDetailsSchema.safeParse(record.details);
+    if (attached.success) return attached.data;
+    const { requestBodyValues: _values, requestBody: _body, requestHeaders: _headers, responseHeaders: _responseHeaders, ...raw } = record;
+    const details: ErrorDetails = {
+      message: typeof record.message === "string" ? record.message : encode(raw),
+    };
+    if (typeof record.name === "string") details.name = record.name;
+    if (typeof record.code === "string" || typeof record.code === "number") details.code = record.code;
+    if (typeof record.stack === "string") details.stack = record.stack;
+    if (typeof record.statusCode === "number") details.statusCode = record.statusCode;
+    if (typeof record.httpStatus === "number") details.httpStatus = record.httpStatus;
+    if (typeof record.responseBody === "string") details.responseBody = record.responseBody;
+    if (typeof record.rawResponse === "string") details.rawResponse = record.rawResponse;
+    if (typeof record.rawEvent === "string") details.rawEvent = record.rawEvent;
+    if (record.responseHeaders && typeof record.responseHeaders === "object") {
+      details.responseHeaders = Object.fromEntries(Object.entries(record.responseHeaders)
+        .filter((entry): entry is [string, string] => typeof entry[1] === "string"
+          && !/^(authorization|proxy-authorization|cookie|set-cookie|x-api-key)$/iu.test(entry[0])));
+    }
+    if (record.data !== undefined) details.data = encode(record.data);
+    else if (!(value instanceof Error)) details.data = encode(raw);
+    const causes = [
+      ...(record.cause !== undefined ? [record.cause] : []),
+      ...(Array.isArray(record.errors) ? record.errors : []),
+    ];
+    if (causes.length) details.causes = causes.map(visit);
+    return details;
+  };
+  return visit(error);
+}

package/src/events.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import type { Json } from "./json.ts";
+import type { Source } from "./workspace.ts";
+import { uiTextSchema } from "./i18n.ts";
+
+export type EventSourceKind = "plugin" | "resource" | "any" | "host";
+export interface EventEnvelope<D extends Json = Json> {
+  readonly contract: { readonly id: string };
+  readonly emittedAt: string;
+  readonly source: Source;
+  readonly data: D;
+}
+export type EventSemantics = { readonly kind: "occurrence" } | { readonly kind: "snapshot"; readonly key: readonly string[] };
+export interface EventContract<I = unknown, D extends Json = Json> {
+  readonly id: string;
+  readonly schema: z.ZodType<D, I>;
+  readonly source: EventSourceKind;
+  readonly semantics: EventSemantics;
+}
+export interface EventDefinition<I, D extends Json> {
+  schema: z.ZodType<D, I>;
+  source: EventSourceKind;
+  semantics: { kind: "occurrence" } | { kind: "snapshot"; key: readonly Extract<keyof D, string>[] };
+}
+export function defineEvent<I, D extends Json>(id: string, definition: EventDefinition<I, D>): EventContract<I, D> {
+  const semantics = definition.semantics.kind === "snapshot"
+    ? Object.freeze({ kind: "snapshot" as const, key: Object.freeze([...definition.semantics.key]) })
+    : Object.freeze({ kind: "occurrence" as const });
+  return Object.freeze({ id, schema: definition.schema, source: definition.source, semantics });
+}
+/** Source conditions filter only the host envelope; they neither interpret domain payloads nor grant resource operation permissions. */
+export interface EventFilter { plugin?: string; sessionId?: string; resourceId?: string; resourceKind?: string }
+export interface EventSubscribeOptions {
+  delivery?: "all" | "latest";
+  source?: EventFilter;
+  signal?: AbortSignal;
+}
+export interface SubscriptionEnd {
+  readonly reason: "closed" | "aborted" | "unavailable" | "invalid_contract" | "consumer_failed" | "disconnected";
+  readonly message?: string;
+}
+export interface EventSubscription {
+  readonly ready: Promise<void>;
+  readonly closed: Promise<SubscriptionEnd>;
+  close(): void;
+}
+export type EventHandler<D extends Json> = (event: EventEnvelope<D>, context: { signal: AbortSignal }) => void | Promise<void>;
+export interface EventSubscriber {
+  subscribe<I, D extends Json>(contract: EventContract<I, D>, options: EventSubscribeOptions, handler: EventHandler<NoInfer<D>>): EventSubscription;
+}
+export interface EventPublisher {
+  /** Deliver immediately after synchronous validation, without waiting for consumption or rolling back with the transaction; publish after a successful commit when effects must be confirmed. */
+  publish<I, D extends Json>(contract: EventContract<I, D>, data: NoInfer<I> & Json): void;
+}
+export interface PluginEvents extends EventSubscriber, EventPublisher {}
+
+/** Public event published by the application itself after a session title actually changes, with no plugin or resource source. */
+export const SessionTitleChanged = defineEvent("asterism/session-title", {
+  schema: z.strictObject({ sessionId: z.string(), title: z.string() }),
+  source: "host",
+  semantics: { kind: "snapshot", key: ["sessionId"] },
+});
+
+/** Transient changes to the current resource set; used to release UI state across sessions. */
+export const ResourcePresenceChanged = defineEvent("asterism/resource-presence", {
+  schema: z.strictObject({
+    sessionId: z.string(),
+    appeared: z.array(z.string()),
+    disappeared: z.array(z.string()),
+  }),
+  source: "host",
+  semantics: { kind: "occurrence" },
+});
+
+/** Each publication fully replaces resource status; running remains visible, while other states are consumed when the session is viewed. */
+export const ResourceStatusChanged = defineEvent("asterism/resource-status", {
+  schema: z.discriminatedUnion("status", [
+    z.strictObject({
+      title: uiTextSchema,
+      status: z.literal("running"),
+      progress: z.strictObject({ value: z.number().min(0).max(1) }).optional(),
+    }),
+    z.strictObject({
+      title: uiTextSchema,
+      status: z.enum(["failed", "awaiting", "completed"]),
+    }),
+  ]),
+  source: "resource",
+  semantics: { kind: "snapshot", key: [] },
+});
+export type ResourceStatus = z.infer<typeof ResourceStatusChanged.schema>;

package/src/i18n.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+export interface SourceMessage {
+  readonly id: string;
+  readonly defaultMessage: string;
+  readonly description?: string;
+}
+
+export type MessageValues = Readonly<Record<string, string | number | boolean>>;
+
+export interface UiMessage extends SourceMessage {
+  readonly kind: "message";
+  readonly owner: string;
+  readonly sourceLocale: string;
+  readonly values?: MessageValues;
+}
+
+export type UiText = string | UiMessage;
+
+export const localeSchema = z.string().refine(value => {
+  try { Intl.getCanonicalLocales(value); return true; }
+  catch { return false; }
+}, { message: "Invalid language tag.", abort: true })
+  .overwrite(value => Intl.getCanonicalLocales(value)[0]!);
+
+export const messageValuesSchema = z.record(z.string(), z.union([z.string(), z.number().finite(), z.boolean()]));
+export const uiMessageSchema = z.strictObject({
+  kind: z.literal("message"),
+  owner: z.string().min(1),
+  sourceLocale: localeSchema,
+  id: z.string().min(1),
+  defaultMessage: z.string().refine(value => !!value.trim(), "A default message is required."),
+  description: z.string().optional(),
+  values: messageValuesSchema.optional(),
+});
+export const uiTextSchema = z.union([z.string(), uiMessageSchema]);
+
+/** Standard static descriptor shape for extraction by the official FormatJS tooling. */
+export function defineMessages<const T extends Record<string, SourceMessage>>(messages: T): T {
+  return messages;
+}
+
+export function bindMessages<T extends Record<string, SourceMessage>>(
+  owner: string,
+  sourceLocale: string,
+  definitions: T,
+): { readonly [K in keyof T]: UiMessage } {
+  const locale = localeSchema.parse(sourceLocale);
+  const entries = Object.entries(definitions).map(([key, value]) => [
+    key,
+    Object.freeze(uiMessageSchema.parse({ ...value, kind: "message", owner, sourceLocale: locale })),
+  ]);
+  return Object.fromEntries(entries) as { readonly [K in keyof T]: UiMessage };
+}
+
+export function withValues(message: UiMessage, values: MessageValues): UiMessage {
+  return uiMessageSchema.parse({ ...message, values: { ...message.values, ...values } });
+}

package/src/json.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export const jsonSchema: z.ZodType<Json> = z.json();

package/src/mcp.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { defineCall } from "./calls.ts";
+import { defineEvent } from "./events.ts";
+import { jsonSchema } from "./json.ts";
+
+export const SERVER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/u;
+export const serverIdSchema = z.string().min(1).max(64).regex(SERVER_ID_PATTERN);
+export const mcpServerSchema = z.strictObject({
+  id: serverIdSchema, name: z.string().trim().min(1), enabled: z.boolean(),
+  mode: z.enum(["eager", "lazy"]), idleSeconds: z.number().int().min(1).max(86_400),
+  transport: z.enum(["stdio", "http"]), command: z.string(), args: z.array(z.string()), cwd: z.string(),
+  url: z.string(), auth: z.enum(["none", "oauth"]),
+}).superRefine((value, ctx) => {
+  if (value.transport === "stdio" && !value.command.trim()) ctx.addIssue({ code: "custom", path: ["command"], message: "An executable is required." });
+  if (value.transport === "http") {
+    try { const url = new URL(value.url); if (!["http:", "https:"].includes(url.protocol)) throw new Error(); }
+    catch { ctx.addIssue({ code: "custom", path: ["url"], message: "An HTTP or HTTPS MCP URL is required." }); }
+  }
+});
+export type McpServerConfig = z.infer<typeof mcpServerSchema>;
+export const mcpSettingsSchema = z.object({ servers: z.array(mcpServerSchema).refine(values =>
+  new Set(values.map(value => value.id)).size === values.length, "Server IDs are unique.") });
+export const defaultMcpSettings = { servers: [] };
+export const credentialsSchema = z.record(z.string(), z.string());
+export const connectionPhases = ["disconnected", "connecting", "awaiting_auth", "authorizing", "connected", "error"] as const;
+export type ConnectionPhase = typeof connectionPhases[number];
+export const mcpServerStateSchema = z.object({
+  id: z.string(), name: z.string(), enabled: z.boolean(), mode: z.enum(["eager", "lazy"]),
+  connection: z.enum(connectionPhases),
+  indexed: z.boolean(), toolCount: z.number(), error: z.string().nullable(), authorizationUrl: z.string().nullable(),
+  authorizationExpiresAt: z.number().nullable(),
+});
+export type McpServerState = z.infer<typeof mcpServerStateSchema>;
+export const cachedMcpToolSchema = z.object({
+  name: z.string(), title: z.string().optional(), description: z.string().optional(),
+  inputSchema: z.record(z.string(), jsonSchema), outputSchema: z.record(z.string(), jsonSchema).optional(),
+  annotations: z.record(z.string(), jsonSchema).optional(),
+});
+export type CachedMcpTool = z.infer<typeof cachedMcpToolSchema>;
+export const mcpDirectorySchema = z.object({ tools: z.array(cachedMcpToolSchema), instructions: z.string().optional() });
+export type McpDirectory = z.infer<typeof mcpDirectorySchema>;
+export interface McpCatalogServer { config: McpServerConfig; state: McpServerState; directory?: McpDirectory }
+
+export const McpChanged = defineEvent("core.mcp.changed", { schema: z.object({}), source: "host", semantics: { kind: "snapshot", key: [] } });
+export const ReadMcp = defineCall("core.mcp.status", { scope: "plugin", input: z.object({}), output: z.array(mcpServerStateSchema) });
+/** keep retains saved environment or headers; a new server with keep starts without any. */
+export const mcpCredentialUpdateSchema = z.discriminatedUnion("action", [
+  z.strictObject({ action: z.literal("keep") }), z.strictObject({ action: z.literal("replace"), values: credentialsSchema }),
+]);
+export type McpCredentialUpdate = z.infer<typeof mcpCredentialUpdateSchema>;
+export const SaveMcpServer = defineCall("core.mcp.save-server", { scope: "plugin",
+  input: z.object({ server: mcpServerSchema, create: z.boolean(), credentials: mcpCredentialUpdateSchema }), output: z.null() });
+export const ReadMcpCredentials = defineCall("core.mcp.read-credentials", { scope: "plugin", input: z.object({ serverId: z.string() }), output: credentialsSchema });
+export const mcpToolSummarySchema = z.object({ name: z.string(), title: z.string().optional(), description: z.string().optional() });
+export type McpToolSummary = z.infer<typeof mcpToolSummarySchema>;
+export const ReadMcpTools = defineCall("core.mcp.read-tools", { scope: "plugin", input: z.object({ serverId: z.string() }),
+  output: z.object({ tools: z.array(mcpToolSummarySchema), instructions: z.string().optional() }).nullable() });
+export const SetMcpServerEnabled = defineCall("core.mcp.set-enabled", { scope: "plugin", input: z.object({ serverId: z.string(), enabled: z.boolean() }), output: z.null() });
+export const RemoveMcpServer = defineCall("core.mcp.remove-server", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.null() });
+export const ConnectMcpServer = defineCall("core.mcp.connect-server", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.null() });
+export const AuthorizeMcpServer = defineCall("core.mcp.authorize-server", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.object({ url: z.string() }) });
+export const DisconnectMcpServer = defineCall("core.mcp.disconnect-server", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.null() });
+export const ResetMcpAuth = defineCall("core.mcp.reset-auth", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.null() });
+
+export type McpErrorCode = "invalid_tool_id" | "server_not_found" | "server_disabled" | "tool_not_found" | "invalid_tool_arguments"
+  | "service_unavailable" | "connection_failed" | "authorization_expired" | "request_failed" | "tool_error";
+export class McpError extends Error {
+  readonly code: McpErrorCode;
+  constructor(code: McpErrorCode, message: string) { super(message); this.code = code; }
+}
+export class McpInterrupted extends Error {
+  readonly outcome: "cancelled" | "unknown";
+  constructor(outcome: "cancelled" | "unknown", message: string) { super(message); this.outcome = outcome; }
+}
+export function mcpToolIdentity(serverId: string, name: string): string { return `${serverId}/${name}`; }
+export function parseMcpToolIdentity(value: string): [string, string] {
+  const split = value.indexOf("/"), serverId = value.slice(0, split), name = value.slice(split + 1);
+  if (split < 1 || !name || !SERVER_ID_PATTERN.test(serverId)) throw new McpError("invalid_tool_id", "Tool identity uses the form server_id/tool_name.");
+  return [serverId, name];
+}