@asterism-app/sdk 0.0.0-stage → 0.47.0

package/src/model-records.ts

@@ -0,0 +1,56 @@
+/** Shared payloads for model execution; consuming plugins declare RecordContract identities, and the SDK does not create a separate history. */
+import { z } from "zod";
+import { jsonSchema, type Json } from "./json.ts";
+import { toolOutcomeSchema } from "./tool-result.ts";
+import { presentationSchema, type DataContract } from "./presentation.ts";
+import type { ModelCompletion } from "./models.ts";
+import { errorDetailsSchema } from "./error-details.ts";
+
+const id = z.string().min(1).max(160);
+export const modelUsageSchema = z.strictObject({
+  input: z.number().nonnegative().nullable(), output: z.number().nonnegative().nullable(),
+  total: z.number().nonnegative().nullable(), reasoning: z.number().nonnegative().nullable(),
+  cacheRead: z.number().nonnegative().nullable(), cacheWrite: z.number().nonnegative().nullable(),
+});
+/** Dates and times locate events; millisecond offsets come from the same monotonic clock, not from subtracting wall-clock timestamps. */
+export const requestTimingSchema = z.strictObject({
+  startedAt: z.iso.datetime(),
+  endedAt: z.iso.datetime(),
+  durationMs: z.number().nonnegative(),
+  firstOutputMs: z.number().nonnegative().nullable(),
+  firstTextMs: z.number().nonnegative().nullable(),
+  firstReasoningMs: z.number().nonnegative().nullable(),
+  lastOutputMs: z.number().nonnegative().nullable(),
+  outputChunks: z.number().int().nonnegative(),
+  outcome: z.enum(["completed", "failed", "cancelled"]),
+});
+export type RequestTiming = z.infer<typeof requestTimingSchema>;
+
+export const modelSourceSchema = z.strictObject({ model: z.string(), adapter: z.string(), scope: z.string() });
+export const modelCompletionSchema = z.strictObject({ usage: modelUsageSchema.nullable(), finishReason: z.string(),
+  rawFinishReason: z.string().nullable(), providerResponseId: z.string().nullable(), timing: requestTimingSchema.optional(),
+  extensions: z.array(presentationSchema).optional() });
+/** Decode only domain extensions known to the caller; unknown or undecodable extensions do not affect the public terminal state. */
+export function completionData<T extends Json>(completion: ModelCompletion | null | undefined, contract: DataContract<T>): T | null {
+  const extension = completion?.extensions?.find(value => value.contract.id === contract.id);
+  if (!extension) return null;
+  const result = contract.schema.safeParse(structuredClone(extension.data));
+  return result.success ? result.data : null;
+}
+const block = { responseId: id, requestParentId: id.nullable(), ordinal: z.number().int().nonnegative(),
+  complete: z.boolean(), continuation: jsonSchema, source: modelSourceSchema, completion: modelCompletionSchema.nullable().optional(),
+  /** Block generation start and end times (millisecond timestamps); blocks finalized before generation ends have a null end time, and unrecorded times are omitted. See outcome for tool execution times. */
+  startedAt: z.number().nonnegative().optional(), endedAt: z.number().nonnegative().nullable().optional() };
+export const modelBlockSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ ...block, kind: z.literal("thinking"), text: z.string(), summary: z.string() }),
+  z.strictObject({ ...block, kind: z.literal("text"), text: z.string() }),
+  z.strictObject({ ...block, kind: z.literal("toolcall"), callId: id, name: id,
+    /** Original model text; retained only when parsed arguments are unavailable (the call is incomplete), otherwise arguments is authoritative. */
+    argumentsText: z.string().nullable(), arguments: jsonSchema, outcome: toolOutcomeSchema.nullable() })
+    .refine(data => data.complete === (data.outcome !== null), "Complete tool calls must have an outcome."),
+]);
+/** Terminal state is embedded in finalized blocks; execution notifications carry only feedback, not response identity or measurements. */
+export const modelRunRecordSchema = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal("block"), block: modelBlockSchema }),
+  z.strictObject({ type: z.literal("diagnostic"), origin: z.enum(["model", "software"]), code: z.string(), message: z.string(), level: z.enum(["error", "warning"]), details: errorDetailsSchema.optional() }),
+]);

