@sophonsai/agent-embed-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @sophonsai/agent-embed-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.
+`@sophonsai/agent-embed-core` 是 Agent Embed 的底层通信协议包，负责定义通信消息结构、协议版本、公共数据形状和运行时校验。
+
+Core 不包含面板挂载、生命周期管理或主题 preset 等产品配置。主题预设由 `@sophonsai/agent-embed-sdk` 定义并对外导出。
+
+该包是 SDK 和框架适配包的底层依赖。业务项目通常应安装 SDK 或 React/Vue 适配包，不需要直接依赖 Core。
+
+URL 模式的 init config 为 `{ mode: "url", appearance, threadId? }`，不携带 Agent ID 或用户凭证。Agent 与身份由 iframe URL 中的 应用接入凭证 在 WebAPI 端解析。

package/dist/index.d.mts

@@ -0,0 +1,299 @@
+//#region src/types.d.ts
+declare const AGENT_EMBED_QUERY_PARAMS: {
+  readonly agentId: "agent_id";
+  readonly threadId: "thread_id";
+  readonly token: "token";
+  readonly theme: "theme";
+  readonly fontSize: "font_size";
+  readonly headerHistoryButton: "header_history_button";
+  readonly headerNewConversationButton: "header_new_conversation_button";
+  readonly headerThemeSettingButton: "header_theme_setting_button";
+};
+interface AgentEmbedTheme {
+  preset: string;
+}
+interface AgentEmbedHeaderAppearance {
+  historyButton?: boolean;
+  newConversationButton?: boolean;
+  themeSettingButton?: boolean;
+}
+interface AgentAppearance {
+  theme?: AgentEmbedTheme;
+  fontSize?: number;
+  header?: AgentEmbedHeaderAppearance;
+}
+interface AgentSessionContext {
+  threadId: string;
+  turnId: string;
+}
+interface AgentTextPayload {
+  version: 1;
+  range_unit: 'utf16';
+  references: Array<{
+    id: string;
+    type: 'resource';
+    provider: string;
+    resource_id: string;
+    label: string;
+    value: string;
+    range: {
+      start: number;
+      end: number;
+    };
+  }>;
+}
+interface AgentSessionRunEventContext {
+  runId: string;
+  threadId: string | null;
+  objectType: 'model' | 'agent' | 'knowledge_base' | 'database' | 'file';
+  objectId: string;
+  step: number;
+  parentToolCallId: string | null;
+}
+type AgentSessionEventContext = AgentSessionRunEventContext & AgentSessionContext;
+interface AgentToolCallStartedEvent {
+  toolCallId: string;
+  toolName: string;
+  toolNameEn?: string;
+  actionDescription?: string;
+  arguments: Record<string, unknown>;
+}
+interface AgentToolCallSucceededEvent extends AgentToolCallStartedEvent {
+  result: string;
+}
+interface AgentToolCallProgressUpdatedEvent extends AgentToolCallStartedEvent {
+  sequence: number;
+  progress: {
+    type: string;
+    phase: string;
+    data: Record<string, unknown>;
+  };
+}
+interface AgentToolCallFailedEvent extends AgentToolCallStartedEvent {
+  error: string;
+}
+interface AgentToolCallBackgroundedEvent {
+  toolCallId: string;
+  toolName: string;
+  toolNameEn?: string;
+  content?: string;
+}
+interface AgentToolCallCancelledEvent {
+  toolCallId: string;
+  toolName: string;
+  toolNameEn?: string;
+  reason?: 'user_terminated' | 'session_disconnected' | 'background_cancelled' | 'unknown';
+}
+type AgentToolCall = AgentToolCallStartedEvent & ({
+  kind: 'tool';
+  executor: 'server';
+} | {
+  kind: 'action';
+  executor: 'client';
+});
+interface AgentToolCallCreatedEvent {
+  toolCall: AgentToolCall;
+  dependsOn?: {
+    toolCallId: string;
+    reason: string;
+  };
+}
+interface AgentToolApprovalRequestedEvent {
+  toolCallIds: string[];
+}
+interface AgentClientActionRequestEvent {
+  actionId: string;
+  actionName: string;
+  actionNameEn?: string;
+  arguments: Record<string, unknown>;
+  actionDescription?: string;
+}
+interface AgentUserFeedbackConsumedEvent {
+  content: string;
+  payload?: AgentTextPayload | null;
+}
+interface AgentUserSteerConsumedEvent {
+  steerId: string;
+  content: string;
+  payload?: AgentTextPayload;
+}
+interface AgentUserSteerCancelledEvent {
+  steerId: string;
+}
+interface AgentUserInputSubmittedEvent {
+  content: string;
+  payload?: AgentTextPayload | null;
+}
+type AgentSessionTurnStartedEvent = Record<string, never>;
+type AgentSessionTurnSucceededEvent = Record<string, never>;
+type AgentSessionRunStartedEvent = Record<string, never>;
+type AgentSessionRunIdledEvent = Record<string, never>;
+type AgentSessionRunEndedEvent = Record<string, never>;
+interface AgentSessionTurnFailedEvent {
+  code: number;
+  error: string;
+}
+interface AgentSessionTurnCancelledEvent {
+  reason: 'user_graceful_termination' | 'user_forced_termination' | 'hitl_user_termination' | 'hitl_timeout' | 'session_orphaned' | 'runtime_lost' | 'unknown';
+}
+interface AgentSystemMessageConsumedEvent {
+  messageId: string;
+  messageType: string;
+  content: string;
+  modelContent: string;
+  data?: unknown;
+}
+interface AgentSessionSuccess {
+  status: 'success';
+  context: AgentSessionContext | null;
+}
+interface AgentSessionFailure {
+  status: 'failure';
+  context: AgentSessionContext | null;
+  error: unknown;
+}
+interface AgentSessionCancelled {
+  status: 'cancelled';
+  context: AgentSessionContext | null;
+}
+type AgentSessionSettlement = AgentSessionSuccess | AgentSessionFailure | AgentSessionCancelled;
+type AgentServerEvent = Record<string, unknown>;
+interface AgentEvents {
+  onConcurrentSend?: () => void;
+  onEvent?: (event: AgentServerEvent) => void;
+  onSessionContextReady?: (context: AgentSessionContext) => void;
+  onToolCallCreated?: (event: AgentToolCallCreatedEvent, context: AgentSessionEventContext) => void;
+  onToolApprovalRequested?: (event: AgentToolApprovalRequestedEvent, context: AgentSessionEventContext) => void;
+  onToolCallStarted?: (event: AgentToolCallStartedEvent, context: AgentSessionEventContext) => void;
+  onToolCallProgressUpdated?: (event: AgentToolCallProgressUpdatedEvent, context: AgentSessionEventContext) => void;
+  onToolCallBackgrounded?: (event: AgentToolCallBackgroundedEvent, context: AgentSessionEventContext) => void;
+  onToolCallSucceeded?: (event: AgentToolCallSucceededEvent, context: AgentSessionEventContext) => void;
+  onToolCallFailed?: (event: AgentToolCallFailedEvent, context: AgentSessionEventContext) => void;
+  onToolCallCancelled?: (event: AgentToolCallCancelledEvent, context: AgentSessionEventContext) => void;
+  onClientActionRequest?: (event: AgentClientActionRequestEvent, context: AgentSessionEventContext) => void;
+  onUserFeedbackConsumed?: (event: AgentUserFeedbackConsumedEvent, context: AgentSessionEventContext) => void;
+  onUserSteerConsumed?: (event: AgentUserSteerConsumedEvent, context: AgentSessionEventContext) => void;
+  onUserSteerCancelled?: (event: AgentUserSteerCancelledEvent, context: AgentSessionRunEventContext) => void;
+  onUserInputSubmitted?: (event: AgentUserInputSubmittedEvent, context: AgentSessionEventContext) => void;
+  onSessionTurnStarted?: (event: AgentSessionTurnStartedEvent, context: AgentSessionEventContext) => void;
+  onSessionTurnSucceeded?: (event: AgentSessionTurnSucceededEvent, context: AgentSessionEventContext) => void;
+  onSessionTurnFailed?: (event: AgentSessionTurnFailedEvent, context: AgentSessionEventContext) => void;
+  onSessionTurnCancelled?: (event: AgentSessionTurnCancelledEvent, context: AgentSessionEventContext) => void;
+  onSessionRunStarted?: (event: AgentSessionRunStartedEvent, context: AgentSessionRunEventContext) => void;
+  onSessionRunIdled?: (event: AgentSessionRunIdledEvent, context: AgentSessionRunEventContext) => void;
+  onSessionRunEnded?: (event: AgentSessionRunEndedEvent, context: AgentSessionRunEventContext) => void;
+  onSystemMessageConsumed?: (event: AgentSystemMessageConsumedEvent, context: AgentSessionEventContext) => void;
+  onSuccess?: (result: AgentSessionSuccess) => void;
+  onError?: (result: AgentSessionFailure) => void;
+  onCancelled?: (result: AgentSessionCancelled) => void;
+  onSettled?: (result: AgentSessionSettlement) => void;
+}
+declare const AGENT_EVENT_NAMES: readonly ["onConcurrentSend", "onEvent", "onSessionContextReady", "onToolCallCreated", "onToolApprovalRequested", "onToolCallStarted", "onToolCallProgressUpdated", "onToolCallBackgrounded", "onToolCallSucceeded", "onToolCallFailed", "onToolCallCancelled", "onClientActionRequest", "onUserFeedbackConsumed", "onUserSteerConsumed", "onUserSteerCancelled", "onUserInputSubmitted", "onSessionTurnStarted", "onSessionTurnSucceeded", "onSessionTurnFailed", "onSessionTurnCancelled", "onSessionRunStarted", "onSessionRunIdled", "onSessionRunEnded", "onSystemMessageConsumed", "onSuccess", "onError", "onCancelled", "onSettled"];
+interface AgentEmbedPlatformUserAuth {
+  type: 'platform.user.credential';
+  credential: string;
+}
+interface AgentEmbedExtensionUserAuth {
+  type: 'extension.user.identity';
+  appId: string;
+  externalUser: {
+    id: string;
+    name?: string;
+  };
+}
+type AgentEmbedAuth = AgentEmbedPlatformUserAuth | AgentEmbedExtensionUserAuth;
+interface AgentEmbedSendMessageInput {
+  text: string;
+}
+interface AgentEmbedInputQuery extends AgentEmbedSendMessageInput {
+  context?: string;
+}
+interface AgentEmbedInstance {
+  sendMessage: (input: AgentEmbedSendMessageInput) => void;
+  addInputQuery: (input: AgentEmbedInputQuery) => void;
+  abortResponse: () => void;
+  openHistoryPanel: () => void;
+  openThemeSettingsPanel: () => void;
+  newConversation: () => void;
+  focusInput: () => void;
+  scrollToBottom: () => void;
+}
+interface AgentEmbedInitError {
+  code: 'invalid_token' | 'forbidden' | 'agent_not_found' | 'request_failed' | 'frame_load_failed';
+  message: string;
+}
+interface AgentEmbedInitConfig {
+  agentId: string;
+  auth: AgentEmbedAuth;
+  /** @deprecated Bridge compatibility for token-mode clients and frames. */
+  token?: string;
+  threadId?: string;
+  appearance: AgentAppearance;
+}
+interface AgentEmbedLegacyInitConfig {
+  agentId: string;
+  token: string;
+  auth?: never;
+  threadId?: string;
+  appearance: AgentAppearance;
+}
+/** URL mode config carries appearance and session context, never platform credentials. */
+type AgentRuntimeValue = string | number | boolean | null | AgentRuntimeValue[] | AgentRuntimeVariables;
+interface AgentRuntimeVariables {
+  [key: string]: AgentRuntimeValue;
+}
+interface AgentEmbedUrlInitConfig {
+  mode: 'url';
+  runtime_variables?: AgentRuntimeVariables;
+  threadId?: string;
+  appearance: AgentAppearance;
+}
+type AgentEmbedBridgeConfig = AgentEmbedInitConfig | AgentEmbedUrlInitConfig;
+//#endregion
+//#region src/protocol.d.ts
+declare const AGENT_EMBED_BRIDGE = "sophonsai/agent-component-bridge";
+declare const AGENT_EMBED_BRIDGE_VERSION = 1;
+type AgentEmbedAction = 'sendMessage' | 'addInputQuery' | 'abortResponse' | 'openHistoryPanel' | 'openThemeSettingsPanel' | 'newConversation' | 'focusInput' | 'scrollToBottom';
+type AgentEmbedCallback = keyof AgentEvents | 'onThemeChange' | 'onFontSizeChange' | 'onInitError';
+interface AgentEmbedInitMessage {
+  bridge: typeof AGENT_EMBED_BRIDGE;
+  version: typeof AGENT_EMBED_BRIDGE_VERSION;
+  type: 'init';
+  instanceId: string;
+  config: AgentEmbedInitConfig | AgentEmbedLegacyInitConfig | AgentEmbedUrlInitConfig;
+}
+interface AgentEmbedCommandMessage {
+  bridge: typeof AGENT_EMBED_BRIDGE;
+  version: typeof AGENT_EMBED_BRIDGE_VERSION;
+  type: 'command';
+  instanceId: string;
+  action: AgentEmbedAction;
+  args: unknown[];
+}
+interface AgentEmbedAppearanceUpdate {
+  theme?: AgentEmbedTheme | null;
+  fontSize?: number | null;
+  header?: AgentEmbedHeaderAppearance | null;
+}
+interface AgentEmbedUpdateAppearanceMessage {
+  bridge: typeof AGENT_EMBED_BRIDGE;
+  version: typeof AGENT_EMBED_BRIDGE_VERSION;
+  type: 'update-appearance';
+  instanceId: string;
+  appearance: AgentEmbedAppearanceUpdate;
+}
+type AgentEmbedHostMessage = AgentEmbedInitMessage | AgentEmbedCommandMessage | AgentEmbedUpdateAppearanceMessage;
+interface AgentEmbedFrameMessage {
+  bridge: typeof AGENT_EMBED_BRIDGE;
+  version: typeof AGENT_EMBED_BRIDGE_VERSION;
+  type: 'hello' | 'ready' | 'callback';
+  instanceId?: string;
+  callback?: AgentEmbedCallback;
+  args?: unknown[];
+}
+/** Runtime variables cross the iframe boundary as a JSON object. */
+declare const isAgentRuntimeVariables: (value: unknown) => value is AgentRuntimeVariables;
+declare const isAgentEmbedHostMessage: (value: unknown) => value is AgentEmbedHostMessage;
+declare const isAgentEmbedFrameMessage: (value: unknown) => value is AgentEmbedFrameMessage;
+//#endregion
+export { AGENT_EMBED_BRIDGE, AGENT_EMBED_BRIDGE_VERSION, AGENT_EMBED_QUERY_PARAMS, AGENT_EVENT_NAMES, AgentAppearance, AgentClientActionRequestEvent, AgentEmbedAction, AgentEmbedAppearanceUpdate, AgentEmbedAuth, AgentEmbedBridgeConfig, AgentEmbedCallback, AgentEmbedCommandMessage, AgentEmbedExtensionUserAuth, AgentEmbedFrameMessage, AgentEmbedHeaderAppearance, AgentEmbedHostMessage, AgentEmbedInitConfig, AgentEmbedInitError, AgentEmbedInitMessage, AgentEmbedInputQuery, AgentEmbedInstance, AgentEmbedLegacyInitConfig, AgentEmbedPlatformUserAuth, AgentEmbedSendMessageInput, AgentEmbedTheme, AgentEmbedUpdateAppearanceMessage, AgentEmbedUrlInitConfig, AgentEvents, AgentRuntimeValue, AgentRuntimeVariables, AgentServerEvent, AgentSessionCancelled, AgentSessionContext, AgentSessionEventContext, AgentSessionFailure, AgentSessionRunEndedEvent, AgentSessionRunEventContext, AgentSessionRunIdledEvent, AgentSessionRunStartedEvent, AgentSessionSettlement, AgentSessionSuccess, AgentSessionTurnCancelledEvent, AgentSessionTurnFailedEvent, AgentSessionTurnStartedEvent, AgentSessionTurnSucceededEvent, AgentSystemMessageConsumedEvent, AgentTextPayload, AgentToolApprovalRequestedEvent, AgentToolCall, AgentToolCallBackgroundedEvent, AgentToolCallCancelledEvent, AgentToolCallCreatedEvent, AgentToolCallFailedEvent, AgentToolCallProgressUpdatedEvent, AgentToolCallStartedEvent, AgentToolCallSucceededEvent, AgentUserFeedbackConsumedEvent, AgentUserInputSubmittedEvent, AgentUserSteerCancelledEvent, AgentUserSteerConsumedEvent, isAgentEmbedFrameMessage, isAgentEmbedHostMessage, isAgentRuntimeVariables };

