@asterism-app/sdk 0.0.0-stage → 1.0.0

package/src/model-catalog.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { defineData } from "./presentation.ts";
+import { modelCostSchema } from "./model-cost.ts";
+import { thinkingSchema } from "./model-selection.ts";
+
+export const catalogModelSchema = z.object({
+  providerId: z.string(), modelId: z.string(), name: z.string(), enabled: z.boolean(),
+  contextWindow: z.number().nullable(), cost: modelCostSchema.nullable(),
+  generation: z.object({ maxOutputTokens: z.number().nullable() }),
+  capabilities: z.object({ reasoning: z.boolean(), tools: z.boolean(), thinkingLevels: z.array(thinkingSchema) }),
+});
+/** Configured model metadata for plugin selectors and diagnostics; credentials remain backend capabilities. */
+export const ModelCatalog = defineData("asterism.models/catalog", z.object({
+  modelProviders: z.array(z.object({ id: z.string(), name: z.string(), enabled: z.boolean() })),
+  models: z.array(catalogModelSchema),
+}));
+export type ModelCatalogSnapshot = z.infer<typeof ModelCatalog.schema>;
+export type CatalogModel = z.infer<typeof catalogModelSchema>;

package/src/model-cost-estimate.ts

@@ -0,0 +1,49 @@
+import type { ModelCost, ModelRates, ModalityRates, UnitPrice } from "./model-cost.ts";
+
+/** Quantities already split by billing category; callers are responsible for preventing overlap between totals and subcategories. */
+export interface CostQuantity {
+  modality: keyof ModelRates;
+  item: keyof ModalityRates;
+  quantity: number | null;
+  unit: UnitPrice["unit"];
+}
+export type CostIssue = "quantity" | "price" | "unit" | "tier" | "invalid";
+export interface CostLine extends CostQuantity { price: UnitPrice | null; amount: number | null; issue: CostIssue | null }
+export interface CostEstimate {
+  status: "complete" | "partial" | "unknown";
+  amount: number | null;
+  fromInputTokens: number | null;
+  lines: CostLine[];
+}
+export function selectModelRates(cost: ModelCost | null, inputTokens: number | null): { rates: ModelRates | null; fromInputTokens: number | null; unknownTier: boolean } {
+  if (!cost) return { rates: null, fromInputTokens: null, unknownTier: false };
+  if (cost.tiers.length && inputTokens === null) return { rates: null, fromInputTokens: null, unknownTier: true };
+  const tier = cost.tiers.findLast(tier => inputTokens !== null && inputTokens >= tier.fromInputTokens);
+  return { rates: tier?.rates ?? cost.rates, fromInputTokens: tier?.fromInputTokens ?? null, unknownTier: false };
+}
+/** Consumes only prices and named quantities, without modifying upstream usage or maintaining a historical ledger. */
+export function estimateModelCost(cost: ModelCost | null, inputTokens: number | null, quantities: readonly CostQuantity[]): CostEstimate {
+  const selected = selectModelRates(cost, inputTokens);
+  const lines = quantities.map((quantity): CostLine => {
+    const price = selected.rates?.[quantity.modality][quantity.item] ?? null;
+    const missing = (issue: CostIssue): CostLine => ({ ...quantity, price, amount: null, issue });
+    if (quantity.quantity === null) return missing("quantity");
+    if (!Number.isFinite(quantity.quantity) || quantity.quantity < 0) return missing("invalid");
+    if (selected.unknownTier) return missing("tier");
+    if (price && price.unit !== quantity.unit) return missing("unit");
+    // A known zero quantity in the same unit needs no price; zero tokens cannot represent zero seconds or zero images.
+    if (quantity.quantity === 0) return { ...quantity, price, amount: 0, issue: null };
+    if (!price) return missing("price");
+    const amount = quantity.quantity / price.per * price.amount;
+    return Number.isFinite(amount) ? { ...quantity, price, amount, issue: null } : missing("invalid");
+  });
+  const complete = lines.length > 0 && lines.every(line => line.issue === null);
+  const hasAmount = complete || lines.some(line => line.quantity !== null && line.quantity > 0 && line.amount !== null);
+  const amount = hasAmount ? lines.reduce((sum, line) => sum + (line.amount ?? 0), 0) : null;
+  return { status: complete ? "complete" : hasAmount ? "partial" : "unknown", amount, fromInputTokens: selected.fromInputTokens, lines };
+}
+export function totalEstimatedCost(estimates: readonly CostEstimate[]): { amount: number | null; incomplete: number } {
+  const known = estimates.filter(estimate => estimate.amount !== null);
+  return { amount: known.length ? known.reduce((sum, estimate) => sum + estimate.amount!, 0) : null,
+    incomplete: estimates.filter(estimate => estimate.status !== "complete").length };
+}

