@asterism-app/sdk 0.47.0 → 1.0.1

package/README.md

@@ -10,7 +10,7 @@ Public interfaces should express a capability an author needs. Internal decompos
 
 ## 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.
+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.
 

package/docs/data-and-lifecycle.md

@@ -28,6 +28,8 @@ A resource opts into data-copy templates with `template: { current: [Settings, C
 
 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.

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -10,14 +10,16 @@ Set the plugin's release version in `package.json.version`. That version identif
 
 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.
+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 `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.
 
+The `.test.` filename marker is reserved for tests, such as `count.test.ts` or `card.test.tsx`. Tests can remain alongside implementation files. Automatic shared-module discovery and application/package distribution exclude `*.test.*`; runtime entries and their imports contain application code only. Plugin compilation reports explicit imports of test files or Vitest instead of silently removing dependencies.
+
 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

package/docs/manual.md

@@ -19,10 +19,14 @@ Each entry names an existing package-relative subdirectory using `/` separators.
 
 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.

package/docs/minimal-plugin.md

@@ -16,6 +16,8 @@ Creation establishes the object. Incrementing reads the configured step, saves t
 
 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

package/docs/project-structure.md

@@ -16,12 +16,18 @@ The general SDK supplies host services and contribution interfaces. Built-in dom
 
 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

@@ -12,6 +12,8 @@ Creation supplies initial state. Actions change the object through typed applica
 
 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
@@ -22,8 +24,20 @@ Use a top-level tool for operations on the execution context or shared resource
 
 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

@@ -22,12 +22,20 @@ Styles remain loaded while the plugin frontend is active, including when individ
 
 ## 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.
+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.

package/examples/author.ts

