@saga-a2ui/core 0.5.6-rc.1 → 0.7.6-rc.1

package/src/actions/limits.ts

@@ -22,7 +22,10 @@ export interface ResolvedLimits {
 }
 
 /** Documented product defaults for usable behavior, not measured latency guarantees. */
-const defaults: ResolvedLimits = Object.freeze({ deadlineMs: 30_000, hookMs: 5_000 });
+const defaults: ResolvedLimits = Object.freeze({
+  deadlineMs: 30_000,
+  hookMs: 5_000,
+});
 
 /** The longest delay one `setTimeout` honors; a longer one would fire at once instead of later. */
 const longestTimerMs = 2_147_483_647;
@@ -65,10 +68,16 @@ export function startTimer(ms: number, onExpire: () => void): LimitTimer {
   };
 }
 
-function readSetting(owner: string, name: keyof Limits, value: unknown): number | undefined {
+function readSetting(
+  owner: string,
+  name: keyof Limits,
+  value: unknown,
+): number | undefined {
   if (value === undefined) return undefined;
   if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-    throw new TypeError(`${owner}: ${name} must be a finite number greater than zero.`);
+    throw new TypeError(
+      `${owner}: ${name} must be a finite number greater than zero.`,
+    );
   }
   return value;
 }
@@ -81,9 +90,14 @@ function readSetting(owner: string, name: keyof Limits, value: unknown): number
 export function readLimits(owner: string, given: unknown): Limits {
   if (given === undefined) return Object.freeze({});
   if (typeof given !== 'object' || given === null || Array.isArray(given)) {
-    throw new TypeError(`${owner}: limits must be an object with optional deadlineMs and hookMs.`);
+    throw new TypeError(
+      `${owner}: limits must be an object with optional deadlineMs and hookMs.`,
+    );
   }
-  const { deadlineMs, hookMs } = given as { deadlineMs?: unknown; hookMs?: unknown };
+  const { deadlineMs, hookMs } = given as {
+    deadlineMs?: unknown;
+    hookMs?: unknown;
+  };
   const checkedDeadline = readSetting(owner, 'deadlineMs', deadlineMs);
   const checkedHook = readSetting(owner, 'hookMs', hookMs);
   return Object.freeze({
@@ -102,7 +116,10 @@ export function snapshotLimits(limits?: Limits): Limits {
 }
 
 /** Per-setting resolution: the action's override, then the instance configuration, then the default. */
-export function resolveLimits(action: Limits, instance: Limits): ResolvedLimits {
+export function resolveLimits(
+  action: Limits,
+  instance: Limits,
+): ResolvedLimits {
   return Object.freeze({
     deadlineMs: action.deadlineMs ?? instance.deadlineMs ?? defaults.deadlineMs,
     hookMs: action.hookMs ?? instance.hookMs ?? defaults.hookMs,

package/src/actions/outcome.ts

@@ -30,8 +30,16 @@ export type InputFailure = (
 
 /** Failures while prerequisites run. The handler has not started and `provided` is incomplete. */
 export type PrerequisiteFailure = (
-  | { readonly kind: 'refused'; readonly prerequisite: string; readonly reason: string }
-  | { readonly kind: 'prerequisite-error'; readonly prerequisite: string; readonly error: unknown }
+  | {
+      readonly kind: 'refused';
+      readonly prerequisite: string;
+      readonly reason: string;
+    }
+  | {
+      readonly kind: 'prerequisite-error';
+      readonly prerequisite: string;
+      readonly error: unknown;
+    }
   | { readonly kind: 'timeout' }
 ) &
   Categorized;
@@ -46,18 +54,30 @@ export type PrerequisiteFailure = (
 export type RunningFailure<Result> = (
   | { readonly kind: 'handler-error'; readonly error: unknown }
   | { readonly kind: 'timeout' }
-  | { readonly kind: 'success-hook-error'; readonly error: unknown; readonly result: Result }
+  | {
+      readonly kind: 'success-hook-error';
+      readonly error: unknown;
+      readonly result: Result;
+    }
   | { readonly kind: 'success-hook-timeout'; readonly result: Result }
 ) &
   Categorized;
 
 /** Steps after the outcome is decided. 'adopt' is a transfer callback that returned a thenable. */
-export type CleanupStep = 'onFailure' | 'onCanceled' | 'onFinally' | 'release' | 'adopt';
+export type CleanupStep =
+  'onFailure' | 'onCanceled' | 'onFinally' | 'release' | 'adopt';
 
 /** A diagnostic about cleanup. It never changes the primary outcome. */
 export type CleanupError =
-  | { readonly step: CleanupStep; readonly reason: 'threw'; readonly error: unknown }
-  | { readonly step: CleanupStep; readonly reason: 'budget-exceeded' | 'obsolete' };
+  | {
+      readonly step: CleanupStep;
+      readonly reason: 'threw';
+      readonly error: unknown;
+    }
+  | {
+      readonly step: CleanupStep;
+      readonly reason: 'budget-exceeded' | 'obsolete';
+    };
 
 /**
  * Canceled stages: 'prerequisites' and 'running' are before the handler's result was observed, so
@@ -66,12 +86,37 @@ export type CleanupError =
  */
 export type Outcome<Result> =
   | { readonly status: 'succeeded'; readonly result: Result }
-  | { readonly status: 'failed'; readonly stage: 'input'; readonly failure: InputFailure }
-  | { readonly status: 'failed'; readonly stage: 'prerequisites'; readonly failure: PrerequisiteFailure }
-  | { readonly status: 'failed'; readonly stage: 'running'; readonly failure: RunningFailure<Result> }
-  | { readonly status: 'canceled'; readonly cause: CancelCause; readonly stage: 'prerequisites' }
-  | { readonly status: 'canceled'; readonly cause: CancelCause; readonly stage: 'running' }
-  | { readonly status: 'canceled'; readonly cause: CancelCause; readonly stage: 'completing'; readonly result: Result };
+  | {
+      readonly status: 'failed';
+      readonly stage: 'input';
+      readonly failure: InputFailure;
+    }
+  | {
+      readonly status: 'failed';
+      readonly stage: 'prerequisites';
+      readonly failure: PrerequisiteFailure;
+    }
+  | {
+      readonly status: 'failed';
+      readonly stage: 'running';
+      readonly failure: RunningFailure<Result>;
+    }
+  | {
+      readonly status: 'canceled';
+      readonly cause: CancelCause;
+      readonly stage: 'prerequisites';
+    }
+  | {
+      readonly status: 'canceled';
+      readonly cause: CancelCause;
+      readonly stage: 'running';
+    }
+  | {
+      readonly status: 'canceled';
+      readonly cause: CancelCause;
+      readonly stage: 'completing';
+      readonly result: Result;
+    };
 
 /**
  * The freshness check supplied to one callback. Each prerequisite, the handler and each hook gets

package/src/actions/prerequisite.ts

@@ -17,23 +17,31 @@ export interface PrerequisiteContext<Needs, Input> extends Freshness {
   readonly scope: InvocationScope;
 }
 
-export type Proceed<Provides> = { readonly kind: 'proceed'; readonly provides: Provides };
+export type Proceed<Provides> = {
+  readonly kind: 'proceed';
+  readonly provides: Provides;
+};
 export type Refuse = { readonly kind: 'refuse'; readonly reason: string };
 export type PrerequisiteResult<Provides> = Proceed<Provides> | Refuse;
 
 /** Continues to the next prerequisite, or the handler, adding `provides` for everything after it. */
 export function proceed(): Proceed<NoValues>;
-export function proceed<Provides extends object>(provides: Provides): Proceed<Provides>;
+export function proceed<Provides extends object>(
+  provides: Provides,
+): Proceed<Provides>;
 export function proceed(provides: object = {}): Proceed<object> {
   if (typeof provides !== 'object' || provides === null) {
-    throw new TypeError('proceed() takes an object of provided values, or nothing.');
+    throw new TypeError(
+      'proceed() takes an object of provided values, or nothing.',
+    );
   }
   return Object.freeze({ kind: 'proceed', provides });
 }
 
 /** Ends the invocation as a refusal: the handler never runs. `reason` is for the failure hook. */
 export function refuse(reason: string): Refuse {
-  if (typeof reason !== 'string') throw new TypeError('refuse() takes a reason string.');
+  if (typeof reason !== 'string')
+    throw new TypeError('refuse() takes a reason string.');
   return Object.freeze({ kind: 'refuse', reason });
 }
 
@@ -46,12 +54,18 @@ export interface Prerequisite<Provides, Needs = unknown, Input = unknown> {
 }
 
 /** Fixes the type parameters from the callback; a plain `{ label, run }` object is equally valid. */
-export function prerequisite<Provides extends object = NoValues, Needs = unknown, Input = unknown>(
+export function prerequisite<
+  Provides extends object = NoValues,
+  Needs = unknown,
+  Input = unknown,
+>(
   label: string,
   run: Prerequisite<Provides, Needs, Input>['run'],
 ): Prerequisite<Provides, Needs, Input> {
-  if (typeof label !== 'string' || label === '') throw new TypeError('A prerequisite needs a non-empty label.');
-  if (typeof run !== 'function') throw new TypeError(`Prerequisite '${label}' needs a function.`);
+  if (typeof label !== 'string' || label === '')
+    throw new TypeError('A prerequisite needs a non-empty label.');
+  if (typeof run !== 'function')
+    throw new TypeError(`Prerequisite '${label}' needs a function.`);
   return Object.freeze({ label, run });
 }
 
@@ -64,10 +78,19 @@ export type Answer =
 /** Reads the unchecked value a prerequisite returned. Unknown shapes are the prerequisite's error. */
 export function readAnswer(value: unknown): Answer {
   if (typeof value !== 'object' || value === null) return { kind: 'malformed' };
-  const answer = value as { kind?: unknown; provides?: unknown; reason?: unknown };
-  if (answer.kind === 'proceed' && typeof answer.provides === 'object' && answer.provides !== null) {
+  const answer = value as {
+    kind?: unknown;
+    provides?: unknown;
+    reason?: unknown;
+  };
+  if (
+    answer.kind === 'proceed' &&
+    typeof answer.provides === 'object' &&
+    answer.provides !== null
+  ) {
     return { kind: 'proceed', provides: answer.provides };
   }
-  if (answer.kind === 'refuse' && typeof answer.reason === 'string') return { kind: 'refuse', reason: answer.reason };
+  if (answer.kind === 'refuse' && typeof answer.reason === 'string')
+    return { kind: 'refuse', reason: answer.reason };
   return { kind: 'malformed' };
 }

package/src/actions/scope.ts

@@ -18,7 +18,10 @@ export interface ReleaseContext {
  * Must affect only the acquisition that `token` identifies, and must be a no-op when the owner has
  * since superseded that token. The scope calls it once per owned token that was not transferred.
  */
-export type Release<Token> = (token: Token, context: ReleaseContext) => void | PromiseLike<void>;
+export type Release<Token> = (
+  token: Token,
+  context: ReleaseContext,
+) => void | PromiseLike<void>;
 
 /** A token the scope owns, and the one way to hand it to a longer-lived owner. */
 export interface Held<Token> {
@@ -36,7 +39,10 @@ export interface Held<Token> {
    * later rejection reaches the observer as a `cleanup-error` with step `adopt`. Work the callback
    * already started is not recalled, so the owner's own `end(token)` must be idempotent.
    */
-  transfer<Returned>(adopt: (token: Token) => Returned, ...synchronous: Synchronous<Returned>): boolean;
+  transfer<Returned>(
+    adopt: (token: Token) => Returned,
+    ...synchronous: Synchronous<Returned>
+  ): boolean;
 }
 
 /** The part of the scope that may be used inside the event turn. */
@@ -60,13 +66,18 @@ export interface InvocationScope extends ActivationScope {
    * released at once and the acquisition rejects with `InvocationEndedError`; an invocation that has
    * already ended does not start the acquisition at all.
    */
-  acquire<Token>(acquire: () => Token | PromiseLike<Token>, release: Release<Token>): Promise<Held<Token>>;
+  acquire<Token>(
+    acquire: () => Token | PromiseLike<Token>,
+    release: Release<Token>,
+  ): Promise<Held<Token>>;
 }
 
 /** The invocation's outcome was already decided, so nothing may be added to its scope. */
 export class InvocationEndedError extends Error {
   constructor(label: string) {
-    super(`Action '${label}': the invocation has ended, so the token was released instead of owned.`);
+    super(
+      `Action '${label}': the invocation has ended, so the token was released instead of owned.`,
+    );
     this.name = 'InvocationEndedError';
   }
 }
@@ -106,7 +117,8 @@ export class InvocationResources {
 
   constructor(private readonly host: ScopeHost) {
     const active = (): boolean => host.isActive();
-    const own = <Token>(token: Token, release: Release<Token>): Held<Token> => this.own(token, release);
+    const own = <Token>(token: Token, release: Release<Token>): Held<Token> =>
+      this.own(token, release);
     this.activation = Object.freeze({
       get active() {
         return active();
@@ -118,8 +130,10 @@ export class InvocationResources {
         return active();
       },
       own,
-      acquire: <Token>(acquire: () => Token | PromiseLike<Token>, release: Release<Token>): Promise<Held<Token>> =>
-        this.acquire(acquire, release),
+      acquire: <Token>(
+        acquire: () => Token | PromiseLike<Token>,
+        release: Release<Token>,
+      ): Promise<Held<Token>> => this.acquire(acquire, release),
     });
   }
 
@@ -141,7 +155,10 @@ export class InvocationResources {
 
   private own<Token>(token: Token, release: Release<Token>): Held<Token> {
     const { host } = this;
-    if (typeof release !== 'function') throw new TypeError(`Action '${host.label}': scope.own needs a release function.`);
+    if (typeof release !== 'function')
+      throw new TypeError(
+        `Action '${host.label}': scope.own needs a release function.`,
+      );
     // Interop assertion: the entry keeps `token` and `release` together, so the scope only ever
     // calls this release with the token it was given.
     const erased = release as Release<unknown>;
@@ -153,15 +170,24 @@ export class InvocationResources {
     this.entries.push(entry);
     return Object.freeze({
       token,
-      transfer: <Returned>(adopt: (token: Token) => Returned, ...synchronous: Synchronous<Returned>): boolean => {
+      transfer: <Returned>(
+        adopt: (token: Token) => Returned,
+        ...synchronous: Synchronous<Returned>
+      ): boolean => {
         void synchronous;
         return this.transfer(entry, adopt);
       },
     });
   }
 
-  private async acquire<Token>(acquire: () => Token | PromiseLike<Token>, release: Release<Token>): Promise<Held<Token>> {
-    if (typeof acquire !== 'function') throw new TypeError(`Action '${this.host.label}': scope.acquire needs an acquire function.`);
+  private async acquire<Token>(
+    acquire: () => Token | PromiseLike<Token>,
+    release: Release<Token>,
+  ): Promise<Held<Token>> {
+    if (typeof acquire !== 'function')
+      throw new TypeError(
+        `Action '${this.host.label}': scope.acquire needs an acquire function.`,
+      );
     if (!this.host.isActive()) throw new InvocationEndedError(this.host.label);
     const token = await acquire();
     // Ownership begins when the token exists. If the invocation ended meanwhile, `own` releases it
@@ -169,9 +195,15 @@ export class InvocationResources {
     return this.own(token, release);
   }
 
-  private transfer<Token>(entry: Entry, adopt: (token: Token) => unknown): boolean {
+  private transfer<Token>(
+    entry: Entry,
+    adopt: (token: Token) => unknown,
+  ): boolean {
     if (entry.state !== 'held' || !this.host.isActive()) return false;
-    if (typeof adopt !== 'function') throw new TypeError(`Action '${this.host.label}': transfer needs an adopt function.`);
+    if (typeof adopt !== 'function')
+      throw new TypeError(
+        `Action '${this.host.label}': transfer needs an adopt function.`,
+      );
     // While the owner adopts, the entry is not the runtime's to release, whatever adoption does.
     entry.state = 'adopting';
     let completed = false;
@@ -232,7 +264,11 @@ export class InvocationResources {
    * Releases a token the invocation can no longer own, with no hook involved and within `hookMs`. A
    * failure or overrun reaches only the observer: the outcome and the hooks are long past.
    */
-  private releaseAtOnce(token: unknown, release: Release<unknown>, hookMs: number): void {
+  private releaseAtOnce(
+    token: unknown,
+    release: Release<unknown>,
+    hookMs: number,
+  ): void {
     const controller = new AbortController();
     let returned: unknown;
     try {

package/src/actions/server.ts

@@ -40,7 +40,10 @@ export interface ServerReply {
  * request is then unknown. `Reply` lets a transport keep its own reply type.
  */
 export interface ServerTransport<Reply extends ServerReply = ServerReply> {
-  callServerTool(request: ServerRequest, options?: ServerRequestOptions): Promise<Reply>;
+  callServerTool(
+    request: ServerRequest,
+    options?: ServerRequestOptions,
+  ): Promise<Reply>;
 }
 
 /** What a handler may ask for beyond the arguments: a shorter wait, and request metadata. */
@@ -66,34 +69,64 @@ export interface ServerCalls<Reply extends ServerReply = ServerReply> {
    * invocation, and aborting the signal ends the client's wait: it does not show that the host
    * forwarded the cancellation or that the server stopped.
    */
-  call(name: string, args: Readonly<Record<string, unknown>>, options?: ServerCallOptions): Promise<Reply>;
+  call(
+    name: string,
+    args: Readonly<Record<string, unknown>>,
+    options?: ServerCallOptions,
+  ): Promise<Reply>;
 }
 
 /** Reads the transport an application passed: an object with a `callServerTool` function. */
-export function checkTransport(label: string, transport: unknown): ServerTransport {
-  const candidate = transport as { callServerTool?: unknown } | null | undefined;
-  if (typeof candidate !== 'object' || candidate === null || typeof candidate.callServerTool !== 'function') {
-    throw new TypeError(`Action '${label}': a server action needs a transport with a callServerTool function.`);
+export function checkTransport(
+  label: string,
+  transport: unknown,
+): ServerTransport {
+  const candidate = transport as
+    { callServerTool?: unknown } | null | undefined;
+  if (
+    typeof candidate !== 'object' ||
+    candidate === null ||
+    typeof candidate.callServerTool !== 'function'
+  ) {
+    throw new TypeError(
+      `Action '${label}': a server action needs a transport with a callServerTool function.`,
+    );
   }
   return candidate as ServerTransport;
 }
 
 /** The smallest of the time left and the handler's own narrower request, or why there is none. */
-export function requestTimeout(label: string, remainingMs: number, supplied: unknown): number {
-  if (supplied !== undefined && (typeof supplied !== 'number' || !Number.isFinite(supplied) || supplied <= 0)) {
-    throw new TypeError(`Action '${label}': timeoutMs must be a finite number greater than zero.`);
+export function requestTimeout(
+  label: string,
+  remainingMs: number,
+  supplied: unknown,
+): number {
+  if (
+    supplied !== undefined &&
+    (typeof supplied !== 'number' ||
+      !Number.isFinite(supplied) ||
+      supplied <= 0)
+  ) {
+    throw new TypeError(
+      `Action '${label}': timeoutMs must be a finite number greater than zero.`,
+    );
   }
   return supplied === undefined ? remainingMs : Math.min(remainingMs, supplied);
 }
 
 /** The request metadata a handler supplied, copied and frozen, or why there is none. */
-export function requestMeta(label: string, supplied: unknown): Readonly<Record<string, unknown>> | undefined {
+export function requestMeta(
+  label: string,
+  supplied: unknown,
+): Readonly<Record<string, unknown>> | undefined {
   if (supplied === undefined) return undefined;
   const plain =
     typeof supplied === 'object' &&
     supplied !== null &&
     !Array.isArray(supplied) &&
-    (Object.getPrototypeOf(supplied) === Object.prototype || Object.getPrototypeOf(supplied) === null);
-  if (!plain) throw new TypeError(`Action '${label}': meta must be a plain object.`);
+    (Object.getPrototypeOf(supplied) === Object.prototype ||
+      Object.getPrototypeOf(supplied) === null);
+  if (!plain)
+    throw new TypeError(`Action '${label}': meta must be a plain object.`);
   return Object.freeze({ ...(supplied as Record<string, unknown>) });
 }

package/src/actions/thenable.ts

@@ -17,7 +17,9 @@ export function isThenable(value: unknown): value is PromiseLike<unknown> {
  * callback that always throws returns `never` and stays valid. The types cannot see a promise
  * hidden behind a declared `unknown` or `void`, so the runtime checks the returned value too.
  */
-export type Synchronous<Returned> = [Extract<Returned, PromiseLike<unknown>>] extends [never]
+export type Synchronous<Returned> = [
+  Extract<Returned, PromiseLike<unknown>>,
+] extends [never]
   ? []
   : [returnedAThenable: never];
 

package/src/delivered-result.ts

@@ -0,0 +1,31 @@
+// What a delivery hands a view as the result of one operation, in terms no delivery owns. A
+// delivery (MCP today) maps its own result onto this value; an application's reader decides what it
+// means. Nothing here interprets: it names no schema, wording, fallback or error policy, and it
+// imports no delivery, renderer or DOM.
+
+/**
+ * One piece of a result's ordered content. Its `type` is always kept. A text block also keeps its
+ * `text`; any other block is carried exactly as the delivery supplied it, so a reader that knows
+ * the block's shape can read it and one that does not leaves it alone.
+ */
+export interface ContentBlock {
+  readonly type: string;
+  readonly text?: string;
+  readonly [field: string]: unknown;
+}
+
+/**
+ * The whole result of one operation, as delivered.
+ *
+ * - `isError` is the delivery's own error indication, kept as a boolean. What an error result
+ *   means, and whether beside valid structured data, is the reader's decision.
+ * - `content` holds every block in the order delivered, possibly none.
+ * - `structuredContent` is unchecked. Absence of the field (`'structuredContent' in result` is
+ *   false), a present `null` and malformed data are three different results, and a reader may
+ *   treat them differently.
+ */
+export interface DeliveredResult {
+  readonly isError: boolean;
+  readonly content: readonly ContentBlock[];
+  readonly structuredContent?: unknown;
+}

package/src/host-links.ts

@@ -0,0 +1,49 @@
+// How a view asks its host to open a link the content policy has already validated. The contract
+// is renderer- and delivery-neutral: the card renderers (Lit, React) consume it, MCP delivery
+// supplies an implementation, and neither depends on the other. They share one definition and one
+// set of reader-facing messages.
+
+/**
+ * What happened to a request to open a validated link.
+ *
+ * - `opened`: the host accepted the request.
+ * - `denied`: the host refused it (user preference, blocked destination, cancelled).
+ * - `unavailable`: the host offers no link-opening capability, so nothing was requested.
+ * - `failed`: the request could not be completed (connection lost, timeout).
+ *
+ * Every outcome other than `opened` leaves the link inert; there is no other way to navigate.
+ */
+export type LinkOpenOutcome = 'opened' | 'denied' | 'unavailable' | 'failed';
+
+/**
+ * The only way content may leave the view: a request to the host to open a destination the
+ * content policy has already validated. A view receives its own instance explicitly.
+ */
+export interface HostLinks {
+  open(url: string): Promise<LinkOpenOutcome>;
+}
+
+/** For a page that has no host at all: every link stays inert and nothing navigates. */
+export const NO_HOST_LINKS: HostLinks = Object.freeze({
+  open: () => Promise.resolve<LinkOpenOutcome>('unavailable'),
+});
+
+const LINK_OUTCOME_MESSAGES: Record<LinkOpenOutcome, string> = {
+  opened: '',
+  denied: 'The host did not open this link.',
+  unavailable: 'This host cannot open links.',
+  failed: 'The link could not be opened.',
+};
+
+/**
+ * The text a reader sees for a link request's outcome. A link that was not opened stays readable:
+ * its destination follows as plain text.
+ */
+export function describeLinkOutcome(
+  outcome: LinkOpenOutcome,
+  url: string,
+): string {
+  return outcome === 'opened'
+    ? LINK_OUTCOME_MESSAGES.opened
+    : `${LINK_OUTCOME_MESSAGES[outcome]} Destination: ${url}`;
+}