package/src/model-selection.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { thinkingLevels, type ThinkingLevel } from "./models.ts";
+
+/** Model expression `<providerId>/<modelId>`: provider and model always appear as a pair, split at the first `/`. */
+export interface ModelExpression { provider: string; model: string }
+export function parseModelExpression(value: string): ModelExpression | null {
+  const index = value.indexOf("/");
+  if (index <= 0 || index === value.length - 1) return null;
+  return { provider: value.slice(0, index), model: value.slice(index + 1) };
+}
+export function formatModelExpression(expression: ModelExpression): string { return `${expression.provider}/${expression.model}`; }
+export const modelExpressionSchema = z.string().max(321).refine(value => parseModelExpression(value) !== null, "Use a model expression such as provider/model.");
+/** A reference string for a specific model; corresponds one-to-one with model records without using random record IDs. */
+export function modelReference(model: { providerId: string; modelId: string }): string {
+  return formatModelExpression({ provider: model.providerId, model: model.modelId });
+}
+export const thinkingSchema = z.enum(thinkingLevels);
+
+/** Display and requests share override calculation; empty values inherit defaults, without checking availability or rewriting selections. */
+export function resolveModelSelection(
+  defaults: { model: string | null; thinking: ThinkingLevel | null } | undefined,
+  overrides: { model?: string | null; thinking?: ThinkingLevel | null },
+) {
+  return {
+    model: overrides.model ?? defaults?.model ?? null,
+    thinking: overrides.thinking ?? defaults?.thinking ?? null,
+  };
+}
+
+/** Generates menu options only; does not resolve existing selections or validate requests. */
+export function availableThinkingLevels(model: { capabilities: { reasoning: boolean; thinkingLevels: readonly typeof thinkingLevels[number][] } } | null) {
+  if (!model) return thinkingLevels;
+  return model.capabilities.reasoning ? thinkingLevels.filter(level => model.capabilities.thinkingLevels.includes(level)) : [];
+}

package/src/models.ts