@@ -128,8 +128,8 @@ export async function modelWork(plugin: PluginContext, object: ObjectExecutor, s
   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." }] },
+      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;

package/examples/counter/package.json

@@ -11,7 +11,7 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@asterism-app/sdk": "0.47.0",
+    "@asterism-app/sdk": "0.48.0",
     "typescript": "^7.0.2",
     "@types/node": "^26.6.1",
     "@types/react": "^19.3.0"

package/examples/counter/src/contracts.ts

@@ -18,6 +18,9 @@ export const Settings = ns.config(
 export const ReadStep = defineCall(ns.name("read-step"), {
   scope: "plugin", input: z.null(), output: z.number(),
 });
+export const StartSession = defineCall(ns.name("start-session"), {
+  scope: "plugin", input: z.strictObject({ key: z.string().min(1) }), output: z.string(),
+});
 const Read = defineTool({
   id: ns.name("read-counter"), name: "read_counter",
   description: "Read the current value of a counter.", guidelines: [],

package/examples/counter/src/renderer.tsx

@@ -1,9 +1,9 @@
 import { useRef, useState } from "react";
 import {
   defineRendererPlugin, cardRenderer, creationEntry, toolRenderer,
-  useRendererObject, useRendererConfiguration, useRendererCalls, useI18n,
+  useRendererObject, useRendererConfiguration, useRendererCalls, useI18n, type SessionEntryProps,
 } from "@asterism-app/sdk/renderer";
-import { ns, card, Counter, View, Create, Increment, Settings, ReadStep, ReadCounter } from "./contracts.ts";
+import { ns, card, Counter, View, Create, Increment, Settings, ReadStep, ReadCounter, StartSession } from "./contracts.ts";
 import styles from "./panel.module.css";
 
 function Operation({ label, disabled = false, run }: {
@@ -52,8 +52,19 @@ function SettingsPage() {
   </div>;
 }
 
+function CounterEntry({ ready, open }: SessionEntryProps) {
+  const calls = useRendererCalls(), retryKey = useRef<string | null>(null);
+  return <Operation label="Start a counter workspace" disabled={!ready} run={async () => {
+    retryKey.current ??= crypto.randomUUID();
+    const sessionId = await calls.invoke(StartSession, { key: retryKey.current }, {});
+    retryKey.current = null;
+    open(sessionId);
+  }} />;
+}
+
 export default defineRendererPlugin({
-  settings: { Body: SettingsPage },
+  sessionEntries: [{ id: "counter", title: "Counter workspace", Body: CounterEntry }],
+  settings: [{ id: "counter", title: "Counter", summary: "Configure the counter step.", Body: SettingsPage }],
   modules: [{
     resources: [{ kind: Counter.kind, label: "Counter", icon: null, card }],
     creations: [creationEntry(Create, {

package/examples/counter/src/runtime.ts

@@ -4,7 +4,7 @@ import {
 } from "@asterism-app/sdk/runtime";
 import {
   ns, card, Counter, Value, View, Changed, Create, Increment,
-  Settings, ReadStep, ReadCounter,
+  Settings, ReadStep, ReadCounter, StartSession,
 } from "./contracts.ts";
 
 const current = (object: ObjectReader) => object.get(Value) ?? 0;
@@ -14,7 +14,13 @@ export default definePlugin({
   setup(plugin) {
     const settings = plugin.config(Settings);
     return {
-      calls: [implementCall(ReadStep, async () => settings.get().step)],
+      calls: [
+        implementCall(ReadStep, async () => settings.get().step),
+        implementCall(StartSession, async ({ key }, { signal }) => plugin.createSession(key, async preparation => {
+          const counter = await preparation.prepare(Create, null);
+          return { title: "Counter workspace", initialize(session) { session.create(counter); } };
+        }, { signal })),
+      ],
       resources: [implementResource(Counter, View, {
         card, records: [Changed],
         template: { current: [Value] },

package/examples/model-input.ts

@@ -8,7 +8,7 @@ export async function describeFile(models: ModelServices, content: ContentScope,
     { kind: "text", text: "Describe the image." },
     { kind: "file", file, mediaType: "image/png", filename: "screenshot.png" },
   ] }];
-  const request = { target: { role: "utility" }, system: { blocks: [] }, messages, signal };
+  const request = { target: { provider: "configured-provider", model: "configured-model" }, system: { blocks: [] }, messages, signal };
   await models.validate(request, { content });
   for await (const event of models.stream(request, { content })) {
     if (event.type === "part.delta") void event.delta;

package/examples/settings-renderer.ts

@@ -23,7 +23,7 @@ function SettingsPage() {
     createElement("p", null, label),
     error ? createElement("p", { role: "alert" }, error) : null);
 }
-export default defineRendererPlugin({ settings: { Body: SettingsPage, locations: ["general"] } });
+export default defineRendererPlugin({ settings: [{ id: "general", title: "Labels", summary: "Configure shared labels.", Body: SettingsPage }] });
 export function OpenSettings() {
   const settings = useRendererSettings();
   return createElement("button", { onClick: () => settings.open(settingsPlugin.id, "general") }, "Open settings");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asterism-app/sdk",
-  "version": "0.47.0",
+  "version": "1.0.1",
   "description": "Public contracts and host capabilities for Asterism plugins",
   "license": "MIT",
   "author": "Chien Zhang",
@@ -33,7 +33,7 @@
   },
   "files": [
     "src",
-    "!src/**/*.test.ts",
+    "!**/*.test.*",
     "docs",
     "examples",
     "README.md"

package/src/calls.ts

@@ -2,6 +2,7 @@ import type { z } from "zod";
 import type { Json } from "./json.ts";
 import { contractReferenceSchema } from "./presentation.ts";
 import type { ResourceRef } from "./workspace.ts";
+import type { ContentReader } from "./content-runtime.ts";
 
 export type CallScope = "plugin" | "object";
 /** Scope is declared by the contract; callers cannot downgrade an object-level operation by omitting the object. */
@@ -17,11 +18,11 @@ export function defineCall<Input extends z.ZodType<Json>, Output extends z.ZodTy
   if (definition.scope !== "plugin" && definition.scope !== "object") throw new Error("A call must declare plugin or object scope.");
   return Object.freeze({ ...contractReferenceSchema.parse({ id }), ...definition });
 }
-export type CallOptions<S extends CallScope = CallScope> = { signal?: AbortSignal } &
+export type CallOptions<S extends CallScope = CallScope, Content = ContentReader> = { signal?: AbortSignal; content?: Content } &
   (S extends "object" ? { object: ResourceRef } : { object?: never });
-export interface PluginCalls {
+export interface PluginCalls<Content = ContentReader> {
   /** Submit JSON matching the input schema's input; receive the output schema's parsed result. */
   invoke<Input extends z.ZodType<Json>, Output extends z.ZodType<Json>, S extends CallScope>(
-    contract: CallContract<Input, Output, S>, input: NoInfer<z.input<Input>> & Json, options: CallOptions<NoInfer<S>>,
+    contract: CallContract<Input, Output, S>, input: NoInfer<z.input<Input>> & Json, options: CallOptions<NoInfer<S>, Content>,
   ): Promise<z.output<Output>>;
 }

package/src/contracts.ts

@@ -22,8 +22,18 @@ export * from "./content.ts";
 export * from "./model-input.ts";
 
 export * from "./model-selection.ts";
+export * from "./model-catalog.ts";
 export * from "./model-cost.ts";
 export * from "./model-cost-estimate.ts";
 export * from "./model-media.ts";
+export * from "./model-provider.ts";
 export * from "./provider-usage.ts";
 export * from "./web.ts";
+
+export * from "./session-title.ts";
+
+export * from "./usage-state.ts";
+
+export * from "./shell.ts";
+export * from "./terminal.ts";
+export * from "./mcp.ts";

package/src/mcp.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { defineCall } from "./calls.ts";
+import { defineEvent } from "./events.ts";
+import { jsonSchema } from "./json.ts";
+
+export const SERVER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/u;
+export const serverIdSchema = z.string().min(1).max(64).regex(SERVER_ID_PATTERN);
+export const mcpServerSchema = z.strictObject({
+  id: serverIdSchema, name: z.string().trim().min(1), enabled: z.boolean(),
+  mode: z.enum(["eager", "lazy"]), idleSeconds: z.number().int().min(1).max(86_400),
+  transport: z.enum(["stdio", "http"]), command: z.string(), args: z.array(z.string()), cwd: z.string(),
+  url: z.string(), auth: z.enum(["none", "oauth"]),
+}).superRefine((value, ctx) => {
+  if (value.transport === "stdio" && !value.command.trim()) ctx.addIssue({ code: "custom", path: ["command"], message: "An executable is required." });
+  if (value.transport === "http") {
+    try { const url = new URL(value.url); if (!["http:", "https:"].includes(url.protocol)) throw new Error(); }
+    catch { ctx.addIssue({ code: "custom", path: ["url"], message: "An HTTP or HTTPS MCP URL is required." }); }
+  }
+});
+export type McpServerConfig = z.infer<typeof mcpServerSchema>;
+export const mcpSettingsSchema = z.object({ servers: z.array(mcpServerSchema).refine(values =>
+  new Set(values.map(value => value.id)).size === values.length, "Server IDs are unique.") });
+export const defaultMcpSettings = { servers: [] };
+export const credentialsSchema = z.record(z.string(), z.string());
+export const connectionPhases = ["disconnected", "connecting", "awaiting_auth", "authorizing", "connected", "error"] as const;
+export type ConnectionPhase = typeof connectionPhases[number];
+export const mcpServerStateSchema = z.object({
+  id: z.string(), name: z.string(), enabled: z.boolean(), mode: z.enum(["eager", "lazy"]),
+  connection: z.enum(connectionPhases),
+  indexed: z.boolean(), toolCount: z.number(), error: z.string().nullable(), authorizationUrl: z.string().nullable(),
+  authorizationExpiresAt: z.number().nullable(),
+});
+export type McpServerState = z.infer<typeof mcpServerStateSchema>;
+export const cachedMcpToolSchema = z.object({
+  name: z.string(), title: z.string().optional(), description: z.string().optional(),
+  inputSchema: z.record(z.string(), jsonSchema), outputSchema: z.record(z.string(), jsonSchema).optional(),
+  annotations: z.record(z.string(), jsonSchema).optional(),
+});
+export type CachedMcpTool = z.infer<typeof cachedMcpToolSchema>;
+export const mcpDirectorySchema = z.object({ tools: z.array(cachedMcpToolSchema), instructions: z.string().optional() });
+export type McpDirectory = z.infer<typeof mcpDirectorySchema>;
+export interface McpCatalogServer { config: McpServerConfig; state: McpServerState; directory?: McpDirectory }
+
+export const McpChanged = defineEvent("core.mcp.changed", { schema: z.object({}), source: "host", semantics: { kind: "snapshot", key: [] } });
+export const ReadMcp = defineCall("core.mcp.status", { scope: "plugin", input: z.object({}), output: z.array(mcpServerStateSchema) });
+/** keep retains saved environment or headers; a new server with keep starts without any. */
+export const mcpCredentialUpdateSchema = z.discriminatedUnion("action", [
+  z.strictObject({ action: z.literal("keep") }), z.strictObject({ action: z.literal("replace"), values: credentialsSchema }),
+]);
+export type McpCredentialUpdate = z.infer<typeof mcpCredentialUpdateSchema>;
+export const SaveMcpServer = defineCall("core.mcp.save-server", { scope: "plugin",
+  input: z.object({ server: mcpServerSchema, create: z.boolean(), credentials: mcpCredentialUpdateSchema }), output: z.null() });
+export const ReadMcpCredentials = defineCall("core.mcp.read-credentials", { scope: "plugin", input: z.object({ serverId: z.string() }), output: credentialsSchema });
+export const mcpToolSummarySchema = z.object({ name: z.string(), title: z.string().optional(), description: z.string().optional() });
+export type McpToolSummary = z.infer<typeof mcpToolSummarySchema>;
+export const ReadMcpTools = defineCall("core.mcp.read-tools", { scope: "plugin", input: z.object({ serverId: z.string() }),
+  output: z.object({ tools: z.array(mcpToolSummarySchema), instructions: z.string().optional() }).nullable() });
+export const SetMcpServerEnabled = defineCall("core.mcp.set-enabled", { scope: "plugin", input: z.object({ serverId: z.string(), enabled: z.boolean() }), output: z.null() });
+export const RemoveMcpServer = defineCall("core.mcp.remove-server", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.null() });
+export const ConnectMcpServer = defineCall("core.mcp.connect-server", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.null() });
+export const AuthorizeMcpServer = defineCall("core.mcp.authorize-server", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.object({ url: z.string() }) });
+export const DisconnectMcpServer = defineCall("core.mcp.disconnect-server", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.null() });
+export const ResetMcpAuth = defineCall("core.mcp.reset-auth", { scope: "plugin", input: z.object({ serverId: z.string() }), output: z.null() });
+
+export type McpErrorCode = "invalid_tool_id" | "server_not_found" | "server_disabled" | "tool_not_found" | "invalid_tool_arguments"
+  | "service_unavailable" | "connection_failed" | "authorization_expired" | "request_failed" | "tool_error";
+export class McpError extends Error {
+  readonly code: McpErrorCode;
+  constructor(code: McpErrorCode, message: string) { super(message); this.code = code; }
+}
+export class McpInterrupted extends Error {
+  readonly outcome: "cancelled" | "unknown";
+  constructor(outcome: "cancelled" | "unknown", message: string) { super(message); this.outcome = outcome; }
+}
+export function mcpToolIdentity(serverId: string, name: string): string { return `${serverId}/${name}`; }
+export function parseMcpToolIdentity(value: string): [string, string] {
+  const split = value.indexOf("/"), serverId = value.slice(0, split), name = value.slice(split + 1);
+  if (split < 1 || !name || !SERVER_ID_PATTERN.test(serverId)) throw new McpError("invalid_tool_id", "Tool identity uses the form server_id/tool_name.");
+  return [serverId, name];
+}

package/src/model-catalog.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { defineData } from "./presentation.ts";
+import { modelCostSchema } from "./model-cost.ts";
+import { thinkingSchema } from "./model-selection.ts";
+
+export const catalogModelSchema = z.object({
+  providerId: z.string(), modelId: z.string(), name: z.string(), enabled: z.boolean(),
+  contextWindow: z.number().nullable(), cost: modelCostSchema.nullable(),
+  generation: z.object({ maxOutputTokens: z.number().nullable() }),
+  capabilities: z.object({ reasoning: z.boolean(), tools: z.boolean(), thinkingLevels: z.array(thinkingSchema) }),
+});
+/** Configured model metadata for plugin selectors and diagnostics; credentials remain backend capabilities. */
+export const ModelCatalog = defineData("asterism.models/catalog", z.object({
+  modelProviders: z.array(z.object({ id: z.string(), name: z.string(), enabled: z.boolean() })),
+  models: z.array(catalogModelSchema),
+}));
+export type ModelCatalogSnapshot = z.infer<typeof ModelCatalog.schema>;
+export type CatalogModel = z.infer<typeof catalogModelSchema>;

package/src/model-provider.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { uiTextSchema, type UiText } from "./i18n.ts";
+import { jsonSchema, type Json } from "./json.ts";
+import { providerUsageIdSchema } from "./provider-usage.ts";
+
+export const modelProviderFixedFields = ["protocol", "baseUrl", "auth", "compatibility", "usage"] as const;
+export interface ModelProviderConnection {
+  protocol: "openai-responses" | "openai-chat" | "anthropic";
+  baseUrl: string;
+  auth: "api_key" | "none";
+  compatibility: { id: string; value?: Json }[];
+  usage?: string | null;
+  fixedFields?: (typeof modelProviderFixedFields)[number][];
+}
+export interface ModelProviderPreset {
+  id: string;
+  name: string;
+  billing: "usage" | "subscription" | "none";
+  region?: UiText;
+  plan?: UiText;
+  connection: ModelProviderConnection;
+  keyUrl?: string;
+  sources: readonly [string, ...string[]];
+  verifiedOn: string;
+  keywords?: readonly string[];
+}
+const webUrl = z.string().url().refine(value => ["http:", "https:"].includes(new URL(value).protocol));
+export const modelProviderConnectionSchema = z.strictObject({
+  protocol: z.enum(["openai-responses", "openai-chat", "anthropic"]),
+  baseUrl: webUrl, auth: z.enum(["api_key", "none"]),
+  compatibility: z.array(z.strictObject({ id: z.string().min(1), value: jsonSchema.optional() })),
+  usage: providerUsageIdSchema.nullable().optional(),
+  fixedFields: z.array(z.enum(modelProviderFixedFields)).optional(),
+});
+export const modelProviderPresetSchema = z.strictObject({
+  id: z.string().trim().min(1).max(160).regex(/^[^/\s]+$/u), name: z.string().trim().min(1).max(160),
+  billing: z.enum(["usage", "subscription", "none"]), region: uiTextSchema.optional(), plan: uiTextSchema.optional(),
+  connection: modelProviderConnectionSchema, keyUrl: webUrl.optional(),
+  sources: z.tuple([webUrl]).rest(webUrl), verifiedOn: z.iso.date(), keywords: z.array(z.string()).optional(),
+});
+/** patch overrides only explicit fields; connection merges by field, arrays are replaced as a whole, and saved connections are not rewritten. */
+export type ModelProviderPresetContribution =
+  | { type: "add"; preset: ModelProviderPreset }
+  | { type: "patch"; id: string; patch: Partial<Omit<ModelProviderPreset, "id" | "connection">> & { connection?: Partial<ModelProviderConnection> } };

package/src/models.ts

@@ -11,11 +11,9 @@ import type { ErrorDetails } from "./error-details.ts";
 /** Standard levels shared across the application; protocol encoding does not change public values. */
 export const thinkingLevels = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevel = typeof thinkingLevels[number];
-export interface ModelTarget { role: string; model?: string; thinking?: ThinkingLevel }
-export type PromptBlock =
-  | { id: string; kind: "system"; from: string; text: string }
-  | { id: string; kind: "agent"; role: string; text: string }
-  | { id: string; kind: "context"; file: string; text: string };
+export interface ModelTarget { provider: string; model: string; thinking?: ThinkingLevel }
+export interface PromptBlock { id: string; text: string; source?: { id: string; plugin: string | null } }
+export interface PromptFile { readonly file: string; readonly text: string }
 export interface SystemPrompt { blocks: readonly PromptBlock[] }
 /** Reasoning text is the plaintext delivered by the protocol, and summary is an independent summary; both can coexist or be empty, and neither fills the other.
  * continuation carries only native data such as signatures/ciphertext; target projection determines whether it can be reused.
@@ -94,7 +92,7 @@ export interface ModelRunRequest {
   userAgent?: string;
   requestParentId: string | null;
   target: ModelTarget;
-  system: SystemPrompt;
+  system: SystemPrompt | ((files: readonly PromptFile[]) => SystemPrompt);
   messages: ModelItem[];
   /** Filters plugin top-level tools and resource tools selected through actual links by name; does not affect fixed host entry points. */
   tools?: { allow?: readonly string[]; exclude?: readonly string[] };
@@ -132,6 +130,5 @@ export interface ModelServices {
   stream(request: StreamRequest, options?: ModelInputOptions): AsyncIterable<ModelEvent>;
   /** One request and its tool batch; neither saves history nor drives the next request. */
   run(request: ModelRunRequest): Promise<ModelRunResult>;
-  roles(): readonly { id: string; description: string; hidden: boolean; model: string | null; thinking: ThinkingLevel | null }[];
   list(): readonly { model: string; provider: string; name: string; contextWindow: number | null; capabilities: { reasoning: boolean; tools: boolean; thinkingLevels: readonly ThinkingLevel[] } }[];
 }

package/src/objects.ts

@@ -1,5 +1,5 @@
 import type { Json } from "./json.ts";
-import type { DataContract } from "./presentation.ts";
+import type { DataContract, Presentation } from "./presentation.ts";
 import type { RecordContract } from "./records.ts";
 import type { ResourceRef, ResourceCreationResult, ResourceSnapshot, SessionSnapshot } from "./workspace.ts";
 import type { ContentReader, ContentScope } from "./content-runtime.ts";
@@ -49,8 +49,8 @@ export interface SessionExecutor extends SessionReader {
   /** Append a resource rename event when the title changes; return the title with leading and trailing whitespace removed. */
   rename(resource: ResourceRef, title: string): string;
   commit(work: (writer: SessionWriter) => undefined): void;
-  /** set directly overwrites the session title; it can be called within a synchronous commit and commits or rolls back with it. */
-  readonly title: SessionReader["title"] & { set(text: string): void };
+  /** Append a host title assignment atomically, with optional plugin-owned detail. */
+  readonly title: SessionReader["title"] & { set(text: string, detail?: Presentation): void };
 }
 /**
  * An operation facade for the same session from the perspective of the tool caller and this request.

package/src/plugin.ts

@@ -55,4 +55,4 @@ export function pluginOf(qualified: string): string | null {
   return index > 0 ? qualified.slice(0, index) : null;
 }
 /** Resource projection for a missing implementation: preserves raw data and the source plugin for fallback UI display. */
-export const missingResourceContract = { id: "asterism.builtin/missing-resource" } as const;
+export const missingResourceContract = { id: "asterism.host/missing-resource" } as const;

package/src/provider-usage.ts

@@ -1,48 +1,8 @@
 import { z } from "zod";
-import { uiTextSchema, type UiText } from "./i18n.ts";
-import { jsonSchema, type Json } from "./json.ts";
+import { uiTextSchema } from "./i18n.ts";
 
-/** Usage queries and presets use global catalog IDs; connection identity is independent, and duplicate catalog identities must fail explicitly. */
+/** Usage implementations have global catalog identities, independent of configured model connections. */
 export const providerUsageIdSchema = z.string().trim().min(1).max(160).regex(/^\S+$/u);
-export const modelProviderFixedFields = ["protocol", "baseUrl", "auth", "compatibility", "usage"] as const;
-export interface ModelProviderConnection {
-  protocol: "openai-responses" | "openai-chat" | "anthropic";
-  baseUrl: string;
-  auth: "api_key" | "none";
-  compatibility: { id: string; value?: Json }[];
-  usage?: string | null;
-  fixedFields?: (typeof modelProviderFixedFields)[number][];
-}
-export interface ModelProviderPreset {
-  id: string;
-  name: string;
-  billing: "usage" | "subscription" | "none";
-  region?: UiText;
-  plan?: UiText;
-  connection: ModelProviderConnection;
-  keyUrl?: string;
-  sources: readonly [string, ...string[]];
-  verifiedOn: string;
-  keywords?: readonly string[];
-}
-const webUrl = z.string().url().refine(value => ["http:", "https:"].includes(new URL(value).protocol));
-export const modelProviderConnectionSchema = z.strictObject({
-  protocol: z.enum(["openai-responses", "openai-chat", "anthropic"]),
-  baseUrl: webUrl, auth: z.enum(["api_key", "none"]),
-  compatibility: z.array(z.strictObject({ id: z.string().min(1), value: jsonSchema.optional() })),
-  usage: providerUsageIdSchema.nullable().optional(),
-  fixedFields: z.array(z.enum(modelProviderFixedFields)).optional(),
-});
-export const modelProviderPresetSchema = z.strictObject({
-  id: z.string().trim().min(1).max(160).regex(/^[^/\s]+$/u), name: z.string().trim().min(1).max(160),
-  billing: z.enum(["usage", "subscription", "none"]), region: uiTextSchema.optional(), plan: uiTextSchema.optional(),
-  connection: modelProviderConnectionSchema, keyUrl: webUrl.optional(),
-  sources: z.tuple([webUrl]).rest(webUrl), verifiedOn: z.iso.date(), keywords: z.array(z.string()).optional(),
-});
-/** patch overrides only explicit fields; connection merges by field, arrays are replaced as a whole, and saved connections are not rewritten. */
-export type ModelProviderPresetContribution =
-  | { type: "add"; preset: ModelProviderPreset }
-  | { type: "patch"; id: string; patch: Partial<Omit<ModelProviderPreset, "id" | "connection">> & { connection?: Partial<ModelProviderConnection> } };
 
 const identity = {
   id: z.string().trim().min(1), label: uiTextSchema,

package/src/renderer-calls.ts

@@ -1,10 +1,14 @@
 import { createContext, useContext } from "react";
-import type { PluginCalls } from "./calls.ts";
+import type { CallContract, PluginCalls } from "./calls.ts";
+import type { RendererContentInput } from "./renderer-content.ts";
 
-const Calls = createContext<PluginCalls | null>(null);
+export interface RendererCalls extends PluginCalls<RendererContentInput> {
+  input(contract: CallContract): RendererContentInput;
+}
+const Calls = createContext<RendererCalls | null>(null);
 export const RendererCallsProvider = Calls.Provider;
 /** Invoke a registered backend contract; associating an object does not change resource ownership. */
-export function useRendererCalls(): PluginCalls {
+export function useRendererCalls(): RendererCalls {
   const calls = useContext(Calls);
   if (!calls) throw new Error("Renderer calls must be provided by the host.");
   return calls;

package/src/renderer-services.ts

@@ -68,8 +68,22 @@ export function useRendererConfiguration<T extends Json>(contract: ConfigContrac
   return { ...configs.get(contract), save: (value: T) => configs.save(contract, value), reset: () => configs.reset(contract), refresh: configs.refresh };
 }
 
-export interface RendererSettingsNavigation { open(pluginId: string, location?: string): void }
+export interface RendererSettingsNavigation {
+  open(pluginId: string, pageId: string, location?: string): void;
+  openHost(pageId: string): void;
+}
 const SettingsNavigation = createContext<RendererSettingsNavigation | null>(null);
 export const RendererSettingsNavigationProvider = SettingsNavigation.Provider;
 /** Open plugin settings without binding the current resource or session. */
 export function useRendererSettings(): RendererSettingsNavigation { return required(useContext(SettingsNavigation), "settings navigation"); }
+
+/** Application-wide frontend capabilities shared by plugin interfaces. */
+export interface RendererApplicationServices {
+  readonly platform: "darwin" | "win32" | "linux";
+  preferences(pluginId: string): import("./renderer-creation.ts").RendererPreferences;
+  pickDirectory(initialPath?: string): Promise<string | null>;
+  openLocalFile(path: string): Promise<void>;
+}
+const Application = createContext<RendererApplicationServices | null>(null);
+export const RendererApplicationProvider = Application.Provider;
+export function useRendererApplication(): RendererApplicationServices { return required(useContext(Application), "application"); }

package/src/renderer.ts

@@ -26,6 +26,7 @@ import type { CreationEntry } from "./renderer-creation.ts";
 import type { ToolRenderer } from "./renderer-tools.ts";
 import type { EventSubscriber } from "./events.ts";
 import type { PluginCalls } from "./calls.ts";
+import type { RendererCalls } from "./renderer-calls.ts";
 import type { ChannelContract, ChannelEnd, ChannelValue } from "./channels.ts";
 
 /** The frontend end of a channel: messages are delivered in order and buffered until a listener registers; closed resolves when either end terminates. */
@@ -84,8 +85,6 @@ export interface ResourceDescription {
   icon: ReactNode;
   /** Default card dimensions available before creation, sharing a declaration with the card renderer. */
   card?: CardAppearance;
-  /** This resource can be the endpoint of a directed link, matching backend links.receive. */
-  receivesLinks?: boolean;
 }
 export interface CardView extends CardAppearance {
   body: ReactNode;
@@ -108,21 +107,38 @@ export interface RendererModule {
   prepare?(context: RendererPrepareContext): Promise<void>;
 }
 export interface PluginSettingsPage {
+  /** Stable page identity within the contributing plugin. */
+  id: string;
+  title: UiText;
+  summary: UiText;
+  /** Icon component drawn by the host at its own size and color; the host uses a plugin icon when omitted. */
+  icon?: ComponentType<{ className?: string; "aria-hidden"?: boolean | "true" | "false" }>;
   /** A directly addressable location within a page; an empty location means the root page. */
   locations?: readonly string[];
   Body: ComponentType<{ location?: string }>;
 }
+export interface SessionEntryProps {
+  active: boolean;
+  ready: boolean;
+  open(sessionId: string): void;
+}
+export interface PluginSessionEntry {
+  id: string;
+  title: UiText;
+  Body: ComponentType<SessionEntryProps>;
+}
 /** Frontend plugins own settings pages and shared service lifecycles; feature views are composed from modules. */
 export interface RendererPlugin {
   modules?: readonly RendererModule[];
-  settings?: PluginSettingsPage;
+  settings?: readonly PluginSettingsPage[];
+  sessionEntries?: readonly PluginSessionEntry[];
   prepare?(context: RendererPrepareContext): Promise<void>;
   closing?(): void | Promise<void>;
 }
 export function defineRendererPlugin(plugin: RendererPlugin): RendererPlugin { return plugin; }
 export interface RendererPrepareContext {
   /** Typed calls for frontend module-level services; cancellation propagates with the preparation scope. */
-  readonly calls: PluginCalls;
+  readonly calls: RendererCalls;
   /** Global subscriptions bound to the module lifecycle, cleaned up on failure, timeout, or application shutdown. */
   readonly events: EventSubscriber;
   /** Triggered when the host stops waiting due to timeout or shutdown; the module should stop promptly. */

package/src/runtime-agent-catalog.ts

@@ -0,0 +1,27 @@
+import type { PluginModule } from "./runtime-contracts.ts";
+
+/** The host stamps plugin provenance; a null plugin identifies a user directory. */
+export type AgentSource = { id: string; plugin: string | null; directory: string };
+export type AgentSkill = { name: string; description: string; directory: string; source: AgentSource };
+export type AgentSkillSource = AgentSource & {
+  skills: AgentSkill[];
+  issues: { file: string; message: string }[];
+};
+export type AgentInstruction = { id: string; plugin: string; text: string };
+export interface AgentSkillDeclaration { id: string; path: string }
+export interface AgentInstructionDeclaration { id: string; text: string }
+export interface AgentCatalog {
+  skills(): readonly AgentSkillSource[];
+  instructions(): readonly AgentInstruction[];
+  refresh(signal: AbortSignal): readonly AgentSkillSource[];
+  /** Read current UTF-8 contents from the captured skill package, independently of later catalog refreshes. */
+  read(skill: AgentSkill, path: string, signal: AbortSignal): Promise<string>;
+}
+/** Package-relative skill directories; the host supplies the actual contributor identity. */
+export function defineAgentSkills(entries: readonly AgentSkillDeclaration[]): PluginModule {
+  return { setup: () => ({ agentSkills: entries }) };
+}
+/** Fixed instruction contributions, assembled into requests by the consuming paradigm. */
+export function defineAgentInstructions(entries: readonly AgentInstructionDeclaration[]): PluginModule {
+  return { setup: () => ({ agentInstructions: entries }) };
+}

package/src/runtime-application.ts

@@ -0,0 +1,7 @@
+/** One directory exposed under a distinct relative path in the manual catalog. */
+export interface ManualSource {
+  readonly path: string;
+  readonly directory: string;
+}
+export interface ManualCatalog { sources(): readonly ManualSource[] }
+export interface ApplicationIdentity { readonly name: string; readonly userAgent: string }

package/src/runtime-calls.ts

@@ -3,11 +3,13 @@ import type { z } from "zod";
 import type { Json } from "./json.ts";
 import type { ObjectReader } from "./objects.ts";
 import type { Source } from "./workspace.ts";
+import type { ContentReader } from "./content-runtime.ts";
 
 export type CallContext<S extends CallScope = CallScope> = {
   /** The host binds the source for backend plugin calls; null for desktop user calls. */
   readonly source: Source;
   readonly signal: AbortSignal;
+  readonly content: ContentReader;
 } & (S extends "object" ? { readonly object: ObjectReader } : { readonly object?: never });
 export interface CallContribution {
   readonly contract: CallContract;

package/src/runtime-contracts.ts

@@ -20,9 +20,12 @@ import type { PluginCalls } from "./calls.ts";
 import type { CallContribution } from "./runtime-calls.ts";
 import type { ChannelContribution } from "./runtime-channels.ts";
 import type { TopLevelTool } from "./runtime-tools.ts";
-import type { ModelProviderServices, UsageProviderServices, UsageProvider, UsageServices } from "./runtime-providers.ts";
+import type { ModelProviderServices } from "./runtime-model-providers.ts";
+import type { UsageProviderServices, UsageProvider, UsageServices, ProviderUsage } from "./runtime-usage.ts";
 import type { WebServices, WebProviderServices, WebProviderDefinition } from "./runtime-web.ts";
-import type { ModelProviderPresetContribution } from "./provider-usage.ts";
+import type { ModelProviderPresetContribution } from "./model-provider.ts";
+import type { AgentCatalog, AgentSkillDeclaration, AgentInstructionDeclaration } from "./runtime-agent-catalog.ts";
+import type { SessionCreation } from "./runtime-sessions.ts";
 export type * from "./objects.ts";
 export type { ResourceRef, ResourceCreationResult, ResourceSnapshot, SessionSnapshot } from "./workspace.ts";
 
@@ -36,11 +39,19 @@ export interface Lifetime {
   defer(cleanup: () => void | Promise<void>): void;
 }
 export interface PluginContext {
+  readonly mcp: import("./runtime-mcp.ts").McpServices;
+  readonly shell: import("./runtime-shell.ts").ShellServices;
+  readonly application: import("./runtime-application.ts").ApplicationIdentity;
+  readonly manual: import("./runtime-application.ts").ManualCatalog;
   readonly id: string;
   /** Plugin-level lifecycle: lasts as long as the host runtime instance; shared plugin services such as connection pools, subscriptions, and public registrations belong here. */
   readonly lifetime: Lifetime;
   readonly sessions: SessionDirectory;
+  readonly createSession: SessionCreation;
   readonly dir: string;
+  /** Resolve a package-relative asset, independently of writable plugin data. */
+  readonly assets: { path(relativePath: string): string };
+  readonly agentCatalog: AgentCatalog;
   readonly log: PluginLogger;
   readonly ipc: { readonly events: PluginEvents; readonly calls: PluginCalls };
   config<T extends Json>(contract: ConfigContract<T>): PluginConfig<T>;
@@ -51,9 +62,9 @@ export interface PluginContext {
   readonly modelProviders: ModelProviderServices;
   readonly usageProviders: UsageProviderServices;
   readonly usages: UsageServices;
+  readonly providerUsage: ProviderUsage;
   readonly webProviders: WebProviderServices;
   readonly web: WebServices;
-  readonly catalogs: { get<T extends Json>(contract: DataContract<T>): T | null };
   session(id: string): SessionExecutor;
   /** Obtain an object handle using a named resource contract; the host validates plugin ownership of the contract, object existence, and matching type, and stamps records accordingly. */
   object<S extends Json>(sessionId: string, contract: ResourceContract<S>, id: string): ObjectExecutor;
@@ -103,7 +114,11 @@ export interface ResourceContribution {
   readonly card?: CardAppearance;
   readonly records: readonly RecordContract[];
   /** Opt into templates that copy encoded resource state and only these current-data contracts, preserving their values under new host identities. */
-  readonly template?: { readonly current: readonly DataContract[] };
+  readonly template?: {
+    readonly current: readonly DataContract[];
+    /** Omit the source title when saving; generate a title for each template instance, overriding any previously saved title. */
+    createTitle?(): string;
+  };
   /** Declare that this resource can receive links and provide the recipient's tool policy; independent of Agent domain types. */
   readonly links?: { receive: boolean; tools?(object: ObjectReader): { allow?: readonly string[]; exclude?: readonly string[] } };
   readonly creation?: CreationContribution;
@@ -135,9 +150,13 @@ export interface ToolInvocation extends ToolInvocationInfo {
 }
 export interface ToolContribution {
   readonly contract: ImplementationContract<Json, Json, Json, Json>;
+  /** Bind resource-specific access and configuration at the model request boundary. The returned contribution handles that request's calls. */
+  capture?(resource: ResourceSnapshot, object: ObjectReader, caller: ToolCaller): ToolContribution;
   prepare(resource: ResourceSnapshot, object: ObjectExecutor, target: Json, args: Json, caller: ToolCaller): ToolInvocation | PreparedResult;
 }
 export interface ModuleContribution {
+  agentSkills?: readonly AgentSkillDeclaration[];
+  agentInstructions?: readonly AgentInstructionDeclaration[];
   webProviders?: readonly WebProviderDefinition[];
   usageProviders?: readonly UsageProvider[];
   modelProviderPresets?: readonly ModelProviderPresetContribution[];

package/src/runtime-mcp.ts

@@ -0,0 +1,24 @@
+import type { Json } from "./json.ts";
+import type { McpCatalogServer, McpServerState } from "./mcp.ts";
+
+export type McpContent =
+  | { type: "text"; text: string }
+  | { type: "image" | "audio"; data: string; mimeType: string }
+  | { type: "resource"; resource: { uri: string; mimeType?: string } & ({ text: string } | { blob: string }) }
+  | { type: "resource_link"; uri: string; name: string; description?: string };
+export interface McpCallResult { content: McpContent[]; structuredContent?: unknown; isError?: boolean }
+export interface McpProgress { progress: number; total?: number; message?: string }
+/** Bound to the server instance and tool identity captured by resolve. */
+export interface McpToolHandle {
+  readonly serverId: string;
+  readonly serverName: string;
+  readonly toolName: string;
+  call(args: Record<string, Json>, options: { signal: AbortSignal; progress(value: McpProgress): void }): Promise<McpCallResult>;
+}
+export interface McpServices {
+  states(): McpServerState[];
+  catalog(): McpCatalogServer[];
+  connect(serverId: string, signal: AbortSignal): Promise<void>;
+  resolve(toolId: string): McpToolHandle;
+  subscribe(listener: () => void): () => void;
+}

package/src/runtime-model-providers.ts

@@ -0,0 +1,16 @@
+import type { ModelProviderConnection, ModelProviderPreset } from "./model-provider.ts";
+
+export interface ModelProviderServices {
+  presets(): readonly ModelProviderPreset[];
+  list(): readonly ModelProviderInfo[];
+  get(id: string): ModelProviderInfo | null;
+  /** Backend only; reads the connection's current credentials, returning null for connections without authentication. */
+  credential(id: string, options?: { signal?: AbortSignal }): Promise<string | null>;
+  /** Connection or preset catalog changes; returns an unsubscribe function and unsubscribes automatically when the plugin closes. */
+  subscribe(listener: () => void): () => void;
+}
+export interface ModelProviderInfo extends ModelProviderConnection {
+  id: string;
+  name: string;
+  enabled: boolean;
+}

package/src/runtime-sessions.ts

@@ -0,0 +1,36 @@
+import type { Json } from "./json.ts";
+import type { ActionContract, CreationContract } from "./commands.ts";
+import type { ResourceContract } from "./module-contract.ts";
+import type { ContentReader } from "./content-runtime.ts";
+import type { ObjectReader, ObjectWriter, SessionReader } from "./objects.ts";
+import type { ResourceCreationResult } from "./workspace.ts";
+
+declare const prepared: unique symbol;
+/** Host-issued resource preparation, valid only within one session creation attempt. */
+export interface PreparedCreation { readonly [prepared]: true }
+export interface SessionPreparation {
+  readonly signal: AbortSignal;
+  prepare<I, S extends Json, O extends Json>(contract: CreationContract<I, S, O>, input: NoInfer<I> & Json): Promise<PreparedCreation>;
+  /** Run action parsing and registered preparers for a resource awaiting initialization; this does not execute the action. */
+  prepareAction<I, O extends Json>(resource: PreparedCreation, contract: ActionContract<I, O>, input: NoInfer<I> & Json): Promise<O>;
+}
+export interface ObjectInitializer extends ObjectReader {
+  commit(work: (writer: ObjectWriter) => undefined): void;
+}
+export interface SessionInitializer extends SessionReader {
+  /** Materialize each prepared resource once, preserving its preparation identity. */
+  create(prepared: PreparedCreation): ResourceCreationResult;
+  object<S extends Json>(contract: ResourceContract<S>, id: string): ObjectInitializer;
+}
+export interface SessionInitialization {
+  title: string;
+  /** Synchronous initialization commits session identity, resources, and initial records together. */
+  initialize(session: SessionInitializer): undefined;
+}
+export interface SessionCreation {
+  /** The key identifies one accepted creation within this plugin; retries return its existing session. */
+  (key: string, prepare: (context: SessionPreparation) => Promise<SessionInitialization>, options?: {
+    signal?: AbortSignal;
+    content?: ContentReader;
+  }): Promise<string>;
+}

package/src/runtime-shell.ts

@@ -0,0 +1,18 @@
+import type { Json } from "./json.ts";
+import type { CallResult } from "./runtime-contracts.ts";
+import type { ExecResult, ShellSettings, ShellProfileList } from "./shell.ts";
+import type { TerminalSessions } from "./runtime-terminal.ts";
+
+export interface ShellProfiles { get(): ShellSettings; list(): Promise<ShellProfileList> }
+/** One noninteractive shell command with piped output and its own process lifetime. */
+export interface ShellExecution {
+  inspect(): Promise<Json>;
+  execute(cwd: string, args: { command: string; timeout?: number }, options: {
+    signal: AbortSignal; publish(data: ExecResult): void;
+  }): Promise<CallResult<ExecResult>>;
+}
+/** Host shell capabilities share configured profiles; plugins own how they compose commands and terminal sessions. */
+export interface ShellServices extends ShellExecution {
+  readonly profiles: ShellProfiles;
+  readonly terminals: TerminalSessions;
+}

package/src/runtime-terminal.ts

@@ -0,0 +1,24 @@
+import type { TerminalConfig, TerminalDown, TerminalUp, TerminalStatus, TerminalImage } from "./terminal.ts";
+
+export interface TerminalViewer { send(frame: TerminalDown): void }
+export class TerminalError extends Error { constructor(readonly code: string, message: string) { super(message); } }
+export interface InteractiveTerminal {
+  readonly status: TerminalStatus;
+  readonly started: boolean;
+  readonly applicationCursor: boolean;
+  start(): Promise<void>;
+  close(): Promise<void>;
+  dispose(): Promise<void>;
+  attach(viewer: TerminalViewer): (message: TerminalUp) => void;
+  detach(viewer: TerminalViewer): void;
+  input(data: string, signal: AbortSignal): Promise<TerminalStatus>;
+  read(source: "screen" | "history" | "raw", offset?: number, limit?: number): Promise<TerminalStatus & {
+    source: "screen" | "history" | "raw"; text: string; cols: number; rows: number;
+    cursor: { x: number; y: number }; offset: number; nextOffset: number; truncated: boolean;
+  }>;
+  image(): Promise<TerminalImage>;
+  waitIdle(timeout: number, signal: AbortSignal): Promise<TerminalStatus & { reason: string; elapsedMs: number }>;
+}
+export interface TerminalSessions {
+  create(config: TerminalConfig, events: { failed(error: unknown): void; log(message: string, error: unknown): void }): InteractiveTerminal;
+}

package/src/{runtime-providers.ts → runtime-usage.ts}

@@ -1,5 +1,7 @@
-import type { ModelProviderConnection, ModelProviderPreset, ProviderUsageError, UsageItem, UsageProviderInfo } from "./provider-usage.ts";
+import type { ProviderUsageError, UsageItem, UsageProviderInfo } from "./provider-usage.ts";
 import type { UiText } from "./i18n.ts";
+import type { ProviderUsageState } from "./usage-state.ts";
+import type { ModelResponse } from "./models.ts";
 
 /** Consumers explicitly supply the connection and credentials required for the query. */
 export interface UsageQueryContext {
@@ -33,20 +35,6 @@ export type UsageProvider = QueryUsageProvider | HeadersUsageProvider;
 export class UsageQueryError extends Error {
   constructor(readonly code: ProviderUsageError) { super(`Provider usage query failed: ${code}.`); }
 }
-export interface ModelProviderServices {
-  presets(): readonly ModelProviderPreset[];
-  list(): readonly ModelProviderInfo[];
-  get(id: string): ModelProviderInfo | null;
-  /** Backend only; reads the connection's current credentials, returning null for connections without authentication. */
-  credential(id: string, options?: { signal?: AbortSignal }): Promise<string | null>;
-  /** Connection or preset catalog changes; returns an unsubscribe function and unsubscribes automatically when the plugin closes. */
-  subscribe(listener: () => void): () => void;
-}
-export interface ModelProviderInfo extends ModelProviderConnection {
-  id: string;
-  name: string;
-  enabled: boolean;
-}
 export interface UsageProviderServices {
   list(): readonly UsageProviderInfo[];
   /** Obtain an implementation bound to the provider lifecycle; does not select connections, read credentials, or save results. */
@@ -58,3 +46,9 @@ export interface UsageServices {
   query(providerId: string, context: UsageQueryContext): Promise<UsageItem[]>;
   parseHeaders(providerId: string, context: UsageHeadersContext): UsageItem[] | null;
 }
+
+/** Host cache and shared queries; consumers supply response headers they obtained themselves. */
+export interface ProviderUsage {
+  query(id: string, options?: { signal?: AbortSignal; refresh?: boolean }): Promise<ProviderUsageState>;
+  consume(response: ModelResponse): void;
+}

package/src/runtime.ts

@@ -7,8 +7,11 @@ export * from "./runtime-resources.ts";
 export * from "./runtime-calls.ts";
 export * from "./runtime-channels.ts";
 export * from "./runtime-tools.ts";
-export * from "./runtime-providers.ts";
+export type * from "./runtime-model-providers.ts";
+export * from "./runtime-usage.ts";
 export * from "./runtime-web.ts";
+export * from "./runtime-agent-catalog.ts";
+export * from "./runtime-sessions.ts";
 export type * from "./content-runtime.ts";
 export type * from "./models.ts";
 export { validationMessage, jsonArgumentHint } from "./tool-validation.ts";
@@ -42,3 +45,9 @@ export interface PluginTasks {
   cancel(key: string): void;
   has(key: string): boolean;
 }
+
+export type * from "./runtime-application.ts";
+
+export * from "./runtime-shell.ts";
+export * from "./runtime-terminal.ts";
+export type * from "./runtime-mcp.ts";

package/src/session-title.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { defineRecord } from "./records.ts";
+import { presentationSchema } from "./presentation.ts";
+
+/** Immutable title assignment; optional detail belongs to the plugin that produced it. */
+export const SessionTitleAssigned = defineRecord("asterism.session/title", {
+  schema: z.strictObject({ title: z.string().trim().min(1).max(160), detail: presentationSchema.optional() }),
+});

package/src/shell.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { defineCall } from "./calls.ts";
+import { defineData } from "./presentation.ts";
+
+export const OUTPUT_CHAR_LIMIT = 16_384;
+export const MAX_TIMEOUT_SECONDS = 2_147_483_647 / 1000;
+
+/** Startup arguments and command arguments are separate, allowing a profile to be shared across different shell usage modes. */
+export const shellProfileSchema = z.strictObject({
+  id: z.string().trim().min(1).max(160).regex(/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/u).refine(value => value !== "auto", "The profile ID 'auto' is reserved."),
+  executable: z.string().trim().min(1),
+  args: z.array(z.string()),
+  commandArgs: z.array(z.string()),
+  env: z.record(z.string(), z.string()),
+});
+export type ShellProfile = z.infer<typeof shellProfileSchema>;
+
+export const shellPresets: ShellProfile[] = [
+  { id: "pwsh", executable: "pwsh", args: [], commandArgs: ["-NonInteractive", "-Command"], env: {} },
+  { id: "nu", executable: "nu", args: ["-l"], commandArgs: ["-c"], env: {} },
+  { id: "fish", executable: "fish", args: [], commandArgs: ["-c"], env: {} },
+  { id: "zsh", executable: "zsh", args: [], commandArgs: ["-c"], env: {} },
+  { id: "bash", executable: "bash", args: [], commandArgs: ["-c"], env: {} },
+  { id: "sh", executable: "sh", args: [], commandArgs: ["-c"], env: {} },
+];
+export const defaultShellSettings = { selected: "auto", profiles: shellPresets };
+export const shellSettingsSchema = z.strictObject({
+  selected: z.string().min(1),
+  profiles: z.array(shellProfileSchema),
+}).superRefine((value, ctx) => {
+  const ids = new Set<string>();
+  value.profiles.forEach((profile, index) => {
+    if (ids.has(profile.id)) ctx.addIssue({ code: "custom", path: ["profiles", index, "id"], message: "Shell profile IDs must be unique." });
+    ids.add(profile.id);
+  });
+  if (value.selected !== "auto" && !ids.has(value.selected))
+    ctx.addIssue({ code: "custom", path: ["selected"], message: "Select an existing shell profile or auto." });
+});
+export type ShellSettings = z.infer<typeof shellSettingsSchema>;
+export const ShellProfilesCatalog = defineData("asterism.shell/profiles", shellSettingsSchema);
+
+export const shellProfileListSchema = z.strictObject({
+  selected: z.string(),
+  resolvedProfile: z.string().nullable(),
+  profiles: z.array(z.strictObject({
+    id: z.string(),
+    executable: z.string(),
+    args: z.array(z.string()),
+    commandArgs: z.array(z.string()),
+    available: z.boolean(),
+    resolvedExecutable: z.string().nullable(),
+  })),
+});
+export type ShellProfileList = z.infer<typeof shellProfileListSchema>;
+
+export const shellOutputSchema = z.strictObject({
+  output: z.string(),
+  truncation: z.strictObject({
+    totalChars: z.number().int().nonnegative(),
+    retainedChars: z.number().int().nonnegative(),
+    file: z.string(),
+  }).nullable(),
+});
+export type ShellOutput = z.infer<typeof shellOutputSchema>;
+export const execResultSchema = shellOutputSchema.extend({
+  shell: z.string(),
+  termination: z.enum(["running", "exited", "timeout", "cancelled", "spawn_error", "io_error"]),
+  exitCode: z.number().int().nullable(),
+  signal: z.string().nullable(),
+  durationMs: z.number().nonnegative(),
+});
+export type ExecResult = z.infer<typeof execResultSchema>;
+
+export const ReadShellProfiles = defineCall("core.shell.profiles.read", {
+  scope: "plugin", input: z.strictObject({}), output: shellProfileListSchema,
+});

package/src/terminal.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+export const terminalStateSchema = z.enum(["inactive", "starting", "idle", "running", "unknown", "exited", "failed"]);
+export type TerminalState = z.infer<typeof terminalStateSchema>;
+export const terminalConfigSchema = z.strictObject({ cwd: z.string(), profile: z.string() });
+export type TerminalConfig = z.infer<typeof terminalConfigSchema>;
+
+export const terminalStatusSchema = z.strictObject({
+  state: terminalStateSchema, shell: z.string().nullable(), integration: z.boolean(),
+  exitCode: z.number().nullable(), error: z.string().nullable(),
+  /** Current directory reported by shell integration; null without integration. */
+  cwd: z.string().nullable(),
+  /** Exit code of the latest foreground command; null without integration or before any command has run. */
+  lastExitCode: z.number().nullable(),
+});
+export type TerminalStatus = z.infer<typeof terminalStatusSchema>;
+export const inactiveStatus: TerminalStatus = { state: "inactive", shell: null, integration: false, exitCode: null, error: null, cwd: null, lastExitCode: null };
+
+/** Terminal channel: the frontend sends input, dimensions, and rendered-character acknowledgments; the backend sends screen resets, output, dimensions, and status, all delivered in order. */
+export type TerminalUp =
+  | { type: "input"; data: string }
+  /** xterm binary input (such as X10 mouse reports), with each character representing one byte. */
+  | { type: "binary"; data: string }
+  | { type: "resize"; cols: number; rows: number }
+  | { type: "ack"; chars: number }
+  /** The frontend screen has remounted and requests a current screen snapshot. */
+  | { type: "refresh" };
+export type TerminalDown =
+  | { type: "reset"; cols: number; rows: number; data: string }
+  | { type: "output"; data: string }
+  | { type: "resize"; cols: number; rows: number }
+  | { type: "status"; status: TerminalStatus };
+
+const cellSchema = z.strictObject({ text: z.string(), width: z.number(), fg: z.string(), bg: z.string(), bold: z.boolean(), italic: z.boolean(), underline: z.boolean(), strike: z.boolean() });
+export const terminalImageSchema = z.strictObject({ cols: z.number(), rows: z.number(), cursor: z.strictObject({ x: z.number(), y: z.number(), visible: z.boolean() }), cells: z.array(z.array(cellSchema)) });
+export type TerminalImage = z.infer<typeof terminalImageSchema>;

package/src/usage-state.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { defineCall } from "./calls.ts";
+import { defineEvent } from "./events.ts";
+import { providerUsageIdSchema, usageItemsSchema, providerUsageErrorSchema } from "./provider-usage.ts";
+
+/** Shared provider usage state; response consumption remains explicit. */
+export const providerUsageStateSchema = z.strictObject({
+  providerId: z.string(), usage: providerUsageIdSchema.nullable(),
+  source: z.enum(["query", "headers"]).optional(), model: z.string().optional(),
+  state: z.enum(["disabled", "waiting", "loading", "ready", "error"]),
+  items: usageItemsSchema, updatedAt: z.number().nonnegative().nullable(), error: providerUsageErrorSchema.nullable(),
+});
+export type ProviderUsageState = z.infer<typeof providerUsageStateSchema>;
+export const ReadUsage = defineCall("core.usage.read", {
+  scope: "plugin", input: z.strictObject({ providerId: z.string(), refresh: z.boolean() }), output: providerUsageStateSchema,
+});
+export const UsageChanged = defineEvent("core.usage.changed", {
+  schema: z.strictObject({ providerId: z.string().nullable() }),
+  source: "host", semantics: { kind: "snapshot", key: ["providerId"] },
+});