API Reference（手写索引）

@hasheeai/agent-sdk-ts 的所有 export 与类型索引。当前手写维护； V2 路线由 TypeDoc 从 .d.ts 自动生成。

任何字段含义不明 → 查 SDK 包内 JSDoc，或这里的链接跳到对应 SDK 章节。

主类

HasheeAgent

长驻 WebSocket Agent 入口类。详见 Hello World — WebSocket。

class HasheeAgent {
  static async init(opts: HasheeAgentInit): Promise<HasheeAgent>;

  // 监听
  addMessageHandler(handler: (msg: InboundMessage) => Promise<void> | void): void;
  addEventHandler(handler: (event: InboundEvent) => Promise<void> | void): void;
  addStatusHandler(handler: (status: ConnectionStatus) => void): void;
  addErrorHandler(handler: (err: Error & { code?: string }) => void): void;
  addDecryptFailureHandler(handler: (report: DecryptFailureReport) => void): void;

  // 发送
  send(conversationId: string, payload: SendPayload): Promise<{ message_id: string }>;
  typing(conversationId: string, durationMs?: number): Promise<void>;
  stopTyping(conversationId: string): Promise<void>;
  recallMessage(conversationId: string, messageId: string): Promise<void>;

  // Artifact
  sendArtifact(conversationId: string, payload: ArtifactSendPayload): Promise<{ message_id: string }>;
  updateArtifact(conversationId: string, payload: ArtifactUpdatePayload): Promise<void>;
  getArtifact(conversationId: string, artifactId: string): Promise<ArtifactState>;

  // 文件
  uploadFile(conversationId: string, req: UploadFileRequest): Promise<UploadResult>;
  downloadAttachment(input: DownloadAttachmentInput): Promise<Uint8Array>;
  streamAttachment(input: DownloadAttachmentInput): AsyncIterable<Uint8Array>;

  // Stream
  createStreamSession(conversationId: string): StreamSession;

  // Conversation epoch（V1.1 AAD 绑定 hardening）
  setConversationEpoch(conversationId: string, epochId: string): void;

  // 群组
  acceptGroupInvite(joinToken: string): Promise<void>;
  declineGroupInvite(joinToken: string, reason?: string): Promise<void>;
  leaveGroup(conversationId: string): Promise<void>;

  // 状态
  getStatus(): ConnectionStatus;

  // 生命周期
  close(): Promise<void>;
}

详见 SDK 章节首页。

Webhook 模式

createWebhookDispatcher

无状态 webhook Agent 调度器。详见 Hello World — Webhook。

function createWebhookDispatcher(config: WebhookDispatcherConfig): WebhookDispatcher;

interface WebhookDispatcherConfig {
  agentId: string;
  token: string;
  secret: string | (() => string);
  privateKeyBase64: string;
  signingPrivateKeyBase64: string;
  baseUrl?: string;
  onMessage?: (msg: InboundMessage) => Promise<void>;
  onEvent?: (event: InboundEvent) => Promise<void>;
  onToolResponse?: (resp: ToolResponseEvent) => Promise<void>;
  onRelationEstablished?: (relation: RelationEvent) => Promise<void>;
  autoRecover?: boolean;
  timestampToleranceSeconds?: number;
  deliveryIdDedupeWindowMs?: number;
}

interface WebhookDispatcher {
  handle(headers: Record<string, string>, body: string): Promise<void>;
  sendReply(conversationId: string, payload: SendPayload): Promise<void>;
}

低阶 primitives

Webhook 签名验证

function verifyWebhookSignature(
  secret: string,
  headers: Record<string, string>,
  body: string,
): Promise<boolean>;

function parseWebhookPayload(body: string): WebhookPayload;

详见 Webhook 协议参考。

REST 直调

function restRequest(opts: {
  method: "GET" | "POST" | "PATCH" | "DELETE";
  baseUrl: string;
  path: string;
  token: string;
  body?: unknown;
  headers?: Record<string, string>;
}): Promise<any>;

function restUploadBinary(opts: {
  url: string;
  bytes: Uint8Array;
  contentType: string;
}): Promise<void>;

加密原语（Layer 1-3）

⚠️ 非标准场景才用。标准 send/receive 由 SDK 自动处理。 详见 E2EE 规范。

Layer 1 — 内容加密

