@asterism-app/sdk 0.0.0-stage → 1.0.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 with `npm install --save-dev --save-exact @asterism-app/sdk@latest` to target the stable application, or `@next` to target the preview application. 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,79 @@
+# 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.
+
+To give each template instance a new title, add a synchronous `createTitle(): string` function to the resource's `template` declaration. Saving then omits the source title, including a user-assigned title. The host calls the function once for each new object when instantiating a template, and uses its result even if an older template contains a title. Saving and previewing templates do not call it. Without this function, templates preserve source titles; a saved entry without a title requires the generator to remain available.
+
+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 pages, Home entries, 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`.
+
+npm distribution tags follow the application's release channels: `latest` matches the newest stable application and `next` matches the newest preview application. Install the tag for the application you target, for example `npm install --save-dev --save-exact @asterism-app/sdk@latest`; add `@asterism-app/builtin-api` with the same tag when using built-in domain APIs. Saving an exact version keeps the declarations stable until an intentional update. The packages include TypeScript source, guides, and examples. Installing a newer 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. The required `displayName` is the plugin's name wherever the application shows it, including plugin management, settings attribution, and session entries; use a message reference owned by the plugin to localize it. The host reads it from the package without running plugin code, so disabled and failed plugins keep their names.
+
+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,38 @@
+# 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.
+
+A public API library named in the plugin's `asterism.publicPackages` can declare its own `asterism.manual` directories. The library needs no plugin identity or executable entry for this declaration. Its documentation remains inside its own package and is available while its implementation provider is loaded.
+
+## 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.
+
+Public-library directories appear under `plugins/<plugin-id>/public/<package-name>/`. The host exposes the same source catalog through the SDK for plugins that provide another documentation interface.
+
+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,35 @@
+# 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 example also contributes a Home entry. It prepares a counter, then initializes a session containing it in one transaction. This entry works with the builtin paradigm disabled and requires no conversation input.
+
+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,33 @@
+# 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.
+
+A paradigm plugin can own a Home entry, configuration, request assembly, and execution behavior. The host supplies sessions, concrete model access, interactive terminals, command execution, MCP, provider usage, and raw skill and instruction catalogs. Compose these capabilities according to the workflow; an Agent resource or conversation card is optional.
+
+## 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.
+
+For a separate API library, declare its package name in the implementation plugin's `asterism.publicPackages` array. Install that library as an ordinary dependency and declare its public entry points through standard package exports. Consumers resolve those entries from the enabled provider's installation. Package names cannot be claimed by competing enabled providers across these two declaration forms.
+
+Libraries that depend on native binaries or files relative to their installed module can be listed in `asterism.runtimeExternals`. The host preserves their resolved installed locations instead of relocating their code into the plugin cache.
+
+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,43 @@
+# 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.
+
+Declare `links: { receive: true }` in the backend resource implementation when the object can receive directed links. The host supplies this capability to the workbench's connection controls and authorization panel. Renderer resource descriptions supply labels, icons, and card geometry; link reception needs no frontend declaration.
+
+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.
+
+A tool contribution can capture resource-specific configuration and access at the start of each model request. Return a bound contribution using the same implementation contract; the host uses it for that request's tool batch. This is useful for a resource whose selected network or reachable objects can change while a model is responding. Capture addressing and authorization facts, while reading ordinary mutable content when the operation runs.
+
+## 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.
+
+## Use shell capabilities
+
+Backend plugins access shell profiles, one-shot execution, and interactive terminals through `plugin.shell`. Profiles are shared host configuration: `profiles.get()` reads that configuration, while `profiles.list()` resolves executable availability. Plugins choose how to expose these capabilities through their resources and tools.
+
+Use `shell.execute(cwd, args, options)` for a noninteractive command with piped output, progress, and a final result. Each execution owns its process; cancellation or timeout stops that execution without undoing completed effects.
+
+Use `shell.terminals.create(config, events)` for a persistent interactive session. Start the returned handle when needed and register its disposal with the owning resource or plugin lifetime. Closing a terminal permits reopening the handle; disposing it releases it permanently. Input and readiness waits are separate operations, and cancelling a wait leaves the shell running.
+
+A terminal can serve several views through its typed input/output messages. Plugins connect viewers through object channels and choose their own presentation. Backend reads expose screen text, retained output, or character-cell image data. The host owns the PTY and screen state; a terminal handle does not create a workbench resource or model tool by itself.

package/docs/session-entries.md

@@ -0,0 +1,31 @@
+# Provide a session entry
+
+A session contains a history tree and a workbench. A plugin can start work with any supported resources, or with an empty workbench. An initial message and an Agent resource are optional domain choices.
+
+## Own the starting interface
+
+Declare a session entry in the renderer plugin. Its body owns the controls, draft, pending state, and error presentation. The host supplies readiness and an operation that opens the resulting session.
+
+Home displays a single available entry directly. Users choose among several entries in General settings. An explicit selection that becomes unavailable stays unresolved until the user chooses another entry. Resource templates remain available independently of the selected entry.
+
+## Prepare and initialize
+
+Use a typed plugin call for submission. Its backend implementation performs business validation and calls `plugin.createSession` with a retry key. Prepare each required resource through the supplied preparation context, using the original registered creation contract.
+
+Preparation can perform asynchronous work. It returns an initial title and a synchronous initializer. The initializer creates prepared resources and writes initial records or current data through authorized object handles. Session identity, resources, initial writes, and the retry receipt commit together. A failed preparation or initializer leaves no partial session.
+
+When initial work uses an existing resource action contract, prepare that action against the resource token before initialization. This applies its parsing and registered preparers to the initial input as well. The pending resource has its final identity, but no persisted state yet. The owning plugin validates its initial business state and uses the prepared input in the initializer.
+
+Reuse the key for a retry of the same accepted submission. Keys belong to the contributing plugin. A successful retry returns the existing session without repeating preparation or initialization. A new piece of work uses a new key.
+
+## Carry attachments
+
+Obtain a renderer content input for the submission call. Pass that input as the call's content option. The backend receives a content reader separately from business input and forwards it to session creation.
+
+Content IDs alone grant no access. Only authorized referenced bytes enter preparation and initial writes. Persisted references retain those bytes after the temporary draft closes.
+
+## Name the work
+
+The entry supplies the initial title. Later user or plugin title assignments append host history. Continuing from an older position restores that path's latest title, or the initial title when the path has no assignment.
+
+A paradigm can attach its own typed detail to a title assignment and implement automatic naming policy. The host preserves that detail and provides generic title operations.

package/docs/views-and-settings.md

@@ -0,0 +1,43 @@
+# 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 declare several settings pages independently of sessions and resources. Each has its own identity, title, summary, optional icon, and body. The icon is a component the host draws at its own size and color; the host draws the card, page heading, and attribution, and the plugin supplies only the body. Entries appear on settings home with the contributing plugin's display name. Plugin management is a separate list for installation and enablement.
+
+The page owns its edit drafts and pending interactions; the plugin service owns shared configuration. Navigation targets a plugin and page, with an optional declared location inside the page. A page failure is isolated and can be retried without disabling other settings pages.
+
+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.
+
+## Start work from Home
+
+A session entry supplies the complete starting interface for a plugin's workflow. It owns drafts, validation feedback, submission, and the initial title. Submit through a typed plugin call, prepare resources in the backend, and initialize the session atomically. Open the resulting session using the entry's host-provided callback.
+
+Keep a retry identity until submission succeeds. Attachments travel through the call's content capability independently of its JSON input. The host handles entry selection and retains access to templates when no entry is available.
+
+## 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: { provider: "configured-provider", model: "configured-model" },
+      system: { blocks: [{ id: research.name("instruction"), 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 });