package/src/model-cost.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+
+export const priceUnits = ["token", "image", "second"] as const;
+/** Amounts use the price table's common currency; amount is the price per per units of unit, and 0 means free. */
+export const unitPriceSchema = z.strictObject({
+  amount: z.number().nonnegative(),
+  unit: z.enum(priceUnits),
+  per: z.number().positive(),
+});
+export type UnitPrice = z.infer<typeof unitPriceSchema>;
+
+/** Billing items within a modality can use different units; missing items and null both mean unknown. */
+const itemPrice = unitPriceSchema.nullable().default(null);
+export const modalityRatesSchema = z.strictObject({
+  input: itemPrice, output: itemPrice, cacheRead: itemPrice, cacheWrite: itemPrice, reasoning: itemPrice,
+});
+export type ModalityRates = z.infer<typeof modalityRatesSchema>;
+export const emptyModalityRates = (): ModalityRates => ({ input: null, output: null, cacheRead: null, cacheWrite: null, reasoning: null });
+export const modelRatesSchema = z.strictObject({
+  text: modalityRatesSchema.default(emptyModalityRates),
+  image: modalityRatesSchema.default(emptyModalityRates),
+  audio: modalityRatesSchema.default(emptyModalityRates),
+  video: modalityRatesSchema.default(emptyModalityRates),
+});
+export type ModelRates = z.infer<typeof modelRatesSchema>;
+export const emptyModelRates = (): ModelRates => ({
+  text: emptyModalityRates(), image: emptyModalityRates(), audio: emptyModalityRates(), video: emptyModalityRates(),
+});
+
+/** Select a tier using the entire request's total input tokens; reaching a threshold applies all prices in that tier, without progressive pricing across tiers. */
+export const modelCostSchema = z.strictObject({
+  currency: z.literal("USD"),
+  rates: modelRatesSchema,
+  tiers: z.array(z.strictObject({
+    fromInputTokens: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    rates: modelRatesSchema,
+  })),
+}).superRefine((cost, context) => {
+  cost.tiers.forEach((tier, index) => {
+    if (index > 0 && tier.fromInputTokens <= cost.tiers[index - 1]!.fromInputTokens)
+      context.addIssue({ code: "custom", path: ["tiers", index, "fromInputTokens"], message: "Price thresholds must be strictly increasing." });
+  });
+});
+export type ModelCost = z.infer<typeof modelCostSchema>;

package/src/model-input.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { contentRefSchema } from "./content.ts";
+
+/** mediaType is the MIME type truthfully identified by the client and sent with the bytes; the client does not infer model capabilities from it, and acceptance is determined by server feedback. */
+export const mediaTypeSchema = z.string().regex(/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/);
+
+/** Model input contains only text and files; files store immutable content identity and consumption metadata, while bytes and read eligibility stay outside messages. */
+export const modelInputPartSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("text"), text: z.string() }),
+  z.strictObject({ kind: z.literal("file"), file: contentRefSchema,
+    mediaType: mediaTypeSchema, filename: z.string().min(1).max(255).optional() }),
+]);
+export type ModelInputPart = z.infer<typeof modelInputPartSchema>;
+export type ModelFilePart = Extract<ModelInputPart, { kind: "file" }>;
+export const modelInputPartsSchema = z.array(modelInputPartSchema).min(1);
+/** Plain-text consumers explicitly extract the body without implicitly reading files. */
+export function modelInputText(parts: readonly (Extract<ModelInputPart, { kind: "text" }> | { kind: "file" })[]): string {
+  return parts.flatMap(part => part.kind === "text" ? [part.text] : []).join("\n");
+}

package/src/model-media.ts

@@ -0,0 +1,11 @@
+/** When the browser supplies no type, infer common MIME types from the extension; mark as binary when still unrecognized. */
+const extensionTypes: Readonly<Record<string, string>> = {
+  jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp", pdf: "application/pdf",
+};
+export function fileMediaType(file: { type: string; name: string }): string {
+  return file.type || extensionTypes[file.name.split(".").at(-1)?.toLowerCase() ?? ""] || "application/octet-stream";
+}
+/** A derived classification for UI display, not a model capability. */
+export const previewsAsImage = (mediaType: string) => mediaType.startsWith("image/");
+/** Client resource limits: per-file size, count, and total size leave room for protocol envelopes and base64. */
+export const modelInputLimits = { file: 5 * 1024 * 1024, files: 20, total: 20 * 1024 * 1024 } as const;

package/src/model-provider.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { uiTextSchema, type UiText } from "./i18n.ts";
+import { jsonSchema, type Json } from "./json.ts";
+import { providerUsageIdSchema } from "./provider-usage.ts";
+
+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> } };

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,134 @@
+/** 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 { provider: string; model: string; thinking?: ThinkingLevel }
+export interface PromptBlock { id: string; text: string; source?: { id: string; plugin: string | null } }
+export interface PromptFile { readonly file: string; readonly 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 | ((files: readonly PromptFile[]) => 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>;
+  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, Presentation } 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;
+  /** Append a host title assignment atomically, with optional plugin-owned detail. */
+  readonly title: SessionReader["title"] & { set(text: string, detail?: Presentation): 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.host/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) };
+}