@hcmai/sdk 0.15.9 → 0.15.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -80,6 +80,7 @@ var CliErrorCode = /* @__PURE__ */ ((CliErrorCode2) => {
80
80
  CliErrorCode2["WS_HANDSHAKE_REJECTED"] = "WS_HANDSHAKE_REJECTED";
81
81
  CliErrorCode2["SCOPE_FORBIDDEN"] = "SCOPE_FORBIDDEN";
82
82
  CliErrorCode2["BUSINESS_RULE_VIOLATION"] = "BUSINESS_RULE_VIOLATION";
83
+ CliErrorCode2["STREAM_FAILED_NO_SERVER_CODE"] = "STREAM_FAILED_NO_SERVER_CODE";
83
84
  CliErrorCode2["MODEL_NOT_FOUND"] = "MODEL_NOT_FOUND";
84
85
  CliErrorCode2["ACTION_NOT_FOUND"] = "ACTION_NOT_FOUND";
85
86
  CliErrorCode2["AGENT_NOT_FOUND"] = "AGENT_NOT_FOUND";
@@ -115,6 +116,9 @@ var CODE_TO_EXIT = {
115
116
  ["WS_HANDSHAKE_REJECTED" /* WS_HANDSHAKE_REJECTED */]: 2 /* AUTH_ERROR */,
116
117
  ["SCOPE_FORBIDDEN" /* SCOPE_FORBIDDEN */]: 2 /* AUTH_ERROR */,
117
118
  ["BUSINESS_RULE_VIOLATION" /* BUSINESS_RULE_VIOLATION */]: 3 /* BUSINESS_ERROR */,
119
+ // 退出码仍是 3:脚本与 P0 runner 按 3 判「这一轮没跑成」,这一刀只换**码**不换档位。
120
+ // 换的是码承载的信息——从「后端说了业务规则不通过」变成「后端什么都没说到我这儿」。
121
+ ["STREAM_FAILED_NO_SERVER_CODE" /* STREAM_FAILED_NO_SERVER_CODE */]: 3 /* BUSINESS_ERROR */,
118
122
  ["MODEL_NOT_FOUND" /* MODEL_NOT_FOUND */]: 3 /* BUSINESS_ERROR */,
119
123
  ["ACTION_NOT_FOUND" /* ACTION_NOT_FOUND */]: 3 /* BUSINESS_ERROR */,
120
124
  ["AGENT_NOT_FOUND" /* AGENT_NOT_FOUND */]: 3 /* BUSINESS_ERROR */,
@@ -259,6 +263,17 @@ function formatCause(cause) {
259
263
  }
260
264
 
261
265
  // src/meta/describe.ts
266
+ var HCM_FIELD_RAW_KEYS = [
267
+ "key",
268
+ "name",
269
+ "type",
270
+ "isRequired",
271
+ "description",
272
+ "enums",
273
+ "object",
274
+ "objectLabel",
275
+ "isI18n"
276
+ ];
262
277
  function normalizeActionParams(action3) {
263
278
  if (action3.parameters) return action3.parameters;
264
279
  if (action3.params) return action3.params;
@@ -281,7 +296,9 @@ async function describe(http, model, _opts = {}) {
281
296
  type: f.type ?? "unknown",
282
297
  required: f.isRequired,
283
298
  description: f.description,
284
- enum: f.enum,
299
+ // 只在真有值时出这一位,口径同下面的 object / i18n:绝大多数字段没有值域,
300
+ // 无条件出一个 `enums: undefined` 会让 --output json 每个字段都多一行噪声。
301
+ ...f.enums?.length ? { enums: f.enums } : {},
285
302
  // 只在有值时出这两位:没有关联目标的普通字段不该多两行 `object: undefined` 噪声
286
303
  ...f.object ? { object: f.object } : {},
287
304
  ...f.objectLabel ? { objectLabel: f.objectLabel } : {},
@@ -2879,12 +2896,17 @@ function classifyMessage(parsed) {
2879
2896
  return "connection";
2880
2897
  }
2881
2898
  var HANDSHAKE_TOKEN_QUERY_PARAM = "token";
2899
+ var HANDSHAKE_CONVERSATION_QUERY_PARAM = "conversationId";
2882
2900
  var HANDSHAKE_AUTH_ERROR_HEADER = "x-websocket-auth-error";
2901
+ var CONTROL_BUFFER_LIMIT = 16;
2883
2902
  var HANDSHAKE_BODY_CAP = 4096;
2884
2903
  var HANDSHAKE_BODY_WAIT_MS = 2e3;
2885
- function buildHandshakeUrl(endpoint, token) {
2904
+ function buildHandshakeUrl(endpoint, token, conversationId) {
2886
2905
  const url = new URL(endpoint);
2887
2906
  url.searchParams.set(HANDSHAKE_TOKEN_QUERY_PARAM, token);
2907
+ if (conversationId && conversationId.trim()) {
2908
+ url.searchParams.set(HANDSHAKE_CONVERSATION_QUERY_PARAM, conversationId.trim());
2909
+ }
2888
2910
  return url.toString();
2889
2911
  }
2890
2912
  function conversationWebSocketEndpoint(endpoint) {
@@ -2893,8 +2915,8 @@ function conversationWebSocketEndpoint(endpoint) {
2893
2915
  url.pathname = url.pathname.replace(/\/$/, "") + "/ws/conversation";
2894
2916
  return url.toString();
2895
2917
  }
2896
- function createHandshakeSocket(endpoint, token, handshakeTimeout) {
2897
- return new WebSocket(buildHandshakeUrl(endpoint, token), {
2918
+ function createHandshakeSocket(endpoint, token, handshakeTimeout, conversationId) {
2919
+ return new WebSocket(buildHandshakeUrl(endpoint, token, conversationId), {
2898
2920
  headers: { Authorization: `Bearer ${token}` },
2899
2921
  ...handshakeTimeout === void 0 ? {} : { handshakeTimeout }
2900
2922
  });
@@ -2984,6 +3006,16 @@ var WsClient = class {
2984
3006
  disconnectHandlers = /* @__PURE__ */ new Set();
2985
3007
  /** 由 close()/ensureConnected 主动关闭 → 不广播 disconnect(非异常断连)。 */
2986
3008
  intentionalClose = false;
3009
+ /**
3010
+ * issue #257:零订阅者时到达的控制帧。
3011
+ *
3012
+ * 后端 `redeliverPending` 的重投帧跟 `auth_success` 挨着发,而 CLI 挂上 onControl
3013
+ * 要晚好几个网络往返(timeline 回放、附件上传)。`dispatchControl` 的循环在零订阅者时
3014
+ * 一次都不转 —— 帧静默消失,与「后端根本没发」完全同形。攒着,等第一个订阅者来取。
3015
+ */
3016
+ controlBuffer = [];
3017
+ /** 缓冲区溢出丢掉的帧数。丢可以,静默丢不行——调用方要分得清「没发」与「我扔了」。 */
3018
+ droppedControl = 0;
2987
3019
  /**
2988
3020
  * 订阅「流进行中 socket 异常断连」(后端重启 / 网络闪断)。主动 close() 不触发。
2989
3021
  * iterator 订阅它 → 断连时 finish()(incomplete 终态),杜绝 await consume 永久挂死。
@@ -3012,7 +3044,8 @@ var WsClient = class {
3012
3044
  message: "no access token; run `hcm login`"
3013
3045
  });
3014
3046
  }
3015
- this.ws = createHandshakeSocket(this.opts.endpoint, tok);
3047
+ this.controlBuffer = [];
3048
+ this.ws = createHandshakeSocket(this.opts.endpoint, tok, void 0, this.opts.conversationId);
3016
3049
  return new Promise((resolve6, reject2) => {
3017
3050
  const settle = (fn) => {
3018
3051
  off();
@@ -3133,10 +3166,22 @@ var WsClient = class {
3133
3166
  onControl(fn) {
3134
3167
  const h = { kind: "control", fn };
3135
3168
  this.handlers.push(h);
3169
+ if (this.controlBuffer.length) {
3170
+ const pending2 = this.controlBuffer;
3171
+ this.controlBuffer = [];
3172
+ for (const ev of pending2) fn(ev);
3173
+ }
3136
3174
  return () => {
3137
3175
  this.handlers = this.handlers.filter((x) => x !== h);
3138
3176
  };
3139
3177
  }
3178
+ /**
3179
+ * 建连窗口里被缓冲区挤掉的控制帧数(填空必自陈)。
3180
+ * 非 0 意味着这条连接错过了那么多张确认卡 / 追问,调用方该据此提示用户去列一次未决暂停。
3181
+ */
3182
+ droppedControlFrames() {
3183
+ return this.droppedControl;
3184
+ }
3140
3185
  isReady() {
3141
3186
  return this.ready;
3142
3187
  }
@@ -3208,7 +3253,18 @@ var WsClient = class {
3208
3253
  for (const h of this.handlers) if (h.kind === "connection") h.fn(msg);
3209
3254
  }
3210
3255
  dispatchControl(ev) {
3211
- for (const h of this.handlers) if (h.kind === "control") h.fn(ev);
3256
+ const subscribers = this.handlers.filter(
3257
+ (h) => h.kind === "control"
3258
+ );
3259
+ if (!subscribers.length) {
3260
+ this.controlBuffer.push(ev);
3261
+ while (this.controlBuffer.length > CONTROL_BUFFER_LIMIT) {
3262
+ this.controlBuffer.shift();
3263
+ this.droppedControl++;
3264
+ }
3265
+ return;
3266
+ }
3267
+ for (const h of subscribers) h.fn(ev);
3212
3268
  }
3213
3269
  };
3214
3270
 
@@ -3257,6 +3313,7 @@ function buildSteer(content, conversationId) {
3257
3313
  }
3258
3314
 
3259
3315
  // src/chat/stream-iterator.ts
3316
+ var SERVER_ERROR_GRACE_MS = 300;
3260
3317
  async function sendMessageAndStream(ws, prompt, opts = {}) {
3261
3318
  const conversationId = opts.conversationId ?? randomUUID2();
3262
3319
  const commandId = randomUUID2();
@@ -3279,6 +3336,16 @@ async function sendMessageAndStream(ws, prompt, opts = {}) {
3279
3336
  offDisconnect?.();
3280
3337
  };
3281
3338
  const offDisconnect = ws.onDisconnect?.(() => finish());
3339
+ let lastServerError = null;
3340
+ let serverErrorWaiters = [];
3341
+ ws.onConnection?.((msg) => {
3342
+ const m = msg;
3343
+ if (!m || m.type !== "error") return;
3344
+ lastServerError = { code: m.code, message: m.message };
3345
+ const waiting = serverErrorWaiters;
3346
+ serverErrorWaiters = [];
3347
+ for (const w of waiting) w(lastServerError);
3348
+ });
3282
3349
  const off = ws.onEvent((ev) => {
3283
3350
  if (done) return;
3284
3351
  if (ev.requestId !== commandId) return;
@@ -3369,7 +3436,27 @@ async function sendMessageAndStream(ws, prompt, opts = {}) {
3369
3436
  if (ev.conversationId === conversationId) fn(ev);
3370
3437
  });
3371
3438
  const sendCommand = (command) => ws.send(command);
3372
- return { conversationId, commandId, events, cancel, onControl, sendCommand };
3439
+ const serverError = (graceMs = SERVER_ERROR_GRACE_MS) => {
3440
+ if (lastServerError) return Promise.resolve(lastServerError);
3441
+ if (graceMs <= 0) return Promise.resolve(null);
3442
+ return new Promise((resolve6) => {
3443
+ let settled = false;
3444
+ const onFrame = (f) => {
3445
+ if (settled) return;
3446
+ settled = true;
3447
+ clearTimeout(timer);
3448
+ resolve6(f);
3449
+ };
3450
+ const timer = setTimeout(() => {
3451
+ if (settled) return;
3452
+ settled = true;
3453
+ serverErrorWaiters = serverErrorWaiters.filter((w) => w !== onFrame);
3454
+ resolve6(null);
3455
+ }, graceMs);
3456
+ serverErrorWaiters.push(onFrame);
3457
+ });
3458
+ };
3459
+ return { conversationId, commandId, events, cancel, onControl, sendCommand, serverError };
3373
3460
  }
3374
3461
 
3375
3462
  // src/chat/delegation-constants.ts
@@ -3833,6 +3920,126 @@ async function fetchRecentConversations(http, limit = 10) {
3833
3920
  return { rows: result.rows, total: result.total };
3834
3921
  }
3835
3922
 
3923
+ // src/chat/interactions.ts
3924
+ var RESPOND_TIMEOUT_MS = 18e4;
3925
+ async function listPendingInteractions(http, agentId, conversationId) {
3926
+ const resp = await http.get(
3927
+ `/api/agents/${agentId}/conversations/${conversationId}/interactions`,
3928
+ { params: { status: "pending" } }
3929
+ );
3930
+ const body = resp.data?.data ?? resp.data;
3931
+ const rows = Array.isArray(body?.interactions) ? body.interactions : [];
3932
+ return rows;
3933
+ }
3934
+ var RESPOND_NEXT_STEP = {
3935
+ // TOOL_EXECUTION_FAILED:这条路上它表达的是「确认已过期或不存在」(见 handleWriteConfirm 的 catch)
3936
+ "5006": "\u8BE5\u6682\u505C\u5DF2\u8FC7\u671F\uFF08\u9ED8\u8BA4 5 \u5206\u949F\uFF09\u6216\u5DF2\u88AB\u5904\u7406\uFF1A\u7528 `hcm interactions list --conversation <\u4F1A\u8BDD>` \u91CD\u65B0\u770B\u4E00\u773C\u8FD8\u5269\u54EA\u4E9B\uFF1B\u90FD\u6CA1\u6709\u4E86\u5C31\u91CD\u53D1\u539F\u59CB\u6307\u4EE4",
3937
+ "5004": "\u65E0\u6743\u56DE\u5E94\u6B64\u6682\u505C\uFF1A\u5B83\u5C5E\u4E8E\u522B\u7684\u7528\u6237\u6216\u522B\u7684\u4F1A\u8BDD\uFF1B\u786E\u8BA4 --conversation \u4E0E\u767B\u5F55\u8EAB\u4EFD\u5BF9\u5F97\u4E0A\uFF08hcm identity list\uFF09",
3938
+ "5011": "\u8FD9\u4E2A\u4F1A\u8BDD\u8FD8\u6709\u522B\u7684\u672A\u51B3\u6682\u505C\u6321\u7740\uFF1A\u5148 `hcm interactions list --conversation <\u4F1A\u8BDD>` \u9010\u6761\u5904\u7406\u5B8C",
3939
+ "9001": "\u540E\u7AEF\u5904\u7406\u786E\u8BA4\u65F6\u5185\u90E8\u51FA\u9519\uFF1A\u628A traceId \u4E00\u8D77\u62A5\u7ED9\u7814\u53D1\uFF1B\u91CD\u8BD5\u524D\u5148 list \u4E00\u6B21\u786E\u8BA4\u8FD9\u6761\u8FD8\u5728"
3940
+ };
3941
+ async function respondToInteraction(ws, opts) {
3942
+ const { conversationId, interactionId, decision } = opts;
3943
+ const timeoutMs = opts.timeoutMs ?? RESPOND_TIMEOUT_MS;
3944
+ return new Promise((resolve6, reject2) => {
3945
+ let settled = false;
3946
+ const finish = (fn) => {
3947
+ if (settled) return;
3948
+ settled = true;
3949
+ clearTimeout(timer);
3950
+ offControl();
3951
+ offConnection();
3952
+ offDisconnect();
3953
+ fn();
3954
+ };
3955
+ const offControl = ws.onControl((ev) => {
3956
+ if (ev.type !== "control.interaction.resolved") return;
3957
+ const p = ev.payload;
3958
+ if (p.interactionId !== interactionId) return;
3959
+ if (p.phase === "RESUMED") {
3960
+ opts.onAccepted?.();
3961
+ return;
3962
+ }
3963
+ if (p.phase !== "TERMINAL") return;
3964
+ finish(
3965
+ () => resolve6({
3966
+ interactionId,
3967
+ type: p.type ?? null,
3968
+ decision: p.decision ?? null,
3969
+ status: p.status ?? null,
3970
+ text: p.text ?? null,
3971
+ originAgentPath: p.originAgentPath ?? null
3972
+ })
3973
+ );
3974
+ });
3975
+ const offConnection = ws.onConnection((msg) => {
3976
+ const m = msg;
3977
+ if (m?.type !== "error") return;
3978
+ const serverCode = m.code === void 0 || m.code === null ? void 0 : String(m.code);
3979
+ finish(
3980
+ () => reject2(
3981
+ new CliError({
3982
+ code: "BUSINESS_RULE_VIOLATION" /* BUSINESS_RULE_VIOLATION */,
3983
+ message: m.message || `\u56DE\u5E94\u6682\u505C\u88AB\u62D2\uFF08\u670D\u52A1\u7AEF\u7801 ${serverCode ?? "\u672A\u7ED9"}\uFF09`,
3984
+ traceId: m.traceId,
3985
+ context: {
3986
+ interactionId,
3987
+ ...serverCode ? { responseCode: serverCode } : {},
3988
+ ...m.reason && m.reason !== "null" ? { details: m.reason } : {},
3989
+ nextStep: serverCode && RESPOND_NEXT_STEP[serverCode] || "\u7528 `hcm interactions list --conversation <\u4F1A\u8BDD>` \u770B\u8FD9\u6761\u8FD8\u5728\u4E0D\u5728\uFF1B\u5728\u5C31\u91CD\u8BD5\uFF0C\u4E0D\u5728\u8BF4\u660E\u5B83\u5DF2\u8FC7\u671F\u6216\u5DF2\u88AB\u5904\u7406"
3990
+ }
3991
+ })
3992
+ )
3993
+ );
3994
+ });
3995
+ const offDisconnect = ws.onDisconnect(
3996
+ () => finish(
3997
+ () => reject2(
3998
+ new CliError({
3999
+ code: "NETWORK_ERROR" /* NETWORK_ERROR */,
4000
+ message: `\u7B49\u5F85\u6682\u505C\u7EC8\u6001\u65F6\u8FDE\u63A5\u65AD\u5F00: interactionId=${interactionId}`,
4001
+ context: {
4002
+ interactionId,
4003
+ // 决定可能已经落库了——续跑是同步跑的,断的只是回程。不能让用户当成「没发生」。
4004
+ nextStep: "\u51B3\u5B9A\u53EF\u80FD\u5DF2\u88AB\u53D7\u7406\uFF1A\u5148 `hcm interactions list --conversation <\u4F1A\u8BDD>` \u770B\u5B83\u8FD8\u5728\u4E0D\u5728\uFF0C\u4E0D\u5728\u5C31\u522B\u91CD\u53D1"
4005
+ }
4006
+ })
4007
+ )
4008
+ )
4009
+ );
4010
+ const timer = setTimeout(() => {
4011
+ finish(
4012
+ () => reject2(
4013
+ new CliError({
4014
+ code: "TIMEOUT" /* TIMEOUT */,
4015
+ message: `\u7B49\u5F85\u6682\u505C\u7EC8\u6001\u8D85\u65F6\uFF08${timeoutMs}ms\uFF09: interactionId=${interactionId}`,
4016
+ context: {
4017
+ interactionId,
4018
+ // 只收到 RESUMED 就超时是常态(续跑是一次完整 LLM 轮次),别说成「失败」。
4019
+ nextStep: "\u7EED\u8DD1\u53EF\u80FD\u8FD8\u5728\u8FDB\u884C\uFF1A\u7528 `--timeout` \u7ED9\u66F4\u957F\u65F6\u95F4\uFF0C\u6216 `hcm interactions list --conversation <\u4F1A\u8BDD>` \u786E\u8BA4\u5B83\u5DF2\u7ECF\u4E0D\u5728\u672A\u51B3\u6E05\u5355\u91CC\uFF08\u4E0D\u5728 = \u5DF2\u5904\u7406\u5B8C\uFF09"
4020
+ }
4021
+ })
4022
+ )
4023
+ );
4024
+ }, timeoutMs);
4025
+ try {
4026
+ ws.send(commandFor(decision, interactionId, conversationId));
4027
+ } catch (e) {
4028
+ finish(() => reject2(e));
4029
+ }
4030
+ });
4031
+ }
4032
+ function commandFor(decision, interactionId, conversationId) {
4033
+ switch (decision.kind) {
4034
+ case "confirm":
4035
+ return buildConfirm(interactionId, conversationId);
4036
+ case "reject":
4037
+ return buildReject(interactionId, conversationId, decision.reason);
4038
+ case "answer":
4039
+ return buildAnswer(interactionId, conversationId, decision.answer, decision.choiceIndex);
4040
+ }
4041
+ }
4042
+
3836
4043
  // src/mini/types.ts
3837
4044
  var MINI_CONTEXT_FILE = "hcm.context.json";
3838
4045
  var MINI_STATE_DIR = ".hcm";
@@ -22179,6 +22386,7 @@ export {
22179
22386
  CODE_UNBIND_READBACK_UNREADABLE,
22180
22387
  CODE_UNBIND_REFUSED,
22181
22388
  CODE_WORDS,
22389
+ CONTROL_BUFFER_LIMIT,
22182
22390
  CREDENTIAL_STORE_MODES,
22183
22391
  CliError,
22184
22392
  CliErrorCode,
@@ -22211,7 +22419,9 @@ export {
22211
22419
  FORCE_STALE_FLAG_TEXT,
22212
22420
  GATE_COMPONENTS,
22213
22421
  HANDSHAKE_AUTH_ERROR_HEADER,
22422
+ HANDSHAKE_CONVERSATION_QUERY_PARAM,
22214
22423
  HANDSHAKE_TOKEN_QUERY_PARAM,
22424
+ HCM_FIELD_RAW_KEYS,
22215
22425
  HCM_LANG_ENV,
22216
22426
  HcmClient,
22217
22427
  IMPERSONATION_ACTIVE_PATH,
@@ -22288,6 +22498,7 @@ export {
22288
22498
  VERDICTS2 as RECONCILE_VERDICTS,
22289
22499
  RECOVERY_WORDS,
22290
22500
  REQUIRED_SECTIONS,
22501
+ RESPOND_TIMEOUT_MS,
22291
22502
  RESTORE_CODES,
22292
22503
  RISK_CODES,
22293
22504
  RISK_FILE,
@@ -22302,6 +22513,7 @@ export {
22302
22513
  RefStore,
22303
22514
  RestoreFailed,
22304
22515
  SDK_VERSION,
22516
+ SERVER_ERROR_GRACE_MS,
22305
22517
  STATUSES,
22306
22518
  STEP_NOTHING,
22307
22519
  STEP_PROBE,
@@ -22484,6 +22696,7 @@ export {
22484
22696
  listEnvs,
22485
22697
  listIdentities,
22486
22698
  listModels,
22699
+ listPendingInteractions,
22487
22700
  listProfiles,
22488
22701
  listTenantMeta,
22489
22702
  listWorkspaceFiles,
@@ -22574,6 +22787,7 @@ export {
22574
22787
  resolveProjectEnvironment,
22575
22788
  resolveRefs,
22576
22789
  resolveSkillInstallOrder,
22790
+ respondToInteraction,
22577
22791
  riskFromArtifacts,
22578
22792
  roundAge,
22579
22793
  roundWarning,