@asterism-app/sdk 0.0.0-stage → 0.47.0

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": "0.47.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,27 @@
+import type { z } from "zod";
+import type { Json } from "./json.ts";
+import { contractReferenceSchema } from "./presentation.ts";
+import type { ResourceRef } from "./workspace.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> = { signal?: AbortSignal } &
+  (S extends "object" ? { object: ResourceRef } : { object?: never });
+export interface PluginCalls {
+  /** 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>>,
+  ): 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,29 @@
+/** 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-cost.ts";
+export * from "./model-cost-estimate.ts";
+export * from "./model-media.ts";
+export * from "./provider-usage.ts";
+export * from "./web.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/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;