@saga-a2ui/core 0.7.7-rc.1 → 0.8.0-rc.1

package/README.md

@@ -1,6 +1,6 @@
 # @saga-a2ui/core
 
-Renderer-independent actions and A2UI v0.9 decoding. Entry points: `/actions`, `/actions/action-button-schema`, `/delivered-result` (the neutral whole-result type a delivery hands a view), `/host-links`, `/protocols/a2ui/v0_9`, `/protocols/a2ui/zod3`.
+Renderer-independent actions and A2UI v0.9 decoding. Entry points: `/actions`, `/actions/action-button-schema`, `/conversation` (the contract by which a view adds a message to the conversation), `/delivered-result` (the neutral whole-result type a delivery hands a view), `/host-links`, `/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.
 

package/package.json

@@ -1 +1 @@
-{"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","./delivered-result":"./src/delivered-result.ts","./host-links":"./src/host-links.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.7.7-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"}}
+{"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","./conversation":"./src/conversation.ts","./delivered-result":"./src/delivered-result.ts","./host-links":"./src/host-links.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.8.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/conversation.ts

@@ -0,0 +1,74 @@
+// How a view adds a message to the conversation around it. The contract is renderer- and
+// delivery-neutral, like the host link contract: an application consumes it, a delivery (MCP Apps
+// today) supplies an implementation, and neither depends on the other.
+
+/**
+ * What happened to one request the host was asked to carry out.
+ *
+ * - `denied`: the host refused it (the person declined, a policy blocked it).
+ * - `unavailable`: the host advertises no capability for the request, or the view has ended. That
+ *   request was not sent.
+ * - `failed`: the request could not complete (connection lost, timeout). Whether the host acted on
+ *   it is unknown.
+ */
+export type RequestOutcome = 'denied' | 'unavailable' | 'failed';
+
+/**
+ * The result of `appendMessage`.
+ *
+ * - `appended`: the host accepted the message. It does not show that the assistant replied, or
+ *   what it said. `context` is set only when a best-effort context was skipped, and says why.
+ * - Any other outcome means nothing was appended. `stage` says which request stopped the append.
+ */
+export type AppendResult =
+  | {
+      readonly outcome: 'appended';
+      readonly context?: RequestOutcome;
+    }
+  | {
+      readonly outcome: RequestOutcome;
+      readonly stage: 'context' | 'message';
+    };
+
+/**
+ * The only way a view reaches the conversation: add a message as the person, which gives the
+ * assistant its turn. A view receives its own instance explicitly.
+ */
+export interface Conversation {
+  /**
+   * Adds a message to the conversation as the person, which gives the assistant its turn.
+   * `context` is information for that turn that the conversation does not show. By default the
+   * message is sent only if the context was accepted; `bestEffort: true` sends it regardless.
+   * Never rejects. A result of `appended` is a prompt delivered, not an action taken.
+   */
+  appendMessage(
+    text: string,
+    options?: {
+      /** The only accepted value; the person's role is what hosts permit a view to speak as. */
+      readonly role?: 'user';
+      readonly context?: {
+        readonly text: string;
+        readonly data?: Record<string, unknown>;
+        /** Send the message even when the context could not be delivered. Default `false`. */
+        readonly bestEffort?: boolean;
+      };
+    },
+  ): Promise<AppendResult>;
+}
+
+/**
+ * For a page that has no host at all: every call resolves `unavailable` and nothing is sent. The
+ * stage is the first request the call would have made: the context, unless it is best effort.
+ */
+export const NO_CONVERSATION: Conversation = Object.freeze<Conversation>({
+  appendMessage: (_text, options) => {
+    const context = options?.context;
+    return Promise.resolve<AppendResult>({
+      outcome: 'unavailable',
+      stage:
+        context !== undefined && context.bestEffort !== true
+          ? 'context'
+          : 'message',
+    });
+  },
+});