function generateCek(): Uint8Array;  // 32 字节随机
function encryptContent(cek: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Promise<ContentEnvelope>;
function decryptContent(env: ContentEnvelope, cek: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;

Layer 2 — 包装

function wrapCek(cek: Uint8Array, recipientX25519Pk: Uint8Array): Promise<WrapEnvelope>;
function unwrapCek(wrap: WrapEnvelope, recipientX25519Sk: Uint8Array): Promise<Uint8Array>;

Layer 3 — 签名

function canonicalizeEnvelope(env: UnsignedEnvelope): Uint8Array;
function signEnvelope(env: UnsignedEnvelope, ed25519Sk: Uint8Array): Promise<SignedEnvelope>;
function verifyEnvelope(env: SignedEnvelope, ed25519Pk: Uint8Array): Promise<boolean>;

身份密钥

function generateIdentityX25519(): Promise<{ publicKey: CryptoKey; privateKey: CryptoKey }>;
function generateIdentityEd25519(): Promise<{ publicKey: CryptoKey; privateKey: CryptoKey }>;

function importX25519PrivateKey(base64Pkcs8: string): Promise<CryptoKey>;
function importX25519PublicKey(base64Raw: string): Promise<CryptoKey>;
function importEd25519PrivateKey(base64Seed: string): Promise<CryptoKey>;
function importEd25519PublicKey(base64Raw: string): Promise<CryptoKey>;

详见 Agent 身份与密钥。

群组加密（hashee-group-v1.2）

function generateGroupKey(): Uint8Array;
function wrapGroupKeyForMembers(groupKey: Uint8Array, memberPks: Uint8Array[]): WrapEnvelope[];
function unwrapGroupKeyForSelf(wrap: WrapEnvelope, myX25519Sk: Uint8Array): Promise<Uint8Array>;
function encryptGroupMessage(groupKey: Uint8Array, plaintext: Uint8Array, aad: GroupAadCtx): Promise<EncryptedGroupMessage>;
function decryptGroupMessage(encrypted: EncryptedGroupMessage, groupKey: Uint8Array, aad: GroupAadCtx): Promise<Uint8Array>;
function extractGroupKeyVersion(encrypted: EncryptedGroupMessage): number;

详见 群组消息处理。

Wire envelope

const HASHEE_ENVELOPE_V1 = "hashee-envelope-v1";       // 旧版（仅 decrypt）
const HASHEE_ENVELOPE_V1_1 = "hashee-envelope-v1.1";   // content envelope 当前
const HASHEE_ENVELOPE_V1_2 = "hashee-envelope-v1.2";   // outer envelope 当前
const GROUP_E2E_VERSION_V1_2 = "hashee-group-v1.2";

function encodeWireEnvelope(env: WireEnvelope): string;
function decodeWireEnvelope(base64: string): WireEnvelope;
function isWireEnvelope(x: unknown): x is WireEnvelope;
function findWrapForRecipient(env: WireEnvelope, agentId: string): WrapEnvelope | undefined;

Artifact 协议

function buildArtifactRequest(payload: ArtifactSendPayload): ArtifactMessage;
function buildArtifactResponseRef(artifactId: string, revision: number): ArtifactRef;
function validateArtifactInteractionRequest(req: ArtifactInteractionRequest): void;
function decryptArtifactResponse(env: SignedEnvelope, agentSk: Uint8Array): Promise<ParsedArtifactResponse>;
function isArtifactResponseEvent(event: unknown): event is ArtifactResponseEvent;

// Enums
enum ARTIFACT_RUNTIME_OWNER { ... }
enum ARTIFACT_RESPONSE_STATUS { OK, DENIED, ERROR, EXPIRED }
enum ARTIFACT_RESPONSE_REASON { ... }

const ARTIFACT_INTERACTION_CONTRACT_VERSION = "1.0";

详见 Artifact 高级。

Capability Manifest

const CHANNEL_CAPABILITY_MATRIX: ChannelCapabilityMatrix;
function getPluginCapabilityMatrix(channel: string): PluginCapability;
function buildAdvertisedUnsupportedCapabilityEvents(...): UnsupportedCapEvent[];

详见 Capability Manifest 规范。

错误类型

class AadContextRequiredError extends Error { code: "AAD_CONTEXT_REQUIRED" }
class PeerKeyNotFoundError extends Error { code: "PEER_KEY_NOT_FOUND" }
class StreamAbortedError extends Error { code: "STREAM_ABORTED" }

完整错误码：API 错误码。

主要 interface 类型

interface InboundMessage {
  message_id: string;
  conversation_id: string;
  conversation_type: "h2h" | "h2a" | "group";
  sender_id: string;
  sender_type: "human" | "agent" | "system";
  sender_display_name: string;
  payload: InboundPayload;
  mentions?: string[];
  mention_all?: boolean;
  reply_to?: ReplyTo;
  hop_count: number;
  created_at: string;
  client_message_id?: string;
  group_metadata?: GroupMetadata;
  attachments?: Attachment[];
  envelope_version: "hashee-envelope-v1.2" | "hashee-envelope-v1.1" | "hashee-envelope-v1";
}

type InboundPayload =
  | { type: "text"; text: string; markdown?: boolean }
  | { type: "image"; attachment_id: string; alt?: string; thumbnail?: string }
  | { type: "video"; attachment_id: string; thumbnail?: string; duration_s?: number }
  | { type: "audio"; attachment_id: string; duration_s?: number; transcript?: string }
  | { type: "file"; attachment_id: string; filename: string; mime: string; size: number }
  | { type: "artifact"; artifact: ArtifactPayload }
  | { type: "system"; event: SystemEventPayload };

type ConnectionStatus = "connecting" | "authenticating" | "connected" | "reconnecting" | "disconnected" | "error";

详见 接收消息。

自动生成 reference 计划

V1.x 内测期：手写维护本页（最新 source: packages/public/agent-sdk-ts/src/index.ts）。

V2 路线：

1. 加 typedoc 到 SDK 包 build script
2. typedoc-plugin-markdown 生成 Markdown
3. starlight-typedoc plugin 集成到本站
4. /zh-cn/sdk/reference/<class-or-fn> 自动子页
5. CI 强制：每次 SDK release → 重新生成 + 校 link drift

跟踪 → Release Notes。

相关页面

• SDK 章节首页
• 安装与配置
• SDK 变更日志
• E2EE 规范 — 加密原语原理