@acid-cat/core-ts 0.3.0 → 0.4.0

package/README.md

@@ -35,9 +35,10 @@ export const aircon = defineApp<{ unit: Unit }>({
 
 - `run` gets the input, an `AbortSignal` and the context. It returns `ok(value)` or `fail(tag, data)`. If it throws, the call fails as `internal`.
 - A failure schema describes the whole failure object, with its `_tag`.
-- `availability` is an optional function that returns an observable availability.
+- `availability` is an optional function that returns an observable availability. A session reads it with `getSnapshot` when a call comes in. It subscribes to it only while `onChange` or the handle has listeners.
 - `state` is an optional `{ schema, source }`: the schema of the [state](../../spec/invocation.md#state), and a function that returns an observable. The handle gives it as `snapshot`.
 - `capabilitiesFor<Context>()` sets the context type one time. The other types come from the schemas.
+- `defineCapability` and `capabilitiesFor` keep the literal type of `id`, so that an application can type its ids. `run`, `availability` and `state` all get the same `Context`.
 
 ## Write the catalog
 
@@ -60,6 +61,20 @@ Standard Schema does not convert to JSON Schema. Give the converter of your sche
 | `cliMain(app, options)`, `runCli(…)` | [CLI](../../spec/bindings/cli.md) | The command line of the process, or an exit code |
 | `installWebMcp(session)` | [WebMCP](../../spec/bindings/webmcp.md) | Tools in the page, with a status |
 
+When the signal of a request aborts, `mcpHandler` and `httpHandler` cancel the call of the request.
+
+### Typed handles
+
+`getHandle(session.handles, capability)` gives the handle of a capability with the types of its schemas. For a capability outside the view, the handle is always unavailable, and each call rejects as `unknown-capability`.
+
+```ts
+import { createSession, getHandle } from "@acid-cat/core-ts";
+
+const session = createSession(aircon, { target: "app", context: { unit }, toJsonSchema });
+const power = getHandle(session.handles, powerSet); // HandleOf<typeof powerSet>
+const result = await power.execute({ on: true }); // Result<null, { _tag: "Offline"; since?: string }>
+```
+
 ### Context for each request
 
 `mcpHandler` and `httpHandler` take `context` or `createContext`. With `context`, all requests share one context. With `createContext(request)`, the handler makes a new context for each request that passes the screening. Use it when a request must not use objects that an earlier request made, for example on Cloudflare Workers, or when a stateful service must not be shared between callers. When the context has `Symbol.asyncDispose` or `Symbol.dispose`, the handler calls it after the response:
@@ -84,6 +99,26 @@ const handler = httpHandler(aircon, {
 });
 ```
 
+### Commands of the application
+
+The option `commands` of `cliMain` and `runCli` adds commands of the application beside the commands of the capabilities, `call` and `list`. A command has a `name`, a `description` for the help, and `run(args, io)`. `run` gets the arguments after the name of the command, and `io` with `stdout`, `stderr`, `signal` and the `context`. It returns the exit code. The name must not be `call`, `list`, the name of another command of the application, or the first word of the command of a capability. If it is, `runCli` throws. The option `description` gives the text at the top of the help. The default is the description of the application, then its title, then the name of the program.
+
+```ts
+import { cliMain } from "@acid-cat/core-ts";
+import type { CliCommand } from "@acid-cat/core-ts";
+
+const report: CliCommand<{ unit: Unit }> = {
+  name: "report",
+  description: "Write the temperature of the room.",
+  run: (_args, { context, stdout }) => {
+    stdout(`The room is at ${context.unit.state.roomCelsius} °C.`);
+    return 0;
+  },
+};
+
+cliMain(aircon, { name: "aircon", version: "0.1.0", context: { unit }, toJsonSchema, description: "Control the air conditioner.", commands: [report] });
+```
+
 ## Examples and tests
 
 - [`examples/aircon.ts`](examples/aircon.ts) is the air conditioner of [`examples/aircon.pkl`](../../examples/aircon.pkl), with a simulated unit. Its catalog agrees with the Pkl catalog.

package/dist/app.d.ts

@@ -7,8 +7,12 @@ export interface Observable<T> {
         unsubscribe(): void;
     };
 }
-type Output<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : null;
-type FailureOf<F> = {
+/** The input that `run` receives: the output of the input schema, or an empty object. */
+export type InputOf<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : Record<string, never>;
+/** The value of a successful call: the output of the output schema, or `null`. */
+export type Output<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : null;
+/** The failures, each with its `_tag`. */
+export type FailureOf<F> = {
     [Tag in keyof F]: {
         readonly _tag: Tag;
     } & (F[Tag] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<F[Tag]> : object);
@@ -17,13 +21,16 @@ export interface Capability<Context = unknown, Input extends StandardSchemaV1 |
     readonly [tag: string]: StandardSchemaV1;
 } = {
     readonly [tag: string]: StandardSchemaV1;
-}> {
-    readonly id: string;
+}, StateSchema extends StandardSchemaV1 = StandardSchemaV1, Id extends string = string> {
+    readonly id: Id;
     readonly description: string;
     /** The targets that can use the capability. With no audience, no target can use it. */
     readonly audience: readonly string[];
     readonly readOnly?: boolean | undefined;
-    /** The input: an object schema. With no input schema, the input is an empty object. */
+    /**
+     * The input: an object schema, or a union of object schemas. The catalog writes a union with `"type": "object"`. With
+     * no input schema, the input is an empty object.
+     */
     readonly input?: Input;
     /** The value of a successful call. With no output schema, the value is `null`. */
     readonly output?: OutputSchema;
@@ -31,21 +38,21 @@ export interface Capability<Context = unknown, Input extends StandardSchemaV1 |
     readonly failures?: Failures;
     /** A value that clients can observe (spec/invocation.md#state): its schema, and its source. */
     readonly state?: {
-        readonly schema: StandardSchemaV1;
-        readonly source: (context: Context) => Observable<unknown>;
+        readonly schema: StateSchema;
+        readonly source: (context: Context) => Observable<StandardSchemaV1.InferOutput<StateSchema>>;
     } | undefined;
     /** The availability of the capability. With none, the capability is always available. */
     readonly availability?: ((context: Context) => Observable<Availability>) | undefined;
-    readonly run: (input: Input extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Input> : Record<string, never>, call: {
+    readonly run: (input: InputOf<Input>, call: {
         readonly signal: AbortSignal;
         readonly context: Context;
     }) => Promise<Result<Output<OutputSchema>, FailureOf<Failures>>> | Result<Output<OutputSchema>, FailureOf<Failures>>;
 }
-export type AnyCapability<Context = any> = Capability<Context, any, any, any>;
-/** Declare a capability. `Context` is the type of the services that `run` receives. */
+export type AnyCapability<Context = any> = Capability<Context, any, any, any, any>;
+/** Declare a capability. `Context` is the type of the services that `run` receives. The id keeps its literal type. */
 export declare const defineCapability: <Context = unknown, Input extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Failures extends {
     readonly [tag: string]: StandardSchemaV1;
-} = {}>(capability: Capability<Context, Input, OutputSchema, Failures>) => Capability<Context, Input, OutputSchema, Failures>;
+} = {}, StateSchema extends StandardSchemaV1 = never, const Id extends string = string>(capability: Capability<Context, Input, OutputSchema, Failures, StateSchema, Id>) => Capability<Context, Input, OutputSchema, Failures, StateSchema, Id>;
 /**
  * Declare capabilities for one context type. The other types come from the schemas:
  *
@@ -56,7 +63,7 @@ export declare const defineCapability: <Context = unknown, Input extends Standar
  */
 export declare const capabilitiesFor: <Context>() => <Input extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Failures extends {
     readonly [tag: string]: StandardSchemaV1;
-} = {}>(capability: Capability<Context, Input, OutputSchema, Failures>) => Capability<Context, Input, OutputSchema, Failures>;
+} = {}, StateSchema extends StandardSchemaV1 = never, const Id extends string = string>(capability: Capability<Context, Input, OutputSchema, Failures, StateSchema, Id>) => Capability<Context, Input, OutputSchema, Failures, StateSchema, Id>;
 export interface Target {
     readonly bindings: readonly string[];
     readonly description?: string | undefined;
@@ -74,7 +81,10 @@ export interface App<Context = unknown> {
 export declare const defineApp: <Context = unknown>(app: App<Context>) => App<Context>;
 /** Converts a schema to JSON Schema 2020-12, for example `(schema) => z.toJSONSchema(schema)` with Zod. */
 export type ToJsonSchema = (schema: StandardSchemaV1) => JsonObject;
-/** The catalog of an application, as a JSON document. */
+/**
+ * The catalog of an application, as a JSON document. The catalog is written one time for each application and
+ * `toJsonSchema`. Later calls with the same two give the same document.
+ */
 export declare function catalogOf(app: App<any>, options: {
     readonly toJsonSchema: ToJsonSchema;
 }): CatalogDocument;
@@ -82,4 +92,3 @@ export declare function catalogOf(app: App<any>, options: {
 export declare const renderCatalog: (app: App<any>, options: {
     readonly toJsonSchema: ToJsonSchema;
 }) => string;
-export {};

package/dist/app.js

@@ -1,10 +1,11 @@
 import { canonicalText } from "@acid-cat/catalog";
+import { objectInput } from "@acid-cat/spec-ts";
 //#region src/app.ts
 /**
 * Capabilities and applications in plain TypeScript. An application writes its own catalog.
 * See spec/catalog.md.
 */
-/** Declare a capability. `Context` is the type of the services that `run` receives. */
+/** Declare a capability. `Context` is the type of the services that `run` receives. The id keeps its literal type. */
 const defineCapability = (capability) => capability;
 /**
 * Declare capabilities for one context type. The other types come from the schemas:
@@ -17,11 +18,28 @@ const defineCapability = (capability) => capability;
 const capabilitiesFor = () => (capability) => capability;
 /** Declare an application. */
 const defineApp = (app) => app;
-/** The catalog of an application, as a JSON document. */
+const catalogs = /* @__PURE__ */ new WeakMap();
+/**
+* The catalog of an application, as a JSON document. The catalog is written one time for each application and
+* `toJsonSchema`. Later calls with the same two give the same document.
+*/
 function catalogOf(app, options) {
+	let byConverter = catalogs.get(app);
+	if (byConverter === void 0) {
+		byConverter = /* @__PURE__ */ new WeakMap();
+		catalogs.set(app, byConverter);
+	}
+	let written = byConverter.get(options.toJsonSchema);
+	if (written === void 0) {
+		written = write(app, options.toJsonSchema);
+		byConverter.set(options.toJsonSchema, written);
+	}
+	return written;
+}
+function write(app, toJsonSchema) {
 	const types = {};
 	const toJson = (schema, where) => {
-		const { $schema: _, $defs, ...json } = options.toJsonSchema(schema);
+		const { $schema: _, $defs, ...json } = toJsonSchema(schema);
 		for (const [name, definition] of Object.entries($defs ?? {})) {
 			const existing = types[name];
 			if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(definition)) throw new Error(`${where}: two different schemas have the name ${name}. Give each one its own name.`);
@@ -36,7 +54,7 @@ function catalogOf(app, options) {
 		capabilities[capability.id] = {
 			description: capability.description,
 			audience: capability.audience,
-			...capability.input === void 0 ? {} : { input: toJson(capability.input, capability.id) },
+			...capability.input === void 0 ? {} : { input: objectInput(toJson(capability.input, capability.id), types) },
 			...capability.output === void 0 ? {} : { output: toJson(capability.output, capability.id) },
 			...Object.keys(failures).length === 0 ? {} : { failures },
 			...capability.readOnly === true ? { readOnly: true } : {},

package/dist/cli.d.ts

@@ -6,12 +6,32 @@ export interface CliOptions<Context> {
     readonly toJsonSchema: ToJsonSchema;
     /** The target that the command line serves. The default is `"cli"`. */
     readonly target?: string | undefined;
+    /**
+     * The text at the top of the help. The default is the description of the application, then its title, then `name`.
+     */
+    readonly description?: string | undefined;
+    /**
+     * The commands of the application, beside the commands of the capabilities, `call` and `list`. The name of each one
+     * must not be `call`, `list`, the name of another command of the application, or the first word of the command of a
+     * capability (spec/bindings/cli.md#commands).
+     */
+    readonly commands?: readonly CliCommand<Context>[] | undefined;
 }
 export interface CliIo {
     readonly stdout: (text: string) => void;
     readonly stderr: (text: string) => void;
     readonly signal?: AbortSignal | undefined;
 }
+/** A command that the application adds to the command line. */
+export interface CliCommand<Context> {
+    readonly name: string;
+    /** The text that the help gives for the command. */
+    readonly description: string;
+    /** Run the command with the arguments that come after its name. The result is the exit code. */
+    run(args: readonly string[], io: CliIo & {
+        readonly context: Context;
+    }): number | Promise<number>;
+}
 /** Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call. */
 export declare function main<Context>(app: App<Context>, options: CliOptions<Context>): void;
 /** Run the command line with arguments. The result is the exit code (spec/bindings/cli.md#outcomes). */

package/dist/cli.js

@@ -36,6 +36,16 @@ async function runCli(app, options, args, io) {
 		path: commandPath(id)
 	}));
 	for (const { path } of commands) if (path[0] === "call" || path[0] === "list") throw new Error(`The command ${path.join(" ")} has the same name as a command of the command line.`);
+	const added = options.commands ?? [];
+	const taken = /* @__PURE__ */ new Set([
+		"call",
+		"list",
+		...commands.map(({ path }) => path[0])
+	]);
+	for (const command of added) {
+		if (taken.has(command.name)) throw new Error(`The command ${command.name} of the application has the same name as another command.`);
+		taken.add(command.name);
+	}
 	const print = (outcome) => {
 		if (isCallFailure(outcome)) io.stderr(JSON.stringify({
 			kind: outcome.kind,
@@ -47,7 +57,8 @@ async function runCli(app, options, args, io) {
 	try {
 		const [first, ...rest] = args;
 		if (first === void 0 || first === "--help" || first === "-h") {
-			io.stdout(help(options.name, commands.map(({ path }) => path.join(" "))));
+			const description = options.description ?? app.description ?? app.title ?? options.name;
+			io.stdout(help(options.name, description, commands.map(({ path }) => path.join(" ")), added));
 			return CLI_EXIT_CODES.value;
 		}
 		if (first === "--version" || first === "-v") {
@@ -80,6 +91,11 @@ async function runCli(app, options, args, io) {
 			}
 			return print(await session.invoke(id, input, { signal: io.signal }));
 		}
+		const command = added.find(({ name }) => name === first);
+		if (command !== void 0) return await command.run(rest, {
+			...io,
+			context: options.context
+		});
 		const match = commands.filter(({ path }) => path.every((word, index) => args[index] === word)).sort((a, b) => b.path.length - a.path.length)[0];
 		if (match === void 0) throw new UsageError(`There is no command ${args.filter((arg) => !arg.startsWith("-")).join(" ")}.`, CLI_EXIT_CODES["unknown-capability"]);
 		const capability = session.view.capabilities[match.id];
@@ -142,14 +158,17 @@ function resolve(property, definitions) {
 	const name = typeof property.$ref === "string" ? REFERENCE.exec(property.$ref)?.[1] : void 0;
 	return name === void 0 ? property : definitions[name] ?? property;
 }
-function help(name, paths) {
+function help(name, description, paths, added) {
 	return [
+		description,
+		"",
 		`Usage: ${name} <command> [flags]`,
 		"",
 		"Commands:",
 		...paths.map((path) => `  ${path}`),
 		"  call <id> [input]",
-		"  list"
+		"  list",
+		...added.map((command) => `  ${command.name}  ${command.description}`)
 	].join("\n");
 }
 function usage(name, path, description, schema) {

package/dist/http.js

@@ -16,6 +16,8 @@ function httpHandler(app, options) {
 			maximumBytes
 		});
 		if (screened !== void 0) return rejection(screened);
+		const body = await readBounded(request, maximumBytes);
+		if ("rejection" in body) return rejection(body.rejection);
 		const path = new URL(request.url).pathname.slice((options.base ?? "").length);
 		return withContext(options, request, async (context) => {
 			const session = createSession(app, {
@@ -31,8 +33,6 @@ function httpHandler(app, options) {
 				if (request.method === "GET" && path === "/catalog" && options.serveCatalog !== false) return json(200, session.view);
 				const id = request.method === "POST" && path.startsWith("/capabilities/") ? path.slice(14) : void 0;
 				if (id === void 0) return json(404, callFailure("unknown-capability", "There is no such route."));
-				const body = await readBounded(request, maximumBytes);
-				if ("rejection" in body) return rejection(body.rejection);
 				let input;
 				try {
 					input = body.text === "" ? {} : JSON.parse(body.text);

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 export { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
 export type { AnyCapability, App, Capability, Observable, Target, ToJsonSchema } from "./app.js";
-export { createSession } from "./session.js";
-export type { Handle, Session, SessionOptions } from "./session.js";
+export { createSession, getHandle } from "./session.js";
+export type { Handle, HandleOf, Session, SessionOptions } from "./session.js";
 export { mcpHandler } from "./mcp.js";
 export type { McpOptions, McpSettings } from "./mcp.js";
 export { httpHandler } from "./http.js";
 export type { HttpOptions, HttpSettings } from "./http.js";
 export type { ContextOption } from "./context.js";
 export { main as cliMain, runCli } from "./cli.js";
-export type { CliIo, CliOptions } from "./cli.js";
+export type { CliCommand, CliIo, CliOptions } from "./cli.js";
 export { findHost, installWebMcp } from "./webmcp.js";
 export type { Installation, ModelContext, ModelContextTool, Phase, Status } from "./webmcp.js";
 export type { StandardSchemaV1 } from "./standard-schema.js";

package/dist/index.js

@@ -1,8 +1,8 @@
 import { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
-import { createSession } from "./session.js";
+import { createSession, getHandle } from "./session.js";
 import { mcpHandler } from "./mcp.js";
 import { httpHandler } from "./http.js";
 import { main, runCli } from "./cli.js";
 import { findHost, installWebMcp } from "./webmcp.js";
 import { AVAILABLE, CallFailureError, fail, ok, unavailable } from "@acid-cat/spec-ts";
-export { AVAILABLE, CallFailureError, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, fail, findHost, httpHandler, installWebMcp, mcpHandler, ok, renderCatalog, runCli, unavailable };
+export { AVAILABLE, CallFailureError, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, fail, findHost, getHandle, httpHandler, installWebMcp, mcpHandler, ok, renderCatalog, runCli, unavailable };

package/dist/session.d.ts

@@ -1,24 +1,39 @@
 import type { Availability, CatalogDocument, Outcome, Result } from "@acid-cat/spec-ts";
-import type { App, Observable, ToJsonSchema } from "./app.js";
-export interface Handle {
+import type { AnyCapability, App, Capability, FailureOf, InputOf, Observable, Output, ToJsonSchema } from "./app.js";
+import type { StandardSchemaV1 } from "./standard-schema.js";
+/**
+ * The handle of a capability (spec/bindings/typescript.md#handles). `Input`, `Value`, `Failure` and `State` are the
+ * types of the schemas of the capability. `getHandle` gives a handle with these types.
+ */
+export interface Handle<Input = unknown, Value = unknown, Failure = unknown, State = unknown> {
     readonly id: string;
     readonly description: string;
     readonly audience: readonly string[];
     readonly availability: Observable<Availability>;
     /** The state of the capability, if it has one. Each value is a copy. */
-    readonly snapshot?: Observable<unknown>;
+    readonly snapshot?: Observable<State>;
     /** A call with an input that is already valid. A call failure rejects with a `CallFailureError`. */
-    execute(input: unknown, options?: {
+    execute(input: Input, options?: {
         readonly signal?: AbortSignal | undefined;
-    }): Promise<Result<unknown, unknown>>;
+    }): Promise<Result<Value, Failure>>;
     /** A call with an input that is not trusted. A call failure rejects with a `CallFailureError`. */
     invokeExternal(input: unknown, options?: {
         readonly signal?: AbortSignal | undefined;
     }): Promise<Result<unknown, unknown>>;
 }
+/** The handle of a capability, with the types of its schemas. */
+export type HandleOf<C> = C extends Capability<any, infer Input, infer OutputSchema, infer Failures, infer StateSchema> ? Handle<InputOf<Input>, Output<OutputSchema>, FailureOf<Failures>, StandardSchemaV1.InferOutput<StateSchema>> : never;
+/**
+ * The handle of a capability in `handles`, with the types of the capability. For a capability outside the view, the
+ * handle is always unavailable, and each call rejects as `unknown-capability`.
+ */
+export declare function getHandle<C extends AnyCapability>(handles: ReadonlyMap<string, Handle>, capability: C): HandleOf<C>;
 export interface Session {
     readonly target: string;
-    /** The view of the target. Bindings take names, descriptions and schemas from it. */
+    /**
+     * The view of the target. Bindings take names, descriptions and schemas from it. The session writes the view when it
+     * is first read.
+     */
     readonly view: CatalogDocument;
     /** The handles of the capabilities in the view, by id. */
     readonly handles: ReadonlyMap<string, Handle>;
@@ -26,7 +41,10 @@ export interface Session {
     invoke(id: string, input: unknown, options?: {
         readonly signal?: AbortSignal | undefined;
     }): Promise<Outcome<unknown, unknown>>;
-    /** An event each time the availability of a capability changes. */
+    /**
+     * An event each time the availability of a capability changes. The session subscribes to the availabilities when the
+     * first listener subscribes, and unsubscribes after the last listener unsubscribes.
+     */
     onChange(listener: () => void): {
         unsubscribe(): void;
     };

package/dist/session.js

@@ -4,23 +4,48 @@ import { AVAILABLE, CallFailureError, callFailure, isCallFailure, viewOf } from
 /**
 * Sessions and handles (spec/invocation.md, spec/bindings/typescript.md).
 */
+/**
+* The handle of a capability in `handles`, with the types of the capability. For a capability outside the view, the
+* handle is always unavailable, and each call rejects as `unknown-capability`.
+*/
+function getHandle(handles, capability) {
+	return handles.get(capability.id) ?? outsideView(capability);
+}
+function outsideView(capability) {
+	const failure = callFailure("unknown-capability", `There is no capability ${capability.id}.`);
+	const unavailable = {
+		available: false,
+		reason: failure.message
+	};
+	const reject = () => Promise.reject(new CallFailureError(failure));
+	return {
+		id: capability.id,
+		description: capability.description,
+		audience: [],
+		availability: {
+			getSnapshot: () => unavailable,
+			subscribe: () => ({ unsubscribe() {} })
+		},
+		execute: reject,
+		invokeExternal: reject
+	};
+}
 const always = {
 	getSnapshot: () => AVAILABLE,
 	subscribe: () => ({ unsubscribe() {} })
 };
 /** Open a session for a target. */
 function createSession(app, options) {
-	const view = viewOf(catalogOf(app, { toJsonSchema: options.toJsonSchema }), options.target);
 	const lifetime = new AbortController();
 	const running = /* @__PURE__ */ new Set();
 	const listeners = /* @__PURE__ */ new Set();
-	const subscriptions = [];
+	let subscriptions = [];
 	const onDefect = options.onDefect ?? ((id, cause) => console.error(`A capability failed with a defect: ${id}`, cause));
 	const served = /* @__PURE__ */ new Map();
 	for (const capability of app.capabilities) {
-		if (!(capability.id in view.capabilities)) continue;
+		if (!capability.audience.includes(options.target)) continue;
+		if (served.has(capability.id)) throw new Error(`The capability ${capability.id} is declared two times.`);
 		const availability = capability.availability?.(options.context) ?? always;
-		subscriptions.push(availability.subscribe(() => listeners.forEach((listener) => listener())));
 		served.set(capability.id, {
 			capability,
 			availability
@@ -77,26 +102,41 @@ function createSession(app, options) {
 		handles.set(id, {
 			id,
 			description: capability.description,
-			audience: capability.audience,
+			audience: [options.target],
 			availability,
 			...state === void 0 ? {} : { snapshot: detached(state) },
 			execute: (input, callOptions) => reject(call(id, input, true, callOptions?.signal)),
 			invokeExternal: (input, callOptions) => reject(call(id, input, false, callOptions?.signal))
 		});
 	}
+	const unsubscribeAll = () => {
+		subscriptions.forEach((subscription) => subscription.unsubscribe());
+		subscriptions = [];
+	};
+	let view;
 	return {
 		target: options.target,
-		view,
+		get view() {
+			return view ??= viewOf(catalogOf(app, { toJsonSchema: options.toJsonSchema }), options.target);
+		},
 		handles,
 		signal: lifetime.signal,
 		invoke: (id, input, callOptions) => call(id, input, false, callOptions?.signal),
 		onChange(listener) {
+			if (lifetime.signal.aborted) return { unsubscribe() {} };
+			if (listeners.size === 0) {
+				const announce = () => listeners.forEach((each) => each());
+				subscriptions = [...served.values()].map(({ availability }) => availability.subscribe(announce));
+			}
 			listeners.add(listener);
-			return { unsubscribe: () => listeners.delete(listener) };
+			return { unsubscribe() {
+				if (listeners.delete(listener) && listeners.size === 0) unsubscribeAll();
+			} };
 		},
 		async dispose() {
 			lifetime.abort();
-			subscriptions.forEach((subscription) => subscription.unsubscribe());
+			listeners.clear();
+			unsubscribeAll();
 			await Promise.allSettled([...running]);
 		}
 	};
@@ -136,4 +176,4 @@ async function checkResult(capability, result) {
 	};
 }
 //#endregion
-export { createSession };
+export { createSession, getHandle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Serve AcidCat capabilities in plain TypeScript, with no Effect dependency.",
   "keywords": [
     "acidcat",
@@ -32,11 +32,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.3.0",
-    "@acid-cat/spec-ts": "0.3.0"
+    "@acid-cat/catalog": "0.4.0",
+    "@acid-cat/spec-ts": "0.4.0"
   },
   "devDependencies": {
-    "@acid-cat/cli": "0.3.0",
+    "@acid-cat/cli": "0.4.0",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
     "playwright": "1.64.0",