@asterism-app/sdk 0.0.0-stage → 1.0.0

package/examples/content-renderer.ts

@@ -0,0 +1,26 @@
+import { creationEntry, type RendererObjectContext } from "@asterism-app/sdk/renderer";
+import { CreateDocument, ReplaceDocument } from "./content-contract.ts";
+
+/** This entry point accepts dropped files (with or without local paths) and clipboard images on the workbench. */
+export const importDocument = creationEntry(CreateDocument, {
+  id: "example.content/import", label: "Import document",
+  triggers: { drop: {
+    accepts: { files: {} },
+    async toInput(item, content) {
+      if (item.kind !== "file" || item.directory) return null;
+      return { file: await content.stage(item.file), name: item.name };
+    },
+  } },
+});
+
+/** The host closes the draft after a successful command; failure preserves it for retry, and abandoning it calls close. */
+export function replacementInput(object: RendererObjectContext) {
+  const draft = object.input(ReplaceDocument);
+  return {
+    async submit(file: File) {
+      const ref = await draft.stage(file);
+      return object.invoke(ReplaceDocument, { file: ref, name: file.name }, { content: draft });
+    },
+    cancel: () => draft.close(),
+  };
+}

package/examples/counter/docs/usage.md

@@ -0,0 +1,9 @@
+# Use the counter plugin
+
+The counter plugin adds a resource that stores an integer, a card for incrementing it, and a read operation for agents. It also has a settings page for choosing the increment step.
+
+Create a Counter from the workbench creation menu. Its initial value is zero. Use Increment on the card to add the configured step. In plugin settings, change the step or read it back from the backend.
+
+Link the counter resource to an agent to make its read operation available under that agent's tool policy. The operation reports the current value.
+
+Incrementing saves the current value and records the change in history. Browsing an earlier history position does not restore the counter value. Removing the resource removes its current workbench presence while preserving its history.

package/examples/counter/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "asterism-example-counter",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": { "typecheck": "tsc --noEmit" },
+  "peerDependencies": {
+    "@asterism-app/sdk": "*",
+    "react": "^19.3.0",
+    "react-intl": "^12.1.4",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@asterism-app/sdk": "0.48.0",
+    "typescript": "^7.0.2",
+    "@types/node": "^26.6.1",
+    "@types/react": "^19.3.0"
+  },
+  "asterism": {
+    "id": "example.counter",
+    "displayName": "Example counter",
+    "runtime": "src/runtime.ts",
+    "renderer": "src/renderer.tsx",
+    "storage": "src/storage.ts",
+    "manual": ["docs"]
+  }
+}

package/examples/counter/src/contracts.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import {
+  pluginNamespace, defineCreation, defineAction, defineCall,
+  defineRecord, defineTool, defineImplementation,
+} from "@asterism-app/sdk/contracts";
+
+export const ns = pluginNamespace("example.counter");
+export const card = { width: 280, height: 180 };
+export const Counter = ns.resource("counter", z.strictObject({}));
+export const Value = ns.data("value", z.number());
+export const View = ns.data("view", z.number());
+export const Changed = defineRecord(ns.name("changed"), { schema: z.number() });
+export const Create = defineCreation(Counter, { id: ns.name("create"), schema: z.null() });
+export const Increment = defineAction(Counter, { id: ns.name("increment"), schema: z.null() });
+export const Settings = ns.config(
+  z.strictObject({ step: z.number().int().min(1).max(10) }), { step: 1 },
+);
+export const ReadStep = defineCall(ns.name("read-step"), {
+  scope: "plugin", input: z.null(), output: z.number(),
+});
+export const StartSession = defineCall(ns.name("start-session"), {
+  scope: "plugin", input: z.strictObject({ key: z.string().min(1) }), output: z.string(),
+});
+const Read = defineTool({
+  id: ns.name("read-counter"), name: "read_counter",
+  description: "Read the current value of a counter.", guidelines: [],
+  argsSchema: z.null().describe("No arguments."),
+});
+export const ReadCounter = defineImplementation({
+  ...ns.data("read-result", z.number().describe("The current counter value.")),
+  resource: Counter, tool: Read,
+  targetSchema: z.null().describe("The whole counter."),
+  effect: "read", execution: "parallel",
+});

