@asterism-app/sdk 0.0.0-stage → 0.47.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Chien Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# Asterism SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The SDK defines the shared language between Asterism and plugins: contracts, host capabilities, and contributions.
+
+Pure declarations can be shared across execution environments. Backend interfaces support work and persistence; frontend interfaces support presentation and interaction.
+
+The SDK describes generic mechanisms. Agent conversation, naming, and other domain behavior belong to the plugin that implements them.
+
+Public interfaces should express a capability an author needs. Internal decomposition is not itself a reason to expose another abstraction.
+
+## Installation
+
+Install the testing release with `npm install --save-dev --save-exact @asterism-app/sdk@next`. Declare `@asterism-app/sdk` as a peer dependency with `"*"` in the plugin package.
+
+The package ships TypeScript source. Asterism compiles plugin entries and supplies its own SDK instance at runtime. Use declarations compatible with the target application; installing a newer SDK does not update the application's APIs.
+
+## Authoring material
+
+The source package includes `docs/` for plugin development guides and `examples/` for public API usage. `examples/counter/` is a complete starter package; the other examples are focused fragments to compose into a plugin. The application's manual exposes these directories directly.
+
+Examples participate in repository type checking. Internal compile-time counterexamples live in `typechecks/` and are excluded from package contents and the manual. Built-in domain guides and examples belong to `@asterism-app/builtin-api`.

package/docs/data-and-lifecycle.md

@@ -0,0 +1,77 @@
+# Manage data and lifecycle
+
+Choose storage from the meaning of the data. Latest values, historical facts, immutable bytes, and running processes have different lifetimes.
+
+## Separate current state from history
+
+Current data records the latest session or object value. Historical records preserve facts needed to understand or reconstruct past work.
+
+Saving a current value does not automatically create history. Moving to an earlier history position does not restore that value. A resource that supports restoration defines the facts and operations that make restoration meaningful.
+
+Plugin-wide private data belongs to the plugin. Temporary interface choices belong to a view or an object-retained view scope, according to how long they should survive.
+
+## Encode data at boundaries
+
+Data schemas describe the values used by plugin code and how they are decoded from stored or transported JSON. Writers, resource creation, tool results, and presentations accept the decoded value and encode it before storage or publication. Typed readers and views decode the saved value.
+
+Use an ordinary Zod schema when both representations are the same. Use a synchronous `z.codec` when they differ. Both the domain value and its encoding remain JSON-compatible. One-way `.transform()` belongs in input preparation or an explicit conversion before writing; Zod cannot encode it in reverse.
+
+Resource creation returns a card title and plugin-owned `data`. State can be any JSON value, including arrays, scalars, or `null`; object fields such as `id`, `type`, and `title` retain their business meaning. The host stores resource identity and card title separately. Renaming a card changes its host title, and creating resources from a template gives them new host identities while preserving the encoded plugin state.
+
+Configuration defaults are complete decoded values. Reading an older configuration may fill absent fields through ordinary `.default()` declarations. Configuration updates receive decoded values, and saving an unchanged value preserves a correctly defined codec's domain value. The host handles encoding of configuration files and frontend responses.
+
+Codecs own their conversion semantics. Verify meaningful round trips when supplying custom encoders, decoders, or normalization callbacks. Tool results reserve `null` for absent output, so a non-null tool value needs a non-null encoding.
+
+## Reuse resources in templates
+
+A resource opts into data-copy templates with `template: { current: [Settings, Content] }` in its implementation. The list contains existing data contracts owned by the resource's plugin. An empty list copies only the resource's creation state. Resources without this declaration remain available for ordinary use and do not appear in the template picker.
+
+Templates retain encoded creation state and the listed current values that exist at save time. Unlisted current data, history, private files, and running instances are excluded. Instantiation creates new host identities and remaps host links; it preserves domain values and content references without rewriting embedded resource IDs or duplicating external services. Creation callbacks are not rerun, and ordinary presence lifetimes apply to the new objects.
+
+Opt in when those copied values are reusable under new identities. For example, a note can retain its body, and an agent can retain its configuration while leaving submission receipts and drafts behind. Resources needing external cloning, reference mapping, or private-state reconstruction need an explicit domain operation. Historical observation does not perform restoration.
+
+The installed resource must still support templates and decode all saved state and selected current data when the template is used. Unsupported or invalid saved entries fail explicitly before a new session is created.
+
+## Commit and observe
+
+Use the host's bound read and execution capabilities. Complete network and file processing outside synchronous transactions, then commit the resulting state.
+
+A historical snapshot fixes what is observed. A later write acts in the current execution context. Holding a snapshot does not redirect later writes into the past.
+
+Transient events announce change. A consumer needing current state establishes its subscription and reads the current value; later notifications prompt another read.
+
+Typed calls describe request and response values with ordinary Zod schemas. The caller supplies the input schema's input; the implementation receives its parsed output, including defaults. The implementation returns JSON accepted by the output schema, and the caller receives that schema's parsed output. These types are inferred from the shared declaration, so a conversion such as string to number does not require separate type annotations.
+
+## Retain file content
+
+Stage immutable bytes through the content service, then store their reference in persistent data or a record that owns them.
+
+A reference identifies content. Copying its identifier does not by itself grant access or retain the bytes. Pass it through the supported operation scope so ownership remains explicit.
+
+Retention follows references in the JSON actually saved. Preserve content references in that encoding when their bytes must remain available; synthesizing a reference during decoding does not retain content or grant access.
+
+## End asynchronous work
+
+Bind shared services to the plugin lifetime and object-owned instances to the resource lifetime. Register cleanup when creating the owned work.
+
+Cancellation requests that work stop. Wait for actual completion before releasing what that work still uses.
+
+Timeline-dependent operations need the host's activity tracking so history changes and object removal can respect active work.
+
+## Evolve stored data
+
+Persistent file formats need explicit preparation when they change. Keep that preparation independent of ordinary service startup.
+
+Historical records retain their original payloads. Supporting an older shape through decoding is different from rewriting the original historical fact.
+
+A codec can accept old and current payload shapes while encoding new writes in the current shape:
+
+```ts
+const current = z.strictObject({ text: z.string() });
+const textSchema = z.codec(z.union([z.string(), current]), current, {
+  decode: value => typeof value === "string" ? { text: value } : value,
+  encode: value => value,
+});
+```
+
+This schema reads an old string as a current object. Plugin code writes the object; historical reads leave the original string untouched.