@@ -0,0 +1,137 @@
+/** Shared model protocol: independent of resource implementations, agent configuration, and host adapters. */
+import type { Json } from "./json.ts";
+import type { ModelInputPart } from "./model-input.ts";
+import type { ContentReader } from "./content-runtime.ts";
+import type { ToolOutcome, ToolInvocationInfo, ToolResult } from "./tool-result.ts";
+import type { ResourceRef } from "./workspace.ts";
+import type { RequestTiming } from "./model-records.ts";
+import type { Presentation } from "./presentation.ts";
+import type { ErrorDetails } from "./error-details.ts";
+
+/** Standard levels shared across the application; protocol encoding does not change public values. */
+export const thinkingLevels = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = typeof thinkingLevels[number];
+export interface ModelTarget { role: string; model?: string; thinking?: ThinkingLevel }
+export type PromptBlock =
+  | { id: string; kind: "system"; from: string; text: string }
+  | { id: string; kind: "agent"; role: string; text: string }
+  | { id: string; kind: "context"; file: string; text: string };
+export interface SystemPrompt { blocks: readonly PromptBlock[] }
+/** Reasoning text is the plaintext delivered by the protocol, and summary is an independent summary; both can coexist or be empty, and neither fills the other.
+ * continuation carries only native data such as signatures/ciphertext; target projection determines whether it can be reused.
+ */
+export type ModelPart =
+  | { kind: "thinking"; text: string; summary: string; continuation: Json }
+  | { kind: "text"; text: string; continuation: Json }
+  | { kind: "toolcall"; callId: string; name: string; arguments: Json; continuation: Json };
+export type ModelItem =
+  | { kind: "input" | "context"; parts: readonly ModelInputPart[] }
+  // scope/adapter constrain native data; they do not gate public content in cross-model requests.
+  | { kind: "output"; parts: ModelPart[]; scope: string; adapter: string }
+  | { kind: "result"; callId: string; name: string; outcome: ToolOutcome };
+export interface Usage {
+  input: number | null; output: number | null; total: number | null;
+  reasoning: number | null; cacheRead: number | null; cacheWrite: number | null;
+}
+export type StreamPart =
+  | { id: string; kind: "text" | "thinking" }
+  | { id: string; kind: "toolcall"; callId: string; name: string };
+export type ModelEvent =
+  | { type: "part.start"; part: StreamPart }
+  | { type: "part.delta"; partId: string; delta: string; channel?: "summary" }
+  | { type: "part.end"; partId: string; arguments?: Json; continuation?: Json }
+  | { type: "finish"; reason: string; usage: Usage | null; responseId?: string; rawFinishReason?: string; source?: ModelSource; timing?: RequestTiming; response?: ModelResponse | null };
+export type ModelSource = { model: string; adapter: string; scope: string };
+export type ModelCompletion = {
+  usage: Usage | null; finishReason: string; rawFinishReason: string | null; providerResponseId: string | null;
+  timing?: RequestTiming;
+  /** Typed data declared and consumed by the domain; the public layer preserves unknown contracts. */
+  extensions?: Presentation[];
+};
+/** Finalized response blocks; these are not session nodes, and the consumer provides timeline identity and persistence. */
+export type ModelBlock = {
+  responseId: string; requestParentId: string | null; ordinal: number; complete: boolean; continuation: Json; source: ModelSource;
+  /** Terminal state is delivered once with the actual response block having the highest ordinal; null for all other blocks. */
+  completion?: ModelCompletion | null;
+  /** Block generation start and end times (millisecond timestamps); blocks finalized before generation ends have a null end time, and unrecorded times are omitted. See outcome for tool execution times. */
+  startedAt?: number; endedAt?: number | null;
+} & (
+  | { kind: "thinking"; text: string; summary: string }
+  | { kind: "text"; text: string }
+  | { kind: "toolcall"; callId: string; name: string; argumentsText: string | null; arguments: Json; outcome: ToolOutcome | null }
+);
+export type ModelLiveBlock = { id: string; responseId: string; ordinal: number } & (
+  | { kind: "text"; text: string; endedAt: number | null }
+  | { kind: "thinking"; text: string; startedAt: number; endedAt: number | null }
+  /** During the input phase, arguments is a display preview parsed tolerantly and cannot be used for execution; other phases contain complete arguments. */
+  | { kind: "toolcall"; name: string; argumentsText: string; arguments: Json; state: "input" | "ready" | "executing";
+      invocation: ToolInvocationInfo | null; result: Extract<ToolResult, { kind: "running" }> | null }
+);
+export type ModelRunEvent =
+  | { type: "block"; block: ModelBlock }
+  | { type: "progress"; blocks: readonly ModelLiveBlock[] }
+  | { type: "diagnostic"; origin: "model" | "software"; code: string; message: string; level: "error" | "warning"; details?: ErrorDetails };
+/** Deliver execution events synchronously; consumers save finalized records, exceptions stop execution, and no further events are delivered after returning. */
+export interface ModelRunObserver { event(event: ModelRunEvent): undefined }
+/** Used only for HTTP request identity; does not enter model messages, history, or resource authorization. */
+export interface ModelRequestIdentity {
+  userAgent?: string;
+  /** Stable within a session; may be omitted for a one-off call without a session. */
+  sessionId?: string;
+}
+/** Transient metadata from the actual HTTP response; contains no request credentials or body and is not automatically written to history. */
+export interface ModelResponse {
+  connection: { id: string };
+  endpoint: string;
+  model: string;
+  status: number;
+  receivedAt: number;
+  headers: Readonly<Record<string, string>>;
+}
+export interface ModelRunRequest {
+  object: ResourceRef;
+  /** Session identity comes from object; callers may declare their own client identity. */
+  userAgent?: string;
+  requestParentId: string | null;
+  target: ModelTarget;
+  system: SystemPrompt;
+  messages: ModelItem[];
+  /** Filters plugin top-level tools and resource tools selected through actual links by name; does not affect fixed host entry points. */
+  tools?: { allow?: readonly string[]; exclude?: readonly string[] };
+  cache?: { expectHit: boolean };
+  /** Synchronously package domain data after final request preparation; delivered with the actual response's completion. */
+  completionExtensions?: (context: ModelRequestContext) => readonly Presentation[];
+  signal: AbortSignal;
+  observer: ModelRunObserver;
+}
+export type ModelRunResult = {
+  responseId: string | null; source: ModelSource | null; completion: ModelCompletion | null; tools: readonly ToolOutcome[];
+  /** Metadata from the last HTTP response received during this call; null if none was received, and excluded from response blocks and history. */
+  response: ModelResponse | null;
+  /** Measured timing for this call; still available for transient feedback when no terminal state was obtained. */
+  timing: RequestTiming | null;
+} & ({ reason: "completed" } | { reason: "cancelled" } | { reason: "failed"; code: string; details?: ErrorDetails });
+/** The final request's input context; an independent copy for domain extension producers to read. */
+export interface ModelRequestContext {
+  system: SystemPrompt;
+  tools: readonly { name: string; description: string; parameters: Json }[];
+}
+export interface StreamRequest extends ModelRequestIdentity {
+  target: ModelTarget;
+  system: SystemPrompt;
+  messages: ModelItem[];
+  /** The output limit for this completion; uses the smaller of this value and the model's configured limit. */
+  maxOutputTokens?: number;
+  tools?: { name: string; description: string; parameters: Json }[];
+  signal: AbortSignal;
+}
+export interface ModelInputOptions { content?: ContentReader }
+export interface ModelServices {
+  /** Check explicit request input and target without sending a model request or saving state. */
+  validate(request: Pick<StreamRequest, "target" | "system" | "messages" | "signal" | "userAgent" | "sessionId">, options?: ModelInputOptions): Promise<void>;
+  stream(request: StreamRequest, options?: ModelInputOptions): AsyncIterable<ModelEvent>;
+  /** One request and its tool batch; neither saves history nor drives the next request. */
+  run(request: ModelRunRequest): Promise<ModelRunResult>;
+  roles(): readonly { id: string; description: string; hidden: boolean; model: string | null; thinking: ThinkingLevel | null }[];
+  list(): readonly { model: string; provider: string; name: string; contextWindow: number | null; capabilities: { reasoning: boolean; tools: boolean; thinkingLevels: readonly ThinkingLevel[] } }[];
+}

