@asterism-app/sdk 0.0.0-stage → 0.47.0

package/examples/counter/src/contracts.ts

@@ -0,0 +1,31 @@
+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(),
+});
+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,69 @@
+import { useRef, useState } from "react";
+import {
+  defineRendererPlugin, cardRenderer, creationEntry, toolRenderer,
+  useRendererObject, useRendererConfiguration, useRendererCalls, useI18n,
+} from "@asterism-app/sdk/renderer";
+import { ns, card, Counter, View, Create, Increment, Settings, ReadStep, ReadCounter } 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>;
+}
+
+export default defineRendererPlugin({
+  settings: { 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,43 @@
+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,
+} 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)],
+      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: { role: "utility" }, 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: { Body: SettingsPage, locations: ["general"] } });
+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;"),
+    },
+  },
+]);

package/examples/tool-renderer.ts

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

package/examples/web-provider.ts

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