package/docs/getting-started.md

@@ -0,0 +1,37 @@
+# Prepare for plugin development
+
+A plugin adds resources, tools, views, settings, or services through Asterism's public software development kit (SDK). Development includes preparing a compatible package, verifying its capabilities and lifecycle in the application, and checking the packaged result before sharing it.
+
+## Prepare a project
+
+Use a TypeScript package and the public SDK compatible with the application you intend to run. A package declaration identifies the plugin and its backend, frontend, and optional storage entries.
+
+Set the plugin's release version in `package.json.version`. That version identifies distributed releases and updates; it does not affect loading or execution. The runtime definition declares its namespace and behavior. Keep ordinary runtime libraries in `dependencies`; npm or another package manager installs them using its usual dependency and lockfile rules.
+
+Declare host-provided packages such as `@asterism-app/sdk` in `peerDependencies` with `"*"`. The running plugin always uses the host's instance, so a narrower range adds maintenance without changing behavior. Install a version of the SDK compatible with the target application in `devDependencies` for editor support and type checking. Extensions to built-in features can use the same arrangement for `@asterism-app/builtin-api`.
+
+The npm `next` tag identifies the current testing release. Install it with `npm install --save-dev --save-exact @asterism-app/sdk@next`; add `@asterism-app/builtin-api@next` when using built-in domain APIs. Saving an exact development version keeps the declarations stable until an intentional update. The packages include TypeScript source, guides, and examples. Installing a newer development package does not update the APIs provided by the running application.
+
+Asterism binds shared public imports to the active host or plugin provider. Dependency ranges do not reject loading; missing modules, missing exports, invalid contributions, and initialization errors produce loading failures. Check the APIs your plugin actually uses with TypeScript and exercise them in the target application.
+
+The `asterism` field declares a namespaced `id` and the needed `runtime`, `renderer`, and `storage` entry paths, relative to the package root. Runtime and renderer entries default-export their SDK plugin definitions. The runtime namespace must match the manifest ID.
+
+Keep shared declarations separate from executable backend and frontend code. Backend work can use local system capabilities; frontend code works through the host's view and communication facilities.
+
+Start with one capability that demonstrates the plugin's purpose. Add further parts when that capability needs them rather than creating an empty framework in advance.
+
+## Load and verify
+
+Prepare the package and its dependencies, run its type checks, then add its local package directory in Asterism's plugin settings. Restart to load changes.
+
+The host compiles TypeScript, TSX, and imported CSS at startup. A separate JavaScript build is optional. Generate CSS with the plugin's own toolchain first when using Tailwind, Sass, or another preprocessor. Source changes take effect after restart.
+
+Check the reported loading state and exercise the capability. Verify its normal result, meaningful errors, and cleanup when an object disappears or the application closes.
+
+Type checking establishes interface consistency. Actual loading and use establish whether the package works in the intended host.
+
+## Prepare for sharing
+
+Include the entries, assets, and dependencies the package needs. Preserve imports of shared public contracts so the host and consumers use the same declarations.
+
+Test the resulting package in an installed application. Development files available on the author's machine should not be necessary to use the distributed plugin.