package/src/module-contract.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { Json } from "./json.ts";
+import { contractReferenceSchema, type ContractReference, type DataContract } from "./presentation.ts";
+
+export interface ResourceContract<S extends Json = Json> {
+  kind: string;
+  /** Decodes saved state; creation callbacks return S for encoding before persistence. State is arbitrary JSON, stored separately from host identity and title. */
+  stateSchema: z.ZodType<S>;
+}
+export interface ToolContract<A extends Json = Json> extends ContractReference {
+  name: string;
+  description: string;
+  guidelines: readonly string[];
+  argsSchema: z.ZodType<A>;
+}
+/** Tool definitions fix selection descriptions, usage guidance, and args; implementations add only target/result and execution information. */
+export interface ImplementationContract<S extends Json, T extends Json, A extends Json, O extends Json> extends DataContract<O> {
+  resource: ResourceContract<S>;
+  tool: ToolContract<A>;
+  targetSchema: z.ZodType<T>;
+  effect: "read" | "write";
+  execution: "parallel" | "sequential";
+}
+export function defineResource<S extends Json>(kind: string, stateSchema: z.ZodType<S>): ResourceContract<S> {
+  return { kind, stateSchema };
+}
+/** Tool args/target/result are projected as JSON Schema for the model; representability is validated at declaration time to avoid failures only when invoked. */
+function requireDescription(schema: z.ZodType, subject: string): void {
+  if (!schema.description?.trim()) throw new Error(`Missing schema description: ${subject}`);
+  try { z.toJSONSchema(schema); } catch (error) { throw new Error(`Schema is not representable as JSON Schema: ${subject}`, { cause: error }); }
+}
+export function defineTool<A extends Json>(definition: ToolContract<A>): ToolContract<A> {
+  if (!definition.name.trim() || !definition.description.trim()) throw new Error("Tool name and description must not be empty.");
+  if (definition.guidelines.some(guideline => !guideline.trim())) throw new Error(`Empty tool guideline: ${definition.name}`);
+  requireDescription(definition.argsSchema, `${definition.name}.args`);
+  return { ...definition, ...contractReferenceSchema.parse({ id: definition.id }), guidelines: [...definition.guidelines] };
+}
+export function defineImplementation<S extends Json, T extends Json, A extends Json, O extends Json>(
+  definition: ImplementationContract<S, T, A, O>,
+): ImplementationContract<S, T, A, O> {
+  requireDescription(definition.targetSchema, `${definition.id}.target`);
+  requireDescription(definition.schema, `${definition.id}.result`);
+  return definition;
+}

package/src/objects.ts