package/examples/counter/src/panel.module.css

@@ -0,0 +1,2 @@
+.panel { display: grid; gap: 8px; padding: 12px; color: var(--foreground); }
+.panel button { font: inherit; }

package/examples/counter/src/renderer.tsx

@@ -0,0 +1,80 @@
+import { useRef, useState } from "react";
+import {
+  defineRendererPlugin, cardRenderer, creationEntry, toolRenderer,
+  useRendererObject, useRendererConfiguration, useRendererCalls, useI18n, type SessionEntryProps,
+} from "@asterism-app/sdk/renderer";
+import { ns, card, Counter, View, Create, Increment, Settings, ReadStep, ReadCounter, StartSession } from "./contracts.ts";
+import styles from "./panel.module.css";
+
+function Operation({ label, disabled = false, run }: {
+  label: string; disabled?: boolean; run(): Promise<void>;
+}) {
+  const pending = useRef(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  return <div>
+    <button disabled={disabled || busy} onClick={() => {
+      if (pending.current) return;
+      pending.current = true; setBusy(true); setError("");
+      void run().catch(error => setError(String(error))).finally(() => {
+        pending.current = false; setBusy(false);
+      });
+    }}>{label}</button>
+    {error && <p role="alert">{error}</p>}
+  </div>;
+}
+
+function CounterBody({ data }: { data: number }) {
+  const object = useRendererObject();
+  const i18n = useI18n();
+  return <div className={styles.panel}>
+    <output>{data}</output>
+    <Operation label="Increment" disabled={!object.view.ready} run={async () => {
+      const receipt = await object.invoke(Increment, null);
+      if (!receipt.ok) throw new Error(i18n.text(receipt.error.display ?? receipt.error.message));
+    }} />
+  </div>;
+}
+
+function SettingsPage() {
+  const settings = useRendererConfiguration(Settings);
+  const calls = useRendererCalls();
+  const i18n = useI18n();
+  const [reported, setReported] = useState<number | null>(null);
+  return <div className={styles.panel}>
+    <p>Step: {settings.value.step}</p>
+    {settings.error && <p role="alert">{i18n.text(settings.error)}</p>}
+    <Operation label="Toggle step between 1 and 2" disabled={!settings.ready}
+      run={() => settings.save({ step: settings.value.step === 1 ? 2 : 1 })} />
+    <Operation label="Read step from backend"
+      run={async () => { setReported(await calls.invoke(ReadStep, null, {})); }} />
+    <output>{reported}</output>
+  </div>;
+}
+
+function CounterEntry({ ready, open }: SessionEntryProps) {
+  const calls = useRendererCalls(), retryKey = useRef<string | null>(null);
+  return <Operation label="Start a counter workspace" disabled={!ready} run={async () => {
+    retryKey.current ??= crypto.randomUUID();
+    const sessionId = await calls.invoke(StartSession, { key: retryKey.current }, {});
+    retryKey.current = null;
+    open(sessionId);
+  }} />;
+}
+
+export default defineRendererPlugin({
+  sessionEntries: [{ id: "counter", title: "Counter workspace", Body: CounterEntry }],
+  settings: [{ id: "counter", title: "Counter", summary: "Configure the counter step.", Body: SettingsPage }],
+  modules: [{
+    resources: [{ kind: Counter.kind, label: "Counter", icon: null, card }],
+    creations: [creationEntry(Create, {
+      id: ns.name("create-menu"), label: "Counter",
+      triggers: { menu: { initialInput: null } },
+    })],
+    cards: [cardRenderer(View, { ...card, Body: CounterBody })],
+    tools: [toolRenderer(ReadCounter, {
+      label: "Read counter",
+      result: { bodyRenderer: ({ result }) => <output>{result.data ?? "—"}</output> },
+    })],
+  }],
+});

package/examples/counter/src/runtime.ts

@@ -0,0 +1,49 @@
+import {
+  definePlugin, implementResource, implementCreation,
+  implementAction, implementTool, implementCall, type ObjectReader,
+} from "@asterism-app/sdk/runtime";
+import {
+  ns, card, Counter, Value, View, Changed, Create, Increment,
+  Settings, ReadStep, ReadCounter, StartSession,
+} from "./contracts.ts";
+
+const current = (object: ObjectReader) => object.get(Value) ?? 0;
+
+export default definePlugin({
+  namespace: ns,
+  setup(plugin) {
+    const settings = plugin.config(Settings);
+    return {
+      calls: [
+        implementCall(ReadStep, async () => settings.get().step),
+        implementCall(StartSession, async ({ key }, { signal }) => plugin.createSession(key, async preparation => {
+          const counter = await preparation.prepare(Create, null);
+          return { title: "Counter workspace", initialize(session) { session.create(counter); } };
+        }, { signal })),
+      ],
+      resources: [implementResource(Counter, View, {
+        card, records: [Changed],
+        template: { current: [Value] },
+        creation: implementCreation(Create, {
+          create: () => ({ title: "Counter", data: {} }),
+        }),
+        actions: [implementAction(Increment, {
+          async execute(_input, object) {
+            object.commit(writer => {
+              const next = current(object) + settings.get().step;
+              writer.set(Value, next);
+              writer.append(Changed, next);
+            });
+          },
+        })],
+        project: (_data, object) => current(object),
+        inspect: async (_data, object) => current(object),
+      })],
+      tools: [implementTool(ReadCounter, {
+        async call(_data, _target, _args, { object }) {
+          return { kind: "succeeded", data: current(object) };
+        },
+      })],
+    };
+  },
+});

package/examples/counter/src/storage.ts

@@ -0,0 +1,4 @@
+import { defineStorage } from "@asterism-app/sdk/runtime";
+export default defineStorage([
+  { kind: "json", path: ".asterism/config.json", version: 1, migrations: {} },
+]);

package/examples/counter/src/styles.d.ts

@@ -0,0 +1,4 @@
+declare module "*.module.css" {
+  const classes: Record<string, string>;
+  export default classes;
+}

package/examples/counter/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2023", "DOM", "ESNext.Disposable"],
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/examples/counter-contract.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { pluginNamespace, defineCreation, defineAction, defineRecord, defineChannel } from "@asterism-app/sdk/contracts";
+
+export const sample = pluginNamespace("example.counter");
+export const Counter = sample.resource("counter", z.strictObject({}));
+/** Shared by frontend and backend for creation placeholders and actual cards. */
+export const counterCard = { width: 300, height: 200 };
+export const Count = sample.data("count", z.strictObject({ value: z.number().int() }));
+export const CounterView = sample.data("card", Count.schema);
+export const CountChanged = defineRecord(sample.name("count-changed"), {
+  schema: Count.schema,
+});
+const createInput = z.strictObject({ title: z.string().trim().min(1).default("Counter") });
+const actionInput = z.strictObject({ amount: z.number().int() });
+export const CreateCounter = defineCreation(Counter, { id: sample.name("create"), schema: createInput });
+export const ChangeCount = defineAction(Counter, { id: sample.name("change"), schema: actionInput });
+/** Object-level duplex channel: the frontend requests live updates, and the backend sends current values per object; does not enter the timeline. */
+export const CounterUpdates = defineChannel<{ type: "subscribe" }, { value: number }>(sample.name("updates"));

package/examples/data-codecs.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { pluginNamespace, defineRecord, present } from "@asterism-app/sdk/contracts";
+import type { ObjectExecutor } from "@asterism-app/sdk/runtime";
+
+const ns = pluginNamespace("example.codec");
+const current = z.strictObject({ text: z.string() });
+/** Read older strings or current objects; write current objects while retaining immutable historical payloads. */
+const textSchema = z.codec(z.union([z.string(), current]), current, {
+  decode: value => typeof value === "string" ? { text: value } : value,
+  encode: value => value,
+});
+export const Text = ns.data("text", textSchema);
+export const TextChanged = defineRecord(ns.name("text-changed"), { schema: textSchema });
+export function saveText(object: ObjectExecutor, text: string) {
+  const value = { text };
+  object.commit(writer => { writer.set(Text, value); writer.append(TextChanged, value); });
+  return present(Text, value);
+}

package/examples/events.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { pluginNamespace, ResourceStatusChanged } from "@asterism-app/sdk/contracts";
+import { defineModule, type ObjectExecutor } from "@asterism-app/sdk/runtime";
+import type { RendererModule } from "@asterism-app/sdk/renderer";
+
+const ns = pluginNamespace("example.downloads");
+export const Progress = ns.event("progress", {
+  schema: z.strictObject({ job: z.string(), completed: z.number(), total: z.number() }),
+  source: "resource",
+  semantics: { kind: "snapshot", key: ["job"] },
+});
+export const backend = defineModule(plugin => {
+  plugin.ipc.events.subscribe(Progress, { delivery: "latest" }, event => {
+    const completed: number = event.data.completed;
+    plugin.log.info(`Downloaded ${completed} bytes from ${event.source?.resource?.id}.`);
+  });
+  return { events: [Progress] };
+});
+export function report(object: ObjectExecutor): void {
+  object.events.publish(Progress, { job: "file", completed: 10, total: 100 });
+}
+/** Public status is registered by the host; plugins publish through their own resource handles. */
+export function reportStatus(object: ObjectExecutor): void {
+  object.events.publish(ResourceStatusChanged, { title: "Download", status: "running" });
+  object.events.publish(ResourceStatusChanged, { title: "Download", status: "running", progress: { value: 0.6 } });
+  object.events.publish(ResourceStatusChanged, { title: "Download", status: "completed" });
+}
+export const renderer: RendererModule = {
+  resources: [], cards: [], tools: [],
+  async prepare({ events }) {
+    const subscription = events.subscribe(Progress, { delivery: "latest" }, event => {
+      const job: string = event.data.job;
+      void job;
+    });
+    await subscription.ready;
+  },
+};

package/examples/i18n.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { defineMessages, pluginNamespace, withValues, type UiText } from "@asterism-app/sdk/contracts";
+import type { PluginContext } from "@asterism-app/sdk/runtime";
+export const namespace = pluginNamespace("example.counter");
+/** Public exports retain their source; ordinary strings require no catalog or initialization. */
+export const messages = namespace.messages("en", defineMessages({
+  title: { id: "counter.title", defaultMessage: "Counter" },
+  items: { id: "counter.items", defaultMessage: "{count, plural, one {# item} other {# items}}", description: "Number of items in the counter" },
+  limit: { id: "counter.limit", defaultMessage: "Limit" },
+  exceeded: { id: "counter.exceeded", defaultMessage: "The limit is {limit, number}." },
+}));
+export const plainLabel: UiText = "Counter";
+export const summary = withValues(messages.items, { count: 3 });
+/** Configuration is independent of page layout; the page formats the messages above through useI18n. */
+export const CounterConfig = namespace.config(z.object({ limit: z.number().int().positive() }), { limit: 20 });
+export function configure(plugin: PluginContext) {
+  return plugin.config(CounterConfig);
+}

package/examples/model-completion.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { pluginNamespace, present, completionData, type ModelCompletion, type ModelRunRequest } from "@asterism-app/sdk/contracts";
+
+const ns = pluginNamespace("example.agent");
+const RequestTools = ns.data("request-tools", z.object({ names: z.array(z.string()) }));
+
+/** Producers declare domain data; the public model service carries only typed envelopes. */
+export const completionExtensions: NonNullable<ModelRunRequest["completionExtensions"]> = context => [
+  present(RequestTools, { names: context.tools.map(tool => tool.name) }),
+];
+
+/** Consumers explicitly import the same contract; missing or unknown extensions do not affect public usage data. */
+export function inspectCompletion(completion: ModelCompletion) {
+  return { usage: completion.usage, tools: completionData(completion, RequestTools)?.names ?? null };
+}

package/examples/model-input.ts

@@ -0,0 +1,16 @@
+import type { ModelItem } from "@asterism-app/sdk/contracts";
+import type { ContentScope, ModelServices } from "@asterism-app/sdk/runtime";
+
+/** content is already available during preparation; files need not become objects or history records before use in a one-off completion. */
+export async function describeFile(models: ModelServices, content: ContentScope, bytes: Uint8Array, signal: AbortSignal) {
+  const file = await content.stage(bytes);
+  const messages: ModelItem[] = [{ kind: "input", parts: [
+    { kind: "text", text: "Describe the image." },
+    { kind: "file", file, mediaType: "image/png", filename: "screenshot.png" },
+  ] }];
+  const request = { target: { provider: "configured-provider", model: "configured-model" }, system: { blocks: [] }, messages, signal };
+  await models.validate(request, { content });
+  for await (const event of models.stream(request, { content })) {
+    if (event.type === "part.delta") void event.delta;
+  }
+}

package/examples/plugin-calls.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { defineCall, pluginNamespace } from "@asterism-app/sdk/contracts";
+import { defineModule, defineTopLevelTool, implementCall } from "@asterism-app/sdk/runtime";
+
+const ns = pluginNamespace("example.interaction");
+export const ReadState = defineCall(ns.name("read"), { scope: "object", input: z.null(), output: z.string() });
+export const module = defineModule(() => {
+  // Share business state within the process; the frontend reads through typed calls without importing backend instances.
+  const values = new Map<string, string>();
+  return {
+    calls: [implementCall(ReadState, async (_input, { object }) => values.get(object.ref.id) ?? "")],
+    topLevelTools: [defineTopLevelTool({
+      id: ns.name("remember"), name: "remember", description: "Remember a short note for this agent.", guidelines: [],
+      argsSchema: z.strictObject({ text: z.string() }).describe("The note to remember."),
+      resultSchema: z.string().describe("The saved note."), effect: "write", execution: "sequential",
+      async execute({ text }, { object }) {
+        values.set(object.ref.id, text);
+        return { kind: "succeeded", data: text };
+      },
+    })],
+  };
+});

package/examples/provider-usage-headers.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { pluginNamespace, type UsageItem } from "@asterism-app/sdk/contracts";
+import { definePlugin, UsageQueryError, type HeadersUsageProvider } from "@asterism-app/sdk/runtime";
+
+const ns = pluginNamespace("example.header-usage");
+const balance = z.coerce.number();
+const currency = z.string().regex(/^[A-Z]{3}$/u);
+/** The example gateway puts account balances in inference response headers; the source and balance/quota result types are independent. */
+const usage: HeadersUsageProvider = {
+  id: "example-header-balance", label: "Example gateway balance", source: "headers",
+  parseHeaders({ headers }) {
+    const amount = headers["x-account-balance"], unit = headers["x-account-currency"];
+    if (amount === undefined || unit === undefined) return null;
+    const value = balance.safeParse(amount), code = currency.safeParse(unit);
+    if (!amount.trim() || !value.success || !code.success) throw new UsageQueryError("protocol");
+    return [{ id: "wallet", type: "balance", scope: "account", label: "Account balance",
+      remaining: value.data, currency: code.data }] satisfies UsageItem[];
+  },
+};
+export default definePlugin({ namespace: ns, setup: () => ({ usageProviders: [usage] }) });

package/examples/provider-usage.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { pluginNamespace, type ModelProviderPreset, type UsageItem } from "@asterism-app/sdk/contracts";
+import { definePlugin, UsageQueryError, type UsageProvider } from "@asterism-app/sdk/runtime";
+
+const ns = pluginNamespace("example.allowance");
+// Example site contract: GET /account/allowance returns the balance and remaining fraction of a five-hour window; the provider handles protocol parsing.
+const response = z.object({ balance: z.number(), currency: z.string().regex(/^[A-Z]{3}$/u), remainingRatio: z.number().min(0).max(1), resetAt: z.number() });
+const usage: UsageProvider = {
+  id: "example-plan", label: "Example plan",
+  async query({ connection, credential, signal }) {
+    if (!credential) throw new UsageQueryError("credential");
+    const result = await fetch(new URL("/account/allowance", connection.endpoint), {
+      headers: { Authorization: `Bearer ${credential}` }, signal, redirect: "error",
+    });
+    if (!result.ok) throw new UsageQueryError(result.status === 401 ? "authentication" : "server");
+    const parsed = response.safeParse(await result.json());
+    if (!parsed.success) throw new UsageQueryError("protocol");
+    const value = parsed.data;
+    return [
+      { id: "wallet", type: "balance", scope: "account", label: "Balance", remaining: value.balance, currency: value.currency },
+      { id: "five-hours", type: "quota", scope: "plan", label: "5h", value: { type: "ratio", remaining: value.remainingRatio },
+        window: { mode: "rolling", durationMs: 18_000_000, resetAt: value.resetAt } },
+    ] satisfies UsageItem[];
+  },
+};
+const preset: ModelProviderPreset = {
+  id: "example-plan", name: "Example plan", billing: "subscription",
+  connection: { protocol: "openai-responses", baseUrl: "https://example.invalid/v1", auth: "api_key", compatibility: [],
+    usage: usage.id, fixedFields: ["protocol", "baseUrl", "auth", "compatibility", "usage"] },
+  sources: ["https://example.invalid/docs"], verifiedOn: "2026-10-20",
+};
+export default definePlugin({ namespace: ns, setup: () => ({
+  usageProviders: [usage], modelProviderPresets: [{ type: "add", preset }],
+}) });

package/examples/renderer.ts

@@ -0,0 +1,47 @@
+import { Counter, CounterView as Card, CreateCounter, ChangeCount, CounterUpdates, counterCard } from "./counter-contract.ts";
+/** Frontend author example: depends only on React, Zod, and the public SDK, without accessing window.host. */
+import { createElement, useEffect, useState } from "react";
+import { z } from "zod";
+import { defineRendererPlugin, cardRenderer, useRendererCard, useRendererObject, type RendererModule, type RendererObjectContext } from "@asterism-app/sdk/renderer";
+
+function CounterBody({ data }: { data: z.infer<typeof Card.schema> }) {
+  const { openChannel, invoke, view, session } = useRendererObject();
+  const [pending, setPending] = useState(false);
+  const card = useRendererCard();
+  const [live, setLive] = useState<number | null>(null);
+  useEffect(() => {
+    const channel = openChannel(CounterUpdates);
+    channel.onMessage(update => setLive(update.value));
+    channel.send({ type: "subscribe" });
+    return () => channel.close();
+  }, [openChannel]);
+  return createElement("div", null, createElement("button", {
+    disabled: !view.ready || pending,
+    onClick: () => {
+      setPending(true);
+      void invoke(ChangeCount, { amount: 1 }).finally(() => setPending(false));
+    },
+  }, `${data.value} · live ${live ?? "-"} · ${session.snapshot()?.records.all({ scope: "timeline" }).length ?? 0} records`),
+  createElement("button", { onClick: () => card.openPanel("details") }, "Details"));
+}
+function CounterDetails({ data }: { data: z.infer<typeof Card.schema> }) {
+  const card = useRendererCard();
+  return createElement("div", null, `Count: ${data.value}`,
+    createElement("button", { onClick: card.closePanel }, "Close"));
+}
+export const renderer = {
+  resources: [{ kind: Counter.kind, label: "Counter", icon: null, card: counterCard }],
+  cards: [cardRenderer(Card, { ...counterCard, Body: CounterBody,
+    panels: [{ id: "details", label: "Details", icon: null, Body: CounterDetails }] })],
+  tools: [],
+} satisfies RendererModule;
+export default defineRendererPlugin({ modules: [renderer] });
+
+export function createCounter(object: RendererObjectContext) {
+  return object.session.create(CreateCounter, {}, { x: 0, y: 0 });
+}
+
+/** Frontend state retained per object: survives remounts and session switches; the host calls release when the object leaves the projection. */
+export function counterNote(object: RendererObjectContext) {
+  return object.retained.get("example.counter/note", () => ({ text: "" }), note => { note.text = ""; });
+}

package/examples/session-resources.ts

@@ -0,0 +1,29 @@
+import type { PluginContext, ResourceRef, ObjectReader } from "@asterism-app/sdk/runtime";
+import { CreateCounter, ChangeCount } from "./counter-contract.ts";
+
+/** Callers provide public creation input, and resource providers handle initialization; the return value contains only identity. */
+export async function createCounter(plugin: PluginContext, sessionId: string, receiver: ResourceRef, signal: AbortSignal) {
+  const session = plugin.session(sessionId);
+  const resource = await session.create(CreateCounter, { title: "Counter" }, { signal, linkTo: receiver });
+  return resource;
+}
+
+/** References must belong to the bound session; removing a busy object fails explicitly without implicit cancellation. */
+export function removeCounter(plugin: PluginContext, resource: ResourceRef) {
+  plugin.session(resource.sessionId).remove(resource);
+}
+
+/** Enumerating summaries neither switches the current view nor loads history. */
+export function sessions(plugin: PluginContext) {
+  return plugin.sessions.list();
+}
+
+/** Read a fresh snapshot for each external event to follow the receiver's current direct links. */
+export function linkedResources(object: ObjectReader) {
+  return object.session.snapshot().resources.linkedTo(object.ref);
+}
+
+/** Public actions are executed by the target resource; callers do not receive its private state or commit facade. */
+export async function changeCounter(plugin: PluginContext, resource: ResourceRef, amount: number, signal: AbortSignal) {
+  await plugin.session(resource.sessionId).invoke(ChangeCount, resource, { amount }, { signal });
+}

package/examples/settings-contract.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { defineCall, pluginNamespace } from "@asterism-app/sdk/contracts";
+
+export const settingsPlugin = pluginNamespace("example.settings");
+export const Settings = settingsPlugin.config(z.object({ label: z.string().min(1) }), { label: "Example" });
+export const ReadLabel = defineCall(settingsPlugin.name("read-label"), {
+  scope: "plugin", input: z.null(), output: z.string(),
+});

package/examples/settings-renderer.ts

@@ -0,0 +1,30 @@
+import { createElement, useState } from "react";
+import { defineRendererPlugin, useRendererCalls, useRendererConfiguration, useRendererSettings } from "@asterism-app/sdk/renderer";
+import { ReadLabel, Settings, settingsPlugin } from "./settings-contract.ts";
+
+function SettingsPage() {
+  const settings = useRendererConfiguration(Settings);
+  const calls = useRendererCalls();
+  const [label, setLabel] = useState("");
+  const [error, setError] = useState("");
+  const [busy, setBusy] = useState(false);
+  const run = async (work: () => Promise<void>) => {
+    setBusy(true);
+    try { await work(); setError(""); }
+    catch (error) { setError(String(error)); }
+    finally { setBusy(false); }
+  };
+  return createElement("div", null,
+    createElement("p", null, settings.value.label),
+    createElement("button", { disabled: !settings.ready || busy,
+      onClick: () => { void run(() => settings.save({ label: "Custom label" })); } }, "Use custom label"),
+    createElement("button", { disabled: busy,
+      onClick: () => { void run(async () => { setLabel(await calls.invoke(ReadLabel, null, {})); }); } }, "Read current label"),
+    createElement("p", null, label),
+    error ? createElement("p", { role: "alert" }, error) : null);
+}
+export default defineRendererPlugin({ settings: [{ id: "general", title: "Labels", summary: "Configure shared labels.", Body: SettingsPage }] });
+export function OpenSettings() {
+  const settings = useRendererSettings();
+  return createElement("button", { onClick: () => settings.open(settingsPlugin.id, "general") }, "Open settings");
+}

package/examples/settings-runtime.ts

@@ -0,0 +1,11 @@
+import { definePlugin, implementCall } from "@asterism-app/sdk/runtime";
+import { Settings, ReadLabel, settingsPlugin } from "./settings-contract.ts";
+
+/** Plugins without feature modules can still maintain configuration and provide global business calls. */
+export default definePlugin({
+  namespace: settingsPlugin,
+  setup(plugin) {
+    const settings = plugin.config(Settings);
+    return { calls: [implementCall(ReadLabel, async () => settings.get().label)] };
+  },
+});

package/examples/storage.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { defineStorage } from "@asterism-app/sdk/runtime";
+
+/**
+ * Storage entry point: `"asterism": { "storage": "./src/storage.ts" }` in package.json points to this file.
+ * The host imports it separately before the plugin runtime, depending only on the format declarations themselves; each step interprets only the historical shape it receives.
+ */
+export default defineStorage([
+  {
+    // Managed configuration: `plugin.config` handles the `{ version, data }` envelope on reads and writes, while the plugin still consumes configuration values.
+    kind: "json", path: ".asterism/config.json", version: 2,
+    migrations: {
+      1: raw => {
+        const old = z.object({ greeting: z.string() }).parse(raw);
+        return { ...old, enabled: true };
+      },
+    },
+  },
+  {
+    // Managed database: the host writes the current `user_version` on initial creation; migrations execute synchronous SQL within a host transaction.
+    kind: "sqlite", path: ".asterism/db.sqlite", version: 2,
+    migrations: {
+      1: db => db.exec("ALTER TABLE notes ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0;"),
+    },
+  },
+]);