package/docs/manual.md

@@ -0,0 +1,34 @@
+# Expose plugin documentation
+
+A plugin can make its documentation and examples available through Asterism's Manual resource. The manual exposes the declared directories directly. The same files remain usable in an editor or another development environment.
+
+## Declare directories
+
+Add a `manual` array to the plugin's existing `asterism` manifest:
+
+```json
+{
+  "asterism": {
+    "id": "example.bridge",
+    "manual": ["docs", "examples"]
+  }
+}
+```
+
+Each entry names an existing package-relative subdirectory using `/` separators. Entries must be normalized, must not overlap, and must resolve inside the package. Include those directories in the package's distributed files. A documentation declaration does not require a runtime entry.
+
+Declare only directories intended for readers. Source examples can be exposed alongside prose; internal test fixtures and credentials belong outside the declared directories.
+
+## Read through the manual
+
+When the plugin loads successfully, its directories appear under `plugins/<plugin-id>/`. For this example, an article at `docs/usage.md` appears as `plugins/example.bridge/docs/usage.md`. The manual supports directory listing, file discovery, content search, and reading selected lines.
+
+The manual reads current files at their original locations. It creates no copied document tree or index. Source declarations follow the loaded package set: changes to declarations, enabling, disabling, or removing a plugin take effect after restart. Plugins with package, startup, or storage failures do not contribute documents.
+
+A search at a virtual parent covers the directories below it. Globs apply within each selected physical search directory. Results include the complete virtual path, so identical filenames in different plugins remain distinguishable. Reading a file or following an explicitly selected symbolic link remains within the declared directory.
+
+## Write independent articles
+
+Each article should explain its purpose, relevant concepts, prerequisites, and working method without depending on a reading sequence. Keep the context needed to understand the topic in the article itself. Use examples to clarify operations and leave complete interface definitions to the public types.
+
+Maintain documentation with the domain that owns its meaning. Generic host capabilities belong to the SDK; a plugin's resource behavior and domain extensions belong to that plugin or its public API package. Documentation is reference material and does not become a system instruction merely by appearing in the manual.

package/docs/minimal-plugin.md