package/dist/index.mjs

@@ -0,0 +1,127 @@
+//#region src/protocol.ts
+const AGENT_EMBED_BRIDGE = "sophonsai/agent-component-bridge";
+const AGENT_EMBED_BRIDGE_VERSION = 1;
+/** Runtime variables cross the iframe boundary as a JSON object. */
+const isAgentRuntimeVariables = (value) => {
+	const ancestors = /* @__PURE__ */ new Set();
+	const isValue = (item) => {
+		if (item === null || typeof item === "string" || typeof item === "boolean") return true;
+		if (typeof item === "number") return Number.isFinite(item);
+		if (typeof item !== "object" || ancestors.has(item)) return false;
+		if (!Array.isArray(item) && Object.prototype.toString.call(item) !== "[object Object]") return false;
+		ancestors.add(item);
+		const valid = Object.values(item).every(isValue);
+		ancestors.delete(item);
+		return valid;
+	};
+	return Boolean(value && typeof value === "object" && !Array.isArray(value) && isValue(value));
+};
+const isAgentEmbedHostMessage = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const message = value;
+	if (message.bridge !== "sophonsai/agent-component-bridge" || message.version !== 1 || typeof message.instanceId !== "string") return false;
+	if (message.type === "init") {
+		const config = message.config;
+		if (config?.mode === "url") return Boolean(config.appearance && typeof config.appearance === "object" && (config.threadId === void 0 || typeof config.threadId === "string") && (config.runtime_variables === void 0 || isAgentRuntimeVariables(config.runtime_variables)));
+		if (!config || typeof config.agentId !== "string") return false;
+		if (!config.auth) return typeof config.token === "string";
+		if (typeof config.auth !== "object") return false;
+		const auth = config.auth;
+		if (auth.type === "platform.user.credential") return typeof auth.credential === "string";
+		if (auth.type !== "extension.user.identity") return false;
+		const externalUser = auth.externalUser;
+		return Boolean(typeof auth.appId === "string" && externalUser && typeof externalUser === "object" && typeof externalUser.id === "string" && (externalUser.name === void 0 || typeof externalUser.name === "string"));
+	}
+	if (message.type === "update-appearance") {
+		const appearance = message.appearance;
+		if (!appearance || typeof appearance !== "object") return false;
+		const hasTheme = Object.prototype.hasOwnProperty.call(appearance, "theme");
+		const hasFontSize = Object.prototype.hasOwnProperty.call(appearance, "fontSize");
+		const hasHeader = Object.prototype.hasOwnProperty.call(appearance, "header");
+		if (!hasTheme && !hasFontSize && !hasHeader) return false;
+		if (Object.keys(appearance).some((key) => key !== "theme" && key !== "fontSize" && key !== "header")) return false;
+		if (hasTheme && appearance.theme !== null && (!appearance.theme || typeof appearance.theme.preset !== "string")) return false;
+		if (hasFontSize && appearance.fontSize !== null && (typeof appearance.fontSize !== "number" || !Number.isFinite(appearance.fontSize))) return false;
+		if (hasHeader && appearance.header !== null) {
+			if (!appearance.header || typeof appearance.header !== "object") return false;
+			const headerKeys = [
+				"historyButton",
+				"newConversationButton",
+				"themeSettingButton"
+			];
+			if (Object.keys(appearance.header).some((key) => !headerKeys.includes(key))) return false;
+			if (Object.values(appearance.header).some((value) => value !== void 0 && typeof value !== "boolean")) return false;
+		}
+		return true;
+	}
+	return message.type === "command" && [
+		"sendMessage",
+		"addInputQuery",
+		"abortResponse",
+		"openHistoryPanel",
+		"openThemeSettingsPanel",
+		"newConversation",
+		"focusInput",
+		"scrollToBottom"
+	].includes(message.action ?? "") && Array.isArray(message.args);
+};
+const isInitError = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const error = value;
+	return typeof error.message === "string" && typeof error.code === "string" && [
+		"invalid_token",
+		"forbidden",
+		"agent_not_found",
+		"request_failed",
+		"frame_load_failed"
+	].includes(error.code);
+};
+const isAgentEmbedFrameMessage = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const message = value;
+	return message.bridge === "sophonsai/agent-component-bridge" && message.version === 1 && (message.type === "hello" || message.type === "ready" || message.type === "callback") && (message.type !== "callback" || message.callback !== "onInitError" || isInitError(message.args?.[0]));
+};
+//#endregion
+//#region src/types.ts
+const AGENT_EMBED_QUERY_PARAMS = {
+	agentId: "agent_id",
+	threadId: "thread_id",
+	token: "token",
+	theme: "theme",
+	fontSize: "font_size",
+	headerHistoryButton: "header_history_button",
+	headerNewConversationButton: "header_new_conversation_button",
+	headerThemeSettingButton: "header_theme_setting_button"
+};
+const AGENT_EVENT_NAMES = [
+	"onConcurrentSend",
+	"onEvent",
+	"onSessionContextReady",
+	"onToolCallCreated",
+	"onToolApprovalRequested",
+	"onToolCallStarted",
+	"onToolCallProgressUpdated",
+	"onToolCallBackgrounded",
+	"onToolCallSucceeded",
+	"onToolCallFailed",
+	"onToolCallCancelled",
+	"onClientActionRequest",
+	"onUserFeedbackConsumed",
+	"onUserSteerConsumed",
+	"onUserSteerCancelled",
+	"onUserInputSubmitted",
+	"onSessionTurnStarted",
+	"onSessionTurnSucceeded",
+	"onSessionTurnFailed",
+	"onSessionTurnCancelled",
+	"onSessionRunStarted",
+	"onSessionRunIdled",
+	"onSessionRunEnded",
+	"onSystemMessageConsumed",
+	"onSuccess",
+	"onError",
+	"onCancelled",
+	"onSettled"
+];
+//#endregion
+export { AGENT_EMBED_BRIDGE, AGENT_EMBED_BRIDGE_VERSION, AGENT_EMBED_QUERY_PARAMS, AGENT_EVENT_NAMES, isAgentEmbedFrameMessage, isAgentEmbedHostMessage, isAgentRuntimeVariables };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@sophonsai/agent-embed-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Framework-independent types and protocol primitives for Sophon Agent Embed.",
+  "type": "module",
+  "keywords": [
+    "sophonsai",
+    "agent",
+    "agent-embed",
+    "protocol"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsdown": "^0.22.14"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  }
 }