@@ -0,0 +1,89 @@
+import type { Json } from "./json.ts";
+import type { DataContract } from "./presentation.ts";
+import type { RecordContract } from "./records.ts";
+import type { ResourceRef, ResourceCreationResult, ResourceSnapshot, SessionSnapshot } from "./workspace.ts";
+import type { ContentReader, ContentScope } from "./content-runtime.ts";
+import type { EventPublisher } from "./events.ts";
+import type { ActionContract, CreationContract } from "./commands.ts";
+
+export interface ResourceCreationOptions {
+  signal?: AbortSignal;
+  /** Read eligibility for content referenced by the input; defaults to the current session content facade when omitted. */
+  content?: ContentReader;
+  /** Link the new resource to this recipient, committed atomically with creation. */
+  linkTo?: ResourceRef;
+  /** Initial resource links received by the new resource, committed atomically with creation. */
+  resources?: readonly ResourceRef[];
+}
+export interface ResourceActionOptions {
+  signal?: AbortSignal;
+  /** The valid content source for this action's input; defaults to the caller's bound session/object content facade when omitted. */
+  content?: ContentReader;
+}
+
+/** Data and event writes within a synchronous transaction; the host limits the validity of writer calls. */
+export interface SessionWriter {
+  /** Append to the current timeline tip at commit time and advance the cursor; previously obtained read-only snapshots do not determine the append position. */
+  append<T extends Json>(contract: RecordContract<T>, data: NoInfer<T>): string;
+  set<T extends Json>(contract: DataContract<T>, data: NoInfer<T>): void;
+}
+export type ObjectWriter = SessionWriter;
+export interface SessionReader {
+  readonly id: string;
+  readonly content: ContentReader;
+  snapshot(): SessionSnapshot;
+  get<T extends Json>(contract: DataContract<T>): T | null;
+  readonly title: { get(): string };
+}
+/** Generic execution facade at the session level; resource operations use explicit references, and the specific call entry point binds the caller's perspective. */
+export interface SessionExecutor extends SessionReader {
+  create<I, S extends Json, O extends Json>(contract: CreationContract<I, S, O>, input: NoInfer<I> & Json, options?: ResourceCreationOptions): Promise<ResourceCreationResult>;
+  /** Invoke a resource's public action; returning means action handling is complete, while the resource manages any independent managed work itself. */
+  invoke<I, O extends Json>(contract: ActionContract<I, O>, target: ResourceRef, input: NoInfer<I> & Json, options?: ResourceActionOptions): Promise<void>;
+  /** Link a resource to a recipient; both ends are resources, and the recipient's resource type declares support for receiving links. */
+  link(receiver: ResourceRef, resource: ResourceRef): void;
+  /** Unlink the specified direction; the reverse link remains independently. */
+  unlink(receiver: ResourceRef, resource: ResourceRef): void;
+  /** Remove a settled object and all its links; preserve history and external entities. */
+  remove(resource: ResourceRef): void;
+  /** Append a resource rename event when the title changes; return the title with leading and trailing whitespace removed. */
+  rename(resource: ResourceRef, title: string): string;
+  commit(work: (writer: SessionWriter) => undefined): void;
+  /** set directly overwrites the session title; it can be called within a synchronous commit and commits or rolls back with it. */
+  readonly title: SessionReader["title"] & { set(text: string): void };
+}
+/**
+ * An operation facade for the same session from the perspective of the tool caller and this request.
+ * The host binds the originating resource, the effective link scope at request start, and the tool execution scope, handling identity and execution validation consistently.
+ * Operations originate from the initiating resource: newly created resources link to it, while removal and rename targets resolve within this request's effective link scope.
+ * New operations use this perspective, explicitly defining implicitly bound endpoints, the operable resource scope, and the execution scope.
+ */
+export interface ToolSession extends SessionReader {
+  create<I, S extends Json, O extends Json>(contract: CreationContract<I, S, O>, input: NoInfer<I> & Json, options?: {
+    resources?: readonly string[];
+    /** Link the bound initiator to the new resource, committed atomically with creation; defaults to false when omitted. */
+    exposeSelf?: boolean;
+  }): Promise<ResourceCreationResult>;
+  remove(resourceId: string): void;
+  rename(resourceId: string, title: string): string;
+}
+export interface ObjectReader {
+  readonly ref: ResourceRef;
+  readonly content: ContentReader;
+  readonly session: SessionReader;
+  /** The resource snapshot bound to the call; null when identity has not yet been established within the creation transaction. */
+  snapshot(): ResourceSnapshot | null;
+  /** Current data is independent of the fixed snapshot and is not restored by cursor rewinding or branching. */
+  get<T extends Json>(contract: DataContract<T>): T | null;
+}
+export interface ObjectExecutor extends ObjectReader {
+  readonly events: EventPublisher;
+  /** Staging is valid only within the host execution scope; reads are validated against content already owned by the object or supplied in this input. */
+  readonly content: ContentScope;
+  readonly session: SessionExecutor;
+  commit(work: (writer: ObjectWriter) => undefined): void;
+  /** Mark asynchronous work that depends on the current timeline path; nested holds release independently, and cancellation waits for work to actually end. */
+  withBusy<T>(work: (signal: AbortSignal) => Promise<T>, options?: { signal?: AbortSignal }): Promise<T>;
+  /** Notify the host to query the projection again after in-memory display data changes; does not append history or save resource data. */
+  invalidate(): void;
+}