@@ -0,0 +1,33 @@
+# Build a small plugin
+
+A counter plugin demonstrates the complete path from shared declarations to backend behavior and a resource card. The SDK includes it as an ordinary package directory under `examples/counter`, with source files, a package manifest, and a TypeScript configuration. Its code is the maintained example; this guide explains how to use and adapt it.
+
+## Prepare the package
+
+Copy the counter directory to a writable development location. Its development dependency selects the SDK version used by the example. Use an Asterism application that provides those APIs. The SDK peer dependency describes a host-provided package, and the host does not use its version range to gate loading. React, React Intl, and Zod are also shared public dependencies supplied by the host when the plugin runs.
+
+Run `npm install` and `npm run typecheck` in the copied directory. The host compiles the TypeScript, TSX, and imported CSS entries, so a separate JavaScript build is optional. Add the package directory in Asterism's plugin settings and restart the application to load it.
+
+## Follow the data
+
+Shared declarations identify the counter, its private current value, projected view, change record, creation entry, increment action, read tool, settings, and typed call. Backend and frontend code import the same declarations. Copying a declaration under the same name does not establish shared runtime identity.
+
+Creation establishes the object. Incrementing reads the configured step, saves the current value, and appends a historical change in one synchronous commit. The example keeps the latest counter value when browsing history; it does not implement restoration. Network and file work belongs outside synchronous commits.
+
+The card reads projected data and invokes the public increment action. Each button owns its pending state and displays failures. Actions return receipts that the view checks; typed calls and settings saves reject on failure. A settings page edits the step and reads it back through the backend call.
+
+The model tool reads the same counter value through its resource implementation. Registering the tool does not grant access: an agent needs a link to the counter and a tool policy that allows the operation.
+
+## Adapt the package
+
+Choose a distinct plugin identity before using the example as a new plugin. Keep shared declarations independent of backend and frontend implementations. Add resource behavior through actions and expose an operation as a model tool when the model needs to call it.
+
+Imported CSS Modules keep the counter's class names local. Host theme variables provide colors. The storage entry declares the managed configuration format; add consecutive migrations when that format changes. Credentials belong in the secret service, and retained file content uses the content service.
+
+Object-owned external connections belong to the resource's attachment lifetime. Register their cleanup when opening them. Shared services belong to the plugin lifetime. Managed tasks own asynchronous work and pass cancellation to their I/O.
+
+## Verify the result
+
+Open the plugin settings page, change the step, and read it back. Create a counter, increment it, and verify the card and history. Link the counter to an agent and use its read tool.
+
+After edits, run type checking and restart Asterism. Verify invalid input, failure messages, cleanup, and reopening saved objects. Type checking establishes interface consistency; loading and using the package establishes its behavior in the host.

package/docs/project-structure.md

@@ -0,0 +1,27 @@
+# Organize a plugin
+
+A plugin is the unit of installation, identity, settings, and lifetime. Its internal modules group capabilities that share that ownership.
+
+## Separate responsibilities
+
+Shared contracts describe transferable data and operations. Backend implementations perform work. Frontend views present state and collect input.
+
+Keep shared declarations independent of backend-only or frontend-only libraries. A view reaches its backend through typed communication rather than importing the backend implementation.
+
+Group a capability's declarations, implementation, and presentation so they remain understandable together. Compose capabilities at the plugin entry through explicit dependencies.
+
+## Use public extension points
+
+The general SDK supplies host services and contribution interfaces. Built-in domain APIs expose extensions specific to existing features, such as Agent interaction.
+
+Use a domain extension when adding to that feature. A plugin with its own resource can define its own behavior and presentation.
+
+## Share contracts and services
+
+A public package can expose declarations or services for other plugins. Consumers declare ordinary package dependencies in `package.json` and import the original public values. The host derives initialization and cleanup dependencies from those imports, including imports through intermediate packages.
+
+Expose shared values through `./public` in the package's standard exports. Public imports bind to the enabled provider's actual exports, including imports through intermediate npm packages. The host uses the import graph for initialization order and reports missing exports or unavailable providers. Package versions and dependency ranges remain package-management metadata; local development copies do not replace the active provider.
+
+A shared declaration has runtime identity as well as a name. Copying it under the same name does not establish shared identity. Backend and frontend environments are separate even when they use the same contract.
+
+Shared service initialization and cleanup belong to the provider. A consumer should depend on the capability it needs rather than the provider's internal organization.

