@saga-a2ui/core 0.0.0-stage → 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @saga-a2ui/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Renderer-independent actions and A2UI v0.9 decoding. Entry points: `/actions`, `/actions/action-button-schema`, `/protocols/a2ui/v0_9`, `/protocols/a2ui/zod3`.
+
+Requires Node >=22.12.0 and a TypeScript-aware bundler; exports are TypeScript source. Apache-2.0, with dependency licenses retained separately.
+
+The prepared prerelease is `0.1.0-rc.1`, intended for the `next` tag. Preparation does not establish npm availability. Install only after the release is announced.
+
+Use matching exact SAGA versions. At the consumer workspace root, pin `@a2ui/markdown-it` to `0.2.1` using your package manager override. React consumers use `@saga-a2ui/react/a2ui`, without direct A2UI dependencies. Keep the A2UI Zod 3 and MCP Zod 4 contexts separate.
+
+See [the installation recipe](https://github.com/MachineWisdomAI/saga-a2ui/blob/main/docs/release-packages.md) and [React consumer dependencies](https://github.com/MachineWisdomAI/saga-a2ui/blob/main/docs/react-consumers.md).

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "@saga-a2ui/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{"name":"@saga-a2ui/core","private":false,"description":"Renderer-independent SAGA A2UI processing: version-specific decoding, validated message cases and the message session, and the renderer-independent action runtime (local and server actions, prerequisites, bounded hooks, resource ownership) at /actions","license":"Apache-2.0","type":"module","exports":{"./actions":"./src/actions/index.ts","./actions/action-button-schema":"./src/actions/action-button-schema.ts","./protocols/a2ui/v0_9":"./src/protocols/a2ui/v0_9/index.ts","./protocols/a2ui/zod3":"./src/protocols/a2ui/zod3.ts"},"files":["src","!src/**/*.test.ts","!src/**/*.test-support.ts"],"scripts":{"typecheck":"tsc --noEmit && tsc --noEmit -p tsconfig.test.json"},"dependencies":{"@a2ui/web_core":"0.13.0","zod3":"npm:zod@3.25.76"},"devDependencies":{"@types/node":"22.20.5","typescript":"^5.9.0","vitest":"^5.0.4"},"version":"0.1.0-rc.1","engines":{"node":">=22.12.0"},"repository":{"type":"git","url":"https://github.com/MachineWisdomAI/saga-a2ui.git","directory":"packages/core"},"publishConfig":{"access":"public","tag":"next"}}

package/src/actions/action-button-schema.ts

@@ -0,0 +1,22 @@
+import { CommonSchemas } from '@a2ui/web_core/v0_9';
+import { z } from '../protocols/a2ui/zod3.js';
+
+/**
+ * Contract of the opt-in action control. It has no `action` property at all: a layout names the
+ * control by ID and type, and application code attaches the callable to the rendered instance.
+ * The schema is strict, so a layout that also supplies an upstream `action`, or a handler name,
+ * is rejected when it is ingested, before any property is resolved or any function evaluated.
+ *
+ * The contract depends on the A2UI schema types and Zod, not on Lit, so another renderer can
+ * share it.
+ */
+export const ActionButtonApi = {
+  name: 'ActionButton',
+  schema: z
+    .object({
+      child: CommonSchemas.ComponentId,
+      // The same field the upstream Button has; it yields `isValid`.
+      checks: z.array(CommonSchemas.CheckRule).optional(),
+    })
+    .strict(),
+};

package/src/actions/binding.ts

@@ -0,0 +1,172 @@
+import { planOf, type ActionDefinition } from './definition.js';
+import { emitObservation, Invocation, type InvocationOwner, type Seam } from './invocation.js';
+import { resolveLimits, type Limits } from './limits.js';
+import { discardOutcome, isThenable } from './thenable.js';
+
+export type BindingPhase = 'idle' | 'running' | 'settling' | 'disposed';
+
+/** Replaced on every change and never mutated, so comparing identities shows whether anything changed. */
+export interface BindingState {
+  readonly phase: BindingPhase;
+}
+
+/** One definition attached to one event of one rendered instance. */
+export interface ActionBinding {
+  /** Opaque and unique within the page session. It finds nothing: no member of this API maps an id to a binding. */
+  readonly id: string;
+  readonly state: BindingState;
+  /**
+   * Calls `listener` synchronously after each state change and returns the unsubscribe function.
+   * The listener carries no event data, and a listener that throws, or returns a promise that
+   * rejects, never affects the action. Nothing is delivered after the final `disposed` state.
+   */
+  subscribe(listener: () => void): () => void;
+  /**
+   * Idempotent. Cancels an undecided invocation with cause `disposed`, detaches this binding's own
+   * callable, so later events do nothing, and ends the subscription after one final `disposed`
+   * state. A decided outcome is never rewritten. Other bindings of the same definition are untouched.
+   */
+  dispose(): void;
+}
+
+/** What a binding needs from the adapter and the application besides the definition. */
+export interface BindingSeam extends Seam {
+  /**
+   * Removes this binding's own installation from its slot. Called once, when the binding is
+   * disposed. A no-op when the slot holds a newer installation.
+   */
+  readonly detach: () => void;
+  /**
+   * The configuration of the SDK instance that owns this binding, already validated and copied.
+   * It supplies each bound the action did not override; absent means the defaults apply.
+   */
+  readonly limits?: Limits;
+}
+
+let bindingCount = 0;
+
+/**
+ * The runtime end of a binding. An activation arrives only through `activate`, and the binding
+ * applies the definition's busy policy to it.
+ *
+ * While an invocation is `running` or `settling`, a new activation first revalidates it, which
+ * applies the outcome rule to whatever changed since its last checkpoint, and only then meets the
+ * policy. `ignore` (the default) drops it: no hook runs, no invocation exists. `replace` cancels a
+ * running invocation with cause `replaced` and starts the new one at once; an invocation already
+ * settling keeps its outcome and finishes its cleanup beside the new one.
+ *
+ * An invocation that is entirely synchronous passes `running` and `settling` and is `idle` again
+ * before `activate` returns, with a listener call for each change. A failure decided in that call
+ * stack is rethrown to the caller of `activate` when the definition has no `onFailure` to receive
+ * it: swallowing it would hide it. A failure decided later has no caller to return to.
+ */
+export function createBinding<Event>(
+  definition: ActionDefinition<Event>,
+  seam: BindingSeam,
+): { readonly binding: ActionBinding; readonly activate: (event: Event) => void } {
+  const plan = planOf(definition);
+  // Resolved here, once, from two immutable layers: an invocation's clocks cannot change afterwards.
+  const limits = resolveLimits(plan.limits, seam.limits ?? {});
+  const listeners = new Set<() => void>();
+  let state: BindingState = Object.freeze({ phase: 'idle' });
+  let disposing = false;
+  /** The newest invocation that has not settled; it alone drives the phase. */
+  let owner: Invocation<Event> | undefined;
+  const unsettled = new Set<Invocation<Event>>();
+  const phase = (): BindingPhase => state.phase;
+  const id = `binding-${++bindingCount}`;
+
+  const notify = (): void => {
+    for (const listener of [...listeners]) {
+      // A callback may have unsubscribed this listener, or disposed the binding, which ended every
+      // subscription after its own final notification. A listener removed meanwhile gets nothing more.
+      if (!listeners.has(listener)) continue;
+      try {
+        const returned: unknown = listener();
+        if (isThenable(returned)) discardOutcome(returned);
+      } catch {
+        // A listener cannot affect the action.
+      }
+    }
+  };
+  const setPhase = (next: BindingPhase): void => {
+    if (state.phase === next) return;
+    state = Object.freeze({ phase: next });
+    notify();
+  };
+  const isDisposed = (): boolean => disposing || phase() === 'disposed';
+
+  const invocationOwner: InvocationOwner<Event> = {
+    bindingId: id,
+    isDisposed,
+    decided(invocation) {
+      if (owner === invocation && !isDisposed() && phase() === 'running') setPhase('settling');
+    },
+    settled(invocation) {
+      unsettled.delete(invocation);
+      if (owner !== invocation) return;
+      owner = undefined;
+      // An older invocation's cleanup, or a disposed binding, never rewrites the phase.
+      if (!isDisposed()) setPhase('idle');
+    },
+    retire() {
+      binding.dispose();
+    },
+  };
+
+  const binding: ActionBinding = {
+    id,
+    get state() {
+      return state;
+    },
+    subscribe(listener) {
+      if (phase() === 'disposed') return () => undefined;
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      if (isDisposed()) return;
+      disposing = true;
+      seam.detach();
+      setPhase('disposed');
+      listeners.clear();
+      for (const invocation of [...unsettled]) invocation.disposed();
+    },
+  };
+
+  const ignore = (busy: Invocation<Event>): void => {
+    emitObservation(plan, id, Date.now(), { phase: 'ignored', ignoredReason: 'busy', busyInvocationId: busy.id });
+  };
+
+  const activate = (event: Event): void => {
+    if (isDisposed()) return;
+    const busy = owner;
+    if (busy !== undefined) {
+      busy.recheck();
+      // Revalidating may have ended it, or retired this binding.
+      if (isDisposed()) return;
+    }
+    if (owner !== undefined && plan.busy === 'ignore') {
+      ignore(owner);
+      return;
+    }
+    const invocation = new Invocation<Event>(plan, invocationOwner, seam, limits);
+    const replaced = owner;
+    owner = invocation;
+    replaced?.replaced();
+    setPhase('running');
+    // A subscriber is application code and may have disposed the binding while being told. A
+    // disposed binding has detached and starts no work.
+    if (isDisposed()) {
+      owner = undefined;
+      return;
+    }
+    unsettled.add(invocation);
+    const failure = invocation.start(event);
+    if (failure !== undefined) throw failure.error;
+  };
+
+  return { binding, activate };
+}

package/src/actions/category.ts

@@ -0,0 +1,60 @@
+// Why an action failed, as far as the evidence goes. The category supplements the stage and the
+// failure kind that already say how far the work got; it never rewrites a decided outcome, and it
+// is not a message to show: raw causes, server text and stack details stay with the application.
+
+/** What the SDK itself can establish. An application may use any other non-empty string. */
+export type KnownErrorCategory =
+  | 'timeout'
+  | 'canceled'
+  | 'authentication-required'
+  | 'permission-denied'
+  | 'unavailable'
+  | 'validation'
+  | 'application'
+  | 'unknown';
+
+/**
+ * Open on purpose: a consumer must handle a category it does not know, and `'unknown'` is the
+ * fallback when nothing established a cause. `(string & {})` keeps the known names in editors.
+ */
+export type ErrorCategory = KnownErrorCategory | (string & Record<never, never>);
+
+/**
+ * A cause that says what happened. An application's handler, prerequisite or hook throws it when
+ * it knows, for instance because the response was a 401 or the error was typed, and wraps the
+ * original error as `cause`. Nothing is inferred from a message, a status code or a field a
+ * foreign error merely happens to have: an error that is not an `ActionError` (or the platform's
+ * own timeout and abort errors) is `'unknown'`, so an unfamiliar failure is never taken for an
+ * authentication failure.
+ */
+export class ActionError extends Error {
+  readonly category: ErrorCategory;
+
+  constructor(category: ErrorCategory, message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    if (typeof category !== 'string' || category === '') {
+      throw new TypeError('An ActionError needs a non-empty category.');
+    }
+    this.name = 'ActionError';
+    this.category = category;
+  }
+}
+
+/**
+ * The category the evidence in `error` supports, or `fallback` when it supports none: the kind of
+ * failure the runtime itself decided on (for example input that could not be read) is that
+ * evidence and is passed in as the fallback.
+ */
+export function categorize(error: unknown, fallback: ErrorCategory = 'unknown'): ErrorCategory {
+  if (error instanceof ActionError) return error.category;
+  // The platform's own typed errors (what `AbortSignal.timeout` and `fetch` reject with) are
+  // DOMExceptions with these exact names. A plain Error that merely carries the same `name` is
+  // not typed evidence.
+  const platform: unknown = (globalThis as { DOMException?: unknown }).DOMException;
+  if (typeof platform === 'function' && error instanceof platform) {
+    const { name } = error as { name?: unknown };
+    if (name === 'TimeoutError') return 'timeout';
+    if (name === 'AbortError') return 'canceled';
+  }
+  return fallback;
+}