package/src/plugin.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { uiTextSchema } from "./i18n.ts";
+import type { Json } from "./json.ts";
+import { bindMessages, type SourceMessage, type UiMessage } from "./i18n.ts";
+import { defineData, type DataContract } from "./presentation.ts";
+import { defineResource, type ResourceContract } from "./module-contract.ts";
+import { defineConfig, type ConfigContract } from "./config.ts";
+import { defineEvent, type EventContract, type EventDefinition } from "./events.ts";
+
+const pluginIdPattern = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+$/u;
+const shortNamePattern = /^[a-z0-9][a-z0-9._-]*$/u;
+
+/** Static information can be read without executing plugin code; the host resolves icon to an image within the package. */
+export const pluginMetadataSchema = z.strictObject({
+  name: uiTextSchema.optional(), description: uiTextSchema.optional(),
+  version: z.string().optional(), author: z.string().optional(), icon: z.string().optional(),
+});
+export type PluginMetadata = z.infer<typeof pluginMetadataSchema>;
+
+/**
+ * Plugin namespace: declare plugin identity only once here; contract files declare resource types and data contracts using short names,
+ * which are expanded here to `<pluginId>/<name>`. Pure contracts shared by frontend and backend.
+ */
+export interface PluginNamespace {
+  readonly id: string;
+  messages<T extends Record<string, SourceMessage>>(sourceLocale: string, definitions: T): { readonly [K in keyof T]: UiMessage };
+  name(short: string): string;
+  resource<S extends Json>(name: string, stateSchema: z.ZodType<S>): ResourceContract<S>;
+  data<T extends Json>(name: string, schema: z.ZodType<T>): DataContract<T>;
+  event<I, D extends Json>(name: string, definition: EventDefinition<I, D>): EventContract<I, D>;
+  /** The plugin's sole user configuration contract. */
+  config<T extends Json>(schema: z.ZodType<T>, defaults: NoInfer<T>): ConfigContract<T>;
+}
+export function pluginNamespace(id: string): PluginNamespace {
+  if (!pluginIdPattern.test(id)) throw new Error(`Invalid plugin ID: ${id}`);
+  const name = (short: string) => {
+    if (!shortNamePattern.test(short)) throw new Error(`Invalid short name in plugin ${id}: ${short}`);
+    return `${id}/${short}`;
+  };
+  return {
+    id, name,
+    messages: (sourceLocale, definitions) => bindMessages(id, sourceLocale, definitions),
+    resource: (short, stateSchema) => defineResource(name(short), stateSchema),
+    data: (short, schema) => defineData(name(short), schema),
+    event: (short, definition) => defineEvent(name(short), definition),
+    config: (schema, defaults) => defineConfig(id, schema, defaults),
+  };
+}
+export function belongsTo(pluginId: string, qualified: string): boolean {
+  return qualified.startsWith(`${pluginId}/`) && qualified.length > pluginId.length + 1;
+}
+/** Extract the source plugin from a namespaced ID; return null when there is no namespace. */
+export function pluginOf(qualified: string): string | null {
+  const index = qualified.indexOf("/");
+  return index > 0 ? qualified.slice(0, index) : null;
+}
+/** Resource projection for a missing implementation: preserves raw data and the source plugin for fallback UI display. */
+export const missingResourceContract = { id: "asterism.builtin/missing-resource" } as const;

package/src/presentation.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { jsonSchema, type Json } from "./json.ts";
+import { encodeJson } from "./data-encoding.ts";
+
+export const contractReferenceSchema = z.strictObject({ id: z.string().min(1).max(160) });
+export type ContractReference = z.infer<typeof contractReferenceSchema>;
+/** The schema decodes stored or transported JSON into T; producers encode T through the same schema. */
+export interface DataContract<T extends Json = Json> extends ContractReference { schema: z.ZodType<T> }
+export const presentationSchema = z.strictObject({ contract: contractReferenceSchema, data: jsonSchema });
+export type Presentation = z.infer<typeof presentationSchema>;
+
+/** Shared declarations depend on no process or UI; each end registers its own implementation. */
+export function defineData<T extends Json>(id: string, schema: z.ZodType<T>): DataContract<T> {
+  return { ...contractReferenceSchema.parse({ id }), schema };
+}
+export function reference(contract: ContractReference): ContractReference {
+  return { id: contract.id };
+}
+export function present<T extends Json>(contract: DataContract<T>, value: NoInfer<T>): Presentation {
+  return { contract: reference(contract), data: encodeJson(contract.schema, value, contract.id) };
+}