package/docs/resources-and-tools.md

@@ -0,0 +1,29 @@
+# Add resources and tools
+
+A resource represents an object with identity and lifetime. A tool represents a model-callable operation. They can evolve independently.
+
+## Add an object
+
+Use a resource for something that belongs in a session and can be inspected or operated on. Define how it is created, what state it owns, and what information it presents.
+
+The resource's lifetime follows its presence in the session. A hidden card does not imply that its backend instance should stop.
+
+Creation supplies initial state. Actions change the object through typed application or plugin operations. Views present the resulting state.
+
+Resource titles belong to session history. Use the session's rename operation with a resource reference to change a title; the host appends the event and reconstructs names along each history path. Tool sessions accept a resource ID within the request's captured links. Existing snapshots keep their captured titles.
+
+Use a session snapshot to query the resources directly linked to a receiver. Results contain resource references, titles, and public data on that snapshot's timeline path. Reverse links and links through another resource are independent. For external event handling, such as forwarding network messages to linked agents, read a fresh snapshot for each event. Session observers can also query their supplied snapshot after commits or cursor changes. The query exposes relationships without granting access to private state or expanding a model request's operation scope.
+
+## Add a model operation
+
+Use a resource tool when an operation targets a linked object. A shared tool can have implementations for different resource types, each with an appropriate internal target and result.
+
+Use a top-level tool for operations on the execution context or shared resource lifecycle, such as creation and renaming. The host supplies caller identity and execution scope.
+
+Describe the operation's purpose and observable behavior. Parameters should explain business meaning that names and types alone do not express. Results should distinguish known success, failure, cancellation, partial output, and uncertain effects.
+
+## Connect other interactions
+
+Typed calls connect request and response between services or views. Events announce transient changes. Object channels support sustained data such as an interactive screen.
+
+An action or service call is not automatically a model tool. Expose it deliberately when the model needs that operation.

package/docs/views-and-settings.md

@@ -0,0 +1,35 @@
+# Build views and settings
+
+Views present state and accept input. Backend services own the work, results, and resource lifetime.
+
+## Present objects and operations
+
+A resource card shows the object's content. A tool view shows one operation, including generated input, execution progress, and the final outcome.
+
+Input previews can be incomplete. Displaying arguments does not establish that execution has begun. A final result should reflect what actually happened.
+
+Use host presentation facilities for the surrounding card or operation. Keep domain content within the view rather than rebuilding application navigation and containment.
+
+## Style plugin views
+
+Import CSS from the renderer entry or its components. Asterism builds the imported styles and loads them before frontend preparation and view registration. CSS references to bundled images and fonts keep their relative paths. Style loading failures appear as frontend plugin failures.
+
+Use CSS Modules (`.module.css`) for component-local class names, importing the generated names into the component. Plain CSS shares the application's document, so global selectors and resets affect other views. Host theme variables can supply colors and spacing without redefining the application theme.
+
+Tailwind and other preprocessors belong to the plugin's build setup. Generate ordinary CSS and import that output; the host does not process the plugin's Tailwind or PostCSS configuration. Utility classes used only by an external plugin need its own generated CSS.
+
+Styles remain loaded while the plugin frontend is active, including when individual cards unmount. Failed initialization releases that plugin's stylesheet; ending the frontend lifetime releases all loaded plugin styles.
+
+## Add settings
+
+A plugin can have a settings page independently of sessions and resources. The page owns its edit drafts and pending interactions; the plugin service owns shared configuration.
+
+Managed configuration suits schema-validated settings. Other plugin data can use a storage model appropriate to its purpose.
+
+Closing a page releases its view subscriptions. It does not end every service the plugin uses.
+
+## Write interface text
+
+Plain text is valid. Message declarations and translation catalogs support plugins that need localized interfaces.
+
+Keep protocol identifiers, code, and raw diagnostics distinct from interface explanations. UI language changes should not reset drafts or running work.

package/examples/author.ts

@@ -0,0 +1,158 @@
+import { sample, Counter, Count, CounterView, CountChanged, CreateCounter, ChangeCount, CounterUpdates, counterCard } from "./counter-contract.ts";
+/** Independent examples of session records, resource behavior, and model execution. */
+import { z } from "zod";
+import { pluginNamespace, defineAction, resourceCall, defineRecord, defineTool, defineImplementation, modelRunRecordSchema, type ModelItem } from "@asterism-app/sdk/contracts";
+import {
+  defineModule, definePlugin, implementCreation, implementAction, implementPreparer, implementResource, implementTool, implementChannel,
+  type PluginContext, type ObjectReader, type ObjectExecutor, type SessionObserver, type SessionSnapshot, type ResourceRef,
+} from "@asterism-app/sdk/runtime";
+
+/** Scenario one: uses only session events and lifecycles, without resources, models, or Agents. */
+const journal = pluginNamespace("example.journal");
+const Annotation = defineRecord(journal.name("annotation"), {
+  schema: z.strictObject({ text: z.string() }),
+});
+export const journalPlugin = definePlugin({
+  namespace: journal, modules: [defineModule(plugin => ({
+    records: [Annotation],
+    observers: [{
+      id: "observe-annotations",
+      committed({ records }) {
+        for (const record of records) {
+          const entry = Annotation.decode(record);
+          if (entry?.status === "known") plugin.log.info("Annotation committed.");
+        }
+      },
+      cursorChanged({ snapshot, session }) {
+        const annotation = snapshot.records.last(Annotation, { scope: "timeline" });
+        if (annotation?.status !== "known") return;
+        session.commit(writer => { writer.set(CurrentSummary, { text: annotation.data.text }); });
+      },
+    } satisfies SessionObserver],
+  }))],
+});
+export function annotate(plugin: PluginContext, sessionId: string, text: string) {
+  plugin.session(sessionId).commit(writer => { writer.append(Annotation, { text }); });
+}
+/** Locate the latest typed record by scope and contract; leave unknown for domain consumers to handle. */
+export function latestAnnotation(plugin: PluginContext, sessionId: string) {
+  return plugin.session(sessionId).snapshot().records.last(Annotation, { scope: "session" });
+}
+const CurrentSummary = journal.data("summary", z.strictObject({ text: z.string() }));
+/** Current session data does not enter the timeline; it is stored separately from object data and private plugin databases. */
+export function saveSummary(plugin: PluginContext, sessionId: string, text: string) {
+  const session = plugin.session(sessionId);
+  session.commit(writer => { writer.set(CurrentSummary, { text }); });
+  return session.get(CurrentSummary);
+}
+
+/** Scenario two: creation, state, events, actions, and tools for an independent resource, without model capabilities. */
+const counterSettings = z.strictObject({
+  maxChange: z.number().int().min(1).max(100).meta({
+    title: "Maximum change", description: "Largest absolute increment accepted by a counter action.",
+  }),
+}).meta({ title: "Counter settings" });
+const CounterConfig = sample.config(counterSettings, { maxChange: 10 });
+const Read = defineTool({
+  id: "example.counter/read_counter", name: "read_counter", description: "Read the current counter value.", guidelines: [],
+  argsSchema: z.strictObject({}).describe("No arguments are required."),
+});
+const CounterRead = defineImplementation({
+  ...sample.data("read", Count.schema.describe("The current integer value.")),
+  resource: Counter, tool: Read,
+  targetSchema: z.null().describe("Pass null to select this counter."),
+  effect: "read", execution: "parallel",
+});
+function currentCount(object: ObjectReader) {
+  const value = object.get(Count);
+  if (value === null) throw new Error("Counter state is unavailable.");
+  return value;
+}
+/** Feature modules receive only their own settings read capability; configuration declarations remain at the assembly site. */
+function counterChange(limit: () => number) {
+  return implementAction(ChangeCount, {
+    prepare(input) {
+      return Math.abs(input.amount) > limit()
+        ? { action: "reject", code: "change_too_large", message: "Change exceeds the limit." }
+        : { action: "accept" };
+    },
+    async execute(input, object) {
+      object.commit(writer => {
+        const value = currentCount(object).value + input.amount;
+        writer.set(Count, { value });
+        writer.append(CountChanged, { value });
+      });
+    },
+  });
+}
+export const counterPlugin = definePlugin({
+  namespace: sample, modules: [defineModule(plugin => {
+    const settings = plugin.config(CounterConfig);
+    return {
+      resources: [implementResource(Counter, CounterView, {
+        card: counterCard,
+        records: [CountChanged],
+        creation: implementCreation(CreateCounter, {
+          create(input, object) {
+            object.commit(writer => { writer.set(Count, { value: 0 }); });
+            return { title: input.title, data: {} };
+          },
+        }),
+        actions: [counterChange(() => settings.get().maxChange)],
+        project(_data, object) { return currentCount(object); },
+        async inspect(_data, object) { return currentCount(object); },
+      })],
+      tools: [implementTool(CounterRead, {
+        async call(_data, _target, _args, context) {
+          context.signal.throwIfAborted();
+          return { kind: "succeeded", data: currentCount(context.object) };
+        },
+      })],
+      // The channel follows the object's lifetime: the host aborts signal when the object is removed or disappears after rewinding.
+      channels: [implementChannel(CounterUpdates, channel => {
+        channel.onMessage(() => channel.send(currentCount(channel.object)));
+        const timer = setInterval(() => channel.send(currentCount(channel.object)), 1000);
+        channel.signal.addEventListener("abort", () => clearInterval(timer), { once: true });
+      })],
+    };
+  })],
+});
+
+/** Scenario three: the plugin's own Agent drives the loop, with context projected from the timeline each time. */
+const research = pluginNamespace("example.research");
+const Execution = defineRecord(research.name("execution"), { schema: modelRunRecordSchema });
+export const modelRecordsModule = defineModule(() => ({ records: [Execution] }));
+/** The domain plugin constructs the projection from its own input/execution events; it is not stored in Agent or run. */
+export async function modelWork(plugin: PluginContext, object: ObjectExecutor, signal: AbortSignal,
+  projectOwnContext: (snapshot: SessionSnapshot, object: ResourceRef) => ModelItem[]) {
+  for (let request = 0; request < 8; request++) {
+    const snapshot = object.session.snapshot();
+    const result = await plugin.models.run({
+      object: object.ref, requestParentId: snapshot.position.nodeId, target: { role: "default" },
+      system: { blocks: [{ id: research.name("instruction"), kind: "system", from: research.id, text: "Inspect linked materials and report findings." }] },
+      messages: projectOwnContext(snapshot, object.ref), cache: { expectHit: request > 0 }, signal,
+      observer: { event(event) {
+        if (event.type === "progress") return;
+        object.commit(writer => { writer.append(Execution, modelRunRecordSchema.parse(event)); });
+      } },
+    });
+    if (result.reason !== "completed" || result.tools.length === 0) return result;
+  }
+  throw new Error("The model request limit was reached.");
+}
+
+/** External preparers also infer input from the action contract they hold, without redeclaring the schema. */
+export const counterLimit = implementPreparer(ChangeCount, {
+  id: "clamp-change",
+  prepare(input) { return { action: "replace", input: { amount: Math.max(-10, Math.min(10, input.amount)) } }; },
+});
+
+/** Invocation and replacement receive raw strings; preparation and execution receive numbers transformed by the schema. */
+export const FromText = defineAction(Counter, { id: sample.name("from-text"),
+  schema: z.string().regex(/^\d+$/u).transform(Number),
+});
+export const parsedAction = implementAction(FromText, {
+  prepare(value) { return value > 10 ? { action: "replace", input: "10" } : { action: "accept" }; },
+  async execute(value, object) { object.commit(writer => { writer.set(Count, { value }); }); },
+});
+export const parsedInput = resourceCall(FromText, "5");