package/src/provider-usage.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { uiTextSchema, type UiText } from "./i18n.ts";
+import { jsonSchema, type Json } from "./json.ts";
+
+/** Usage queries and presets use global catalog IDs; connection identity is independent, and duplicate catalog identities must fail explicitly. */
+export const providerUsageIdSchema = z.string().trim().min(1).max(160).regex(/^\S+$/u);
+export const modelProviderFixedFields = ["protocol", "baseUrl", "auth", "compatibility", "usage"] as const;
+export interface ModelProviderConnection {
+  protocol: "openai-responses" | "openai-chat" | "anthropic";
+  baseUrl: string;
+  auth: "api_key" | "none";
+  compatibility: { id: string; value?: Json }[];
+  usage?: string | null;
+  fixedFields?: (typeof modelProviderFixedFields)[number][];
+}
+export interface ModelProviderPreset {
+  id: string;
+  name: string;
+  billing: "usage" | "subscription" | "none";
+  region?: UiText;
+  plan?: UiText;
+  connection: ModelProviderConnection;
+  keyUrl?: string;
+  sources: readonly [string, ...string[]];
+  verifiedOn: string;
+  keywords?: readonly string[];
+}
+const webUrl = z.string().url().refine(value => ["http:", "https:"].includes(new URL(value).protocol));
+export const modelProviderConnectionSchema = z.strictObject({
+  protocol: z.enum(["openai-responses", "openai-chat", "anthropic"]),
+  baseUrl: webUrl, auth: z.enum(["api_key", "none"]),
+  compatibility: z.array(z.strictObject({ id: z.string().min(1), value: jsonSchema.optional() })),
+  usage: providerUsageIdSchema.nullable().optional(),
+  fixedFields: z.array(z.enum(modelProviderFixedFields)).optional(),
+});
+export const modelProviderPresetSchema = z.strictObject({
+  id: z.string().trim().min(1).max(160).regex(/^[^/\s]+$/u), name: z.string().trim().min(1).max(160),
+  billing: z.enum(["usage", "subscription", "none"]), region: uiTextSchema.optional(), plan: uiTextSchema.optional(),
+  connection: modelProviderConnectionSchema, keyUrl: webUrl.optional(),
+  sources: z.tuple([webUrl]).rest(webUrl), verifiedOn: z.iso.date(), keywords: z.array(z.string()).optional(),
+});
+/** patch overrides only explicit fields; connection merges by field, arrays are replaced as a whole, and saved connections are not rewritten. */
+export type ModelProviderPresetContribution =
+  | { type: "add"; preset: ModelProviderPreset }
+  | { type: "patch"; id: string; patch: Partial<Omit<ModelProviderPreset, "id" | "connection">> & { connection?: Partial<ModelProviderConnection> } };
+
+const identity = {
+  id: z.string().trim().min(1), label: uiTextSchema,
+  scope: z.enum(["account", "plan", "key", "connection"]),
+};
+export const quotaValueSchema = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal("ratio"), remaining: z.number().min(0).max(1) }),
+  z.strictObject({ type: z.literal("quantity"), remaining: z.number().nonnegative(), limit: z.number().positive(), unit: uiTextSchema })
+    .refine(value => value.remaining <= value.limit, "Remaining quota cannot exceed its limit."),
+]);
+export const usageItemSchema = z.discriminatedUnion("type", [
+  z.strictObject({ ...identity, type: z.literal("balance"), remaining: z.number(), currency: z.string().regex(/^[A-Z]{3}$/u) }),
+  z.strictObject({ ...identity, type: z.literal("quota"), value: quotaValueSchema,
+    category: z.enum(["allowance", "rate_limit"]).optional(),
+    window: z.strictObject({
+      mode: z.enum(["rolling", "fixed", "unknown"]),
+      /** Supply an actual fixed duration only when known; unknown periods must not be fabricated as weeks or months. */
+      durationMs: z.number().positive().nullable(),
+      resetAt: z.number().nonnegative().nullable(),
+    }),
+  }),
+]);
+export const usageItemsSchema = z.array(usageItemSchema).refine(items => new Set(items.map(item => item.id)).size === items.length,
+  "Usage item IDs must be unique.");
+export type UsageItem = z.infer<typeof usageItemSchema>;
+export type QuotaItem = Extract<UsageItem, { type: "quota" }>;
+export const providerUsageErrorSchema = z.enum(["unavailable", "credential", "authentication", "unsupported", "rate_limit", "network", "timeout", "protocol", "server"]);
+export type ProviderUsageError = z.infer<typeof providerUsageErrorSchema>;
+export const usageProviderInfoSchema = z.strictObject({ id: providerUsageIdSchema, label: uiTextSchema, owner: z.string(),
+  source: z.enum(["query", "headers"]).default("query") });
+export type UsageProviderInfo = z.infer<typeof usageProviderInfoSchema>;
+
+export function quotaRemaining(item: QuotaItem): number {
+  return item.value.type === "ratio" ? item.value.remaining : item.value.remaining / item.value.limit;
+}
+/** Select the window with the shortest period, independently of the reset countdown; unknown periods follow known ones, and equal lengths retain source order. */
+export function primaryQuota(items: readonly UsageItem[]): QuotaItem | null {
+  let selected: QuotaItem | null = null;
+  for (const item of items) if (item.type === "quota" && (!selected ||
+    (item.window.durationMs ?? Infinity) < (selected.window.durationMs ?? Infinity))) selected = item;
+  return selected;
+}