package/examples/consume-usage.ts

@@ -0,0 +1,29 @@
+import type { StreamRequest, UsageItem } from "@asterism-app/sdk/contracts";
+import type { PluginContext } from "@asterism-app/sdk/runtime";
+
+/** Example consumer: actively queries before a request and parses response headers against the current catalog for the response's connection. */
+export async function* streamWithUsage(plugin: PluginContext, connectionId: string, request: StreamRequest,
+  receive: (items: UsageItem[]) => void) {
+  const connection = plugin.modelProviders.get(connectionId);
+  const usage = connection?.enabled && connection.usage ? plugin.usageProviders.get(connection.usage) : null;
+  if (connection && usage && usage.source !== "headers") {
+    const credential = await plugin.modelProviders.credential(connection.id, { signal: request.signal });
+    const items = await plugin.usages.query(usage.id, { connection: { id: connection.id, endpoint: connection.baseUrl }, credential, signal: request.signal });
+    receive(items);
+  }
+  for await (const event of plugin.models.stream(request)) {
+    const response = event.type === "finish" ? event.response : null;
+    if (response) {
+      const current = plugin.modelProviders.get(response.connection.id);
+      const parser = current?.enabled && current.usage ? plugin.usageProviders.get(current.usage) : null;
+      if (parser?.source === "headers") {
+        try {
+          const items = plugin.usages.parseHeaders(parser.id, { connection: { id: response.connection.id, endpoint: response.endpoint },
+            model: response.model, status: response.status, receivedAt: response.receivedAt, headers: response.headers });
+          if (items !== null) receive(items);
+        } catch { plugin.log.warn("Usage response parsing failed."); }
+      }
+    }
+    yield event;
+  }
+}