package/src/records.ts

@@ -0,0 +1,60 @@
+import type { z } from "zod";
+import type { Json } from "./json.ts";
+import type { Source } from "./workspace.ts";
+
+/** Public envelope for session records: the host maps its storage format to this envelope, and plugins decode by contract without depending on internal node structure. */
+export interface RecordRef { readonly id: string }
+export interface SessionRecord {
+  readonly id: string;
+  readonly sessionId: string;
+  readonly parentId: string | null;
+  /** Append order within the session, starting at 1. */
+  readonly sequence: number;
+  readonly createdAt: string;
+  readonly contract: RecordRef;
+  /** Writer; stamped by the host according to the write channel, while the associated object belongs in data. */
+  readonly source: Source;
+  /** Model-visible text written by the platform, consumed when executors project context; recipient being null means all executors. */
+  readonly context: { readonly text: string; readonly recipient: string | null } | null;
+  readonly data: Json;
+}
+export type Decoded<D> =
+  | { readonly status: "known"; readonly record: SessionRecord; readonly data: D }
+  | { readonly status: "unknown"; readonly record: SessionRecord; readonly reason: "invalid_data" };
+export interface RecordContract<D extends Json = Json> extends RecordRef {
+  /** Decodes persisted JSON into D; record writers encode D through the same schema. */
+  readonly schema: z.ZodType<D>;
+  /** Return null when the record does not belong to this contract; compatibility and transformations are determined by the schema, and failure preserves the raw record. */
+  decode(record: SessionRecord): Decoded<D> | null;
+}
+export function defineRecord<D extends Json>(id: string, definition: {
+  schema: z.ZodType<D>;
+}): RecordContract<D> {
+  const { schema } = definition;
+  return {
+    id, schema,
+    decode(record) {
+      if (record.contract.id !== id) return null;
+      const data = structuredClone(record.data);
+      try {
+        const parsed = schema.safeParse(data);
+        return parsed.success ? { status: "known", record, data: parsed.data } : { status: "unknown", record, reason: "invalid_data" };
+      } catch { return { status: "unknown", record, reason: "invalid_data" }; }
+    },
+  };
+}
+/** timeline reads the complete ancestor path to the snapshot tip; session reads all session records within the snapshot's upper bound in save order. */
+export interface RecordQuery { readonly scope: "timeline" | "session" }
+/** An observation handle fixed at one read position; reads records on demand and does not switch to the latest state after await. */
+export interface SessionView {
+  readonly id: string;
+  readonly title: string;
+  readonly records: {
+    all(query: RecordQuery): readonly SessionRecord[];
+    /** The earliest matching record; returns unknown if it cannot be decoded, without skipping it. */
+    first<D extends Json>(contract: RecordContract<D>, query: RecordQuery): Decoded<D> | null;
+    /** The latest matching record, located by scope and contract; decodes only that record and returns unknown if undecodable, without falling back. */
+    last<D extends Json>(contract: RecordContract<D>, query: RecordQuery): Decoded<D> | null;
+    query<D extends Json>(contract: RecordContract<D>, query: RecordQuery): Decoded<D>[];
+  };
+}

package/src/renderer-calls.ts

@@ -0,0 +1,11 @@
+import { createContext, useContext } from "react";
+import type { PluginCalls } from "./calls.ts";
+
+const Calls = createContext<PluginCalls | null>(null);
+export const RendererCallsProvider = Calls.Provider;
+/** Invoke a registered backend contract; associating an object does not change resource ownership. */
+export function useRendererCalls(): PluginCalls {
+  const calls = useContext(Calls);
+  if (!calls) throw new Error("Renderer calls must be provided by the host.");
+  return calls;
+}

package/src/renderer-card.ts

@@ -0,0 +1,29 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import type { UiText } from "./i18n.ts";
+
+/** Auxiliary panel identities are unique within a single card renderer; content receives the same validated projection as the body. */
+export interface CardPanelDefinition<T> {
+  id: string;
+  label: UiText;
+  icon: ReactNode;
+  Body: ComponentType<{ data: T }>;
+}
+export interface CardPanelView {
+  id: string;
+  label: UiText;
+  icon: ReactNode;
+  body: ReactNode;
+}
+/** Local card view operations; do not submit resource commands or write task history. */
+export interface RendererCard {
+  readonly activePanel: string | null;
+  openPanel(id: string): void;
+  closePanel(): void;
+}
+const CardContext = createContext<RendererCard | null>(null);
+export const RendererCardProvider = CardContext.Provider;
+export function useRendererCard(): RendererCard {
+  const card = useContext(CardContext);
+  if (!card) throw new Error("The renderer must be bound to a card.");
+  return card;
+}