package/examples/content-author.ts

@@ -0,0 +1,29 @@
+import { defineModule, definePlugin, implementAction, implementCreation, implementResource } from "@asterism-app/sdk/runtime";
+import { CreateDocument, Document, DocumentContent, Imported, ReplaceDocument, files } from "./content-contract.ts";
+
+/** The session owns content, and plugins only interpret business formats; this example does not access host source code or private paths. */
+export default definePlugin({ namespace: files, modules: [defineModule(() => ({
+  resources: [implementResource(Document, DocumentContent, {
+    records: [Imported],
+    creation: implementCreation(CreateDocument, {
+      async prepare(input, { content }) {
+        // Format checks can read a bounded range or use open to stream large files.
+        await content.read(input.file, { length: 512 });
+        return { action: "accept" };
+      },
+      create(input, object) {
+        object.commit(writer => {
+          writer.set(DocumentContent, input);
+          // This example explicitly retains the originally imported content; resources that store only the current value can omit this event.
+          writer.append(Imported, input);
+        });
+        return { title: input.name, data: {} };
+      },
+    }),
+    actions: [implementAction(ReplaceDocument, {
+      async execute(input, object) { object.commit(writer => { writer.set(DocumentContent, input); }); },
+    })],
+    project: (_data, object) => object.get(DocumentContent)!,
+    inspect: async (_data, object) => object.get(DocumentContent),
+  })],
+}))] });

package/examples/content-contract.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { contentRefSchema, defineAction, defineCreation, defineRecord, pluginNamespace } from "@asterism-app/sdk/contracts";
+
+/** Content identities can be embedded in ordinary contracts; authors need not declare a separate list of persistent attachments. */
+export const files = pluginNamespace("example.content");
+export const Document = files.resource("document", z.object({}));
+export const DocumentContent = files.data("content", z.object({ file: contentRefSchema, name: z.string() }));
+export const Imported = defineRecord(files.name("imported"), { schema: DocumentContent.schema });
+export const CreateDocument = defineCreation(Document, { id: files.name("create"), schema: DocumentContent.schema });
+export const ReplaceDocument = defineAction(Document, { id: files.name("replace"), schema: DocumentContent.schema });

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.47.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"]
+  }
+}